sp_execute_external_script (Transact-SQL)

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

Transact-SQL-Syntaxkonventionen

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

Argumente

[ @language = ] N'language'

[ @script = ] N'script'

Externes Sprachskript, das als Literal- oder Variableneingabe angegeben ist. script is nvarchar(max).

[ @input_data_1 = ] N'input_data_1'

Gibt die Eingabedaten an, die vom externen Skript in Form einer Transact-SQL-Abfrage verwendet werden. Der Datentyp von input_data_1 ist nvarchar(max).

[ @input_data_1_name = ] N'input_data_1_name'

Gibt den Namen der Variablen an, die verwendet wird, um die von @input_data_1. Der Datentyp der Variablen im externen Skript hängt von der Sprache ab. Bei R ist die Eingabevariable ein Datenrahmen. Bei Python muss die Eingabe tabellarisch sein. input_data_1_name ist "sysname". Der Standardwert ist InputDataSet.

[ @output_data_1_name = ] N'output_data_1_name'

Gibt den Namen der Variablen im externen Skript an, die die Daten enthält, die nach Abschluss des Aufrufs der gespeicherten Prozedur an SQL Server zurückgegeben werden sollen. Der Datentyp der Variablen im externen Skript hängt von der Sprache ab. Für R muss die Ausgabe ein Datenrahmen sein. Für Python muss die Ausgabe ein Pandas-Datenframe sein. output_data_1_name ist "sysname". Der Standardwert ist OutputDataSet.

[ @parallel = ] { 0 | 1 }

Aktivieren Sie die parallele Ausführung von R-Skripts, indem Sie den @parallel Parameter auf 1. Der Standardwert für diesen Parameter ist 0 (kein Parallelismus). Wenn @parallel = 1 und die Ausgabe direkt an den Clientcomputer gestreamt wird, ist die WITH RESULT SETS Klausel erforderlich und ein Ausgabeschema muss angegeben werden.

• Für R-Skripts, die keine RevoScaleR-Funktionen verwenden, kann die Verwendung des Parameters für die @parallel Verarbeitung großer Datasets von Vorteil sein, vorausgesetzt, das Skript kann trivial parallelisiert werden. Wenn Sie z. B. die R-Funktion predict mit einem Modell verwenden, um neue Vorhersagen zu generieren, legen Sie @parallel = 1 diesen als Hinweis auf das Abfragemodul fest. Wenn die Abfrage parallelisiert werden kann, werden Zeilen gemäß der MAXDOP-Einstellung verteilt.

• Für R-Skripts, die RevoScaleR-Funktionen verwenden, wird die parallele Verarbeitung automatisch behandelt, und Sie sollten den sp_execute_external_script Aufruf nicht angeben@parallel = 1.

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

Eine Liste der Eingabeparameterdeklarationen, die im externen Skript verwendet werden.

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

Eine Liste der Werte für die Eingabeparameter, die vom externen Skript verwendet werden.

Hinweise

Standardmäßig werden von dieser gespeicherten Prozedur zurückgegebene Resultsets mit nicht benannten Spalten ausgegeben. Spaltennamen, die in einem Skript verwendet werden, sind lokal in der Skriptumgebung und werden nicht im ausgegebenen Resultset widergespiegelt. Verwenden Sie die WITH RESULT SET Execute-Klausel, um Ergebnissatzspalten zu benennen.

Zusätzlich zum Zurückgeben eines Resultsets können Sie skalare Werte mithilfe von OUTPUT-Parametern zurückgeben.

Überwachen der Skriptausführung

Überwachen Sie die Skriptausführung mithilfe von sys.dm_external_script_requests und sys.dm_external_script_execution_stats.

Streamingausführung für Python- und R-Skripts

Streaming ermöglicht es dem Python- oder R-Skript, mit mehr Daten zu arbeiten, als in den Arbeitsspeicher passen können. Um die Anzahl der zeilen zu steuern, die während des Streamings übergeben werden, geben Sie einen ganzzahligen Wert für den Parameter @r_rowsPerRead in der @params Auflistung an. Wenn Sie beispielsweise ein Modell trainieren, das sehr breite Daten verwendet, können Sie den Wert so anpassen, dass weniger Zeilen gelesen werden, um sicherzustellen, dass alle Zeilen in einem Datenabschnitt gesendet werden können. Sie können diesen Parameter auch verwenden, um die Anzahl der gleichzeitig gelesenen und verarbeiteten Zeilen zu verwalten, um Serverleistungsprobleme zu vermeiden.

