sp_execute_external_script (Transact-SQL)

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

Convenzioni relative alla sintassi Transact-SQL

sp_execute_external_script
    [ @language = ] N'language'
    , [ @script = ] N'script'
    [ , [ @input_data_1 = ] N'input_data_1' ]
    [ , [ @input_data_1_name = ] N'input_data_1_name' ]
    [ , [ @input_data_1_order_by_columns = ] N'input_data_1_order_by_columns' ]
    [ , [ @input_data_1_partition_by_columns = ] N'input_data_1_partition_by_columns' ]
    [ , [ @output_data_1_name = ] N'output_data_1_name' ]
    [ , [ @parallel = ] { 0 | 1 } ]
    [ , [ @params = ] N'@parameter_name data_type [ OUT | OUTPUT ] [ , ...n ]' ]
    [ , [ @parameter1 = ] 'value1' [ OUT | OUTPUT ] [ , ...n ] ]
[ ; ]

EXEC sp_execute_external_script
    @language = N'language'
    , @script = N'script'
    [ , [ @input_data_1 = ] N'input_data_1' ]
    [ , [ @input_data_1_name = ] N'input_data_1_name' ]
    [ , [ @output_data_1_name = ] N'output_data_1_name' ]
    [ , [ @parallel = ] { 0 | 1 } ]
    [ , [ @params = ] N'@parameter_name data_type [ OUT | OUTPUT ] [ , ...n ]' ]
    [ , [ @parameter1 = ] 'value1' [ OUT | OUTPUT ] [ , ...n ] ]

Argomenti

[ @language = ] N'language'

[ @script = ] N'script'

Script del linguaggio esterno specificato come input letterale o variabile. script è nvarchar(max).

[ @input_data_1 = ] N'input_data_1'

Specifica i dati di input usati dallo script esterno sotto forma di query Transact-SQL. Il tipo di dati di input_data_1 è nvarchar(max).

[ @input_data_1_name = ] N'input_data_1_name'

Specifica il nome della variabile utilizzata per rappresentare la query definita da @input_data_1. Il tipo di dati della variabile nello script esterno dipende dal linguaggio. Per R, la variabile di input è un frame di dati. Per Python, l'input deve essere tabulare. input_data_1_name è sysname. Il valore predefinito è InputDataSet.

[ @output_data_1_name = ] N'output_data_1_name'

Specifica il nome della variabile nello script esterno che contiene i dati da restituire a SQL Server al termine della chiamata alla stored procedure. Il tipo di dati della variabile nello script esterno dipende dal linguaggio. Per R, l'output deve essere un frame di dati. Per Python, l'output deve essere un frame di dati pandas. output_data_1_name è sysname. Il valore predefinito è OutputDataSet.

[ @parallel = ] { 0 | 1 }

Abilitare l'esecuzione parallela degli script R impostando il @parallel parametro su 1. Il valore predefinito per questo parametro è 0 (nessun parallelismo). Se @parallel = 1 e l'output viene trasmesso direttamente al computer client, la WITH RESULT SETS clausola è obbligatoria e deve essere specificato uno schema di output.

• Per gli script R che non usano le funzioni RevoScaleR, l'uso del @parallel parametro può essere utile per l'elaborazione di set di dati di grandi dimensioni, presupponendo che lo script possa essere facilmente parallelizzato. Ad esempio, quando si usa la funzione R predict con un modello per generare nuove stime, impostare @parallel = 1 come hint per il motore di query. Se la query può essere parallelizzata, le righe vengono distribuite in base all'impostazione MAXDOP .

• Per gli script R che usano le funzioni RevoScaleR, l'elaborazione parallela viene gestita automaticamente e non è consigliabile specificare @parallel = 1 per la sp_execute_external_script chiamata.

[ @params = ] N'@parameter_name data_type' [ OUT | OUTPUT ] [ , ... n ]

Elenco di dichiarazioni di parametri di input utilizzate nello script esterno.

[ @parameter1 = ] 'value1' [ OUT | OUTPUT ] [ , ... n ]

Elenco di valori per i parametri di input usati dallo script esterno.

Osservazioni:

Per impostazione predefinita, i set di risultati restituiti da questa stored procedure vengono restituiti con colonne senza nome. I nomi di colonna usati all'interno di uno script sono locali per l'ambiente di scripting e non si riflettono nel set di risultati restituito. Per assegnare un nome alle colonne del set di risultati, usare la WITH RESULT SET clausola EXECUTE.

Oltre a restituire un set di risultati, è possibile restituire valori scalari all'uso dei parametri OUTPUT.

Monitorare l'esecuzione di script

Monitorare l'esecuzione di script usando sys.dm_external_script_requests e sys.dm_external_script_execution_stats.

Esecuzione di streaming per script Python e R

Lo streaming consente di usare lo script Python o R con più dati di quanto possa essere inserito in memoria. Per controllare il numero di righe passate durante lo streaming, specificare un valore intero per il parametro , @r_rowsPerRead nella @params raccolta. Ad esempio, se si esegue il training di un modello che usa dati molto ampi, è possibile modificare il valore in modo da leggere meno righe, per assicurarsi che tutte le righe possano essere inviate in un unico blocco di dati. È anche possibile usare questo parametro per gestire il numero di righe in lettura ed elaborazione contemporaneamente, per attenuare i problemi di prestazioni del server.

