CREATE EXTERNAL LIBRARY (Transact-SQL)

Si applica a: SQL Server 2017 (14.x) e versioni successive Istanza gestita di SQL di Azure

Carica file di pacchetti R, Python o Java in un database dal flusso di byte o dal percorso di file specificato. Questa istruzione funge da meccanismo generico per l'amministratore del database per il caricamento degli artefatti necessari per i nuovi runtime dei linguaggi esterni e per le piattaforme del sistema operativo che SQL Server supporta.

Nota

In SQL Server 2017 sono supportati il linguaggio R e la piattaforma Windows. In SQL Server 2019 e versioni successive sono supportati R, Python e linguaggi esterni nelle piattaforme Windows e Linux.

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

Argomenti

library_name

Le librerie caricate nell'istanza possono essere pubbliche o private. Se la libreria viene creata da un membro di dbo, la libreria è pubblica e può essere condivisa da tutti gli utenti. In caso contrario, la libreria è privata e disponibile solo per tale utente.

I nomi delle librerie devono essere univoci nel contesto di un utente o proprietario specifico. I due utenti RUser1 e RUser2, ad esempio, possono entrambi caricare la libreria R ggplot2 individualmente e separatamente. Tuttavia, se RUser1 vuole caricare una versione più recente di ggplot2, la seconda istanza deve essere denominata in modo diverso o deve sostituire la libreria esistente.

I nomi delle librerie non possono essere assegnati in modo arbitrario. Il nome di una libreria deve corrispondere al nome necessario per caricare la libreria nello script esterno.

owner_name

Specifica il nome dell'utente o del ruolo che è proprietario della libreria esterna. Se viene omesso, la proprietà viene assegnata all'utente corrente.

Le librerie di proprietà del proprietario del database sono considerate globali per il database e il runtime. In altre parole, i proprietari di database possono creare librerie contenenti un set comune di librerie o pacchetti condiviso da molti utenti. Quando viene creata una libreria esterna da un utente diverso dall'utente dbo, la libreria esterna è privata e disponibile solo per tale utente.

Quando l'utente RUser1 esegue uno script esterno, il valore di libPath può contenere più percorsi. Il primo percorso è sempre il percorso della libreria condivisa creata dal proprietario del database. La seconda parte di libPath specifica il percorso che contiene i pacchetti caricati individualmente da RUser1.

file_spec

Specifica il contenuto del pacchetto per una piattaforma specifica. È supportato soltanto un elemento di tipo file per piattaforma.

Il file può essere specificato usando il percorso locale o il percorso di rete.

Quando si prova ad accedere al file specificato in <client_library_specifier>, SQL Server rappresenta il contesto di sicurezza dell'account di accesso di Windows corrente. Se <client_library_specifier> specifica un percorso di rete (percorso UNC), la rappresentazione dell'account di accesso corrente non viene riportata nel percorso di rete a causa dei limiti di delega. In questo caso, l'accesso viene eseguito tramite il contesto di sicurezza dell'account del servizio SQL Server. Per altre informazioni, vedere Credenziali (motore di database).

Facoltativamente, è possibile specificare una piattaforma del sistema operativo per il file. È consentito un solo elemento di tipo file o un contenuto per piattaforma del sistema operativo per un linguaggio o un runtime specifico.

library_bits

Specifica il contenuto del pacchetto come valore letterale esadecimale, analogamente agli assembly.

Questa opzione è utile se è necessario creare una libreria o modificare una libreria esistente (e si hanno le autorizzazioni necessarie a tale scopo), ma il file system del server è soggetto a restrizioni e non è possibile copiare i file di libreria in un percorso a cui il server può accedere.

PIATTAFORMA

Specifica la piattaforma per il contenuto della libreria. Il valore predefinito corrisponde alla piattaforma host in cui è in esecuzione SQL Server. Per l'utente, quindi, non è necessario specificare questo valore. È necessario nel caso in cui siano supportate più piattaforme o l'utente debba specificare una piattaforma diversa. In SQL Server 2019 Windows e Linux sono le piattaforme supportate.

language

Specifica il linguaggio del pacchetto. Il valore può essere R, Python o il nome di un linguaggio esterno (vedere CREATE EXTERNAL LANGUAGE).

Osservazioni:

Per il linguaggio R, quando si usa un file è necessario preparare i pacchetti sotto forma di file di archivio compressi usando l'estensione zip.

Per il linguaggio Python, è necessario preparare il pacchetto in un file WHL o ZIP sotto forma di file di archivio compresso. Se il pacchetto è già un file ZIP, deve essere incluso in un nuovo file ZIP. Il caricamento di un pacchetto direttamente come file WHL o ZIP attualmente non è supportato.

L'istruzione CREATE EXTERNAL LIBRARY carica i bit della libreria nel database. La libreria viene installata quando un utente esegue uno script esterno tramite sp_execute_external_script e chiama il pacchetto o la libreria.

Le librerie caricate nell'istanza possono essere pubbliche o private. Se la libreria viene creata da un membro di dbo, la libreria è pubblica e può essere condivisa da tutti gli utenti. In caso contrario, la libreria è privata e disponibile solo per tale utente.

Una serie di pacchetti, detti pacchetti di sistema, sono preinstallati in un'istanza di SQL. L'utente non può aggiungere, aggiornare o rimuovere i pacchetti di sistema.