Sowohl der @r_rowsPerRead Parameter für Streaming als auch das @parallel Argument sollten als Hinweise betrachtet werden. Damit der Hinweis angewendet werden kann, muss es möglich sein, einen SQL-Abfrageplan zu generieren, der die parallele Verarbeitung umfasst. Wenn dies nicht möglich ist, kann die parallele Verarbeitung nicht aktiviert werden.

Begrenzungen

Datentypen

Die folgenden Datentypen werden nicht unterstützt, wenn sie in der Eingabeabfrage oder den Parametern der sp_execute_external_script Prozedur verwendet werden, und es wird ein Fehler vom Typ "Nicht unterstützt" zurückgegeben.

Als Problemumgehung wird CAST die Spalte oder der Wert an einen unterstützten Typ in Transact-SQL gesendet, bevor sie an das externe Skript gesendet wird.

• Cursor
• timestamp
• datetime2, datetimeoffset, time
• sql_variant
• Text, Bild
• xml
• hierarchyid, geometry, geography
• Benutzerdefinierte CLR-Typen

Im Allgemeinen wird jedes Resultset, das keinem Transact-SQL-Datentyp zugeordnet werden kann, ausgegeben als NULL.

Spezifische Einschränkungen für R

Wenn die Eingabe Datum-/Uhrzeitwerte enthält, die nicht dem zulässigen Wertebereich in R entsprechen, werden die Werte in "R" konvertiertNA. Dies ist erforderlich, da SQL Machine Learning einen größeren Wertebereich zulässt, als in der Sprache R unterstützt wird.

Float-Werte (z. B+Inf. , , -InfNaN) werden in SQL Machine Learning nicht unterstützt, obwohl beide Sprachen IEEE 754 verwenden. Aktuelles Verhalten sendet nur die Werte direkt an SQL; Daher löst der SQL-Client einen Fehler aus. Daher werden diese Werte in NULL.

Berechtigungen

Erfordert EXECUTE ANY EXTERNAL SCRIPT database permission.

Beispiele

Dieser Abschnitt enthält Beispiele dafür, wie diese gespeicherte Prozedur zum Ausführen von R- oder Python-Skripts mit Transact-SQL verwendet werden kann.

A. Zurückgeben eines R-Datasets an SQL Server

Im folgenden Beispiel wird eine gespeicherte Prozedur erstellt, die verwendet wird, sp_execute_external_script um das Iris-Dataset zurückzugeben, das in R enthalten ist.

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. Erstellen eines Python-Modells und Generieren von Bewertungen daraus

In diesem Beispiel wird veranschaulicht, wie sp_execute_external_script Sie Bewertungen für ein einfaches Python-Modell generieren.

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

Spaltenüberschriften, die im Python-Code verwendet werden, werden nicht in SQL Server ausgegeben. Verwenden Sie daher die WITH RESULT-Anweisung, um die Zu verwendenden Spaltennamen und Datentypen für SQL anzugeben.

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

Zur Bewertung können Sie auch die native PREDICT-Funktion verwenden, die in der Regel schneller ist, weil sie die Python- bzw. R-Laufzeit nicht aufrufen muss.

Zugehöriger Inhalt

• SQL Machine Learning
• Was sind SQL Server-Spracherweiterungen?
• Gespeicherte Systemprozeduren (Transact-SQL)
• CREATE EXTERNAL LIBRARY (Transact-SQL)
• sp_prepare (Transact SQL)
• sp_configure (Transact-SQL)
• Externe Skripts aktiviert (Serverkonfigurationsoption)
• SERVERPROPERTY (Transact-SQL)
• SQL Server-Objekt, Externe Skripts
• sys.dm_external_script_requests
• sys.dm_external_script_execution_stats