sp_execute_external_script (Transact-SQL)

platí pro: SQL Server 2016 (13.x) a novější azure SQL Managed Instance

Uložená procedura sp_execute_external_script spustí skript zadaný jako vstupní argument procedury a používá se s Machine Learning Services a language Extensions.

Pro Machine Learning Services jsou podporované jazyky pythonu Pythonu a R. U jazykových rozšíření je jazyk Java podporován, ale musí být definován pomocí CREATE EXTERNAL LANGUAGE.

Pokud chcete spustit sp_execute_external_script, musíte nejprve nainstalovat službu Machine Learning Services nebo rozšíření jazyka. Další informace najdete v tématu Instalace sql Server Machine Learning Services (Python a R) ve Windows a Linuxnebo Instalace sql Server Language Extensions ve Windows a Linux.

Transact-SQL konvence syntaxe

Syntax

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

Argumenty

[ @language = ] Jazyk N''

Označuje jazyk skriptu. jazyk jesysname . Platné hodnoty jsou R, Pythona libovolný jazyk definovaný pomocí CREATE EXTERNAL LANGUAGE (například Java).

[ @script = ] N'skript'

Skript externího jazyka zadaný jako vstup literálu nebo proměnné skript je nvarchar(max).

[ @input_data_1 = ] N'input_data_1'

Určuje vstupní data používaná externím skriptem ve formě dotazu Transact-SQL. Datový typ input_data_1 je nvarchar(max).

[ @input_data_1_name = ] N'input_data_1_name'

Určuje název proměnné použité k reprezentaci dotazu definovaného @input_data_1. Datový typ proměnné v externím skriptu závisí na jazyce. Pro R je vstupní proměnná datový rámec. V případě Pythonu musí být vstup tabulkový. input_data_1_name je sysname . Výchozí hodnota je InputDataSet.

[ @input_data_1_order_by_columns = ] N'input_data_1_order_by_columns'

Používá se k vytváření modelů pro jednotlivé oddíly. Určuje název sloupce použitého k seřazení sady výsledků, například podle názvu produktu. Datový typ proměnné v externím skriptu závisí na jazyce. Pro R je vstupní proměnná datový rámec. V případě Pythonu musí být vstup tabulkový.

[ @input_data_1_partition_by_columns = ] N'input_data_1_partition_by_columns'

Používá se k vytváření modelů pro jednotlivé oddíly. Určuje název sloupce použitého k segmentování dat, jako je geografická oblast nebo datum. Datový typ proměnné v externím skriptu závisí na jazyce. Pro R je vstupní proměnná datový rámec. V případě Pythonu musí být vstup tabulkový.

[ @output_data_1_name = ] N'output_data_1_name'

Určuje název proměnné v externím skriptu, který obsahuje data, která se mají vrátit do SQL Serveru po dokončení volání uložené procedury. Datový typ proměnné v externím skriptu závisí na jazyce. Výstupem jazyka R musí být datový rámec. Pro Python musí být výstup datový rámec pandas. output_data_1_name je sysname . Výchozí hodnota je outputDataSet.

[ @parallel = ] { 0 | 1 }

Povolte paralelní spouštění skriptů jazyka R nastavením parametru @parallel na 1. Výchozí hodnota pro tento parametr je 0 (bez paralelismu). Pokud @parallel = 1 a výstup se streamuje přímo do klientského počítače, je vyžadována klauzule WITH RESULT SETS a musí být zadáno výstupní schéma.

• Pro skripty R, které nepoužívají funkce RevoScaleR, může být použití parametru @parallel přínosné pro zpracování velkých datových sad za předpokladu, že skript může být triviálně paralelizován. Například při použití funkce R predict s modelem k vygenerování nových předpovědí nastavte @parallel = 1 jako nápovědu pro dotazovací modul. Pokud lze dotaz paralelizovat, řádky se distribuují podle nastavení MAXDOP.

• U skriptů jazyka R, které používají funkce RevoScaleR, se paralelní zpracování zpracovává automaticky a neměli byste zadávat @parallel = 1 volání sp_execute_external_script.

[ @params = ] N'@parameter_name data_type' [ OUT | VÝSTUP ] [ , ... n ]

