ALTER EXTERNAL LIBRARY (Transact-SQL)

Se aplica a: SQL Server 2017 (14.x) y versiones posteriores Azure SQL Managed Instance

Modifica el contenido de una biblioteca de paquetes externa existente.

Nota

En SQL Server 2017, se admiten el lenguaje R y la plataforma Windows. SQL Server 2019 y versiones posteriores admiten R, Python y lenguajes externos en las plataformas Windows y Linux.

Sintaxis para SQL Server 2019

ALTER EXTERNAL LIBRARY library_name
[ AUTHORIZATION owner_name ]
SET <file_spec>
WITH ( LANGUAGE = <language> )
[ ; ]

<file_spec> ::=
{
    (CONTENT = { <client_library_specifier> | <library_bits> | NONE}
    [, PLATFORM = <platform> )
}

<client_library_specifier> :: =
{
      '[\\computer_name\]share_name\[path\]manifest_file_name'
    | '[local_path\]manifest_file_name'
    | '<relative_path_in_external_data_source>'
}

<library_bits> :: =
{ 
      varbinary_literal 
    | varbinary_expression 
}

<platform> :: = 
{
      WINDOWS
    | LINUX
}

<language> :: = 
{
      'R'
    | 'Python'
    | <external_language>
}

Argumentos

library_name

Especifica el nombre de una biblioteca de paquetes existente. Las bibliotecas tienen como ámbito el usuario. Los nombres de biblioteca deben ser únicos dentro del contexto de un usuario o propietario específico.

El nombre de biblioteca no se puede asignar de forma arbitraria. Es decir, se debe usar el nombre que el tiempo de ejecución que realiza la llamada espera cuando se carga el paquete.

owner_name

Especifica el nombre del usuario o rol que es propietario de la biblioteca externa.

file_spec

Especifica el contenido del paquete para una plataforma específica. Solo se admite un artefacto de archivo por cada plataforma.

El archivo se puede especificar como una ruta de acceso local o una ruta de acceso de red. Si se especifica la opción de origen de datos, el nombre de archivo puede ser una ruta de acceso relativa con respecto al contenedor al que hace referencia en el EXTERNAL DATA SOURCE.

Opcionalmente, se puede especificar una plataforma de sistema operativo para el archivo. Solo se permite un artefacto de archivo o contenido para cada plataforma de sistema operativo para un determinado lenguaje o tiempo de ejecución.

library_bits

Especifica el contenido del paquete como un literal hexadecimal, similar a los ensamblados.

Esta opción es útil si se dispone del permiso requerido para modificar una biblioteca, pero el acceso de archivo en el servidor está restringido y no se puede guardar el contenido en una ruta de acceso a la que el servidor pueda tener acceso.

En su lugar, se puede pasar el contenido del paquete como una variable en formato binario.

platform

Especifica la plataforma para el contenido de la biblioteca. Este valor es obligatorio al modificar una biblioteca para agregar una plataforma diferente. En SQL Server 2019, Windows y Linux son las únicas plataformas admitidas.

language

Especifica el lenguaje del paquete. El valor puede ser R, Python o el nombre de un lenguaje externo (consulte CREAR LENGUAJE EXTERNO).

Comentarios

En el lenguaje R, cuando se usa un archivo, los paquetes deben estar preparados en forma de archivos de almacenamiento comprimidos con la extensión .ZIP.

Para el lenguaje Python, el paquete en un archivo .whl o .zip se debe preparar como un archivo comprimido. Si el paquete ya es un archivo .zip, se debe incluir en un nuevo archivo .zip. En la actualidad no se permite la carga directa de un paquete como archivo .whl o .zip.

La instrucción ALTER EXTERNAL LIBRARY solo carga los bits de biblioteca en la base de datos. La biblioteca modificada se instala cuando un usuario ejecuta código en el sp_execute_external_script (Transact-SQL) que llama a la biblioteca.

Varios paquetes, denominados paquetes del sistema, se instalan previamente en una instancia de SQL. El usuario no puede agregar, actualizar ni quitar paquetes del sistema.

Permisos

De forma predeterminada, el usuario dbo o cualquier miembro del rol db_owner tiene permiso para ejecutar ALTER EXTERNAL LIBRARY. Además, el usuario que crea una biblioteca externa puede modificarla.

Ejemplos

En los ejemplos siguientes se cambia una biblioteca externa denominada customPackage.

Sustitución del contenido de una biblioteca mediante un archivo

En el ejemplo siguiente se modifica una biblioteca externa denominada customPackage, mediante un archivo comprimido que contiene los bits actualizados.

ALTER EXTERNAL LIBRARY customPackage 
SET 
  (CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL14.MSSQLSERVER\customPackage.zip')
WITH (LANGUAGE = 'R');

Para instalar la biblioteca actualizada, ejecute el procedimiento almacenado sp_execute_external_script.

EXEC sp_execute_external_script 
@language =N'R', 
@script=N'library(customPackage)'
;

Para el lenguaje Python, el ejemplo también funciona si se reemplaza 'R' con 'Python'.

Modificación de una biblioteca existente mediante un flujo de bytes

En el ejemplo siguiente se modifica la biblioteca existente pasando los nuevos bits como un literal hexadecimal.

ALTER EXTERNAL LIBRARY customLibrary 
SET (CONTENT = 0xABC123...) WITH (LANGUAGE = 'R');

Para el lenguaje Python, el ejemplo también funciona si se reemplaza 'R' con 'Python'.

Nota

En este ejemplo de código solo se muestra la sintaxis; el valor binario de CONTENT = se ha truncado para mejorar la lectura y no se puede crear una biblioteca funcional. El contenido real de la variable binaria sería mucho más largo.

Consulte también

CREATE EXTERNAL LIBRARY (Transact-SQL)
DROP EXTERNAL LIBRARY (Transact-SQL)
sys.external_library_files
sys.external_libraries