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

적용 대상: 예SQL Server(2008부터) 예Azure SQL Database 예Azure SQL Data Warehouse 예병렬 데이터 웨어하우스 APPLIES TO: yesSQL Server (starting with 2008) yesAzure SQL Database yesAzure SQL Data Warehouse yesParallel Data Warehouse

여러 번 사용할 수 있거나 동적으로 빌드된 Transact-SQLTransact-SQL 문이나 일괄 처리를 실행합니다.Executes a Transact-SQLTransact-SQL statement or batch that can be reused many times, or one that has been built dynamically. Transact-SQLTransact-SQL 문 또는 일괄 처리는 포함 매개 변수를 포함할 수 있습니다.The Transact-SQLTransact-SQL statement or batch can contain embedded parameters.

중요

런타임 컴파일된 Transact-SQLTransact-SQL 문은 악의적인 공격에 응용 프로그램을 노출시킬 수 있습니다.Run time-compiled Transact-SQLTransact-SQL statements can expose applications to malicious attacks.

항목 링크 아이콘 Transact-SQL 구문 규칙Topic link icon Transact-SQL Syntax Conventions

구문Syntax

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

인수Arguments

[ @stmt= ] statement[ @stmt= ] statement
포함 하는 유니코드 문자열을 Transact-SQLTransact-SQL 문 또는 일괄 처리 합니다.Is a Unicode string that contains a Transact-SQLTransact-SQL statement or batch. @stmt은 유니코드 상수 또는 유니코드 변수 여야 합니다.@stmt must be either a Unicode constant or a Unicode variable. + 연산자로 두 문자열을 연결한 식처럼 더 복잡한 유니코드 식은 사용할 수 없습니다.More complex Unicode expressions, such as concatenating two strings with the + operator, are not allowed. 문자 상수도 사용할 수 없습니다.Character constants are not allowed. 유니코드 상수를 지정 하면이 접두사로 추가 해야 합니다는 N합니다. 예를 들어 유니코드 상수 N'sp_who ' 유효 하지만 문자 상수 'sp_who' 아닙니다.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. 문자열의 크기는 사용 가능한 데이터베이스 서버 메모리의 용량에 따라서만 제한됩니다.The size of the string is limited only by available database server memory. 64 비트 서버의 문자열의 크기는 최대 크기인 2GB로 제한 됩니다 nvarchar (max) 합니다.On 64-bit servers, the size of the string is limited to 2 GB, the maximum size of nvarchar(max).

참고

@stmt 매개 변수는 변수 이름과 동일한 형식의 예를 들어를 포함할 수 있습니다. 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'

에 포함 된 각 매개 변수에 @stmt는 둘 다에 해당 하는 항목이 있어야 합니다 @params 매개 변수 정의 목록과 매개 변수 값 목록입니다.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 ] '
에 포함 된 모든 매개 변수의 정의 포함 하는 하나의 문자열 @stmt 합니다. 문자열은 유니코드 상수 또는 유니코드 변수여야 합니다.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. 각 매개 변수의 정의는 매개 변수 이름과 데이터 형식으로 구성됩니다.Each parameter definition consists of a parameter name and a data type. n 추가 매개 변수 정의 나타내는 자리 표시자입니다.n is a placeholder that indicates additional parameter definitions. 에 지정 된 모든 매개 변수에 @stmt에 정의 되어 있어야 @매개 변수입니다.Every parameter specified in @stmt must be defined in @params. 경우는 Transact-SQLTransact-SQL 문 또는 일괄 처리 @stmt 매개 변수는 @params가 필요 하지 않습니다.If the Transact-SQLTransact-SQL statement or batch in @stmt does not contain parameters, @params is not required. 이 매개 변수의 기본값은 NULL입니다.The default value for this parameter is NULL.

