CREATE EXTERNAL LIBRARY (Transact-SQL)

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

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.

Observação

No SQL Server 2017 (14.x), há suporte para a linguagem R e a plataforma Windows. Há suporte para linguagens R, Python e externas nas plataformas Windows e Linux no SQL Server 2019 (15.x) e versões posteriores.

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

Argumentos

LIBRARY_NAME

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

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

Os nomes da biblioteca 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 da função que é a proprietária da biblioteca externa. Se não estiver especificada, a propriedade será dada ao usuário atual.

As bibliotecas que pertencem ao proprietário do banco de dados são consideradas globais para o banco de dados e o runtime. Em outras palavras, os proprietários do banco 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 usuário dbo, a biblioteca externa é particular somente a esse usuário.

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

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, <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á encaminhada para o local da 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.

LIBRARY_BITS

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

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

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. Ele é necessário caso haja suporte para várias plataformas ou se o usuário precisar especificar uma plataforma diferente. No SQL Server 2019 (15.x), Windows e Linux são as plataformas compatíveis.

LANGUAGE = 'R'

Especifica a linguagem do pacote. O R tem suporte no SQL Server 2017 (14.x).

LANGUAGE

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

LANGUAGE

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

Comentários

Para a linguagem R, ao usar um arquivo, os pacotes devem ser preparados na forma de arquivos de arquivos compactados com a .zip extensão para Windows. No SQL Server 2017 (14.x), há suporte apenas para a plataforma Windows.

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

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

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

Vários pacotes, conhecidos como pacotes do sistema, são pré-instalados em uma instância do SQL. Você não pode adicionar, atualizar ou remover pacotes do sistema.

Permissões

Requer a permissão CREATE EXTERNAL LIBRARY. Por padrão, todos os usuários que tenham o dbo ou que sejam membros da função db_owner têm permissões para criar uma biblioteca externa. Para todos os outros usuários, você deve conceder permissão explicitamente usando uma instrução GRANT , especificando CREATE EXTERNAL LIBRARY como o privilégio.

No SQL Server 2019 (15.x), além CREATE EXTERNAL LIBRARY da permissão, o usuário também precisa de permissão de referência 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 uma biblioteca, é necessário ter 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 .

Exemplos

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 sp_execute_external_script procedimento para instalar a biblioteca.

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

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

Instalar pacotes com dependências

Se o pacote que você deseja instalar tiver dependências, é fundamental que você analise dependências de primeiro e segundo nível e verifique se todos os pacotes necessários estão disponíveis antes de tentar instalar o pacote de destino.

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

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

Para instalar o packageA com êxito, você precisa criar bibliotecas para o packageB e packageC, ao mesmo tempo adicionar packageA ao SQL Server. Lembre-se de verificar as versões de pacote também.

Na prática, as dependências de pacote para pacotes populares são mais complicadas do que este 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. Um pacote ausente ou uma versão de pacote incorreta pode causar falha na instalação.

Como pode ser difícil determinar todas as dependências apenas examinando o manifesto do pacote, use um pacote como miniCRAN para identificar todos os pacotes 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 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 qualquer pacote necessário não estiver disponível, a instalação do pacote packageA de destino falhará.
```
EXECUTE sp_execute_external_script
    @language = N'R',
    @script = N'
    # load the desired package packageA
    library(packageA)
    ';
```

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

Criar uma biblioteca com base em um fluxo de bytes

Se você não tiver a capacidade de salvar os arquivos de 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 (15.x), o exemplo também funciona substituindo RPythonpor .

Observação

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

Alterar uma biblioteca de pacote existente

A instrução DDL ALTER EXTERNAL LIBRARY pode ser usada para adicionar um novo conteúdo da biblioteca ou modificar o conteúdo da biblioteca existente. Para modificar uma biblioteca existente, é necessário ter a permissão ALTER ANY EXTERNAL LIBRARY.

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

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

O exemplo a seguir adiciona um arquivo externo .jar 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 sp_execute_external_script procedimento para instalar a biblioteca.

EXECUTE 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ê usa sp_execute_external_script para instalar o pacote, dependendo da plataforma em que a instância do SQL Server está em execução, o conteúdo da biblioteca dessa plataforma é usado.

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

Comentários

Esta página foi útil?

Last updated on 2026-01-28

Compartilhar via

CREATE EXTERNAL LIBRARY (Transact-SQL)

Sintaxe do SQL Server 2019

Sintaxe do SQL Server 2017

Sintaxe para a Instância Gerenciada de SQL do Azure

Argumentos

LIBRARY_NAME

OWNER_NAME

FILE_SPEC

LIBRARY_BITS

PLATAFORMA

LANGUAGE = 'R'

LANGUAGE

LANGUAGE

Comentários

Permissões

Exemplos

Adicionar uma biblioteca externa a um banco de dados

Instalar pacotes com dependências

Criar uma biblioteca com base em um fluxo de bytes

Alterar uma biblioteca de pacote existente

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

Adicionar um pacote externo para o Windows e o Linux

Conteúdo relacionado

Comentários

Recursos adicionais