ALTER EXTERNAL LIBRARY (Transact-SQL)

S’applique à : SQL Server 2017 (14.x) et versions ultérieures Azure SQL Managed Instance

Modifie le contenu d’une bibliothèque de package externe existante.

Notes

Dans SQL Server 2017, le langage R et la plateforme Windows sont pris en charge. R, Python et les langages externes sur les plateformes Windows et Linux sont pris en charge dans SQL Server 2019 et ultérieur.

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

Arguments

library_name

Spécifie le nom d’une bibliothèque de package existante. Les bibliothèques sont limitées à l’utilisateur. Les noms de bibliothèques doivent être uniques dans le contexte d’un utilisateur ou d’un propriétaire donné.

Le nom de la bibliothèque ne peut pas être assigné arbitrairement. Autrement dit, vous devez utiliser le nom que le runtime appelant attend quand il charge le package.

owner_name

Spécifie le nom de l’utilisateur ou du rôle propriétaire de la bibliothèque externe.

file_spec

Spécifie le contenu du package pour une plateforme spécifique. Un seul artefact de fichier par plateforme est pris en charge.

Le fichier peut être spécifié sous la forme d’un chemin local ou d’un chemin réseau. Si l’option de source de données est spécifiée, le nom de fichier peut être un chemin relatif au conteneur référencé dans EXTERNAL DATA SOURCE.

Si vous le souhaitez, vous pouvez spécifier une plateforme de système d’exploitation pour le fichier. Un seul artefact de fichier ou contenu est autorisé pour chaque plateforme de système d’exploitation pour un langage ou un runtime spécifique.

library_bits

Spécifie le contenu du package en tant que littéral hexadécimal, similaire aux assemblys.

Cette option est utile si vous avez l’autorisation nécessaire pour modifier une bibliothèque, mais que l’accès aux fichiers sur le serveur est restreint et que vous ne pouvez pas enregistrer le contenu à un emplacement accessible au serveur.

Au lieu de cela, vous pouvez passer le contenu du package en tant que variable au format binaire.

platform

Spécifie la plateforme pour le contenu de la bibliothèque. Cette valeur est nécessaire lors de la modification d’une bibliothèque existante pour ajouter une autre plateforme. Dans SQL Server 2019, les plateformes Windows et Linux sont prises en charge.

language

Spécifie le langage du package. La valeur peut être R, Python ou le nom d’un langage externe (consultez CREATE EXTERNAL LANGUAGE).

Remarque

Pour afficher la syntaxe Transact-SQL pour SQL Server 2014 (12.x) et versions antérieures, consultez la Documentation sur les versions antérieures.

Notes

Pour le langage R, lors de l’utilisation d’un fichier, les packages doivent être préparés sous la forme de fichiers d’archive compressés avec l’extension .ZIP.

Pour le langage Python, le package contenu dans un fichier .whl ou .zip doit être préparé sous la forme d’un fichier d’archive compressé. Si le package est déjà un fichier .zip, il doit être inclus dans un nouveau fichier .zip. Le chargement direct d’un package sous la forme de fichier .whl ou .zip n’est actuellement pas pris en charge.

L’instruction ALTER EXTERNAL LIBRARY charge uniquement les bits de la bibliothèque vers la base de données. La bibliothèque modifiée est installée quand un utilisateur exécute dans sp_execute_external_script (Transact-SQL) du code qui appelle la bibliothèque.

Un certain nombre de packages, appelés packages système, sont préinstallés dans une instance SQL. Les packages systèmes ne peuvent être ni ajoutés, ni mis à jour, ni supprimés par l’utilisateur.

Autorisations

Par défaut, l’utilisateur dbo ou n’importe quel membre du rôle db_owner a l’autorisation d’exécuter ALTER EXTERNAL LIBRARY. Par ailleurs, l’utilisateur qui a créé la bibliothèque externe peut la modifier.

Exemples

Les exemples suivants modifient une bibliothèque externe nommée customPackage.

Remplacer le contenu d’une bibliothèque à l’aide d’un fichier

L’exemple suivant modifie une bibliothèque externe nommée customPackage, à l’aide d’un fichier compressé qui contient les bits mis à jour.

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

Pour installer la bibliothèque mise à jour, exécutez la procédure stockée sp_execute_external_script.

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

Pour le langage Python, l’exemple fonctionne également en remplaçant 'R' par 'Python'.

Modifier une bibliothèque existante à l’aide d’un flux d’octets

L’exemple suivant modifie la bibliothèque existante en passant les nouveaux bits sous forme d’un littéral hexadécimal.

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

Pour le langage Python, l’exemple fonctionne également en remplaçant 'R' par 'Python'.

Notes

Cet exemple de code montre uniquement la syntaxe ; la valeur binaire de CONTENT = a été tronquée pour des raisons de clarté et ne crée pas une bibliothèque fonctionnelle. Son véritable contenu serait beaucoup plus long.

Voir aussi

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