CREATE EXTERNAL LIBRARY (Transact-SQL)

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

Carga los archivos de paquete de R, Python o Java en una base de datos desde la ruta de acceso de archivo o la secuencia de bytes especificada. Esta instrucción actúa como un mecanismo genérico para que el administrador de base de datos pueda cargar los artefactos necesarios para cualquier runtime de lenguaje externo nuevo y plataformas de sistema operativo compatibles con SQL Server.

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

CREATE EXTERNAL LIBRARY library_name  
[ AUTHORIZATION owner_name ]  
FROM <file_spec> [ ,...2 ]  
WITH ( LANGUAGE = <language> )  
[ ; ]  

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

<client_library_specifier> :: = 
{
    '[file_path\]manifest_file_name'  
} 

<library_bits> :: =  
{ 
      varbinary_literal 
    | varbinary_expression 
}

<platform> :: = 
{
      WINDOWS
    | LINUX
}

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

Argumentos

library_name

Las bibliotecas cargadas en la instancia pueden ser públicas o privadas. Si es un miembro de dbo quien ha creado la biblioteca, esta será pública y se podrá compartir con todos los usuarios. En caso contrario, será privada exclusivamente del usuario.

Los nombres de biblioteca deben ser únicos dentro del contexto de un usuario o propietario específico. Por ejemplo, dos usuarios, RUser1 y RUser2, pueden cargar individualmente y por separado la biblioteca de R ggplot2. Sin embargo, si RUser1 desea cargar una versión más reciente de ggplot2, la segunda instancia debe llamarse de forma diferente o debe reemplazar la biblioteca existente.

Los nombres de biblioteca no se pueden asignar de forma arbitraria; el nombre de biblioteca debe ser el mismo que el nombre necesario para cargar la biblioteca en el script externo.

owner_name

Especifica el nombre del usuario o rol que es propietario de la biblioteca externa. Si no se especifica, la propiedad se otorga al usuario actual.

Las bibliotecas que pertenecen al propietario de la base de datos se consideran globales en la base de datos y en tiempo de ejecución. Dicho de otro modo, los propietarios de bases de datos pueden crear bibliotecas que contienen un conjunto común de bibliotecas o paquetes que se comparten entre varios usuarios. Cuando un usuario distinto del usuario dbo crea una biblioteca externa, esta es privada exclusivamente de ese usuario.

Cuando el usuario RUser1 ejecuta un script externo, el valor de libPath puede contener varias rutas de acceso. La primera ruta de acceso es siempre la ruta de acceso a la biblioteca compartida creada por el propietario de la base de datos. La segunda parte de libPath especifica la ruta de acceso que contiene paquetes cargados individualmente por RUser1.

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 especifica como una ruta de acceso local o una ruta de acceso de red.

Cuando se intenta acceder al archivo especificado en <especificador_biblioteca_cliente>, SQL Server suplanta el contexto de seguridad del inicio de sesión de Windows actual. Si >especificador_biblioteca_cliente< especifica una ubicación de red (ruta de acceso UNC), la suplantación del inicio de sesión actual no se mantiene en la ubicación de red debido a las limitaciones de delegación. En este caso, el acceso se realiza mediante el contexto de seguridad de la cuenta del servicio SQL Server. Para más información, vea Credenciales (motor de base de datos).

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 necesita crear una biblioteca o modificar una ya existente (y tiene los permisos necesarios para hacerlo), pero el sistema de archivos en el servidor está restringido y no puede copiar los archivos de la biblioteca en una ubicación a la que pueda tener acceso el servidor.

PLATFORM

Especifica la plataforma para el contenido de la biblioteca. El valor se establece de forma predeterminada en la plataforma de host en la que SQL Server se ejecuta, con lo cual no es necesario que el usuario lo especifique. Es necesario en caso de que se admitan varias plataformas o si el usuario debe especificar 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).

Observaciones

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 CREATE EXTERNAL LIBRARY carga los bits de biblioteca en la base de datos. La biblioteca se instala cuando un usuario ejecuta un script externo con sp_execute_external_script y llama al paquete o a la biblioteca.

Las bibliotecas cargadas en la instancia pueden ser públicas o privadas. Si es un miembro de dbo quien ha creado la biblioteca, esta será pública y se podrá compartir con todos los usuarios. En caso contrario, será privada exclusivamente del usuario.

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

Requiere el permiso CREATE EXTERNAL LIBRARY. De forma predeterminada, cualquier usuario que tenga dbo y sea miembro del rol db_owner tiene permisos para crear una biblioteca externa. Para todos los demás usuarios, debe concederles explícitamente permiso con una instrucción GRANT y especificando CREATE EXTERNAL LIBRARY como privilegio.

En SQL Server 2019, además del permiso “CREATE EXTERNAL LIBRARY”, el usuario también necesita el permiso de referencia en un lenguaje externo para poder crear bibliotecas externas para dicho lenguaje.

GRANT REFERENCES ON EXTERNAL LANGUAGE::Java to user
GRANT CREATE EXTERNAL LIBRARY to user

Para modificar una biblioteca, se necesita el permiso ALTER ANY EXTERNAL LIBRARY.

Para crear una biblioteca externa mediante una ruta de acceso de archivo, el usuario debe ser miembro del inicio de sesión autenticado de Windows o del rol fijo de servidor sysadmin.

Ejemplos