Seznam deklarací vstupních parametrů, které se používají v externím skriptu.

[ @parameter1 = ] 'hodnota1' [ OUT | VÝSTUP ] [ , ... n ]

Seznam hodnot vstupních parametrů používaných externím skriptem

Poznámky

Důležitý

Strom dotazů je řízen strojovým učením SQL a uživatelé nemůžou s dotazem provádět libovolné operace.

Pomocí sp_execute_external_script můžete spouštět skripty napsané v podporovaném jazyce. Podporované jazyky jsou Pythonu a R používané se službou Machine Learning Services a libovolný jazyk definovaný CREATE EXTERNAL LANGUAGE (například Java) používaný s jazykovými rozšířeními.

Ve výchozím nastavení jsou sady výsledků vrácené touto uloženou procedurou výstupem s nepojmenovanými sloupci. Názvy sloupců používané ve skriptu jsou místní pro skriptovací prostředí a neprojevují se ve výstupní sadě výsledků. Chcete-li pojmenovat sloupce sady výsledků, použijte klauzuli WITH RESULT SETEXECUTE.

Kromě vrácení sady výsledků můžete skalární hodnoty vrátit pomocí parametrů OUTPUT.

Prostředky používané externími skripty můžete řídit konfigurací externího fondu zdrojů. Další informace naleznete v tématu CREATE EXTERNAL RESOURCE POOL. Informace o úloze lze získat ze zobrazení katalogu správce prostředků, zobrazení dynamické správy a čítačů. Další informace naleznete v tématu Zobrazení katalogu správce prostředků, správce prostředků související zobrazení dynamické správya SQL Server, objekt externí skripty.

Monitorování spouštění skriptů

Monitorování spouštění skriptů pomocí sys.dm_external_script_requests a sys.dm_external_script_execution_stats.

Parametry pro modelování oddílů

Můžete nastavit dva další parametry, které umožňují modelování na dělených datech, kde oddíly vycházejí z jednoho nebo více sloupců, které přirozeně segmentují datovou sadu do logických oddílů, vytvořené a používané pouze během provádění skriptu. Sloupce obsahující opakující se hodnoty pro věk, pohlaví, geografickou oblast, datum nebo čas, představují několik příkladů, které se hodí pro dělené datové sady.

Dva parametry jsou input_data_1_partition_by_columns a input_data_1_order_by_columns, kde se druhý parametr používá k seřazení sady výsledků. Parametry se předávají jako vstupy sp_execute_external_script s externím skriptem spouštěným jednou pro každý oddíl. Další informace a příklady najdete v tématu Kurz: Vytváření modelů založených na oddílech v jazyce R na SQL Serveru.

Skript můžete spustit paralelně zadáním @parallel = 1. Pokud lze vstupní dotaz paralelizovat, měli byste nastavit @parallel = 1 jako součást argumentů na sp_execute_external_script. Optimalizátor dotazů ve výchozím nastavení pracuje v @parallel = 1 v tabulkách s více než 256 řádky, ale pokud to chcete zpracovat explicitně, zahrnuje tento skript parametr jako ukázku.

Spropitné

Pro trénovací úlohy můžete použít @parallel s libovolným trénovacím skriptem, a to i s použitím algoritmů jiných než Microsoft-rx. V trénovacích scénářích v SQL Serveru obvykle nabízejí paralelismus pouze algoritmy RevoScaleR (s předponou rx). S novými parametry v SQL Serveru 2019 (15.x) a novějších verzích ale můžete paralelizovat skript, který volá funkce, které nejsou speciálně navrženy s danou schopností.

Spouštění streamování pro skripty Pythonu a R

Streamování umožňuje skriptu Pythonu nebo jazyka R pracovat s více daty, než se vejde do paměti. Pokud chcete řídit počet řádků předaných během streamování, zadejte celočíselnou hodnotu parametru @r_rowsPerRead v kolekci @params. Pokud například trénujete model, který používá velmi široká data, můžete upravit hodnotu tak, aby četla méně řádků, aby se zajistilo, že se všechny řádky dají odeslat do jednoho bloku dat. Tento parametr můžete také použít ke správě počtu řádků, které se čtou a zpracovávají najednou, a zmírnit tak problémy s výkonem serveru.

