sp_executesql (Transact-SQL)sp_executesql (Transact-SQL)

Dieses Thema gilt für: JaSQL Server (ab 2008)JaAzure SQL-DatenbankJaAzure SQL Data Warehouse Ja Parallel Datawarehouse THIS TOPIC APPLIES TO: yesSQL Server (starting with 2008)yesAzure SQL DatabaseyesAzure SQL Data Warehouse yesParallel Data Warehouse

Führt eine Transact-SQLTransact-SQL-Anweisung oder einen -Batch aus, die bzw. der mehrfach wiederverwendet werden kann oder dynamisch erstellt wurde.Executes a Transact-SQLTransact-SQL statement or batch that can be reused many times, or one that has been built dynamically. Die Transact-SQLTransact-SQL-Anweisung oder der -Batch können eingebettete Parameter enthalten.The Transact-SQLTransact-SQL statement or batch can contain embedded parameters.

Wichtig

Durch zur Laufzeit kompilierte Transact-SQLTransact-SQL-Anweisungen können Anwendungen böswilligen Angriffen ausgesetzt werden.Run time-compiled Transact-SQLTransact-SQL statements can expose applications to malicious attacks.

Themenlinksymbol Transact-SQL Syntax Conventions (Transact-SQL-Syntaxkonventionen)Topic link icon Transact-SQL Syntax Conventions

SyntaxSyntax

-- Syntax for SQL Server, Azure SQL Database, Azure SQL Data Warehouse, Parallel Data Warehouse  

sp_executesql [ @stmt = ] statement  
[   
  { , [ @params = ] N'@parameter_name data_type [ OUT | OUTPUT ][ ,...n ]' }   
     { , [ @param1 = ] 'value1' [ ,...n ] }  
]  

ArgumenteArguments

[ @stmt= ] statement[ @stmt= ] statement
Ist eine Unicode-Zeichenfolge, enthält eine Transact-SQLTransact-SQL Anweisung oder eines Batches.Is a Unicode string that contains a Transact-SQLTransact-SQL statement or batch. @stmt eine Unicode-Konstante oder eine Unicode-Variable muss sein.@stmt must be either a Unicode constant or a Unicode variable. Komplexere Unicodeausdrücke, wie z. B. die Verkettung von zwei Zeichenfolgen mit dem +-Operator, sind nicht zulässig.More complex Unicode expressions, such as concatenating two strings with the + operator, are not allowed. Zeichenkonstanten sind nicht zulässig.Character constants are not allowed. Wenn eine Unicode-Konstante angegeben wird, muss er mit vorangestellt ein N. Beispielsweise die Unicode-Konstante N 'Sp_who' gültig ist, aber die Zeichenkonstante 'Sp_who' nicht.If a Unicode constant is specified, it must be prefixed with an N. For example, the Unicode constant N'sp_who' is valid, but the character constant 'sp_who' is not. Die Länge der Zeichenfolge wird nur durch den verfügbaren Arbeitsspeicher des Datenbankservers begrenzt.The size of the string is limited only by available database server memory. Auf 64-Bit-Servern, die Größe der Zeichenfolge ist auf 2 GB sind, die maximale Größe des beschränkt nvarchar(max).On 64-bit servers, the size of the string is limited to 2 GB, the maximum size of nvarchar(max).

Hinweis

@stmt kann Parameter aufweisen, z. B. das gleiche Format wie ein Variablenname enthalten: N'SELECT * FROM HumanResources.Employee WHERE EmployeeID = @IDParameter'@stmt can contain parameters having the same form as a variable name, for example: N'SELECT * FROM HumanResources.Employee WHERE EmployeeID = @IDParameter'

Für jeden Parameter in @stmt ist ein entsprechender Eintrag in der @params-Parameterdefinitionsliste und in der Parameterwerteliste erforderlich.Each parameter included in @stmt must have a corresponding entry in both the @params parameter definition list and the parameter values list.

[ @params=] N'@Parameter_name ** Data_type [,... n ] "[ @params= ] N'@parameter_namedata_type [ ,... n ] '
Eine Zeichenfolge, die die Definitionen aller Parameter enthält, die in @stmt eingebettet wurden. Die Zeichenfolge muss eine Unicode-Konstante oder eine Unicode-Variable sein.Is one string that contains the definitions of all parameters that have been embedded in @stmt. The string must be either a Unicode constant or a Unicode variable. Jede Parameterdefinition besteht aus einem Parameternamen und einem Datentyp.Each parameter definition consists of a parameter name and a data type. n ist ein Platzhalter, der zusätzliche Parameterdefinitionen.n is a placeholder that indicates additional parameter definitions. Jeder Parameter im angegebenen @stmtmust definiert werden, @params.Every parameter specified in @stmtmust be defined in @params. Wenn die Transact-SQLTransact-SQL-Anweisung bzw. ein solcher Batch in @stmt keine Parameter enthält, ist @params nicht erforderlich.If the Transact-SQLTransact-SQL statement or batch in @stmt does not contain parameters, @params is not required. Der Standardwert für diesen Parameter ist NULL.The default value for this parameter is NULL.

