CREATE EXTERNAL LIBRARY (Transact-SQL)

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

Charge des fichiers de package R, Python ou Java vers une base de données à partir du chemin de fichier ou du flux d’octets spécifié. Cette instruction sert de mécanisme générique permettant à l’administrateur de base de données de charger des artefacts nécessaires pour tout nouveau runtime de langage externe et toute nouvelle plateforme de système d’exploitation pris en charge par SQL Server.

Notes

Dans SQL Server 2017 (14.x), le langage R et la plateforme Windows sont pris en charge. Les langages R, Python et externes sur les plateformes Windows et Linux sont pris en charge dans SQL Server 2019 (15.x) et versions ultérieures.

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

Les bibliothèques chargées vers l’instance peuvent être publiques ou privées. Si la bibliothèque est créée par un membre de dbo, elle est publique et peut être partagée avec tous les utilisateurs. Dans le cas contraire, la bibliothèque est privée pour cet utilisateur uniquement.

Les noms de bibliothèques doivent être uniques dans le contexte d’un utilisateur ou d’un propriétaire donné. Par exemple, deux utilisateurs RUser1 et RUser2 peuvent charger individuellement et séparément la bibliothèque R ggplot2. Toutefois, si RUser1 vous souhaitez charger une version plus récente de ggplot2, la deuxième instance doit être nommée différemment ou remplacer la bibliothèque existante.

Les noms de bibliothèque ne peuvent pas être attribués arbitrairement ; le nom de la bibliothèque doit être identique au nom requis pour charger la bibliothèque dans le script externe.

OWNER_NAME

Spécifie le nom de l’utilisateur ou du rôle propriétaire de la bibliothèque externe. En l'absence de spécification, la propriété revient à l'utilisateur actuel.

Les bibliothèques appartenant au propriétaire de la base de données sont considérées comme globales pour la base de données et le runtime. En d’autres termes, les propriétaires de bases de données peuvent créer des bibliothèques qui contiennent un ensemble commun de bibliothèques ou de packages partagés par de nombreux utilisateurs. Quand une bibliothèque externe est créée par un utilisateur autre que l’utilisateur dbo, la bibliothèque externe est privée pour cet utilisateur uniquement.

Lorsque l’utilisateur RUser1 exécute un script externe, la valeur de libPath peut contenir plusieurs chemins d’accès. Le premier est toujours le chemin de la bibliothèque partagée créée par le propriétaire de la base de données. La deuxième partie de libPath spécifie le chemin contenant les packages chargés individuellement par RUser1.

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.

Lorsque vous tentez d’accéder au fichier spécifié, <client_library_specifier>SQL Server emprunte l’identité du contexte de sécurité de la connexion Windows actuelle. Si <client_library_specifier> elle spécifie un emplacement réseau (chemin UNC), l’emprunt d’identité de la connexion actuelle n’est pas transféré vers l’emplacement réseau en raison des limitations de délégation. Dans ce cas, l’accès a lieu en utilisant le contexte de sécurité du compte de service SQL Server. Pour plus d’informations, consultez Informations d’identification (moteur de base de données).

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 devez créer une bibliothèque ou modifier une bibliothèque existante (et disposer des autorisations requises pour le faire), mais que le système de fichiers sur le serveur est restreint et que vous ne pouvez pas copier les fichiers de bibliothèque à un emplacement auquel le serveur peut accéder.

PLATE-FORME

Spécifie la plateforme pour le contenu de la bibliothèque. La valeur par défaut est la plateforme hôte sur laquelle SQL Server est en cours d’exécution. Par conséquent, l’utilisateur n’a pas à spécifier la valeur. Il est nécessaire dans le cas où plusieurs plateformes sont prises en charge, ou l’utilisateur doit spécifier une autre plateforme. Dans SQL Server 2019 (15.x), Windows et Linux sont les plateformes 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).

Notes

Pour la langue 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 d’un fichier ou .zip d’un .whl fichier doit être préparé sous la forme d’un fichier d’archive compressé. Si le package est déjà un .zip fichier, il doit être inclus dans un nouveau .zip fichier. Le chargement d’un package en tant que fichier ou .zip directement .whl n’est pas pris en charge actuellement.

L’instruction CREATE EXTERNAL LIBRARY charge les bits de la bibliothèque vers la base de données. La bibliothèque est installée quand un utilisateur exécute un script externe à l’aide de sp_execute_external_script et appelle le package ou la bibliothèque.

Les bibliothèques chargées vers l’instance peuvent être publiques ou privées. Si la bibliothèque est créée par un membre de dbo, elle est publique et peut être partagée avec tous les utilisateurs. Dans le cas contraire, la bibliothèque est privée pour cet utilisateur uniquement.

Plusieurs packages, appelés packages système, sont préinstallés dans une instance SQL. Vous ne pouvez pas ajouter, mettre à jour ou supprimer des packages système.

Autorisations

