다음을 통해 공유

JSON_QUERY(Transact-SQL)

적용 대상: Microsoft Fabric의 Microsoft Fabric Warehouse에 있는 SQL Server 2016(13.x) 이상 Azure SQL Database Azure SQL Managed Instance Azure Synapse AnalyticsSQL 분석 엔드포인트

JSON 문자열에서 개체 또는 배열을 추출합니다.

개체 또는 배열 대신 JSON 문자열에서 스칼라 값을 추출하려면 JSON_VALUE 참조하세요. JSON_VALUE와 JSON_QUERY의 차이점에 대한 정보는, JSON_VALUE 및 JSON_QUERY 비교를 참조하세요.

Transact-SQL 구문 표기 규칙

구문

JSON_QUERY ( expression [ , path ] [WITH ARRAY WRAPPER])

인수

표현식

식입니다. 일반적으로 JSON 텍스트를 포함하는 변수 또는 열의 이름입니다.

JSON_QUERY로 식별된 값을 찾기 전에 식에서 유효하지 않은 JSON을 찾으면 함수는 오류를 반환합니다. JSON_QUERY 경로로 식별된 값을 찾지 못하면 전체 텍스트를 검색하고 식에서 유효하지 않은 JSON을 찾으면 오류를 반환합니다.

경로

추출할 개체 또는 배열을 지정하는 JSON 경로입니다.

SQL Server 2017(14.x) 및 Azure SQL Database에서 path 값으로 변수를 제공할 수 있습니다.

JSON 경로는 구문 분석을 위해 lax 또는 strict 모드를 지정할 수 있습니다. 구문 분석 모드를 지정하지 않으면 lax 모드가 기본값입니다. 자세한 내용은 JSON 경로 식(SQL Server)을 참조하세요.

경로의 기본값은 .입니다$. 결과적으로 경로에 값을 제공하지 않으면 JSON_QUERY이(가) 입력된 식을 반환합니다.

경로의 형식이 유효하지 않으면 JSON_QUERY이(가) 오류를 반환합니다.

WITH ARRAY WRAPPER

비고

WITH ARRAY WRAPPER 는 현재 미리 보기 상태이며 SQL Server 2025(17.x) 미리 보기에서만 사용할 수 있습니다.

ANSI SQL JSON_QUERY 함수는 현재 지정된 경로에서 JSON 개체 또는 배열을 반환하는 데 사용됩니다. SQL Server 2025(17.x) 미리 보기 에 도입된 SQL/JSON 경로 식에서 JSON_QUERY를 지원하여 각 요소가 JSON 개체인 JSON 배열에 있는 요소의 지정된 속성을 반환하는 데 사용할 수 있습니다. 와일드카드 검색은 여러 값을 반환할 수 있으므로 JSON 쿼리 식에 와일드카드 또는 범위 또는 목록이 있는 SQL/JSON 경로 식과 함께 절을 지정 WITH ARRAY WRAPPER 하여 값을 JSON 배열로 반환합니다. WITH ARRAY WRAPPER 절은 입력이 json 형식인 경우에만 지원됩니다.

다음 JSON 문서를 고려합니다.

declare @j JSON = '{
    "id": 2,
    "first_name": "Mamie",
    "last_name": "Baudassi",
    "email": "mbaudassi1@abc.net.au",
    "gender": "Female",
    "ip_address": "148.199.129.123",
    "credit_cards": [
        {
            "type": "jcb",
            "card#": "3545138777072343",
            "currency": "Koruna"
        },
        {
            "type": "diners-club-carte-blanche",
            "card#": "30282304348533",
            "currency": "Dong"
        },
        {
            "type": "jcb",
            "card#": "3585303288595361",
            "currency": "Yuan Renminbi"
        },
        {
            "type": "maestro",
            "card#": "675984450768756054",
            "currency": "Rupiah"
        },
        {
            "type": "instapayment",
            "card#": "6397068371771473",
            "currency": "Euro"
        }
    ]
}';

경로 $.credit_cards 는 각 요소가 유효한 JSON 개체인 JSON 배열을 가리킵니다. JSON_QUERY 이제 배열 와일드카드 지원과 함께 함수를 사용하여 다음과 같은 속성의 type 모든 또는 특정 값을 반환할 수 있습니다.

SELECT JSON_QUERY(@j, '$.creditcards[*].type' WITH ARRAY WRAPPER);

다음 표에서는 와일드카드가 있는 SQL/JSON 경로 식과 다음을 사용하는 반환 값의 다양한 예제를 JSON_QUERY WITH ARRAY WRAPPER보여 줍니다.

