ALTER EXTERNAL LIBRARY (Transact-SQL)

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

Modifica o conteúdo de uma biblioteca de pacotes externa existente.

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.

Sintaxe do 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 o nome de uma biblioteca de pacotes existente. As bibliotecas estão no escopo do usuário. Os nomes de bibliotecas devem ser exclusivos no contexto de um usuário ou proprietário específico.

O nome da biblioteca não pode ser atribuído arbitrariamente. Ou seja, você precisa usar o nome que o runtime de chamada espera ao carregar o pacote.

OWNER_NAME

Especifica o nome do usuário ou da função que é a proprietária da biblioteca externa.

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 na forma de um caminho local ou de um caminho de rede. Se a opção de fonte de dados for especificada, o nome do arquivo poderá ser um caminho relativo em relação ao contêiner referenciado em EXTERNAL DATA SOURCE.

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ê tiver a permissão necessária para alterar uma biblioteca, mas o acesso a arquivos no servidor for restrito e você não puder salvar o conteúdo em um caminho que o servidor possa acessar.

Nesse caso, você pode passar o conteúdo do pacote como uma variável em formato binário.

PLATAFORMA

Especifica a plataforma para o conteúdo da biblioteca. Esse valor é necessário ao modificar uma biblioteca existente para adicionar uma plataforma diferente. No SQL Server 2019 (15.x), Windows e Linux são as plataformas compatíveis.

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 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 ALTER EXTERNAL LIBRARY carrega apenas os bits de biblioteca para o banco de dados. A biblioteca modificada é instalada quando um usuário executa o código em sp_execute_external_script que chama 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

Por padrão, o usuário dbo ou qualquer membro da função db_owner tem permissão para executar ALTER EXTERNAL LIBRARY. Além disso, os usuários que criaram a biblioteca externa podem alterá-la.

Exemplos

Os exemplos a seguir alteram uma biblioteca externa chamada customPackage.

Substituir o conteúdo de uma biblioteca usando um arquivo

O exemplo a seguir modifica uma biblioteca externa chamada customPackage, usando um arquivo compactado que contém os bits atualizados.

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

Para instalar a biblioteca atualizada, execute o procedimento armazenado sp_execute_external_script.

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

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

Alterar uma biblioteca existente usando um fluxo de bytes

O exemplo a seguir altera a biblioteca existente, passando os novos bits como um literal hexadecimal.

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

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

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.

Conteúdo relacionado

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