[ @param1= ] 'value1'[ @param1= ] 'value1'
매개 변수 문자열에 정의된 첫 번째 매개 변수의 값입니다.Is a value for the first parameter that is defined in the parameter string. 값은 유니코드 상수 또는 유니코드 변수가 될 수 있습니다.The value can be a Unicode constant or a Unicode variable. 에 포함 된 모든 매개 변수에 제공 되는 매개 변수 값이 있어야 @stmt 합니다. 값이 필요한 경우는 Transact-SQLTransact-SQL 문 또는 일괄 처리 @stmt에 매개 변수가 없습니다.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 ]
매개 변수가 출력 매개 변수임을 나타냅니다.Indicates that the parameter is an output parameter. 텍스트하십시오 ntext, 및 이미지 프로시저 공용 언어 런타임 (CLR) 프로시저가 아닐 경우 출력 매개 변수로 매개 변수를 사용할 수 있습니다.text, ntext, and image parameters can be used as OUTPUT parameters, unless the procedure is a common language runtime (CLR) procedure. 프로시저가 CLR 프로시저가 아닐 경우 OUTPUT 키워드를 사용하는 출력 매개 변수가 커서 자리 표시자일 수 있습니다.An output parameter that uses the OUTPUT keyword can be a cursor placeholder, unless the procedure is a CLR procedure.

nn
추가 매개 변수의 값에 대한 자리 표시자입니다.Is a placeholder for the values of additional parameters. 값은 상수 또는 변수만 가능합니다.Values can only be constants or variables. 함수 또는 연산자를 사용하여 작성한 식처럼 더 복잡한 식은 값으로 사용할 수 없습니다.Values cannot be more complex expressions such as functions, or expressions built by using operators.

반환 코드 값Return Code Values

0(성공) 또는 0이 아닌 값(실패)0 (success) or non-zero (failure)

결과 집합Result Sets

작성된 모든 SQL 문에서 SQL 문자열로 결과 집합을 반환합니다.Returns the result sets from all the SQL statements built into the SQL string.

RemarksRemarks

이 항목 앞부분에서의 "구문" 섹션에 설명 된 대로 sp_executesql 매개 변수를 특정 순서로 입력 되어야 합니다.sp_executesql parameters must be entered in the specific order as described in the "Syntax" section earlier in this topic. 매개 변수 순서가 잘못되면 오류 메시지가 나타납니다.If the parameters are entered out of order, an error message will occur.

sp_executesql은 일괄 처리, 이름의 범위 및 데이터베이스 컨텍스트 면에서 EXECUTE와 동작이 동일합니다.sp_executesql has the same behavior as EXECUTE with regard to batches, the scope of names, and database context. 합니다 Transact-SQLTransact-SQL 문 또는 일괄 처리는 sp_executesql @stmt 매개 변수는 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. 내용을 @stmt는 컴파일되고 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. sp_executesql 일괄 처리는 sp_executesql을 호출하는 일괄 처리에서 선언된 변수를 참조할 수 없습니다.The sp_executesql batch cannot reference variables declared in the batch that calls sp_executesql. sp_executesql 일괄 처리의 로컬 커서 또는 변수는 sp_executesql을 호출하는 일괄 처리에 노출되지 않습니다.Local cursors or variables in the sp_executesql batch are not visible to the batch that calls sp_executesql. 데이터베이스 컨텍스트의 변경 내용은 sp_executesql 문이 종료될 때까지만 지속됩니다.Changes in database context last only to the end of the sp_executesql statement.

문에 대한 매개 변수 값의 변경 내용이 변형뿐인 경우 저장 프로시저 대신 sp_executesql을 사용하여 Transact-SQLTransact-SQL 문을 여러 번 실행할 수 있습니다.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. Transact-SQLTransact-SQL 문 자체는 달라지지 않고 매개 변수 값만 달라지므로 SQL ServerSQL Server 쿼리 최적화 프로그램은 처음 실행할 때 생성되는 실행 계획을 다시 사용합니다.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.

참고

문의 문자열에 정규화된 개체 이름을 사용하여 성능을 향상시킬 수 있습니다.To improve performance use fully qualified object names in the statement string.

다음 예와 같이 sp_executesql은 Transact-SQLTransact-SQL 문자열과 별도로 매개 변수 값 설정을 지원합니다.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;  

출력 매개 변수는 sp_executesql에도 사용할 수 있습니다.Output parameters can also be used with sp_executesql. 다음 예에서는 AdventureWorks2012.HumanResources.Employee 테이블에서 직함을 검색하여 출력 매개 변수 @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;  

