CREATE EXTERNAL LIBRARY (Transact-SQL)

Lädt R-, Python- oder Java-Paketdateien vom angegebenen Bytedatenstrom oder Dateipfad in eine Datenbank hoch. Diese Anweisung dient als generischer Mechanismus, mithilfe dessen der Datenbankadministrator Artefakte hochladen kann, die von Runtimes neuer externer Sprachen und Betriebssystemplattformen benötigt werden, die von SQL Server unterstützt werden.

Lädt R- oder Python-Paketdateien vom angegebenen Bytedatenstrom oder Dateipfad in eine Datenbank hoch. Diese Anweisung dient als generischer Mechanismus für den Datenbankadministrator zum Hochladen von benötigten Artefakten.

Syntax für 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>
}

Syntax für 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 
}

Syntax für Azure SQL Managed Instance

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

file_spec

Gibt den Inhalt des Pakets für eine bestimmte Plattform an. Nur ein Dateiartefakt pro Plattform wird unterstützt.

Die Datei kann in Form eines lokalen Pfads oder eines Netzwerkpfads angegeben werden.

Bei dem Versuch, auf die in <client_library_specifier> angegebene Datei zuzugreifen, nimmt SQL Server den Sicherheitskontext der aktuellen Windows-Anmeldung an. Falls <client_library_specifier> einen Netzwerkspeicherort (UNC-Pfad) angibt, wird der Identitätswechsel der aktuellen Anmeldung aufgrund von Delegierungsbeschränkungen nicht auf den neuen Netzwerkspeicherort übertragen. In diesem Fall erfolgt der Zugriff mithilfe des Sicherheitskontexts des SQL Server-Dienstkontos. Weitere Informationen finden Sie unter Anmeldeinformationen (Datenbank-Engine).

Optional kann eine Betriebssystemplattform für die Datei angegeben werden. Für jede Betriebssystemplattform für eine bestimmte Sprache oder Runtime ist nur jeweils ein Darteiartefakt oder Inhalt erlaubt.

PLATFORM

Gibt die Plattform für den Inhalt der Bibliothek an. Der Standardwert ist die Hostplattform, auf der SQL Server ausgeführt wird. Aus diesem Grund muss der Benutzer den Wert nicht angeben. Dies ist in Fällen erforderlich, in denen mehrere Plattformen unterstützt werden oder in denen der Benutzer eine andere Plattform angeben muss. Für SQL Server 2019 werden die Plattformen Windows und Linux unterstützt.

LANGUAGE = 'R'

gibt die Sprache des Pakets an. R wird in SQL Server 2017 unterstützt.

language

gibt die Sprache des Pakets an. Der Wert kann R oder Python in Azure SQL Managed Instance sein.

language

gibt die Sprache des Pakets an. Der Wert kann R, Python oder der Name einer externen Programmiersprache sein (siehe CREATE EXTERNAL LANGUAGE).

Bei der R-Sprache müssen bei Verwendung einer Datei Pakete in Form von gezippten Archivdateien mit der Dateiendung .ZIP für Windows vorbereitet werden. Für SQL Server 2017 wird nur die Windows-Plattform unterstützt.

Bei der R-Sprache müssen bei Verwendung einer Datei Pakete in Form von gezippten Archivdateien mit der Erweiterung „.ZIP“ vorbereitet werden.

Für Python muss das Paket in einer WHL- oder ZIP-Datei als ZIP-Archivdatei vorbereitet werden. Wenn das Paket bereits eine ZIP-Datei ist, muss es in eine neue ZIP-Datei eingefügt werden. Der direkte Upload einer WHL- oder ZIP-Datei wird derzeit nicht unterstützt.

In SQL Server 2019 benötigt der Benutzer zusätzlich zur Berechtigung CREATE EXTERNAL LIBRARY auch die REFERENCES-Berechtigung für eine externe Sprache, um externe Bibliotheken für diese externe Sprache zu erstellen.

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

Hinzufügen einer externen Bibliothek zu einer Datenbank

Im folgenden Beispiel wird eine externe Bibliothek namens customPackage zu einer Datenbank hinzugefügt.

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

Nachdem die Bibliothek erfolgreich in die Instanz hochgeladen wurde, führt ein Benutzer den Vorgang sp_execute_external_script aus, um die Bibliothek zu installieren.

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

Das Beispiel funktioniert auch für Python in SQL Server 2019, wenn Sie 'R' durch 'Python' ersetzen.

• Laden Sie das Zielpaket und dessen Abhängigkeiten hoch. Alle Dateien müssen sich in einem Ordner befinden, auf den der Server Zugriff hat.

  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
  

• Installieren Sie zunächst die erforderlichen Pakete.

  Wenn ein erforderliches Paket bereits in die Instanz hochgeladen wurde, müssen Sie dieses nicht erneut hinzufügen. Achten Sie nur darauf, zu überprüfen, ob es sich bei der Version des vorhandenen Pakets um die richtige handelt.

  Die erforderlichen Pakete packageC und packageB werden beim ersten Ausführen von sp_execute_external_script zur Installation des Pakets packageA in der richtigen Reihenfolge installiert.

  Wenn ein erforderliches Paket jedoch nicht verfügbar ist, tritt ein Fehler bei der Installation des Zielpakets packageA auf.

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

Das Beispiel funktioniert auch für Python in SQL Server 2019, wenn Sie 'R' durch 'Python' ersetzen.

Das Beispiel funktioniert auch für Python in SQL Server 2019, wenn Sie 'R' durch 'Python' ersetzen.

Hinzufügen einer JAR-Datei zu einer Datenbank

Im folgenden Beispiel wird eine externe JAR-Datei namens customJar zu einer Datenbank hinzugefügt.

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

Nachdem die Bibliothek erfolgreich in die Instanz hochgeladen wurde, führt ein Benutzer den Vorgang sp_execute_external_script aus, um die Bibliothek zu installieren.

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

Hinzufügen eines externen Pakets für Windows und Linux

Sie können <file_spec> maximal zweimal angeben, einmal für Windows und einmal für 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')

Wenn Sie sp_execute_external_script zum Installieren des Pakets verwenden, wird der Bibliotheksinhalt je nach Plattform verwendet, auf der die SQL Server-Instanz ausgeführt wird.

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