Autorizzazioni

È necessaria l'autorizzazione CREATE EXTERNAL LIBRARY. Per impostazione predefinita, ogni utente con dbo che è membro del ruolo db_owner ha le autorizzazioni per creare una libreria esterna. Per tutti gli altri utenti, è necessario concedere in modo esplicito le autorizzazioni usando un'istruzione GRANT specificando CREATE EXTERNAL LIBRARY come privilegio.

In SQL Server 2019, oltre all'autorizzazione "CREATE EXTERNAL LIBRARY", l'utente deve anche avere l'autorizzazione REFERENCES su un linguaggio esterno per poter creare librerie esterne per il linguaggio esterno.

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

Per modificare qualsiasi libreria è inoltre necessaria l'autorizzazione ALTER ANY EXTERNAL LIBRARY.

Per creare una libreria esterna usando un percorso di file, l'utente corrente deve avere un account di accesso autenticato in Windows o essere un membro del ruolo predefinito del server sysadmin.

Esempi

Aggiungere una libreria esterna a un database

L'esempio seguente aggiunge una libreria esterna denominata customPackage a un database.

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

Dopo il caricamento della libreria nell'istanza, l'utente esegue la procedura sp_execute_external_script per installare la libreria.

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

Per il linguaggio Python in SQL Server 2019, l'esempio funziona anche sostituendo 'R' con 'Python'.

Installare pacchetti con dipendenze

Se il pacchetto che si vuole installare presenta dipendenze, è fondamentale analizzare le dipendenze sia di primo che di secondo livello e assicurarsi che tutti i pacchetti necessari siano disponibili prima di tentare l'installazione del pacchetto di destinazione.

Si supponga ad esempio di voler installare un nuovo pacchetto, packageA:

• packageA ha una dipendenza da packageB
• packageB ha una dipendenza da packageC

Perché l'installazione di packageA sia possibile, è necessario creare librerie per packageB e packageC contemporaneamente all'aggiunta di packageA a SQL Server. Assicurarsi di controllare anche le versioni dei pacchetti richiesti.

In pratica, le dipendenze dei pacchetti dai pacchetti più diffusi sono in genere molto più complesse rispetto a questo semplice esempio. Ad esempio, ggplot2 può richiedere oltre 30 pacchetti e questi ultimi possono richiedere pacchetti aggiuntivi non disponibili nel server. La mancanza o una versione non corretta di uno qualsiasi di questi pacchetti può causare la mancata riuscita dell'installazione.

Poiché può essere difficile determinare tutte le dipendenze semplicemente esaminando il manifesto del pacchetto, è consigliabile usare un pacchetto come miniCRAN per identificare tutti i pacchetti che possono essere necessari per eseguire l'installazione.

• Caricare il pacchetto di destinazione e le sue dipendenze. Tutti i file devono essere in una cartella accessibile al server.

  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
  

• Installare per primi i pacchetti richiesti.

  Se un pacchetto richiesto è già stato caricato nell'istanza, non è necessario aggiungerlo nuovamente. È sufficiente assicurarsi che la versione del pacchetto esistente sia corretta.

  I pacchetti richiesti packageC e packageB vengono installati, nell'ordine corretto, quando sp_execute_external_script viene eseguita per la prima volta per installare il pacchetto packageA.

  Se tuttavia un qualsiasi pacchetto richiesto non è disponibile, l'installazione del pacchetto di destinazione packageA non riesce.

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

Per il linguaggio Python in SQL Server 2019, l'esempio funziona anche sostituendo 'R' con 'Python'.

Creare una libreria da un flusso di byte

Se non si ha la possibilità di salvare i file del pacchetto in un percorso nel server, è possibile passare il contenuto del pacchetto in una variabile. L'esempio seguente crea una libreria passando i bit come valore letterale esadecimale.

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

Per il linguaggio Python SQL Server 2019, l'esempio funziona anche sostituendo R con Python.

Nota

Questo esempio di codice illustra solo la sintassi. Il valore binario in CONTENT = è stato troncato per migliorare la leggibilità e non crea una libreria di lavoro. Il contenuto effettivo della variabile binaria sarebbe molto più lungo.

Modificare una libreria di pacchetti esistente

È possibile usare l'istruzione DDL ALTER EXTERNAL LIBRARY per aggiungere nuovo contenuto a una libreria o modificare il contenuto esistente della libreria stessa. Per modificare una libreria esistente è necessaria l'autorizzazione ALTER ANY EXTERNAL LIBRARY.

Per altre informazioni, vedere ALTER EXTERNAL LIBRARY.

Aggiungere un file JAR Java a un database

L'esempio seguente aggiunge un file JAR esterno denominato customJar a un database.

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

Dopo il caricamento della libreria nell'istanza, l'utente esegue la procedura sp_execute_external_script per installare la libreria.

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

Aggiungere un pacchetto esterno per Windows e Linux

È possibile specificare fino a due <file_spec>, uno per Windows e uno per 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')

Quando si usa sp_execute_external_script per installare il pacchetto, a seconda della piattaforma in cui è in esecuzione l'istanza di SQL Server verrà usato il contenuto della libreria per quella piattaforma.

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

Vedi anche

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