FOR JSON를 사용하여 쿼리 결과를 JSON으로 포맷

적용 대상: SQL Server 2016(13.x) 이상 Azure SQL 데이터베이스 Azure SQL Managed Instance Azure Synapse Analytics (서버리스 SQL 풀 한정)

쿼리 결과 형식을 JSON으로 지정하거나, SELECT 문에 FOR JSON 절을 추가하여 데이터를 SQL Server에서 JSON으로 내보냅니다. FOR JSON 절을 사용하여 JSON 출력 형식 지정을 앱에서 SQL Server로 위임하여 클라이언트 애플리케이션을 간소화합니다.

참고 항목

Azure Data Studio는 이 문서에서 보다시피 JSON 결과에 서식을 자동으로 지정하므로 JSON 쿼리에 권장되는 쿼리 편집기입니다. SQL Server Management Studio는 형식이 지정되지 않은 문자열을 표시합니다.

쿼리 결과 서식 지정

FOR JSON 절을 사용하는 경우 JSON 출력의 구조를 명시적으로 지정하거나 SELECT 문의 구조에 따라 출력이 결정되도록 할 수 있습니다.

• JSON 출력의 형식을 완전하게 제어하려면 FOR JSON PATH를 사용합니다. 래퍼 개체를 만들고 복잡한 속성을 중첩할 수 있습니다.

• SELECT 문의 구조에 따라 JSON 출력 형식을 자동으로 지정하려면 FOR JSON AUTO를 사용합니다.

다음은 FOR JSON 절을 사용한 SELECT 문과 해당 출력의 예입니다.

FOR JSON PATH

FOR JSON PATH로 출력 제어

PATH 모드에서는 점 구문(예: Item.Price)을 사용하여 중첩 출력을 서식 지정할 수 있습니다.

다음은 FOR JSON 절에서 PATH 모드를 사용하는 샘플 쿼리입니다. 다음 예제에서는 ROOT 옵션을 사용하여 명명된 루트 요소를 지정합니다.

FOR JSON PATH에 대한 자세한 정보

더 자세한 내용과 예제는 PATH 모드로 중첩 JSON 출력 서식 지정(SQL Server)을 참조하세요.

구문 및 사용법은 FOR 절(Transact-SQL)을 참조하세요.

FOR JSON AUTO

SELECT 문은 FOR JSON AUTO를 사용하여 출력을 제어합니다.

AUTO 모드에서 SELECT 문의 구조는 JSON 출력의 형식을 결정합니다.

기본적으로 NULL 값은 출력에 포함되지 않습니다. INCLUDE_NULL_VALUES를 사용하여 이 동작을 변경할 수 있습니다.

다음은 FOR JSON 절에서 AUTO 모드를 사용하는 샘플 쿼리입니다.

SELECT name, surname
FROM emp
FOR JSON AUTO;

반환된 JSON은 다음과 같습니다.

[{
    "name": "John"
}, {
    "name": "Jane",
    "surname": "Doe"
}]

JOIN 및 NULL 예제

다음 예제 SELECT...FOR JSON AUTO에서는 조인된 테이블의 데이터 간에 1:다 관계가 있을 경우 JSON 결과의 모양을 표시합니다.

반환된 JSON에서 null 값이 없는 것도 설명합니다. 그러나 FOR 절에서 INCLUDE_NULL_VALUES 키워드를 사용하여 이 기본 동작을 재정의할 수 있습니다.

DROP TABLE IF EXISTS #tabStudent;
DROP TABLE IF EXISTS #tabClass;
GO

CREATE TABLE #tabClass (
    ClassGuid UNIQUEIDENTIFIER NOT NULL DEFAULT newid(),
    ClassName NVARCHAR(32) NOT NULL
);

CREATE TABLE #tabStudent (
    StudentGuid UNIQUEIDENTIFIER NOT NULL DEFAULT newid(),
    StudentName NVARCHAR(32) NOT NULL,
    ClassGuid UNIQUEIDENTIFIER NULL -- Foreign key.
);
GO

INSERT INTO #tabClass (ClassGuid, ClassName)
VALUES
    ('DE807673-ECFC-4850-930D-A86F921DE438', 'Algebra Math'),
    ('C55C6819-E744-4797-AC56-FF8A729A7F5C', 'Calculus Math'),
    ('98509D36-A2C8-4A65-A310-E744F5621C83', 'Art Painting');

INSERT INTO #tabStudent (StudentName, ClassGuid)
VALUES
    ('Alice Apple', 'DE807673-ECFC-4850-930D-A86F921DE438'),
    ('Alice Apple', 'C55C6819-E744-4797-AC56-FF8A729A7F5C'),
    ('Betty Boot', 'C55C6819-E744-4797-AC56-FF8A729A7F5C'),
    ('Betty Boot', '98509D36-A2C8-4A65-A310-E744F5621C83'),
    ('Carla Cap', null);
GO

SELECT c.ClassName,
    s.StudentName
FROM #tabClass AS c
RIGHT JOIN #tabStudent AS s ON s.ClassGuid = c.ClassGuid
ORDER BY c.ClassName,
    s.StudentName
FOR JSON AUTO
    -- To include NULL values in the output, uncomment the following line:
    --, INCLUDE_NULL_VALUES
    ;
GO

