CREATE EXTERNAL LIBRARY (Transact-SQL)

Carrega os arquivos de pacotes do R, Python ou Java em um banco de dados do caminho de arquivo ou fluxo de bytes especificado. Essa instrução funciona como um mecanismo genérico para que o administrador de banco de dados carregue os artefatos necessários para novos runtimes de idiomas externos e plataformas de sistema operacional compatíveis com o SQL Server.

Carrega arquivos de pacotes do R ou Python em um banco de dados do caminho de arquivo ou fluxo de bytes especificado. Essa instrução serve como um mecanismo genérico para o administrador de banco de dados carregar os artefatos necessários.

Sintaxe do 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>
}

Sintaxe do SQL Server 2017

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

<file_spec> ::=  
{  
    (CONTENT = { <client_library_specifier> | <library_bits> })  
}  

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

<library_bits> :: =  
{ 
      varbinary_literal 
    | varbinary_expression 
}

Sintaxe para a Instância Gerenciada de SQL do Azure

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

<file_spec> ::=  
{  
    (CONTENT = <library_bits>)  
}  

<library_bits> :: =  
{ 
      varbinary_literal 
    | varbinary_expression 
}

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

file_spec

Especifica o conteúdo do pacote para uma plataforma específica. Há compatibilidade apenas com um artefato de arquivo por plataforma.

O arquivo pode ser especificado no formato de um caminho local ou caminho de rede.

Ao tentar acessar o arquivo especificado em <client_library_specifier>, o SQL Server representa o contexto de segurança do logon atual do Windows. Se <client_library_specifier> especificar um local de rede (caminho UNC), a representação do logon atual não será repassada ao local de rede devido a limitações de delegação. Nesse caso, o acesso é feito usando o contexto de segurança da conta de serviço do SQL Server. Para obter mais informações, consulte Credenciais (Mecanismo de Banco de Dados).

Opcionalmente, uma plataforma de sistema operacional para o arquivo pode ser especificada. Somente um artefato ou conteúdo de arquivo é permitido para cada plataforma de sistema operacional em uma linguagem ou um runtime específico.

PLATAFORMA

Especifica a plataforma para o conteúdo da biblioteca. O valor usa como padrão a plataforma de host na qual o SQL Server está sendo executado. Portanto, o usuário não precisa especificar o valor. É necessário no caso em que várias plataformas são compatíveis ou quando o usuário precisa especificar outra plataforma. No SQL Server 2019, o Windows e o Linux são as plataformas compatíveis.

LANGUAGE = 'R'

Especifica a linguagem do pacote. O R tem suporte no SQL Server 2017.

linguagem

Especifica a linguagem do pacote. O valor pode ser R ou Python na Instância Gerenciada de SQL do Azure.

linguagem

Especifica a linguagem do pacote. O valor pode ser R, Python ou o nome de uma linguagem externa (confira CREATE EXTERNAL LANGUAGE).

Para a linguagem R, ao usar um arquivo, os pacotes precisam ser preparados no formato de arquivos mortos compactados com a extensão .ZIP para o Windows. No SQL Server 2017, apenas a plataforma Windows é compatível.

Para a linguagem R, ao usar um arquivo, os pacotes precisam ser preparados no formato de arquivos mortos compactados com a extensão .zip.

Para a linguagem Python, o pacote em um arquivo .whl ou .zip deve estar preparado na forma de um arquivo morto compactado. Se o pacote já for um arquivo .zip, ele deverá ser incluído em um novo arquivo .zip. Carregar um pacote diretamente como arquivo .whl ou .zip não é uma ação compatível atualmente.

No SQL Server 2019, além da permissão 'CREATE EXTERNAL LIBRARY', o usuário também precisa referenciar a permissão em uma linguagem externa para criar bibliotecas externas para essa linguagem externa.

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

Adicionar uma biblioteca externa a um banco de dados

O exemplo a seguir adiciona uma biblioteca externa chamada customPackage a um banco de dados.

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

Depois que a biblioteca é carregada com êxito na instância, um usuário executa o procedimento sp_execute_external_script para instalar a biblioteca.

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

Para a linguagem Python no SQL Server 2019, o exemplo também funciona, substituindo 'R' com 'Python'.

• Carregue o pacote de destino e suas dependências. Todos os arquivos devem estar em uma pasta que seja acessível ao 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 os pacotes necessários primeiro.

  Se um pacote obrigatório já foi carregado na instância, você não precisa adicioná-lo novamente. Verifique se o pacote existente é a versão correta.

  Os pacotes packageC e packageB necessários são instalados na ordem correta, quando sp_execute_external_script é executado pela primeira vez para instalar o pacote packageA.

  No entanto, se um pacote obrigatório não estiver disponível, a instalação do pacote de destino packageA falhará.

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

Para a linguagem Python no SQL Server 2019, o exemplo também funciona, substituindo 'R' com 'Python'.

Para a linguagem Python no SQL Server 2019, o exemplo também funciona, substituindo 'R' com 'Python' .

Adicionar um arquivo .jar do Java a um banco de dados

O exemplo a seguir adiciona um arquivo jar externo chamado customJar a um banco de dados.

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

Depois que a biblioteca é carregada com êxito na instância, um usuário executa o procedimento sp_execute_external_script para instalar a 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))

Adicionar um pacote externo para o Windows e o Linux

Você pode especificar até dois <file_spec>, um para o Windows e outro para o 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')

Quando você usar sp_execute_external_script para instalar o pacote, dependendo da plataforma na qual a Instância do SQL Server está em execução, o conteúdo da biblioteca dessa plataforma será usado.

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