JSON_VALUE (Transact-SQL)

A következőkre vonatkozik: Az SQL Server 2016 (13.x) és újabb verziói Az Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsSQL Analytics végpontja a Microsoft FabricWarehouse-ban a Microsoft FabricSQL Database-ben a Microsoft Fabricben

JSON_VALUE A szintaxis használatával skaláris értéket nyerhet ki egy JSON-sztringből.

Ha skaláris érték helyett JSON-sztringből szeretne kinyerni egy objektumot vagy tömböt, olvassa el a JSON_QUERY. A különbségekről JSON_VALUEJSON_QUERYa JSON_VALUE és a JSON_QUERY összehasonlítása című témakörben olvashat.

Transact-SQL szintaxis konvenciók

Syntax

Az SQL Server 2025 (17.x) és újabb verzióinak szintaxisa.

JSON_VALUE ( expression , path [ RETURNING data_type ] )

Note

Az SQL Server 2022 -ben (16.x) és a korábbi verziókban a RETURNING nem szerepel.

Arguments

expression

Olyan kifejezés, amely általában egy változó vagy egy JSON-szöveget tartalmazó oszlop neve.

Ha JSON_VALUE a kifejezésben érvénytelen JSON-t talál, mielőtt megkeresi az elérési út által azonosított értéket, a függvény hibát ad vissza. Ha JSON_VALUE nem találja az elérési út által azonosított értéket, a teljes szöveget megvizsgálja, és hibát ad vissza, ha olyan JSON-t talál, amely a kifejezésben sehol nem érvényes.

path

A JSON elérési út, amely megadja a kinyerni kívánt tulajdonságot. További információ: JSON-elérésiút-kifejezések az SQL Database Engine-ben.

Az SQL Server 2017-ben (14.x) és az Azure SQL Database-ben megadhat egy változót az elérési út értékeként.

Ha az elérési út formátuma érvénytelen, JSON_VALUE hibát ad vissza.

data_type

A visszatérési értékhez használni kívánt adattípus. Ez a típus csak akkor támogatott, ha a bemenet JSON-típus. A támogatott adattípusok a következők: tinyint, smallint, int, bigint, decimal, numerikus, float, real, char, varchar, varchar(max), nchar, nvarchar, nvarchar(max), date, time, datetime2 és datetimeoffset.

Visszaadott érték

Érvényes: SQL Server 2025 (17.x) és újabb verziók.

Ha nem tartalmazza a következőt RETURNING:

• Egy nvarchar(4000) típusú szöveges értéket ad vissza. A visszaadott érték rendezése megegyezik a bemeneti kifejezés rendezésével.

• Ha az érték nagyobb, mint 4000 karakter:

  • Hasad módban a JSON_VALUE visszaadott NULLérték.
  • Szigorú módban JSON_VALUE hibát ad vissza.

  Ha 4000 karakternél nagyobb skaláris értékeket kell visszaadnia, használja OPENJSON a helyett.JSON_VALUE További információ: OPENJSON.

Ha a következőt adja meg RETURNING:

A data_type megadott értéket adja vissza. A támogatott adattípusok a következők: tinyint, smallint, int, bigint, decimal, numerikus, float, real, char, varchar, varchar(max), nchar, nvarchar, nvarchar(max), date, time, datetime2 és datetimeoffset.

A JSON-függvények ugyanúgy működnek, mint a JSON-dokumentum varcharban, nvarcharban vagy natív JSON-adattípusban .

Remarks

Hasadt mód és szigorú mód

Vegye figyelembe a következő JSON-szöveget:

DECLARE @jsonInfo AS NVARCHAR (MAX);

SET @jsonInfo = N'{
     "info":{
       "type":1,
       "address":{
         "town":"Bristol",
         "county":"Avon",
         "country/region":"England"
       },
       "tags":["Sport", "Water polo"]
    },
    "type":"Basic"
 }';

Az alábbi táblázat a JSON_VALUE viselkedését hasonlítja össze laza módban és szigorú módban. Az opcionális elérésiút-mód specifikációjáról (lax vagy szigorú) további információt az SQL Database Engine JSON-elérésiút-kifejezéseiben talál.

Path	Visszatérési érték hasadó módban	Érték visszaadott értéke szigorú módban	További információk
$	NULL	Error	Nem skaláris érték. A JSON_QUERY használható helyette.
$.info.type	N'1'	N'1'	N/a
$.info.address.town	N'Bristol'	N'Bristol'	N/a
$.info." cím"	NULL	Error	Nem skaláris érték. A JSON_QUERY használható helyette.
$.info.tags	NULL	Error	Nem skaláris érték. A JSON_QUERY használható helyette.
$.info.type[0]	NULL	Error	Nem tömb.
$.info.none	NULL	Error	A tulajdonság nem létezik.

Examples

1. példa

Az alábbi példa a JSON-tulajdonságok townstate és a lekérdezési eredmények értékeit használja. Mivel JSON_VALUE megőrzi a forrás rendezését, az eredmények rendezési sorrendje az oszlop rendezésétől jsonInfo függ.

Note

Ez a példa feltételezi, hogy egy névvel ellátott Person.Person tábla JSON-szövegoszlopot jsonInfo tartalmaz, és hogy ez az oszlop a korábban a hasáb mód és a szigorú mód megvitatása során látható struktúrával rendelkezik. AdventureWorks A mintaadatbázisban a Person tábla nem tartalmaz oszlopotjsonInfo.

SELECT FirstName,
       LastName,
       JSON_VALUE(jsonInfo, '$.info.address.town') AS Town
FROM Person.Person
WHERE JSON_VALUE(jsonInfo, '$.info.address.state') LIKE 'US%'
ORDER BY JSON_VALUE(jsonInfo, '$.info.address.town');

2. példa

Az alábbi példa a JSON tulajdonság town értékét egy helyi változóba nyeri ki.

DECLARE @jsonInfo AS NVARCHAR (MAX);
DECLARE @town AS NVARCHAR (32);

SET @jsonInfo = N'{"info":{"address":[{"town":"Paris"},{"town":"London"}]}}';
SET @town = JSON_VALUE(@jsonInfo, '$.info.address[0].town'); -- Paris
SET @town = JSON_VALUE(@jsonInfo, '$.info.address[1].town'); -- London

3. példa

Az alábbi példa a JSON-tulajdonságok értékei alapján hoz létre számított oszlopokat.

CREATE TABLE dbo.Store
(
    StoreID INT IDENTITY (1, 1) NOT NULL,
    Address VARCHAR (500),
    jsonContent NVARCHAR (4000),
    Longitude AS JSON_VALUE(jsonContent, '$.address[0].longitude'),
    Latitude AS JSON_VALUE(jsonContent, '$.address[0].latitude')
);

4. példa

Az alábbi példa egy JSON-tömbből JSON_VALUE nyer ki egy értéket dátumtípus-értékként, és visszaadja az értéket.

DECLARE @j AS JSON = '[1, 1.3333, true, "a", "1", "2025-01-01"]';

SELECT JSON_VALUE(@j, '$[5]' RETURNING date) AS date_value;

date_value
--------
2025-01-01

Kapcsolódó tartalom

• JSON-elérésiút-kifejezések az SQL Database Engine-ben
• JSON-adatok AZ SQL Server