CREATE EXTERNAL LIBRARY (Transact-SQL)

Gilt für: SQL Server 2017 (14.x) und höher Azure SQL Managed Instance

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.

Hinweis

In SQL Server 2017 werden die R-Sprache und die Windows-Plattform unterstützt. Ab SQL Server 2019 werden R, Python und externe Programmiersprachen auf Windows- und Linux-Plattformen unterstützt.

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

Argumente

library_name

Bibliotheken, die in die Instanz hochgeladen werden, können entweder öffentlich oder privat sein. Wenn die Bibliothek von einem Mitglied von dbo erstellt wird, ist sie öffentlich und kann mit allen Benutzern geteilt werden. Andernfalls ist die Bibliothek für diesen Benutzer privat.

Bibliotheksnamen müssen innerhalb des Kontexts eines bestimmten Benutzers oder Besitzers eindeutig sein. Beispielsweise können zwei Benutzer, RUser1 und RUser2, die R-Bibliothek ggplot2 individuell und separat hochladen. Wenn jedoch RUser1 eine neuere Version von ggplot2 hochladen möchte, muss die zweite Instanz anders benannt werden oder die vorhandene Bibliothek ersetzen.

Bibliotheksnamen können nicht beliebig zugewiesen werden. Der Bibliotheksname sollte mit dem Namen übereinstimmen, der benötigt wird, um die Bibliothek im externen Skript zu laden.

owner_name

Gibt den Namen eines Benutzers oder einer Rolle an, der oder die die externe Bibliothek besitzt. Wird kein Wert angegeben, wird der aktuelle Benutzer zum Besitzer.

Bibliotheken, die Datenbankbesitzern gehören, gelten als global für die Datenbank und Runtime. Sprich, Datenbankbesitzer können Bibliotheken erstellen, die eine gemeinsame Menge von Bibliotheken oder Paketen enthalten, die von vielen Benutzern geteilt werden. Wenn eine externe Bibliothek von einem anderen Benutzer als dem dbo-Benutzer erstellt wurde, ist die externe Bibliothek nur für diesen Benutzer privat.

Wenn der Benutzer RUser1 ein externes Skript ausführt, kann der Wert von libPath mehrere Pfade enthalten. Der erste Pfad ist immer der Pfad zur gemeinsamen Bibliothek, die vom Datenbankbesitzer erstellt wurde. Der zweite Teil von libPath gibt den Pfad an, der Pakete enthält, die von RUser1 individuell hochgeladen wurden.

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.

library_bits

Gibt ähnlich wie bei Assemblys den Inhalt des Pakets als Hexadezimalliteral an.

Diese Option ist hilfreich, wenn Sie eine Bibliothek erstellen oder eine bestehende Bibliothek ändern müssen (und über die erforderlichen Berechtigungen dafür verfügen), das Dateisystem auf dem Server jedoch eingeschränkt ist und die Bibliotheksdateien nicht an einen Speicherort kopieren kann, auf den der Server Zugriff hat.

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

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

Bemerkungen

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.

Die CREATE EXTERNAL LIBRARY-Anweisung lädt die Bibliothekbits in die Datenbank hoch. Die Bibliothek wird installiert, wenn ein Benutzer mithilfe von sp_execute_external_script ein externes Skript ausführt und das Paket oder die Bibliothek aufruft.

Bibliotheken, die in die Instanz hochgeladen werden, können entweder öffentlich oder privat sein. Wenn die Bibliothek von einem Mitglied von dbo erstellt wird, ist sie öffentlich und kann mit allen Benutzern geteilt werden. Andernfalls ist die Bibliothek für diesen Benutzer privat.

In einer SQL-Instanz sind einige Pakete vorinstalliert. Diese werden als Systempakete bezeichnet. Systempakete können vom Benutzer weder hinzugefügt noch aktualisiert oder entfernt werden.

Berechtigungen

Erfordert die CREATE EXTERNAL LIBRARY-Berechtigung. Standardmäßig verfügt jeder Benutzer mit dbo, der Mitglied der Rolle db_owner ist, über die Berechtigung zum Erstellen einer externen Bibliothek. Allen anderen Benutzern müssen Sie die Berechtigung mithilfe einer GRANT-Anweisung explizit gewähren, in der Sie CREATE EXTERNAL LIBRARY als Berechtigung angeben.

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

Zum Bearbeiten einer Bibliothek ist die separate Berechtigung ALTER ANY EXTERNAL LIBRARY erforderlich.

Zum Erstellen einer externen Bibliothek mithilfe eines Dateipfads muss der Benutzer über eine authentifizierte Anmeldung verfügen oder Mitglied der festen sysadmin-Serverrolle sein.

Beispiele

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.

Installieren von Paketen mit Abhängigkeiten

Wenn das Paket, das Sie installieren möchten, Abhängigkeiten aufweist, ist es sehr wichtig, dass Sie sowohl Abhängigkeiten der ersten als auch der zweiten Ebene analysieren und sicherstellen, dass alle erforderlichen Pakete verfügbar sind, bevor Sie versuchen, das Zielpaket zu installieren.

Nehmen wir beispielsweise an, dass Sie ein neues Paket, packageA, installieren möchten:

• packageA ist abhängig von packageB.
• packageB ist abhängig von packageC.

Damit die Installation von packageA erfolgreich ist, müssen Sie Bibliotheken für packageB und packageC zur selben Zeit erstellen, zu der Sie packageA zu SQL Server hinzufügen. Achten Sie darauf, dass Sie auch die erforderlichen Paketversionen überprüfen.

In der Praxis sind Paketabhängigkeiten für häufig verwendete Pakete in der Regel viel komplizierter als in diesem einfachen Beispiel. Beispielsweise könnte ggplot2 mehr als 30 Pakete erfordern, und diese Pakete könnten wiederum zusätzliche Pakete erfordern, die auf dem Server nicht verfügbar sind. Jedes fehlende Paket und jede falsche Paketversion kann zu einem Fehler bei der Installation führen.

Da es schwierig sein kann, alle Abhängigkeiten nur durch Betrachten des Paketmanifests zu bestimmen, empfiehlt sich die Verwendung eines Pakets wie miniCRAN, um alle Pakete zu identifizieren, die für eine erfolgreiche Installation erforderlich sein könnten.

• 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.

Erstellen einer Bibliothek aus einem Bytedatenstrom

Wenn Sie nicht die Möglichkeit haben, die Paketdateien in einem Speicherort auf dem Server zu speichern, können Sie die Paketinhalte in einer Variable übergeben. Im folgenden Beispiel wird eine Bibliothek erstellt, indem die Bits als Hexadezimalliteral übergeben werden.

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

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

Hinweis

Dieses Codebeispiel zeigt nur die Syntax; der Binärwert in CONTENT = wurde zur besseren Lesbarkeit gekürzt und erstellt keine funktionierende Bibliothek. Der tatsächliche Inhalt der binären Variable wäre wesentlich länger.

Löschen einer vorhandenen Paketbibliothek

Die ALTER EXTERNAL LIBRARY-DDL-Anweisung kann verwendet werden, um neuen Bibliotheksinhalt hinzuzufügen oder bestehenden Bibliotheksinhalt zu ändern. Zum Bearbeiten einer bestehenden Bibliothek ist die Berechtigung ALTER ANY EXTERNAL LIBRARY erforderlich.

Weitere Informationen finden Sie unter ALTER EXTERNAL LIBRARY.

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

Weitere Informationen

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