MSSQL 출력 파라미터 사용법과 프로시저 결과 전달 완벽 가이드

⚙️ MSSQL 출력 파라미터란?

MSSQL에서 출력 파라미터(Output Parameter)란, 저장 프로시저(Stored Procedure)나 함수(Function)에서 실행 후 결과를 호출한 쪽으로 반환하는 특별한 매개변수입니다.
일반적으로 SELECT문을 통해 결과를 반환할 수도 있지만, 특정한 계산값이나 상태 코드, 처리 여부와 같이 하나의 값만 간단히 전달하고 싶을 때 출력 파라미터가 더 효율적입니다.

출력 파라미터는 다음과 같은 상황에서 특히 유용합니다.
프로시저 내부에서 조건문과 반복문을 거쳐 최종적인 결과값을 계산해야 하는 경우, 그 값을 호출한 프로그램에 직접 전달할 수 있습니다.
또한, 단순히 데이터 자체가 아니라 처리 성공 여부나 에러 코드를 반환하는 데에도 자주 사용됩니다.
이렇게 하면 SELECT 결과를 파싱하지 않아도 되기 때문에, 애플리케이션 코드가 간결해지고 성능도 향상됩니다.

💬 OUTPUT 파라미터는 단순한 데이터 반환이 아니라, 로직 제어와 상태 관리에도 적극 활용되는 기능입니다.

MSSQL에서 출력 파라미터를 선언할 때는 변수 이름 옆에 OUTPUT 키워드를 붙입니다.
이 키워드는 프로시저 선언부뿐만 아니라 호출부에서도 동일하게 명시해야 하며, 그렇지 않으면 값이 반환되지 않습니다.

CREATE PROCEDURE usp_GetOrderCount
    @CustomerID NVARCHAR(10),
    @OrderCount INT OUTPUT
AS
BEGIN
    SELECT @OrderCount = COUNT(*)
    FROM Orders
    WHERE CustomerID = @CustomerID
END

위 예시에서 @OrderCount가 바로 출력 파라미터입니다.
프로시저가 실행되면 고객 ID에 해당하는 주문 건수를 계산해 @OrderCount 변수에 담아 호출한 쪽으로 반환하게 됩니다.
이 방식은 결과 집합이 아닌 단일 값만 필요할 때 매우 간편합니다.

🛠️ OUTPUT 파라미터 선언과 기본 사용법

OUTPUT 파라미터를 사용하려면 프로시저 정의 시 매개변수에 OUTPUT 키워드를 반드시 붙여야 합니다.
그리고 호출하는 쪽에서도 동일하게 OUTPUT을 명시해야 값이 반환됩니다.
이 부분을 놓치면 프로시저는 정상 실행되더라도 호출부에서 값이 비어 있는 상황이 발생할 수 있습니다.

기본적인 사용 순서는 다음과 같습니다.
먼저, 프로시저 내부에서 특정 값을 계산하거나 조회하여 OUTPUT 변수에 대입합니다.
그 다음, 호출하는 곳에서 미리 변수를 선언하고, 해당 변수를 OUTPUT 인자로 전달하면 프로시저 실행 후 해당 변수에 값이 저장됩니다.

• 🛠️프로시저 선언부에서 OUTPUT 명시
• ⚙️호출부에서도 동일하게 OUTPUT 키워드 기재
• 🔌반환받을 변수는 호출 전 반드시 선언

-- 프로시저 정의
CREATE PROCEDURE usp_GetProductStock
    @ProductID INT,
    @StockQty INT OUTPUT
AS
BEGIN
    SELECT @StockQty = StockQuantity
    FROM Products
    WHERE ProductID = @ProductID
END
GO

-- 호출 예시
DECLARE @CurrentStock INT;
EXEC usp_GetProductStock @ProductID = 101, @StockQty = @CurrentStock OUTPUT;

PRINT @CurrentStock; -- 재고 수량 출력

위 예제에서는 @StockQty가 OUTPUT 파라미터로 선언되었고, 호출 시에도 OUTPUT 키워드가 붙었습니다.
이렇게 하면 프로시저가 조회한 재고 수량이 @CurrentStock 변수에 저장되어 이후 로직에서 자유롭게 활용할 수 있습니다.

💡 프로시저 내부 계산 결과 전달하기

OUTPUT 파라미터의 가장 대표적인 활용 예시는 프로시저 내부에서 계산된 결과를 외부로 전달하는 것입니다.
예를 들어, 특정 고객의 주문 금액 총합이나, 조건에 맞는 데이터 건수를 계산한 뒤 이를 호출한 애플리케이션에서 바로 활용할 수 있습니다.
이 방식은 특히 보고서 생성, 통계 처리, 실시간 알림 등과 같이 빠른 데이터 반환이 필요한 업무에 적합합니다.

계산 결과를 OUTPUT 파라미터로 반환하면, SELECT문으로 결과 집합을 전송하는 경우보다 네트워크 부하가 적고, 애플리케이션 로직에서 별도로 집계 로직을 구현할 필요가 없어집니다.
이 덕분에 코드 유지보수가 훨씬 용이해지고 성능 최적화에도 도움이 됩니다.