Sia il parametro per lo @r_rowsPerRead streaming che l'argomento @parallel devono essere considerati hint. Per applicare l'hint, è necessario generare un piano di query SQL che include l'elaborazione parallela. Se non è possibile, l'elaborazione parallela non può essere abilitata.

Limiti

Tipo di dati

I tipi di dati seguenti non sono supportati quando vengono usati nella query di input o nei parametri della routine e restituiscono un errore di sp_execute_external_script tipo non supportato.

Come soluzione alternativa, CAST la colonna o il valore a un tipo supportato in Transact-SQL prima di inviarlo allo script esterno.

• cursor
• timestamp
• datetime2, datetimeoffset, time
• sql_variant
• text, image
• xml
• hierarchyid, geometry, geography
• Tipi CLR definiti dall'utente

In generale, qualsiasi set di risultati di cui non è possibile eseguire il mapping a un tipo di dati Transact-SQL viene restituito come NULL.

Restrizioni specifiche di R

Se l'input include valori datetime che non rientrano nell'intervallo consentito di valori in R, i valori vengono convertiti in NA. Questa operazione è necessaria perché l'apprendimento automatico di SQL consente un intervallo di valori superiore a quello supportato nel linguaggio R.

I valori float (ad esempio, +Inf, -Inf, ) NaNnon sono supportati in Machine Learning SQL anche se entrambi i linguaggi usano IEEE 754. Il comportamento corrente invia solo i valori direttamente a SQL; di conseguenza, il client SQL genera un errore. Di conseguenza, questi valori vengono convertiti in NULL.

Autorizzazioni

È richiesta l'autorizzazione EXECUTE ANY EXTERNAL SCRIPT per il database.

Esempi

Questa sezione contiene esempi di come questa stored procedure può essere usata per eseguire script R o Python usando Transact-SQL.

R. Restituire un set di dati R a SQL Server

Nell'esempio seguente viene creata una stored procedure che usa sp_execute_external_script per restituire il set di dati Iris incluso in R.

DROP PROCEDURE IF EXISTS get_iris_dataset;
GO
CREATE PROCEDURE get_iris_dataset
AS
BEGIN
    EXEC sp_execute_external_script @language = N'R',
        @script = N'iris_data <- iris;',
        @input_data_1 = N'',
        @output_data_1_name = N'iris_data'
    WITH RESULT SETS((
        "Sepal.Length" FLOAT NOT NULL,
        "Sepal.Width" FLOAT NOT NULL,
        "Petal.Length" FLOAT NOT NULL,
        "Petal.Width" FLOAT NOT NULL,
        "Species" VARCHAR(100)
    ));
END;
GO

B. Creare un modello Python e generare punteggi da esso

Questo esempio illustra come usare sp_execute_external_script per generare punteggi in un modello Python semplice.

CREATE PROCEDURE [dbo].[py_generate_customer_scores]
AS
BEGIN
    -- Input query to generate the customer data
    DECLARE @input_query NVARCHAR(MAX) = N'SELECT customer, orders, items, cost FROM dbo.Sales.Orders'

    EXEC sp_execute_external_script @language = N'Python',
        @script = N'
import pandas as pd
from sklearn.cluster import KMeans

# Get data from input query
customer_data = my_input_data

# Define the model
n_clusters = 4
est = KMeans(n_clusters=n_clusters, random_state=111).fit(customer_data[["orders","items","cost"]])
clusters = est.labels_
customer_data["cluster"] = clusters

OutputDataSet = customer_data
',
        @input_data_1 = @input_query,
        @input_data_1_name = N'my_input_data'
    WITH RESULT SETS((
        "CustomerID" INT,
        "Orders" FLOAT,
        "Items" FLOAT,
        "Cost" FLOAT,
        "ClusterResult" FLOAT
    ));
END;
GO

Le intestazioni di colonna usate nel codice Python non vengono restituite in SQL Server; utilizzare pertanto l'istruzione WITH RESULT per specificare i nomi di colonna e i tipi di dati da usare per SQL.

DROP PROCEDURE IF EXISTS generate_iris_model;
GO
CREATE PROCEDURE generate_iris_model
AS
BEGIN
    EXEC sp_execute_external_script @language = N'R',
        @script = N'
      library(e1071);
      irismodel <-naiveBayes(iris_data[,1:4], iris_data[,5]);
      trained_model <- data.frame(payload = as.raw(serialize(irismodel, connection=NULL)));
',
        @input_data_1 = N'select "Sepal.Length", "Sepal.Width", "Petal.Length", "Petal.Width", "Species" from iris_data',
        @input_data_1_name = N'iris_data',
        @output_data_1_name = N'trained_model'
    WITH RESULT SETS((model VARBINARY(MAX)));
END;
GO

Per il punteggio, è anche possibile usare la funzione nativa PREDICT, che è in genere più veloce, perché consente di evitare la chiamata al runtime di Python o R.

Contenuto correlato

• Machine Learning SQL
• Cosa sono le estensioni del linguaggio di SQL Server?
• Stored procedure di sistema (Transact-SQL)
• CREATE EXTERNAL LIBRARY (Transact-SQL)
• sp_prepare (Transact SQL)
• sp_configure (Transact-SQL)
• Opzione di configurazione del server external scripts enabled
• SERVERPROPERTY (Transact-SQL)
• SQL Server, oggetto External Scripts
• sys.dm_external_script_requests
• sys.dm_external_script_execution_stats