[ @param1= ] 'value1'[ @param1= ] 'value1'
Der Wert für den ersten Parameter, der in der Parameterzeichenfolge definiert ist.Is a value for the first parameter that is defined in the parameter string. Bei diesem Wert kann es sich um eine Unicode-Konstante oder eine Unicode-Variable handeln.The value can be a Unicode constant or a Unicode variable. Für jeden Parameter in @stmt muss ein Parameterwert angegeben werden. Die Werte sind nicht erforderlich, wenn die Transact-SQLTransact-SQL-Anweisung oder der -Batch in @stmt keine Parameter aufweist.There must be a parameter value supplied for every parameter included in @stmt. The values are not required when the Transact-SQLTransact-SQL statement or batch in @stmt has no parameters.

[ OUT | OUTPUT ][ OUT | OUTPUT ]
Gibt an, dass es sich bei dem Parameter um einen Ausgabeparameter handelt.Indicates that the parameter is an output parameter. Text, Ntext, und Image Parameter können als OUTPUT-Parameter verwendet werden, es sei denn, die Prozedur eine Prozedur der common Language Runtime (CLR) ist.text, ntext, and image parameters can be used as OUTPUT parameters, unless the procedure is a common language runtime (CLR) procedure. Ein Ausgabeparameter, der das Schlüsselwort OUTPUT verwendet, kann ein Cursorplatzhalter sein, es sei denn, bei der Prozedur handelt es sich um eine CLR-Prozedur (Common Language Runtime).An output parameter that uses the OUTPUT keyword can be a cursor placeholder, unless the procedure is a CLR procedure.

nn
Ein Platzhalter für die Werte zusätzlicher Parameter.Is a placeholder for the values of additional parameters. Werte können nur Konstanten oder Variablen sein.Values can only be constants or variables. Werte können keine komplexeren Ausdrücke sein, wie z. B. Funktionen oder Ausdrücke, die mithilfe von Operatoren erstellt werden.Values cannot be more complex expressions such as functions, or expressions built by using operators.

RückgabecodewerteReturn Code Values

0 (Erfolg) oder ungleich 0 (Fehler)0 (success) or non-zero (failure)

ResultsetsResult Sets

Gibt die Resultsets von allen SQL-Anweisungen der SQL-Zeichenfolge zurück.Returns the result sets from all the SQL statements built into the SQL string.

HinweiseRemarks

Sp_executesql-Parameter müssen in der Reihenfolge eingegeben werden, wie im Abschnitt "Syntax" weiter oben in diesem Thema beschrieben.sp_executesql parameters must be entered in the specific order as described in the "Syntax" section earlier in this topic. Wenn die Parameter nicht in der vorgegebenen Reihenfolge eingegeben werden, wird eine Fehlermeldung ausgegeben.If the parameters are entered out of order, an error message will occur.

sp_executesql verhält sich hinsichtlich Batches, Namensbereichen und Datenbankkontext wie EXECUTE.sp_executesql has the same behavior as EXECUTE with regard to batches, the scope of names, and database context. Die Transact-SQLTransact-SQL -Anweisung oder einen Batch im Sp_executesql @stmt Parameter wird nicht kompiliert werden, bis die Sp_executesql-Anweisung ausgeführt wird.The Transact-SQLTransact-SQL statement or batch in the sp_executesql @stmt parameter is not compiled until the sp_executesql statement is executed. Der Inhalt von @stmt wird dann kompiliert und als Ausführungsplan ausgeführt, der separat vom Ausführungsplan des Batches ist, der sp_executesql aufgerufen hat.The contents of @stmt are then compiled and executed as an execution plan separate from the execution plan of the batch that called sp_executesql. Der sp_executesql-Batch kann nicht auf Variablen verweisen, die in dem Batch deklariert werden, der sp_executesql aufruft.The sp_executesql batch cannot reference variables declared in the batch that calls sp_executesql. Lokale Cursor oder Variablen im sp_executesql-Batch sind für den Batch, der sp_executesql aufruft, nicht sichtbar.Local cursors or variables in the sp_executesql batch are not visible to the batch that calls sp_executesql. Änderungen am Datenbankkontext sind nur bis zum Ende der sp_executesql-Anweisung vorhanden.Changes in database context last only to the end of the sp_executesql statement.

