CRIAR BIBLIOTECA EXTERNA (Transact-SQL)

Aplica-se a: SQL Server 2017 (14.x) e versões posteriores Instância Gerenciada SQL do Azure

Carrega arquivos de pacote R, Python ou Java para um banco de dados a partir do fluxo de bytes ou caminho de arquivo especificado. Esta instrução serve como um mecanismo genérico para o administrador de banco de dados carregar artefatos necessários para quaisquer novos tempos de execução de linguagem externa e plataformas de sistema operacional suportadas pelo SQL Server.

Observação

No SQL Server 2017, há suporte para a linguagem R e a plataforma Windows. R, Python e linguagens externas nas plataformas Windows e Linux são suportados no SQL Server 2019 e posterior.

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

Arguments

library_name

As bibliotecas carregadas para a instância podem ser públicas ou privadas. Se a biblioteca for criada por um membro do dbo, a biblioteca será pública e poderá ser compartilhada com todos os usuários. Caso contrário, a biblioteca será privada apenas para esse usuário.

Os nomes das bibliotecas devem ser exclusivos dentro do contexto de um usuário ou proprietário específico. Por exemplo, dois usuários RUser1 e RUser2 podem carregar a biblioteca ggplot2R individualmente e separadamente. No entanto, se RUser1 quiser carregar uma versão mais recente do ggplot2, a segunda instância deve ser nomeada de forma diferente ou deve substituir a biblioteca existente.

Os nomes das bibliotecas não podem ser atribuídos arbitrariamente; O nome da biblioteca deve ser o mesmo que o nome necessário para carregar a biblioteca no script externo.

owner_name

Especifica o nome do usuário ou função que possui a biblioteca externa. Se não for especificado, a propriedade será dada ao usuário atual.

As bibliotecas de propriedade do proprietário do banco de dados são consideradas globais para o banco de dados e o tempo de execução. Em outras palavras, os proprietários de bancos de dados podem criar bibliotecas que contêm um conjunto comum de bibliotecas ou pacotes que são compartilhados por muitos usuários. Quando uma biblioteca externa é criada por um usuário diferente do dbo usuário, a biblioteca externa é privada apenas para esse usuário.

Quando o usuário RUser1 executa um script externo, o valor de libPath pode conter vários caminhos. O primeiro caminho é sempre o caminho para a biblioteca compartilhada criada pelo proprietário do banco de dados. A segunda parte do libPath especifica o caminho que contém os pacotes carregados individualmente pelo RUser1.

file_spec

Especifica o conteúdo do pacote para uma plataforma específica. Apenas um artefato de arquivo por plataforma é suportado.

O arquivo pode ser especificado na forma de um caminho local ou caminho de rede.

Ao tentar acessar o arquivo especificado no <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á levada adiante para o 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. Apenas um arquivo, artefato ou conteúdo é permitido para cada plataforma do sistema operacional para uma linguagem ou tempo de execução específico.

library_bits

Especifica o conteúdo do pacote como um literal hexadecimal, semelhante aos assemblies.

Essa opção é útil se você precisar criar uma biblioteca ou alterar uma biblioteca existente (e tiver as permissões necessárias para fazê-lo), mas o sistema de arquivos no servidor é restrito e você não pode copiar os arquivos da biblioteca para um local que o servidor possa acessar.

PLATAFORMA

Especifica a plataforma para o conteúdo da biblioteca. O valor assume como padrão a plataforma 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 suportadas, ou o usuário precisa especificar uma plataforma diferente. No SQL Server 2019, Windows e Linux são as plataformas suportadas.

Idioma

Especifica o idioma do pacote. O valor pode ser R, Pythonou o nome de um idioma externo (consulte CREATE EXTERNAL LANGUAGE).

Observações

Para a linguagem R, ao usar um arquivo, os pacotes devem ser preparados na forma de arquivos compactados com a extensão .ZIP.

Para a linguagem Python, o pacote em um arquivo .whl ou .zip deve ser preparado na forma de um arquivo compactado. Se o pacote já for um arquivo .zip, ele deve ser incluído em um novo arquivo .zip. Atualmente, não há suporte para o upload de um pacote como arquivo .whl ou .zip diretamente.

A CREATE EXTERNAL LIBRARY instrução carrega os bits da biblioteca para o banco de dados. A biblioteca é instalada quando um usuário executa um script externo usando sp_execute_external_script e chama o pacote ou biblioteca.