DROP TABLE IF EXISTS #tabStudent;
DROP TABLE IF EXISTS #tabClass;
GO

다음은 이전 SELECT에서 출력하는 JSON입니다.

JSON_F52E2B61-18A1-11d1-B105-00805F49916B

[
   {"s":[{"StudentName":"Carla Cap"}]},
   {"ClassName":"Algebra Math","s":[{"StudentName":"Alice Apple"}]},
   {"ClassName":"Art Painting","s":[{"StudentName":"Betty Boot"}]},
   {"ClassName":"Calculus Math","s":[{"StudentName":"Alice Apple"},{"StudentName":"Betty Boot"}]}
]

FOR JSON AUTO에 대한 자세한 정보

더 자세한 내용과 예제는 AUTO 모드를 사용하여 JSON 출력 형식 자동 지정(SQL Server)을 참조하세요.

구문 및 사용법은 FOR 절(Transact-SQL)을 참조하세요.

기타 JSON 출력 옵션 제어

다음의 추가 옵션을 사용하여 FOR JSON 절의 출력을 제어합니다.

• ROOT

  단일 최상위 요소를 FOR JSON 출력에 추가하려면 ROOT 옵션을 지정합니다. 이 옵션을 지정하지 않은 경우 JSON 출력에는 루트 요소가 없습니다. 자세한 내용은 ROOT 옵션을 사용하여 JSON 출력에 루트 노드 추가(SQL Server)를 참조하세요.

• INCLUDE_NULL_VALUES

  JSON 출력에 null 값을 포함하려면 INCLUDE_NULL_VALUES 옵션을 지정합니다. 이 옵션을 지정하지 않은 경우 쿼리 결과의 NULL 값에 대해서는 출력에 JSON 속성을 포함하지 않습니다. 자세한 내용은 JSON에 Null 값 포함 - INCLUDE_NULL_VALUES 옵션을 참조하세요.

• WITHOUT_ARRAY_WRAPPER

  기본적으로 FOR JSON 절의 JSON 출력을 둘러싸고 있는 대괄호를 제거하려면 WITHOUT_ARRAY_WRAPPER 옵션을 지정합니다. 이 옵션을 사용하면 단일 JSON 개체를 단일 행 결과의 출력으로 생성할 수 있습니다. 이 옵션을 지정하지 않으면 JSON 출력은 배열 형식으로 지정되어 출력이 대괄호로 묶입니다. 자세한 내용은 JSON에서 대괄호 제거 - WITHOUT_ARRAY_WRAPPER 옵션을 참조하세요.

FOR JSON 절의 출력

FOR JSON 절의 출력은 다음과 같은 특징이 있습니다.

1. 결과 집합은 단일 열로 구성됩니다.

   • 작은 결과 집합은 단일 행을 포함할 수 있습니다.
   • 결과 집합이 크면 긴 JSON 문자열이 여러 행으로 분할됩니다.

     • 기본적으로 SSMS(SQL Server Management Studio)는 출력 설정이 표 형태로 결과 표시인 경우 결과를 단일 행으로 연결합니다. SSMS 상태 표시줄에 실제 행 수가 표시됩니다.

     • 다른 클라이언트 애플리케이션에는 여러 행의 콘텐츠를 연결하여 긴 결과를 유효한 단일 JSON 문자열로 다시 조합하는 코드가 필요할 수 있습니다. C# 애플리케이션에서 이 코드의 예제는 C# 클라이언트 앱에서 FOR JSON 출력 사용을 참조하세요.

       

2. 결과는 JSON 개체의 배열로 서식 지정됩니다.

   • JSON 배열의 요소 수는 SELECT 문 결과(FOR JSON 절을 적용하기 전)의 행 수와 같습니다.

   • SELECT 문 결과(FOR JSON 절을 적용하기 전)의 각 행은 배열에서 별개의 JSON 개체가 됩니다.

   • SELECT 문 결과(FOR JSON 절을 적용하기 전)의 각 열은 JSON 개체의 속성이 됩니다.

3. 열 이름과 해당 값은 모두 JSON 구문에 따라 이스케이프됩니다. 자세한 내용은 FOR JSON이 특수 문자 및 제어 문자를 이스케이프 처리하는 방법(SQL Server)을 참조하세요.

예시

다음은 FOR JSON 절에서 JSON 출력의 형식을 지정하는 방법을 보여 주는 예제입니다.

쿼리 결과

A	B	C	D
10	11	12	X
20	21	22	Y
30	31	32	Z

JSON 출력

[{
    "A": 10,
    "B": 11,
    "C": 12,
    "D": "X"
}, {
    "A": 20,
    "B": 21,
    "C": 22,
    "D": "Y"
}, {
    "A": 30,
    "B": 31,
    "C": 32,
    "D": "Z"
}]

관련 콘텐츠

• FOR JSON을 통해 SQL Server 데이터 형식을 JSON 데이터 형식으로 변환하는 방법(SQL Server)
• FOR JSON이 특수 문자 및 제어 문자를 이스케이프 처리하는 방법(SQL Server)
• NoSQL과 관계형 세계 간의 브리지로서의 JSON
• SELECT - FOR 절(Transact-SQL)
• SQL Server 및 클라이언트 앱에서 FOR JSON 출력 사용(SQL Server)