sp_executesql kann anstelle von gespeicherten Prozeduren verwendet werden, um eine Transact-SQLTransact-SQL-Anweisung mehrere Male auszuführen, wenn sich nur die Parameterwerte in der Anweisung ändern.sp_executesql can be used instead of stored procedures to execute a Transact-SQLTransact-SQL statement many times when the change in parameter values to the statement is the only variation. Da die Transact-SQLTransact-SQL-Anweisung selbst unverändert bleibt und nur die Parameterwerte geändert werden, wird der SQL ServerSQL Server-Abfrageoptimierer wahrscheinlich den Ausführungsplan wiederverwenden, der für die erste Ausführung erstellt wird.Because the Transact-SQLTransact-SQL statement itself remains constant and only the parameter values change, the SQL ServerSQL Server query optimizer is likely to reuse the execution plan it generates for the first execution.

Hinweis

Verwenden Sie zur Verbesserung der Leistung vollqualifizierte Objektnamen in der Anweisungszeichenfolge.To improve performance use fully qualified object names in the statement string.

sp_executesql unterstützt das von der Transact-SQLTransact-SQL-Zeichenfolge getrennte Festlegen von Parameterwerten, wie dem folgenden Beispiel zu entnehmen ist.sp_executesql supports the setting of parameter values separately from the Transact-SQLTransact-SQL string as shown in the following example.

DECLARE @IntVariable int;  
DECLARE @SQLString nvarchar(500);  
DECLARE @ParmDefinition nvarchar(500);  

/* Build the SQL string one time.*/  
SET @SQLString =  
     N'SELECT BusinessEntityID, NationalIDNumber, JobTitle, LoginID  
       FROM AdventureWorks2012.HumanResources.Employee   
       WHERE BusinessEntityID = @BusinessEntityID';  
SET @ParmDefinition = N'@BusinessEntityID tinyint';  
/* Execute the string with the first parameter value. */  
SET @IntVariable = 197;  
EXECUTE sp_executesql @SQLString, @ParmDefinition,  
                      @BusinessEntityID = @IntVariable;  
/* Execute the same string with the second parameter value. */  
SET @IntVariable = 109;  
EXECUTE sp_executesql @SQLString, @ParmDefinition,  
                      @BusinessEntityID = @IntVariable;  

Die Verwendung von Ausgabeparametern mit sp_executesql ist ebenfalls möglich.Output parameters can also be used with sp_executesql. Im folgenden Beispiel wird eine Berufsbezeichnung aus der AdventureWorks2012.HumanResources.Employee-Tabelle abgerufen und im Ausgabeparameter @max_title zurückgegeben.The following example retrieves a job title from the AdventureWorks2012.HumanResources.Employee table and returns it in the output parameter @max_title.

DECLARE @IntVariable int;  
DECLARE @SQLString nvarchar(500);  
DECLARE @ParmDefinition nvarchar(500);  
DECLARE @max_title varchar(30);  

SET @IntVariable = 197;  
SET @SQLString = N'SELECT @max_titleOUT = max(JobTitle)   
   FROM AdventureWorks2012.HumanResources.Employee  
   WHERE BusinessEntityID = @level';  
SET @ParmDefinition = N'@level tinyint, @max_titleOUT varchar(30) OUTPUT';  

EXECUTE sp_executesql @SQLString, @ParmDefinition, @level = @IntVariable, @max_titleOUT=@max_title OUTPUT;  
SELECT @max_title;  

