JSON-sökvägsuttryck i SQL Database Engine

Gäller för: SQL Server 2016 (13.x) och senare versioner Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics (serverless SQL pool only)SQL database in Microsoft Fabric

Använd JSON-sökvägsuttryck för att referera till egenskaperna för JSON-objekt.

Du måste ange ett sökvägsuttryck när du anropar följande funktioner.

  • När du anropar OPENJSON för att skapa en relationsvy över JSON-data.
  • När du anropar JSON_VALUE för att extrahera ett värde från JSON-text.
  • När du anropar JSON_QUERY för att extrahera ett JSON-objekt eller en matris.
  • När du anropar JSON_MODIFY för att uppdatera värdet för en egenskap i en JSON-sträng.

Delar av ett sökvägsuttryck

Ett sökvägsuttryck har två komponenter.

  1. Det valfria sökvägsläget med värdet lax eller strict.

  2. Själva sökvägen .

Sökvägsläge

I början av sökvägsuttrycket kan du deklarera sökvägsläget genom att ange nyckelordet lax eller strict. Standardvärdet är lax.

  • I lax läget returnerar funktionen tomma värden om sökvägsuttrycket innehåller ett fel. Om du till exempel begär värdet $.name, och JSON-texten inte innehåller en name nyckel, returnerar funktionen null, men genererar inget fel.

  • I strict läge genererar funktionen ett fel om sökvägsuttrycket innehåller ett fel.

Följande fråga anger lax uttryckligen läget i sökvägsuttrycket.

DECLARE @json AS NVARCHAR (MAX);

SET @json = N'{ ... }';

SELECT *
FROM OPENJSON (@json, N'lax $.info');

Path

Efter den valfria sökvägslägesdeklarationen anger du själva sökvägen.

  • Dollartecknet ($) representerar kontextobjektet.

  • Egenskapsstigen är en serie steg längs stigen. Sökvägssteg kan innehålla följande element och operatorer.

    • Nyckelnamn. Till exempel $.name och $."first name". Om nyckelnamnet börjar med ett dollartecken eller innehåller specialtecken som blanksteg eller punktoperatorer(.) ska det omgivas med citattecken.

    • Vektorelement. Till exempel $.product[3]. Matriser är nollbaserade.

    • Punktoperatorn (.) anger en medlem i ett objekt. I $.people[1].surname är surname ett barn till people.

    • Matrisens jokertecken och intervallsökningar stöds också om indata är ett JSON-typvärde.

Stöd för jokertecken och intervall för array

ANSI SQL/JSON-pathuttryck har stöd för jokertecken för matriser. Arrayens wildcard låter dig specificera alla element, ett intervall av element, en lista av element eller den speciella token last för att ange det senaste värdet i en JSON-array. SQL/JSON-arrayer använder nollbaserade index. Du kan använda SQL/JSON-vägar med jokrar i JSON_QUERY,JSON_PATH_EXISTS och JSON_CONTAINS.

Funktionen JSON_VALUE stöder sökvägsuttrycket SQL/JSON, men returvärdet för en JSON_VALUE funktion är en SQL-skalär och därför returneras NULL alltid funktionen för alla SQL/JSON-sökvägar som pekar på ett JSON-objekt eller en matris. Endast wildcard-tecken för array stöds om indata är av typen json.

Följande syntax visar hur jokertecken, intervall och specialtoken last kan användas:

path[elements ]

elements ::= {
*
| number
| number to number
| last
| {number...[, number] }
}

Den speciella token last kan användas i stället för talvärde. Om ett intervall anges måste intervallet anges i ökande ordning.

Exempel på några giltiga SQL/JSON-sökvägsuttryck:

Path Description
$[*] Alla element
$[0] Första elementet
$[0 to 2] De tre första elementen
$[last] Sista elementet
$[last, 0] Invalid
$[last, 2, 0, last] Invalid
$.creditcards[0].type Returnerar typegenskapsvärdet för det första elementet i creditcards matrisen
$.credit_cards[*].type Returnerar typegenskapsvärdet för alla element i creditcards matrisen
$.credit_cards[0, 2].type Returnerar typegenskapsvärdet för det första och tredje elementet i creditcards matrisen
$.credit_cards[1 to 3].type Returnerar typegenskapsvärdet för det andra till fjärde elementet i creditcards matrisen
$.credit_cards[last].type Returnerar typegenskapsvärdet för det sista elementet i creditcards matrisen
$.credit_cards[last, 0].type Returnerar typegenskapsvärdet för det sista och första elementet i creditcards matrisen

Examples

Exemplen i det här avsnittet refererar till följande JSON-text.

{
    "people": [{
        "name": "John",
        "surname": "Doe"
    }, {
        "name": "Jane",
        "surname": null,
        "active": true
    }]
}

I följande tabell visas några exempel på sökvägsuttryck.

Sökvägsuttryck Value
$.people[0].name John
$.people[1] { "name": "Jane", "surname": null, "active": true }
$.people[1].surname NULL
$ { "people": [ { "name": "John", "surname": "Doe" },{ "name": "Jane", "surname": null, "active": true } ] }
$.people[last].name ["Jane"]
$.people[0 to 1].name ["John","Jane"]
$.people[0, 1].name ["John","Jane"]

Så här hanterar inbyggda funktioner duplicerade sökvägar

Om JSON-texten innehåller dubblettegenskaper – till exempel två nycklar med samma namn på samma nivå – returnerar funktionerna JSON_VALUE och JSON_QUERY endast det första värdet som matchar sökvägen. Om du vill parsa ett JSON-objekt som innehåller dubblettnycklar och returnera alla värden använder du OPENJSON, som du ser i följande exempel.

DECLARE @json AS NVARCHAR (MAX);

SET @json = N'{"person":{"info":{"name":"John", "name":"Jack"}}}';

SELECT value
FROM OPENJSON (@json, '$.person.info');

Läs mer om JSON

En visuell introduktion till det inbyggda JSON-stödet finns i följande video:

Relaterat innehåll

  • Last updated on