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

SI APPLICA A: sìSQL Server sìDatabase SQL di Azure sìAzure SQL Data Warehouse sìParallel Data Warehouse APPLIES TO: yesSQL Server yesAzure SQL Database yesAzure SQL Data Warehouse yesParallel Data Warehouse

Esegue un'istruzione o un batch Transact-SQLTransact-SQL che può essere riutilizzato più volte o che è stato compilato in modo dinamico.Executes a Transact-SQLTransact-SQL statement or batch that can be reused many times, or one that has been built dynamically. L'istruzione o il batch Transact-SQLTransact-SQL può contenere parametri incorporati.The Transact-SQLTransact-SQL statement or batch can contain embedded parameters.

Importante

Istruzioni Transact-SQLTransact-SQL compilate in fase di esecuzione possono esporre le applicazioni ad attacchi dannosi, ad esempio intrusioni nel codice SQL.Run time-compiled Transact-SQLTransact-SQL statements can expose applications to malicious attacks.

Icona di collegamento a un argomentoConvenzioni della sintassi Transact-SQLTopic link icon Transact-SQL Syntax Conventions

SintassiSyntax

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

ArgomentiArguments

[ @stmt= ] statement[ @stmt= ] statement
È una stringa Unicode che contiene un Transact-SQLTransact-SQL istruzione o il batch.Is a Unicode string that contains a Transact-SQLTransact-SQL statement or batch. @stmt deve essere una costante Unicode o una variabile Unicode.@stmt must be either a Unicode constant or a Unicode variable. Non sono consentite le espressioni Unicode più complesse, ad esempio per la concatenazione di due stringhe tramite l'operatore +.More complex Unicode expressions, such as concatenating two strings with the + operator, are not allowed. Le costanti di tipo carattere non sono consentite.Character constants are not allowed. Se viene specificata una costante Unicode, devono essere preceduto da un N. Ad esempio, la costante Unicode n' sp_who' valido, ma la costante carattere 'sp_who' non.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. Le dimensioni massime della stringa dipendono dalla memoria disponibile nel server di database.The size of the string is limited only by available database server memory. Nei server a 64 bit, le dimensioni della stringa sono limitate a 2 GB, la dimensione massima del nvarchar (max) .On 64-bit servers, the size of the string is limited to 2 GB, the maximum size of nvarchar(max).

Nota

@stmt può contenere parametri con lo stesso formato di un nome di variabile, ad esempio: 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'

Ogni parametro incluso in @stmt deve avere una voce corrispondente in entrambe le @params elenco di definizioni di parametro e il parametro di elenco di valori.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_name data_type [ ,... n ] '
Stringa che contiene le definizioni di tutti i parametri che sono stati incorporati in @stmt. La stringa deve essere una costante o una variabile Unicode.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. Ogni definizione di parametro è costituita da un nome del parametro e da un tipo di dati.Each parameter definition consists of a parameter name and a data type. n è un segnaposto che indica definizioni di parametro aggiuntive.n is a placeholder that indicates additional parameter definitions. Ogni parametro specificato in @stmt deve essere definito in @params.Every parameter specified in @stmt must be defined in @params. Se il Transact-SQLTransact-SQL istruzione o il batch nel @stmt non contiene parametri, @params non è obbligatorio.If the Transact-SQLTransact-SQL statement or batch in @stmt does not contain parameters, @params is not required. Il valore predefinito per questo parametro è NULL.The default value for this parameter is NULL.

[ @param1 =] 'value1'[ @param1= ] 'value1'
Valore per il primo parametro definito nella stringa di parametri.Is a value for the first parameter that is defined in the parameter string. Il valore può essere una costante o una variabile Unicode.The value can be a Unicode constant or a Unicode variable. Deve esistere un valore di parametro per ogni parametro incluso in @stmt. I valori non sono necessari se il Transact-SQLTransact-SQL istruzione o il batch in @stmt non ha parametri.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 ]
Indica che si tratta di un parametro di output.Indicates that the parameter is an output parameter. testo, ntext, e immagine parametri possono essere utilizzati come parametri di OUTPUT, a meno che la procedura è una routine di runtime (CLR) di linguaggio comuni.text, ntext, and image parameters can be used as OUTPUT parameters, unless the procedure is a common language runtime (CLR) procedure. Un parametro di output che utilizza la parola chiave OUTPUT può essere il segnaposto di un cursore, a meno che la procedura non sia una procedura CLR.An output parameter that uses the OUTPUT keyword can be a cursor placeholder, unless the procedure is a CLR procedure.