Die Möglichkeit, Parameter in sp_executesql zu ersetzen, bietet die folgenden Vorteile gegenüber der Verwendung der EXECUTE-Anweisung, um eine Zeichenfolge auszuführen:Being able to substitute parameters in sp_executesql offers the following advantages to using the EXECUTE statement to execute a string:

  • Da sich der tatsächliche Text der Transact-SQLTransact-SQL-Anweisung in der sp_executesql-Zeichenfolge für die verschiedenen Ausführungen nicht ändert, findet der Abfrageoptimierer wahrscheinlich für die Transact-SQLTransact-SQL-Anweisung bei der zweiten Ausführung die Übereinstimmung mit dem Ausführungsplan, der für die erste Ausführung generiert wurde.Because the actual text of the Transact-SQLTransact-SQL statement in the sp_executesql string does not change between executions, the query optimizer will probably match the Transact-SQLTransact-SQL statement in the second execution with the execution plan generated for the first execution. Deshalb muss SQL ServerSQL Server die zweite Anweisung nicht kompilieren.Therefore, SQL ServerSQL Server does not have to compile the second statement.

  • Die Transact-SQLTransact-SQL-Zeichenfolge wird nur einmal erstellt.The Transact-SQLTransact-SQL string is built only one time.

  • Der integer-Parameter wird im systemeigenen Format angegeben.The integer parameter is specified in its native format. Die Konvertierung in Unicode ist nicht erforderlich.Casting to Unicode is not required.

BerechtigungenPermissions

Erfordert die Mitgliedschaft in der public-Rolle.Requires membership in the public role.

BeispieleExamples

A.A. Ausführen einer einfachen SELECT-AnweisungExecuting a simple SELECT statement

In diesem Beispiel wird eine einfache SELECT-Anweisung erstellt und ausgeführt, die den eingebetteten Parameter @level enthält.The following example creates and executes a simple SELECT statement that contains an embedded parameter named @level.

EXECUTE sp_executesql   
          N'SELECT * FROM AdventureWorks2012.HumanResources.Employee   
          WHERE BusinessEntityID = @level',  
          N'@level tinyint',  
          @level = 109;  

B.B. Ausführen einer dynamisch erstellten ZeichenfolgeExecuting a dynamically built string

In folgenden Beispiel wird veranschaulicht, wie mithilfe von sp_executesql eine dynamisch erstellte Zeichenfolge ausgeführt wird.The following example shows using sp_executesql to execute a dynamically built string. Mit der gespeicherten Prozedur im Beispiel werden Daten in mehrere Tabellen eingefügt, die zum Partitionieren der Jahresverkaufszahlen verwendet werden.The example stored procedure is used to insert data into a set of tables that are used to partition sales data for a year. Für jeden Monat des Jahres ist eine Tabelle mit dem folgenden Format vorhanden:There is one table for each month of the year that has the following format:

CREATE TABLE May1998Sales  
    (OrderID int PRIMARY KEY,  
    CustomerID int NOT NULL,  
    OrderDate  datetime NULL  
        CHECK (DATEPART(yy, OrderDate) = 1998),  
    OrderMonth int  
        CHECK (OrderMonth = 5),  
    DeliveryDate datetime  NULL,  
        CHECK (DATEPART(mm, OrderDate) = OrderMonth)  
    )  

Die gespeicherte Prozedur in diesem Beispiel erstellt eine INSERT-Anweisung dynamisch und führt sie aus, um neue Aufträge in die entsprechende Tabelle einzufügen.This sample stored procedure dynamically builds and executes an INSERT statement to insert new orders into the correct table. Im Beispiel wird das Bestelldatum verwendet, um den Namen der Tabelle zu erstellen, die die Daten enthalten soll. Anschließend wird dieser Name in eine INSERT-Anweisung integriert.The example uses the order date to build the name of the table that should contain the data, and then incorporates that name into an INSERT statement.

Hinweis

Dies ist ein einfaches Beispiel für sp_executesql.This is a simple example for sp_executesql. Das Beispiel enthält keine Fehlerprüfung und keine Überprüfung etwaiger Geschäftsregeln, wie z. B. um sicherzustellen, dass Bestellnummern in den Tabellen nicht doppelt vorhanden sind.The example does not contain error checking and does not include checks for business rules, such as guaranteeing that order numbers are not duplicated between tables.

CREATE PROCEDURE InsertSales @PrmOrderID INT, @PrmCustomerID INT,  
                 @PrmOrderDate DATETIME, @PrmDeliveryDate DATETIME  
AS  
DECLARE @InsertString NVARCHAR(500)  
DECLARE @OrderMonth INT  

-- Build the INSERT statement.  
SET @InsertString = 'INSERT INTO ' +  
       /* Build the name of the table. */  
       SUBSTRING( DATENAME(mm, @PrmOrderDate), 1, 3) +  
       CAST(DATEPART(yy, @PrmOrderDate) AS CHAR(4) ) +  
       'Sales' +  
       /* Build a VALUES clause. */  
       ' VALUES (@InsOrderID, @InsCustID, @InsOrdDate,' +  
       ' @InsOrdMonth, @InsDelDate)'  

/* Set the value to use for the order month because  
   functions are not allowed in the sp_executesql parameter  
   list. */  