💬 OUTPUT 파라미터는 단순 조회를 넘어, 서버 쪽에서 데이터를 가공해 즉시 전달하는 데 강점을 가집니다.

CREATE PROCEDURE usp_GetCustomerTotalAmount
    @CustomerID NVARCHAR(10),
    @TotalAmount MONEY OUTPUT
AS
BEGIN
    SELECT @TotalAmount = SUM(OrderAmount)
    FROM Orders
    WHERE CustomerID = @CustomerID
END
GO

DECLARE @Amount MONEY;
EXEC usp_GetCustomerTotalAmount @CustomerID = 'ALFKI', @TotalAmount = @Amount OUTPUT;

PRINT '총 주문 금액: ' + CAST(@Amount AS NVARCHAR);

이 예제에서 @TotalAmount는 고객의 총 주문 금액을 담는 OUTPUT 파라미터입니다.
프로시저 실행이 끝나면 외부 변수 @Amount에 계산된 값이 저장되어 즉시 활용할 수 있습니다.
이처럼 집계 작업이 많은 시스템에서는 OUTPUT 파라미터를 통해 애플리케이션의 처리 속도를 크게 높일 수 있습니다.

📈 다중 결과 반환 시 OUTPUT 파라미터 활용

하나의 프로시저에서 여러 개의 값을 반환해야 할 때도 OUTPUT 파라미터가 유용합니다.
예를 들어, 고객 정보와 최근 주문 수, 총 구매 금액을 한 번에 가져와야 한다면, 세 개의 OUTPUT 파라미터를 선언하여 각 값을 전달할 수 있습니다.
이 방식은 결과 집합을 여러 번 나눠 전송하지 않고도 필요한 데이터를 일괄적으로 받을 수 있다는 장점이 있습니다.

또한 다중 결과 반환은 API나 외부 시스템과 연동 시 성능을 높이는 데 도움을 줍니다.
SELECT문을 여러 번 호출하거나, 애플리케이션에서 별도 계산을 하지 않아도 되므로, 네트워크 부하와 서버 처리량을 동시에 줄일 수 있습니다.

CREATE PROCEDURE usp_GetCustomerStats
    @CustomerID NVARCHAR(10),
    @Name NVARCHAR(100) OUTPUT,
    @OrderCount INT OUTPUT,
    @TotalAmount MONEY OUTPUT
AS
BEGIN
    SELECT 
        @Name = CustomerName,
        @OrderCount = COUNT(*),
        @TotalAmount = SUM(OrderAmount)
    FROM Customers c
    JOIN Orders o ON c.CustomerID = o.CustomerID
    WHERE c.CustomerID = @CustomerID
    GROUP BY CustomerName
END
GO

DECLARE 
    @CustName NVARCHAR(100),
    @Orders INT,
    @Amount MONEY;

EXEC usp_GetCustomerStats 
    @CustomerID = 'ALFKI', 
    @Name = @CustName OUTPUT,
    @OrderCount = @Orders OUTPUT,
    @TotalAmount = @Amount OUTPUT;

PRINT '고객명: ' + @CustName;
PRINT '주문 건수: ' + CAST(@Orders AS NVARCHAR);
PRINT '총 금액: ' + CAST(@Amount AS NVARCHAR);

위 예제에서는 세 개의 OUTPUT 파라미터를 통해 고객명, 주문 건수, 총 구매 금액을 한 번에 반환합니다.
이렇게 하면 데이터를 각각 SELECT해서 받아오는 것보다 훨씬 효율적이며, 호출부 코드도 간결해집니다.

⚠️ OUTPUT 파라미터 사용 시 주의사항

OUTPUT 파라미터는 매우 유용하지만, 올바르게 사용하지 않으면 의도한 값을 받지 못하거나 예기치 않은 버그가 발생할 수 있습니다.
특히, 프로시저 선언부와 호출부 모두에서 OUTPUT 키워드를 빼먹는 실수가 자주 발생하므로 반드시 확인해야 합니다.

또한 OUTPUT 파라미터에 값을 할당하지 않으면 기본적으로 NULL이 반환됩니다.
따라서 조건문 안에서만 값을 설정하는 경우에는 모든 분기에서 변수가 할당되도록 하거나, 초기에 기본값을 세팅하는 습관이 필요합니다.

• 🛠️선언부와 호출부 모두에서 OUTPUT 명시
• ⚙️값을 할당하지 않으면 NULL 반환
• 🔌RETURN 값과 OUTPUT 파라미터의 용도를 혼동하지 않기

CREATE PROCEDURE usp_TestOutput
    @Value INT OUTPUT
AS
BEGIN
    -- 기본값 설정
    SET @Value = 0;

    IF (SELECT COUNT(*) FROM Orders) > 0
        SET @Value = 100;
END
GO

DECLARE @Result INT;
EXEC usp_TestOutput @Value = @Result OUTPUT;
PRINT @Result; -- 0 또는 100

위 예시처럼 OUTPUT 파라미터에 기본값을 세팅하면, 조건이 맞지 않아도 NULL 대신 안전한 값이 반환됩니다.
이렇게 하면 호출하는 쪽에서 예상치 못한 NULL 예외를 방지할 수 있습니다.

❓ 자주 묻는 질문 (FAQ)