nn
Segnaposto per i valori di parametri aggiuntivi.Is a placeholder for the values of additional parameters. I valori possono essere solo costanti o variabili.Values can only be constants or variables. Non sono consentite espressioni più complesse quali funzioni o espressioni compilate tramite operatori.Values cannot be more complex expressions such as functions, or expressions built by using operators.

Valori restituitiReturn Code Values

0 (esito positivo) o valore diverso da zero (esito negativo)0 (success) or non-zero (failure)

Set di risultatiResult Sets

Restituisce i set di risultati di tutte le istruzioni SQL compilate nella stringa SQL.Returns the result sets from all the SQL statements built into the SQL string.

NoteRemarks

i parametri di stored procedure sp_executesql devono essere immesso nell'ordine specifico, come descritto nella sezione "Sintassi" più indietro in questo argomento.sp_executesql parameters must be entered in the specific order as described in the "Syntax" section earlier in this topic. Se i parametri non vengono immessi in ordine, verrà visualizzato un messaggio di errore.If the parameters are entered out of order, an error message will occur.

La stored procedure sp_executesql funziona in modo analogo a EXECUTE per quanto riguarda i batch, l'ambito dei nomi e il contesto del database.sp_executesql has the same behavior as EXECUTE with regard to batches, the scope of names, and database context. Il Transact-SQLTransact-SQL istruzione o un batch di sp_executesql @stmt parametro non viene compilato finché non viene eseguita l'istruzione sp_executesql.The Transact-SQLTransact-SQL statement or batch in the sp_executesql @stmt parameter is not compiled until the sp_executesql statement is executed. Il contenuto di @stmt viene quindi compilato ed eseguito come piano di esecuzione distinto dal piano di esecuzione del batch che ha chiamato sp_executesql.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. Il batch di sp_executesql non può fare riferimento a variabili dichiarate nel batch che chiama sp_executesql.The sp_executesql batch cannot reference variables declared in the batch that calls sp_executesql. I cursori o le variabili locali del batch sp_executesql non sono visibili per il batch che chiama sp_executesql.Local cursors or variables in the sp_executesql batch are not visible to the batch that calls sp_executesql. Le modifiche apportate al contesto del database durano solo fino al termine dell'esecuzione dell'istruzione sp_executesql.Changes in database context last only to the end of the sp_executesql statement.

È possibile utilizzare sp_executesql anziché stored procedure per eseguire un'istruzione Transact-SQLTransact-SQL più volte quando l'unica variazione è costituita dalla modifica dei valori dei parametri.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. Poiché l'istruzione Transact-SQLTransact-SQL stessa rimane costante e cambiano solo i valori dei parametri, è probabile che Query Optimizer di SQL ServerSQL Server riutilizzi il piano di esecuzione generato per la prima esecuzione.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.

Nota

Per ottimizzare le prestazioni, utilizzare nomi di oggetto completi nella stringa dell'istruzione.To improve performance use fully qualified object names in the statement string.

L'impostazione dei valori dei parametri è supportata in modo autonomo da sp_executesql rispetto alla stringa Transact-SQLTransact-SQL, come illustrato nell'esempio seguente.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;  

È inoltre possibile utilizzare parametri di output con sp_executesql.Output parameters can also be used with sp_executesql. Nell'esempio seguente un titolo professionale viene recuperato dalla tabella AdventureWorks2012.HumanResources.Employee e restituito nel parametro di output @max_title.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;  