Nécessite l’autorisation CREATE EXTERNAL LIBRARY. Par défaut, les utilisateurs qui possèdent dbo, membre du rôle db_owner, disposent des autorisations nécessaires pour créer une bibliothèque externe. Pour tous les autres utilisateurs, vous devez lui accorder explicitement l’autorisation à l’aide d’une instruction GRANT , en spécifiant CREATE EXTERNAL LIBRARY comme privilège.

Dans SQL Server 2019 (15.x), en plus CREATE EXTERNAL LIBRARY de l’autorisation, l’utilisateur a également besoin d’une autorisation de référence sur un langage externe afin de créer des bibliothèques externes pour ce langage externe.

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

La modification de toute bibliothèque nécessite l’autorisation distincte ALTER ANY EXTERNAL LIBRARY.

Pour créer une bibliothèque externe à l’aide d’un chemin d’accès de fichier, l’utilisateur doit être une connexion authentifiée Windows ou un membre du rôle serveur fixe sysadmin .

Exemples

Ajouter une bibliothèque externe à une base de données

L’exemple suivant ajoute une bibliothèque externe nommée customPackage à une base de données.

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

Une fois la bibliothèque chargée sur l’instance, un utilisateur exécute la sp_execute_external_script procédure pour installer la bibliothèque.

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

Pour le langage Python dans SQL Server 2019 (15.x), l’exemple fonctionne également en remplaçant 'R''Python'par .

Installer des packages avec des dépendances

Si le package que vous souhaitez installer a des dépendances, il est essentiel d’analyser les dépendances de premier niveau et de deuxième niveau et de vérifier que tous les packages requis sont disponibles avant d’essayer d’installer le package cible.

Par exemple, supposez que vous souhaitez installer un nouveau package, packageA :

• packageA a une dépendance envers packageB.
• packageB a une dépendance envers packageC.

Pour que l’installation de packageA réussisse, vous devez créer des bibliothèques pour packageB et packageC en même temps que vous ajoutez packageA à SQL Server. Veillez à vérifier également les versions de package nécessaires.

Dans la pratique, les dépendances de package pour les packages populaires sont plus complexes que cet exemple. Par exemple, ggplot2 peut nécessiter plus de 30 packages, et ces packages peuvent nécessiter des packages supplémentaires qui ne sont pas disponibles sur le serveur. Tout package manquant ou dont la version est incorrecte peut provoquer l’échec de l’installation.

Étant donné qu’il peut être difficile de déterminer toutes les dépendances en examinant le manifeste du package, utilisez un package tel que miniCRAN pour identifier tous les packages requis pour terminer l’installation correctement.

• Chargez le package cible et ses dépendances. Tous les fichiers doivent se trouver dans un dossier accessible au serveur.

  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
  

• Installez d’abord les packages nécessaires.

  Si un package nécessaire a déjà été chargé vers l’instance, vous n’avez pas besoin de l’ajouter à nouveau. Vérifiez simplement si le package existant est la version correcte.

  Les packages nécessaires packageC et packageB sont installés dans l’ordre correct, quand sp_execute_external_script est exécuté pour la première fois afin d’installer le package packageA.

  Toutefois, si aucun package requis n’est disponible, l’installation du package packageA cible échoue.

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

Pour le langage Python dans SQL Server 2019 (15.x), l’exemple fonctionne également en remplaçant 'R''Python'par .

Créer une bibliothèque à partir d’un flux d’octets

Si vous n’avez pas la possibilité d’enregistrer les fichiers de package dans un emplacement sur le serveur, vous pouvez transmettre le contenu du package dans une variable. L’exemple suivant crée une bibliothèque en passant les bits sous forme de littéral hexadécimal.

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

Pour le langage Python dans SQL Server 2019 (15.x), l’exemple fonctionne également en remplaçant RPythonpar .

Notes

Cet exemple de code illustre uniquement la syntaxe ; la valeur binaire dans laquelle CONTENT = elle est tronquée pour la lisibilité et ne crée pas de bibliothèque de travail. Le contenu réel de la variable binaire est plus long.

Changer une bibliothèque de package existante

Vous pouvez utiliser l’instruction DDL ALTER EXTERNAL LIBRARY pour ajouter du nouveau contenu à la bibliothèque ou modifier le contenu existant de la bibliothèque. La modification d’une bibliothèque existante nécessite l’autorisation ALTER ANY EXTERNAL LIBRARY.

Pour plus d’informations, consultez ALTER EXTERNAL LIBRARY.

Ajouter un fichier .jar Java à une base de données

L’exemple suivant ajoute un fichier externe .jar appelé customJar à une base de données.

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

Une fois la bibliothèque chargée sur l’instance, un utilisateur exécute la sp_execute_external_script procédure pour installer la bibliothèque.

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)
);

Ajouter un package externe pour Windows et Linux

Vous pouvez spécifier jusqu’à deux <file_spec>, un pour Windows et l’autre pour 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');

Lorsque vous utilisez sp_execute_external_script pour installer le package, en fonction de la plateforme sur laquelle l’instance SQL Server s’exécute, le contenu de la bibliothèque pour cette plateforme est utilisé.

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

Contenu connexe

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