As bibliotecas carregadas para a instância podem ser públicas ou privadas. Se a biblioteca for criada por um membro do dbo, a biblioteca será pública e poderá ser compartilhada com todos os usuários. Caso contrário, a biblioteca será privada apenas para esse usuário.

Vários pacotes, conhecidos como pacotes do sistema, são pré-instalados em uma instância SQL. Os pacotes do sistema não podem ser adicionados, atualizados ou removidos pelo usuário.

Permissions

Requer a CREATE EXTERNAL LIBRARY permissão. Por padrão, qualquer usuário que tenha dbo que seja membro da função db_owner tem permissões para criar uma biblioteca externa. Para todos os outros usuários, você deve explicitamente dar-lhes permissão usando uma instrução GRANT , especificando CREATE EXTERNAL LIBRARY como o privilégio.

No SQL Server 2019, além da permissão 'CREATE EXTERNAL LIBRARY', o usuário também precisa da permissão de referências em um idioma externo para criar bibliotecas externas para esse idioma externo.

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

Para modificar qualquer biblioteca é necessária a permissão separada, ALTER ANY EXTERNAL LIBRARY.

Para criar uma biblioteca externa usando um caminho de arquivo, o usuário deve ser um logon autenticado do Windows ou um membro da função de servidor fixa sysadmin.

Examples

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 for carregada com êxito na instância, um usuário executará o sp_execute_external_script procedimento 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' por 'Python'.

Instalando pacotes com dependências

Se o pacote que você deseja instalar tiver dependências, é fundamental analisar as dependências de primeiro e segundo nível e garantir que todos os pacotes necessários estejam disponíveis antes de tentar instalar o pacote de destino.

Por exemplo, suponha que você deseja instalar um novo pacote, packageA:

• packageA tem uma dependência de packageB
• packageB tem uma dependência de packageC

Para ter êxito na instalação packageAdo , você deve criar bibliotecas para packageB e packageC ao mesmo tempo que você adiciona packageA ao SQL Server. Certifique-se de verificar as versões de pacote necessárias também.

Na prática, as dependências de pacotes para pacotes populares são geralmente muito mais complicadas do que este simples exemplo. Por exemplo, ggplot2 pode exigir mais de 30 pacotes, e esses pacotes podem exigir pacotes adicionais que não estão disponíveis no servidor. Qualquer pacote ausente ou versão errada do pacote pode fazer com que a instalação falhe.

Como pode ser difícil determinar todas as dependências apenas examinando o manifesto do pacote, recomendamos que você use um pacote como miniCRAN para identificar todos os pacotes que podem ser necessários para concluir a instalação com êxito.

• Carregue o pacote de destino e suas dependências. Todos os arquivos devem estar em uma pasta 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 necessário já tiver sido carregado na instância, você não precisará adicioná-lo novamente. Apenas certifique-se de verificar se o pacote existente é a versão correta.

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

  No entanto, se algum pacote necessário não estiver disponível, a instalação do pacote packageA de destino 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' por 'Python'.

Criar uma biblioteca a partir de um fluxo de bytes

Se você não tiver a capacidade de salvar os arquivos do pacote em um local no servidor, poderá passar o conteúdo do pacote em uma variável. O exemplo a seguir cria uma biblioteca passando os bits como um literal hexadecimal.

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

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

Observação

Este exemplo de código demonstra apenas a sintaxe; O valor binário em CONTENT = foi truncado para legibilidade e não cria uma biblioteca de trabalho. O conteúdo real da variável binária seria muito mais longo.

Alterar uma biblioteca de pacotes existente

A ALTER EXTERNAL LIBRARY instrução DDL pode ser usada para adicionar novo conteúdo de biblioteca ou modificar conteúdo de biblioteca existente. Para modificar uma biblioteca existente requer a ALTER ANY EXTERNAL LIBRARY permissão.

Para obter mais informações, consulte ALTER EXTERNAL LIBRARY.

Adicionar um arquivo Java .jar 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 for carregada com êxito na instância, um usuário executará o sp_execute_external_script procedimento 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 Windows e Linux

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

Quando você usa sp_execute_external_script para instalar o pacote, dependendo da plataforma em que a instância do SQL Server está sendo executada, o conteúdo da biblioteca para essa plataforma será usado.

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

Consulte também

ALTER BIBLIOTECA EXTERNA (Transact-SQL)
DROP BIBLIOTECA EXTERNA (Transact-SQL)
sys.external_library_files
sys.external_libraries