Parametr @r_rowsPerRead pro streamování i argument @parallel by se měly považovat za rady. Aby bylo možné použít nápovědu, musí být možné vygenerovat plán dotazu SQL, který zahrnuje paralelní zpracování. Pokud to není možné, paralelní zpracování nejde povolit.

Poznámka

Streamování a paralelní zpracování se podporuje jenom v Enterprise Edition. Parametry můžete zahrnout do dotazů v edici Standard Edition bez vyvolání chyby, ale parametry nemají žádný vliv a skripty jazyka R se spouštějí v jednom procesu.

Omezení

Datové typy

Následující datové typy nejsou podporovány, pokud se používají ve vstupním dotazu nebo parametrech sp_execute_external_script procedury a vrací chybu nepodporovaného typu.

Jako alternativní řešení CAST sloupec nebo hodnotu podporovaného typu Transact-SQL před odesláním do externího skriptu.

• kurzoru
• časové razítko
• datetime2, datetimeoffset , čas
• sql_variant
• textu obrázku
• xml
• ,geometrie , zeměpisné
• Uživatelem definované typy CLR

Obecně platí, že jakákoli sada výsledků, která se nedá mapovat na datový typ Transact-SQL, je výstupem NULL.

Omezení specifická pro R

Pokud vstup obsahuje hodnoty data a času, které neodpovídají přípustnému rozsahu hodnot v jazyce R, hodnoty se převedou na NA. To je povinné, protože strojové učení SQL umožňuje větší rozsah hodnot, než je podporováno v jazyce R.

Hodnoty float (například +Inf, -Inf, NaN) nejsou ve strojovém učení SQL podporované, i když oba jazyky používají IEEE 754. Aktuální chování pouze odesílá hodnoty přímo do SQL; V důsledku toho klient SQL vyvolá chybu. Proto jsou tyto hodnoty převedeny na NULL.

Dovolení

Vyžaduje oprávnění KE SPUŠTĚNÍ LIBOVOLNÉ DATABÁZE EXTERNÍCH SKRIPTŮ.

Příklady

Tato část obsahuje příklady použití této uložené procedury ke spouštění skriptů jazyka R nebo Python pomocí jazyka Transact-SQL.

A. Vrácení datové sady R na SQL Server

Následující příklad vytvoří uloženou proceduru, která používá sp_execute_external_script k vrácení datové sady Iris zahrnuté v jazyce 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. Vytvoření modelu Pythonu a vygenerování skóre z něj

Tento příklad ukazuje, jak pomocí sp_execute_external_script vygenerovat skóre v jednoduchém modelu Pythonu.

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

Záhlaví sloupců používaná v kódu Pythonu nejsou výstupem sql Serveru; proto použijte příkaz WITH RESULT k určení názvů sloupců a datových typů, které má sql použít.

C. Generování modelu R na základě dat z SQL Serveru

Následující příklad vytvoří uloženou proceduru, která používá sp_execute_external_script k vygenerování modelu iris a vrácení modelu.

Poznámka

Tento příklad vyžaduje pokročilou instalaci balíčku e1071. Další informace naleznete v tématu Instalace balíčků R pomocí sqlmlutils.

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

Pokud chcete vygenerovat podobný model pomocí Pythonu, změnili byste identifikátor jazyka z @language=N'R' na @language = N'Python'a udělali potřebné úpravy argumentu @script. V opačném případě všechny parametry fungují stejně jako pro R.

Pro bodování můžete také použít nativní funkci PREDICT, což je obvykle rychlejší, protože se vyhne volání modulu runtime Python nebo R.

Související obsah

• strojového učení SQL
• Co je sql Server Language Extensions?
• uložené procedury systému (Transact-SQL)
• CREATE EXTERNAL LIBRARY (Transact-SQL)
• sp_prepare (Transact SQL)
• sp_configure (Transact-SQL)
• možnost konfigurace serveru s povolenými externími skripty
• SERVERPROPERTY (Transact-SQL)
• SQL Serveru, objekt externích skriptů
• sys.dm_external_script_requests
• sys.dm_external_script_execution_stats