경로 반환 값
$.creditcards[0].type ["jcb"]
$.credit_cards[*].type ["jcb","diners-club-carte-blanche","jcb","maestro","instapayment"]
$.credit_cards[0, 2].type ["jcb","jcb"]
$.credit_cards[1 to 3].type ["diners-club-carte-blanche","jcb","maestro"]
$.credit_cards[last].type ["instapayment"]
$.credit_cards[last, 0].type ["instapayment","jcb"]
$.credit_cards[last, last].type ["instapayment","instapayment"]
$.credit_cards[ 0, 2, 4].type ["jcb","jcb","instapayment"]

반환 값

nvarchar(max) 형식의 JSON 조각을 반환합니다. 반환된 값의 데이터 정렬은 입력된 식의 데이터 정렬과 동일합니다.

값이 개체 또는 배열이 아닌 경우:

  • lax 모드에서는 JSON_QUERY이(가) null을 반환합니다.

  • strict 모드에서는 JSON_QUERY이(가) 오류를 반환합니다.

설명

lax 모드와 strict 모드

다음 JSON 텍스트를 살펴보십시오.

{
   "info": {
      "type": 1,
      "address": {
         "town": "Cheltenham",
         "county": "Gloucestershire",
         "country": "England"
      },
      "tags": ["Sport", "Water polo"]
   },
   "type": "Basic"
}

다음 표에서는 lax 모드 및 strict 모드에서 JSON_QUERY의 동작을 비교합니다. 선택적 경로 모드 사양(lax 또는 strict)에 대한 자세한 내용은 JSON 경로 식(SQL Server)을 참조하세요.

경로 lax 모드에서 값을 반환합니다. strict 모드에서 값을 반환합니다. 추가 정보
$ 전체 JSON 텍스트를 반환합니다. 전체 JSON 텍스트를 반환합니다.
$.info.type NULL 오류 개체 또는 배열이 아닙니다.

대신 JSON_VALUE를 사용하세요.
$.info.address.town NULL 오류 개체 또는 배열이 아닙니다.

대신 JSON_VALUE를 사용하세요.
$.info."address" N'{ "town":"Cheltenham", "county":"Gloucestershire", "country":"England" }' N'{ "town":"Cheltenham", "county":"Gloucestershire", "country":"England" }'
$.info.tags N'[ "Sport", "Water polo"]' N'[ "Sport", "Water polo"]'
$.info.type[0] NULL 오류 배열이 아닙니다.
$.info.none NULL 오류 속성이 없습니다.

FOR JSON과 함께 JSON_QUERY 사용

JSON_QUERY는 유효한 JSON 조각을 반환합니다. 따라서 FOR JSONJSON_QUERY 반환 값에서 특수 문자를 이스케이프하지 않습니다.

FOR JSON을 사용하여 결과를 반환하고 이미 JSON 형식인 데이터(열 또는 식의 결과)를 포함하는 경우 JSON_QUERY 매개 변수 없이 로 JSON 데이터를 래핑하세요.

예제

A. JSON 조각 반환

다음 예에서는 쿼리 결과의 CustomFields 열에서 JSON 조각을 반환하는 방법을 보여줍니다.

SELECT PersonID,
       FullName,
       JSON_QUERY(CustomFields, '$.OtherLanguages') AS Languages
FROM Application.People;

B. FOR JSON 출력에 JSON 조각 포함

다음 예에서는 FOR JSON 절의 출력에 JSON 조각을 포함하는 방법을 보여줍니다.

SELECT StockItemID,
       StockItemName,
       JSON_QUERY(Tags) AS Tags,
       JSON_QUERY(CONCAT('["', ValidFrom, '","', ValidTo, '"]')) AS ValidityPeriod
FROM Warehouse.StockItems
FOR JSON PATH;

C. JSON_QUERY 함수와 함께 WITH ARRAY WRAPPER 사용

다음 예제에서는 함수를 사용하여 WITH ARRAY WRAPPERJSON_QUERY JSON 배열에서 여러 요소를 반환하는 방법을 보여줍니다.

DECLARE @j JSON = ' {"id":2,"first_name":"Mamie","last_name":"Baudassi","email":"mbaudassi1@abc.net.au","gender":"Female","ip_address":"148.199.129.123","credit_cards":[{"type":"jcb","card#":"3545138777072343","currency":"Koruna"},{"type":"diners-club-carte-blanche","card#":"30282304348533","currency":"Dong"},{"type":"jcb","card#":"3585303288595361","currency":"Yuan Renminbi"},{"type":"maestro","card#":"675984450768756054","currency":"Rupiah"},{"type":"instapayment","card#":"6397068371771473","currency":"Euro"}]}
';
SELECT JSON_QUERY(@j, '$.credit_cards[*].type' WITH ARRAY WRAPPER ) as credit_card_types;

결과 집합은 다음과 같습니다.

credit_card_types
--------
["jcb","diners-club-carte-blanche","jcb","maestro","instapayment"]

관련 콘텐츠