Share via


Using sp_executesql

To execute a string, we recommend that you use the sp_executesql stored procedure instead of the EXECUTE statement. Because this stored procedure supports parameter substitution, sp_executesql is more versatile than EXECUTE; and because sp_executesql generates execution plans that are more likely to be reused by SQL Server, sp_executesql is more efficient than EXECUTE.

Self-contained Batches

When either sp_executesql or the EXECUTE statement executes a string, the string is executed as its own self-contained batch. SQL Server compiles the Transact-SQL statement or statements in the string into an execution plan that is separate from the execution plan of the batch that contained the sp_executesql or the EXECUTE statement. The following rules apply for self-contained batches:

  • The Transact-SQL statements in the sp_executesql or EXECUTE string are not compiled into an execution plan until sp_executesql or the EXECUTE statement are executed. The strings are not parsed or checked for errors until they are executed. The names referenced in the strings are not resolved until they are executed.

  • The Transact-SQL statements in the executed string do not have access to any variables declared in the batch that contains sp_executesql or the EXECUTE statement. The batch that contains sp_executesql or the EXECUTE statement does not have access to variables or local cursors defined in the executed string.

  • If the executed string contains a USE statement that changes the database context, the change to the database context only lasts until sp_executesql or the EXECUTE statement has finished running.

Running the following two batches illustrates these points:

/*Show not having access to variables from the calling batch. */
DECLARE @CharVariable CHAR(3);
SET @CharVariable = 'abc';
/* sp_executesql fails because @CharVariable has gone out of scope. */
EXECUTE sp_executesql N'PRINT @CharVariable';
GO

/* Show database context resetting after sp_executesql finishes. */
USE master;
GO
EXECUTE sp_executesql N'USE AdventureWorks2008R2;'
GO
/* This statement fails because the database context
   has now returned to master. */
SELECT * FROM Sales.Store;
GO

Substituting Parameter Values

sp_executesql supports the substitution of parameter values for any parameters that are specified in the Transact-SQL string, but the EXECUTE statement does not. Therefore, the Transact-SQL strings that are generated by sp_executesql are more similar than those generated by the EXECUTE statement. The SQL Server query optimizer will probably match the Transact-SQL statements from sp_executesql with execution plans from the previously executed statements, saving the overhead of compiling a new execution plan.

With the EXECUTE statement, all parameter values must be converted to character or Unicode and made a part of the Transact-SQL string.

If the statement is executed repeatedly, a completely new Transact-SQL string must be built for each execution, even when the only differences are in the values supplied for the parameters. This generates additional overhead in the following ways:

  • The ability of the SQL Server query optimizer to match the new Transact-SQL string with an existing execution plan is hampered by the constantly changing parameter values in the text of the string, especially in complex Transact-SQL statements.

  • The whole string must be rebuilt for each execution.

  • Parameter values (other than character or Unicode values) must be cast to a character or Unicode format for each execution.

sp_executesql supports setting of parameter values separately from the Transact-SQL string:

DECLARE @IntVariable INT;
DECLARE @SQLString NVARCHAR(500);
DECLARE @ParmDefinition NVARCHAR(500);

/* Build the SQL string one time. */
SET @SQLString =
     N'SELECT * FROM AdventureWorks2008R2.Sales.Store WHERE SalesPersonID = @SalesID';
/* Specify the parameter format one time. */
SET @ParmDefinition = N'@SalesID int';

/* Execute the string with the first parameter value. */
SET @IntVariable = 275;
EXECUTE sp_executesql @SQLString, @ParmDefinition,
                      @SalesID = @IntVariable;
/* Execute the same string with the second parameter value. */
SET @IntVariable = 276;
EXECUTE sp_executesql @SQLString, @ParmDefinition,
                      @SalesID = @IntVariable;

sp_executesql offers the following additional benefits:

  • Because the actual text of the Transact-SQL statement does not change between executions, the query optimizer should match the Transact-SQL statement in the second execution with the execution plan generated for the first execution. Therefore, SQL Server does not have to compile the second statement.

  • The Transact-SQL string is built only one time.

  • The integer parameter is specified in its native format. Conversion to Unicode is not required.

    Note

    Object names in the statement string must be fully qualified for SQL Server to reuse the execution plan.

Reusing Execution Plans

In earlier versions of SQL Server, the only way to be able to reuse execution plans is to define the Transact-SQL statements as a stored procedure and have the application execute the stored procedure. This generates additional administrative overhead for the applications. Using sp_executesql can help reduce this overhead and still let SQL Server reuse execution plans. sp_executesql can be used instead of stored procedures when executing a Transact-SQL statement several times, when the only variation is in the parameter values supplied to the Transact-SQL statement. Because the Transact-SQL statements themselves remain constant and only the parameter values change, the SQL Server query optimizer is likely to reuse the execution plan it generates for the first execution.

The following example builds and executes a DBCC CHECKDB statement for every database on a server, except for the four system databases.

USE master;
GO
SET NOCOUNT ON;
GO
DECLARE AllDatabases CURSOR FOR
SELECT name FROM sys.databases WHERE database_id > 4
OPEN AllDatabases;

DECLARE @DBNameVar NVARCHAR(128);
DECLARE @Statement NVARCHAR(300);

FETCH NEXT FROM AllDatabases INTO @DBNameVar;
WHILE (@@FETCH_STATUS = 0)
BEGIN
   PRINT N'CHECKING DATABASE ' + @DBNameVar;
   SET @Statement = N'USE ' + @DBNameVar + CHAR(13)
      + N'DBCC CHECKDB (' + @DBNameVar + N')' + N'WITH PHYSICAL_ONLY';
   EXEC sp_executesql @Statement;
   PRINT CHAR(13) + CHAR(13);
   FETCH NEXT FROM AllDatabases INTO @DBNameVar;
END;

CLOSE AllDatabases;
DEALLOCATE AllDatabases;
GO
SET NOCOUNT OFF;
GO

The SQL Server ODBC driver uses sp_executesql to implement SQLExecDirect when the Transact-SQL statement that is being executed contains bound parameter markers. This extends the advantages provided by sp_executesql to all applications that use ODBC or APIs defined over ODBC, such as RDO. Existing ODBC applications ported to SQL Server automatically acquire the performance gains without having to be rewritten. The one exception is that sp_executesql is not used with data-at-execution parameters. For more information, see Using Statement Parameters.

The SQL Server Native Client ODBC Provider also uses sp_executesql to implement the direct execution of statements with bound parameters. Applications that use OLE DB or ADO gain the advantages provided by sp_executesql without having to be rewritten.