Agregar una biblioteca externa a una base de datos

En el siguiente ejemplo se agrega una biblioteca externa denominada customPackage a una base de datos.

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

Después de que la biblioteca se haya cargado correctamente en la instancia, un usuario ejecuta el procedimiento sp_execute_external_script para instalar esa biblioteca.

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

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

Instalar paquetes con dependencias

Si el paquete que se va a instalar tiene dependencias, es fundamental analizar las dependencias de primer y de segundo nivel, así como procurar que todos los paquetes necesarios estén disponibles antes de intentar instalar el paquete de destino.

Por ejemplo, imagine que quiere instalar un nuevo paquete, packageA:

• packageA tiene una dependencia en packageB.
• packageB tiene una dependencia en packageC.

Para instalar packageA correctamente, debe crear bibliotecas para packageB y packageC al mismo tiempo que agrega packageA a SQL Server. Asegúrese de comprobar también las versiones de paquete necesarias.

En la práctica, las dependencias de paquete de los paquetes más conocidos suelen ser mucho más complicadas que en este sencillo ejemplo. Por ejemplo, ggplot2 podría necesitar más de 30 paquetes y estos, a su vez, podrían requerir más paquetes que no están disponibles en el servidor. Cualquier paquete que falte o versión de paquete incorrecta puede hacer que la instalación no se lleve a cabo.

Dado que puede ser difícil determinar todas las dependencias únicamente consultando el manifiesto del paquete, se recomienda usar un paquete como miniCRAN para identificar todos los paquetes que pueden ser necesarios para que la instalación se lleve a cabo correctamente.

• Cargue el paquete de destino y sus dependencias. Todos los archivos deben estar en una carpeta que sea accesible para el servidor.

  CREATE EXTERNAL LIBRARY packageA 
  FROM (CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL14.MSSQLSERVER\packageA.zip') 
  WITH (LANGUAGE = 'R'); 
  GO
  
  CREATE EXTERNAL LIBRARY packageB FROM (CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL14.MSSQLSERVER\packageB.zip') 
  WITH (LANGUAGE = 'R');
  GO
  
  CREATE EXTERNAL LIBRARY packageC FROM (CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL14.MSSQLSERVER\packageC.zip') 
  WITH (LANGUAGE = 'R');
  GO
  

• Instale primero los paquetes necesarios.

  Si un paquete necesario ya se ha cargado en la instancia, no tendrá que agregarlo de nuevo. Bastará con comprobar que su versión es la correcta.

  Los paquetes necesarios packageC y packageB se instalan en el orden correcto cuando sp_execute_external_script se ejecuta por primera vez para instalar el paquete packageA.

  Pero si alguno de los paquetes necesarios no está disponible, la instalación del paquete de destino packageA no se llevará a cabo.

  EXEC sp_execute_external_script 
  @language =N'R', 
  @script=N'
  # load the desired package packageA
  library(packageA)
  '
  

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

Crear una biblioteca a partir de una secuencia de bytes

Si no tiene la posibilidad de guardar los archivos del paquete en una ubicación en el servidor, puede pasar el contenido del paquete en una variable. En el siguiente ejemplo se crea una biblioteca pasando los bits como un literal hexadecimal.

CREATE EXTERNAL LIBRARY customLibrary FROM (CONTENT = 0xABC123...) WITH (LANGUAGE = 'R');

Para el lenguaje Python en SQL Server 2019, 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.

Cambiar una biblioteca de paquetes existente

La instrucción DDL ALTER EXTERNAL LIBRARY sirve para agregar nuevo contenido de biblioteca o para modificar el contenido de biblioteca ya existente. Para modificar una biblioteca existente, se necesita el permiso ALTER ANY EXTERNAL LIBRARY.

Para más información, vea ALTER EXTERNAL LIBRARY.

Agregar un archivo .jar de Java a una base de datos

En el ejemplo siguiente se agrega un archivo JAR externo denominado customJar a una base de datos.

CREATE EXTERNAL LIBRARY customJar
FROM (CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL15.MSSQLSERVER\customJar.jar') 
WITH (LANGUAGE = 'Java');

Después de que la biblioteca se haya cargado correctamente en la instancia, un usuario ejecuta el procedimiento sp_execute_external_script para instalar esa biblioteca.

EXEC sp_execute_external_script
    @language = N'Java'
    , @script = N'customJar.MyCLass.myMethod'
    , @input_data_1 = N'SELECT * FROM dbo.MyTable'
WITH RESULT SETS ((column1 int))

Incorporación de un paquete externo para Windows y Linux

Puede especificar hasta dos <file_spec>, uno para Windows y otro para Linux.

CREATE EXTERNAL LIBRARY lazyeval 
FROM (CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL15.MSSQLSERVER\packageA.zip', PLATFORM = WINDOWS),
(CONTENT = 'C:\Program Files\Microsoft SQL Server\MSSQL15.MSSQLSERVER\packageA.tar.gz', PLATFORM = LINUX)
WITH (LANGUAGE = 'R')

Al usar sp_execute_external_script para instalar el paquete, según la plataforma en la que se ejecuta la instancia de SQL Server, se usará el contenido de la biblioteca para dicha plataforma.

EXECUTE sp_execute_external_script 
    @LANGUAGE = N'R',
    @SCRIPT = N'
library(packageA)'

Consulte también

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