SET @OrderMonth = DATEPART(mm, @PrmOrderDate)  

EXEC sp_executesql @InsertString,  
     N'@InsOrderID INT, @InsCustID INT, @InsOrdDate DATETIME,  
       @InsOrdMonth INT, @InsDelDate DATETIME',  
     @PrmOrderID, @PrmCustomerID, @PrmOrderDate,  
     @OrderMonth, @PrmDeliveryDate  

GO  

Das Verwenden von sp_executesql in dieser Prozedur ist effizienter als das Verwenden von EXECUTE zum Ausführen einer Zeichenfolge.Using sp_executesql in this procedure is more efficient than using EXECUTE to execute a string. Beim Verwenden von sp_executesql werden nur 12 Versionen der INSERT-Zeichenfolge generiert, nämlich eine Version für jede Monatstabelle.When sp_executesql is used, there are only 12 versions of the INSERT string that are generated, one for each monthly table. Mit EXECUTE ist jede INSERT-Zeichenfolge eindeutig, weil die Parameterwerte unterschiedlich sind.With EXECUTE, each INSERT string is unique because the parameter values are different. Obwohl beide Methoden die gleiche Anzahl von Batches generieren, ist es wegen der Ähnlichkeit der von sp_executesql generierten INSERT-Zeichenfolgen wahrscheinlicher, dass der Abfrageoptimierer die Ausführungspläne wiederverwendet.Although both methods generate the same number of batches, the similarity of the INSERT strings generated by sp_executesql makes it more likely that the query optimizer will reuse execution plans.

C.C. Verwenden des OUTPUT-ParametersUsing the OUTPUT Parameter

Im folgenden Beispiel wird ein OUTPUT Parameter zum Speichern von generierten Resultset die SELECT -Anweisung in der @SQLString Parameter. Zwei SELECT Anweisungen werden dann ausgeführt, die den Wert des verwenden die OUTPUT Parameter.The following example uses an OUTPUT parameter to store the result set generated by the SELECT statement in the @SQLString parameter.Two SELECT statements are then executed that use the value of the OUTPUT parameter.

USE AdventureWorks2012;  
GO  
DECLARE @SQLString nvarchar(500);  
DECLARE @ParmDefinition nvarchar(500);  
DECLARE @SalesOrderNumber nvarchar(25);  
DECLARE @IntVariable int;  
SET @SQLString = N'SELECT @SalesOrderOUT = MAX(SalesOrderNumber)  
    FROM Sales.SalesOrderHeader  
    WHERE CustomerID = @CustomerID';  
SET @ParmDefinition = N'@CustomerID int,  
    @SalesOrderOUT nvarchar(25) OUTPUT';  
SET @IntVariable = 22276;  
EXECUTE sp_executesql  
    @SQLString  
    ,@ParmDefinition  
    ,@CustomerID = @IntVariable  
    ,@SalesOrderOUT = @SalesOrderNumber OUTPUT;  
-- This SELECT statement returns the value of the OUTPUT parameter.  
SELECT @SalesOrderNumber;  
-- This SELECT statement uses the value of the OUTPUT parameter in  
-- the WHERE clause.  
SELECT OrderDate, TotalDue  
FROM Sales.SalesOrderHeader  
WHERE SalesOrderNumber = @SalesOrderNumber;  

Beispiele: Azure SQL Data WarehouseAzure SQL Data Warehouse und Parallel Data WarehouseParallel Data Warehouse.Examples: Azure SQL Data WarehouseAzure SQL Data Warehouse and Parallel Data WarehouseParallel Data Warehouse

D.D. Ausführen einer einfachen SELECT-AnweisungExecuting a simple SELECT statement

In diesem Beispiel wird eine einfache SELECT-Anweisung erstellt und ausgeführt, die den eingebetteten Parameter @level enthält.The following example creates and executes a simple SELECT statement that contains an embedded parameter named @level.

-- Uses AdventureWorks  

EXECUTE sp_executesql   
          N'SELECT * FROM AdventureWorksPDW2012.dbo.DimEmployee   
          WHERE EmployeeKey = @level',  
          N'@level tinyint',  
          @level = 109;  

Weitere Beispiele finden Sie unter Sp_executesql (Transact-SQL).For additional examples, see sp_executesql (Transact-SQL).

Siehe auchSee Also

EXECUTE (Transact-SQL) EXECUTE (Transact-SQL)
Gespeicherte Systemprozeduren (Transact-SQL)System Stored Procedures (Transact-SQL)