La possibilità di sostituire i parametri in sp_executesql offre i vantaggi seguenti rispetto all'utilizzo dell'istruzione EXECUTE per l'esecuzione di una stringa:Being able to substitute parameters in sp_executesql offers the following advantages to using the EXECUTE statement to execute a string:

  • Dato che il testo effettivo dell'istruzione Transact-SQLTransact-SQL nella stringa sp_executesql rimane invariato tra un'esecuzione e la successiva, Query Optimizer cerca probabilmente di far corrispondere l'istruzione Transact-SQLTransact-SQL nella seconda esecuzione con il piano di esecuzione generato per la prima esecuzione.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. Di conseguenza SQL ServerSQL Server non deve compilare la seconda istruzione.Therefore, SQL ServerSQL Server does not have to compile the second statement.

  • La stringa Transact-SQLTransact-SQL viene compilata una sola volta.The Transact-SQLTransact-SQL string is built only one time.

  • Il parametro integer viene specificato nel formato nativo.The integer parameter is specified in its native format. Non è necessario eseguire il cast a Unicode.Casting to Unicode is not required.

PermissionsPermissions

È richiesta l'appartenenza al ruolo public.Requires membership in the public role.

EsempiExamples

R.A. Esecuzione di un'istruzione SELECT sempliceExecuting a simple SELECT statement

Nell'esempio seguente viene creata ed eseguita un'istruzione SELECT semplice che contiene un parametro incorporato denominato @level.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. Esecuzione di una stringa compilata in modo dinamicoExecuting a dynamically built string

Nell'esempio seguente viene illustrato l'utilizzo di sp_executesql per l'esecuzione di una stringa compilata in modo dinamico.The following example shows using sp_executesql to execute a dynamically built string. La stored procedure di esempio consente di inserire dati in un set di tabelle utilizzate per il partizionamento dei dati relativi alle vendite annuali.The example stored procedure is used to insert data into a set of tables that are used to partition sales data for a year. È disponibile una sola tabella per ogni mese dell'anno nel formato seguente: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)  
    )  

Questa stored procedure di esempio compila in modo dinamico ed esegue un'istruzione INSERT per l'inserimento di nuovi ordini nella tabella corretta.This sample stored procedure dynamically builds and executes an INSERT statement to insert new orders into the correct table. La data dell'ordine viene utilizzata per compilare il nome della tabella che deve contenere i dati, quindi il nome viene incorporato in un'istruzione INSERT.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.

Nota

Si tratta di un semplice esempio di utilizzo di sp_executesql.This is a simple example for sp_executesql. Non è previsto alcun controllo degli errori o delle regole business, ad esempio non viene verificato che i numeri di ordine siano univoci tra le tabelle.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  

L'utilizzo di sp_executesql in questa procedura è più funzionale rispetto all'utilizzo di EXECUTE per l'esecuzione di una stringa.Using sp_executesql in this procedure is more efficient than using EXECUTE to execute a string. Quando si utilizza sp_executesql, vengono generate solo 12 versioni della stringa INSERT, una per ogni tabella mensile.When sp_executesql is used, there are only 12 versions of the INSERT string that are generated, one for each monthly table. Con l'istruzione EXECUTE ogni stringa INSERT è univoca, in quanto i valori dei parametri sono diversi.With EXECUTE, each INSERT string is unique because the parameter values are different. Sebbene entrambi i metodi generino lo stesso numero di batch, data la similarità delle stringhe INSERT generate da sp_executesql è più probabile che Query Optimizer riutilizzi i piani di esecuzione.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. Utilizzo del parametro OUTPUTUsing the OUTPUT Parameter

L'esempio seguente usa un' OUTPUT parametro per archiviare il set di risultati generato dal SELECT istruzione il @SQLString parametro. Due SELECT vengono quindi eseguite che utilizzano il valore di istruzioni il OUTPUT parametro.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;  

Esempi: Azure SQL Data WarehouseAzure SQL Data Warehouse e Parallel Data WarehouseParallel Data WarehouseExamples: Azure SQL Data WarehouseAzure SQL Data Warehouse and Parallel Data WarehouseParallel Data Warehouse

D.D. Esecuzione di un'istruzione SELECT sempliceExecuting a simple SELECT statement

Nell'esempio seguente viene creata ed eseguita un'istruzione SELECT semplice che contiene un parametro incorporato denominato @level.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;  

Vedere ancheSee Also

EXECUTE (Transact-SQL) EXECUTE (Transact-SQL)
Stored procedure di sistema (Transact-SQL)System Stored Procedures (Transact-SQL)