sp_executesql에서 매개 변수를 대체할 수 있으면 EXECUTE 문을 사용하여 문자열을 실행할 때 다음과 같은 이점이 있습니다.Being able to substitute parameters in sp_executesql offers the following advantages to using the EXECUTE statement to execute a string:

  • sp_executesql 문자열에 있는 Transact-SQLTransact-SQL 문의 실제 텍스트는 모든 실행에서 동일하기 때문에 쿼리 최적화 프로그램이 두 번째 실행의 Transact-SQLTransact-SQL 문과 첫 번째 실행에서 생성된 실행 계획을 일치시킬 수 있습니다.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. 따라서 SQL ServerSQL Server에서 두 번째 문을 컴파일할 필요가 없습니다.Therefore, SQL ServerSQL Server does not have to compile the second statement.

  • Transact-SQLTransact-SQL 문자열이 한 번만 작성됩니다.The Transact-SQLTransact-SQL string is built only one time.

  • 정수 매개 변수는 해당 네이티브 형식으로 지정됩니다.The integer parameter is specified in its native format. 유니코드로 캐스팅할 필요가 없습니다.Casting to Unicode is not required.

사용 권한Permissions

public 역할의 멤버 자격이 필요합니다.Requires membership in the public role.

Examples

1.A. 단순 SELECT 문 실행Executing a simple SELECT statement

다음은 SELECT이라는 포함 매개 변수를 포함한 단순 @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;  

2.B. 동적으로 작성된 문자열 실행Executing a dynamically built string

다음 예에서는 sp_executesql을 사용하여 동적으로 작성된 문자열 실행을 보여 줍니다.The following example shows using sp_executesql to execute a dynamically built string. 예로 사용된 저장 프로시저는 1년 간의 판매 데이터를 분할하기 위해 사용하는 일련의 테이블에 데이터를 삽입하는 데 사용됩니다.The example stored procedure is used to insert data into a set of tables that are used to partition sales data for a year. 해당 연도의 각 달마다 다음과 같은 형식의 테이블이 하나씩 있습니다.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)  
    )  

이 예제 저장 프로시저는 동적으로 INSERT 문을 작성하고 실행하여 새 주문을 알맞은 테이블에 삽입합니다.This sample stored procedure dynamically builds and executes an INSERT statement to insert new orders into the correct table. 이 예에서는 주문 날짜를 사용하여 데이터를 포함해야 하는 테이블의 이름을 작성한 다음 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.

참고

다음은 sp_executesql의 간단한 예입니다.This is a simple example for sp_executesql. 이 예에는 오류 검사가 포함되지 않으며 여러 테이블에서 주문 번호가 중복되지 않도록 하는 등의 비즈니스 규칙 확인이 포함되지 않습니다.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  

이 프로시저에서는 EXECUTE를 사용하는 것보다 sp_executesql을 사용하여 문자열을 실행하는 것이 효과적입니다.Using sp_executesql in this procedure is more efficient than using EXECUTE to execute a string. sp_executesql을 사용하는 경우 월별 테이블마다 하나씩 12개 버전의 INSERT 문자열만 작성됩니다.When sp_executesql is used, there are only 12 versions of the INSERT string that are generated, one for each monthly table. EXECUTE를 사용하면 매개 변수 값이 다르므로 각 INSERT 문자열이 고유합니다.With EXECUTE, each INSERT string is unique because the parameter values are different. 두 방법 모두 같은 수의 일괄 처리를 생성하지만 sp_executesql에 의해 생성된 INSERT 문자열이 서로 비슷하기 때문에 쿼리 최적화 프로그램이 실행 계획을 다시 사용하기 쉽습니다.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.

3.C. OUTPUT 매개 변수 사용Using the OUTPUT Parameter

다음 예제에서는 OUTPUT 매개 변수에서 생성 된 결과 집합을 저장 합니다 SELECT 문에서 @SQLString 매개 변수입니다. 두 개의 SELECT 문이 실행 됩니다의 값을 사용 하 여 OUTPUT 매개 변수입니다.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;  

예제: Azure SQL 데이터 웨어하우스Azure SQL Data Warehouse병렬 데이터 웨어하우스Parallel Data WarehouseExamples: Azure SQL 데이터 웨어하우스Azure SQL Data Warehouse and 병렬 데이터 웨어하우스Parallel Data Warehouse

4.D. 단순 SELECT 문 실행Executing a simple SELECT statement

다음은 SELECT이라는 포함 매개 변수를 포함한 단순 @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;  

추가 예제를 보려면 sp_executesql (TRANSACT-SQL)합니다.For additional examples, see sp_executesql (Transact-SQL).

관련 항목See Also

EXECUTE(Transact-SQL) EXECUTE (Transact-SQL)
시스템 저장 프로시저(Transact-SQL)System Stored Procedures (Transact-SQL)