Lekérdezési eredmények formázása JSON-ként a FOR JSON használatával

Vonatkozik a következőkre: SQL Server 2016 (13.x) és későbbi verziók Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics (csak szerver nélküli SQL pool)SQL analytics endpoint a Microsoft FabricbanTárház a Microsoft FabricbanAdatbázis a Microsoft Fabricban

A lekérdezési eredmények formázása JSON-ként, vagy adatok exportálása az SQL Serverből JSON-ként a FOR JSON záradék SELECT utasításhoz való hozzáadásával. Az FOR JSON záradék használatával egyszerűsítheti az ügyfélalkalmazásokat az alkalmazás JSON-kimenetének az SQL Serverre való delegálásával.

Note

Az Azure Data Studio a JSON-lekérdezések ajánlott lekérdezésszerkesztője, mert automatikusan formázja a JSON-eredményeket, ahogyan az ebben a cikkben látható. Az SQL Server Management Studio formázatlan sztringet jelenít meg.

A Fabric Data Warehouse-ban FOR JSON kell lennie a lekérdezés utolsó operátorának, ezért nem engedélyezett az al lekérdezésekben.

Lekérdezési eredmények formázása

A FOR JSON záradék használatakor explicit módon megadhatja a JSON-kimenet struktúráját, vagy engedélyezheti, hogy a SELECT utasítás szerkezete határozza meg a kimenetet.

• A JSON-kimenet formátumának teljes vezérléséhez használja a FOR JSON PATH. Burkolóobjektumokat hozhat létre, és összetett tulajdonságokat ágyazhat be.

• Ha a JSON-kimenetet a SELECT utasítás struktúrája alapján szeretné automatikusan formázni, használja a FOR JSON AUTO.

Íme egy példa egy SELECT utasításra a FOR JSON záradékkal és kimenetével.

JSON-ELÉRÉSI ÚT

Kimenet szabályozása a FOR JSON PATH használatával

PATH módban a pontszintaxis ( például Item.Price ) használatával formázhatja a beágyazott kimenetet.

Íme egy minta lekérdezés, amely PATH módot használ a FOR JSON záradékkal. Az alábbi példa a ROOT lehetőséget is használja egy elnevezett gyökérelem megadásához.

További információ a FOR JSON PATH-ról

Részletesebb információkért és példákért lásd: Beágyazott JSON-kimenet formázása PATH móddal.

A szintaxisról és a használatról lásd a SELECT - FOR kifejezést (Transact-SQL).

A JSON AUTO

A SELECT utasítás a kimenetet a FOR JSON AUTO használatával vezérli

AUTO módban a SELECT utasítás szerkezete határozza meg a JSON-kimenet formátumát.

Alapértelmezés szerint NULL értékek nem szerepelnek a kimenetben. A INCLUDE_NULL_VALUES használatával módosíthatja ezt a viselkedést.

Íme egy minta lekérdezés, amely AUTO módot használ a FOR JSON záradékkal.

SELECT name, surname
FROM emp
FOR JSON AUTO;

És itt van a visszaadott JSON.

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

Példa JOIN és NULL

Az alábbi SELECT...FOR JSON AUTO példa azt mutatja be, hogy a JSON-eredmények hogyan néznek ki, ha 1:több kapcsolat van az összekapcsolt táblák adatai között.

A visszaadott JSON null értékének hiánya is látható. Ezt az alapértelmezett viselkedést azonban felülbírálhatja a INCLUDE_NULL_VALUES záradék FOR kulcsszójának használatával.

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

A következő pedig az a JSON, amelyet az előző SELECT kimenete ad ki.

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"}]}
]

További információ a FOR JSON AUTO-ról

Részletesebb információkért és példákért lásd: A JSON-kimenet automatikus formázása AUTOMATIKUS móddal.

A szintaxisról és a használatról lásd a SELECT - FOR kifejezést (Transact-SQL).

Egyéb JSON-kimeneti beállítások szabályozása

A FOR JSON záradék kimenetének szabályozása az alábbi további lehetőségek használatával.

• ROOT

  Ha egyetlen legfelső szintű elemet szeretne hozzáadni a JSON-kimenethez, adja meg a ROOT beállítást. Ha nem adja meg ezt a beállítást, a JSON-kimenetnek nincs gyökéreleme. További információért lásd A JSON-kimenethez való gyökércsomópont hozzáadását a ROOT beállítással.

• INCLUDE_NULL_VALUES

  Ha null értékeket szeretne belefoglalni a JSON-kimenetbe, adja meg a INCLUDE_NULL_VALUES beállítást. Ha nem adja meg ezt a beállítást, a kimenet nem tartalmazza NULL értékek JSON-tulajdonságait a lekérdezés eredményében. További információ: Null értékek belefoglalása a JSON-ban – INCLUDE_NULL_VALUES Beállítás.

• WITHOUT_ARRAY_WRAPPER

  Ha alapértelmezés szerint el szeretné távolítani a FOR JSON záradék JSON-kimenetét körülvevő szögletes zárójeleket, adja meg a WITHOUT_ARRAY_WRAPPER beállítást. Ezzel a beállítással egyetlen JSON-objektumot hozhat létre egy egysoros eredmény kimeneteként. Ha nem adja meg ezt a beállítást, a JSON-kimenet tömbként van formázva, vagyis a kimenet szögletes zárójelek közé van zárva. További információért lásd: Szögletes zárójelek eltávolítása a JSON-ból – WITHOUT_ARRAY_WRAPPER opció.

A FOR JSON záradék kimenete

A FOR JSON záradék kimenete a következő jellemzőkkel rendelkezik:

1. Az eredményhalmaz egyetlen oszlopot tartalmaz.

   • A kis eredményhalmazok egyetlen sort tartalmazhatnak.
   • Egy nagy eredményhalmaz több sorra osztja a hosszú JSON-sztringet.

     • Az SQL Server Management Studio (SSMS) alapértelmezés szerint egyetlen sorba fűzi az eredményeket, ha a kimeneti beállítás Eredmények rácsbavan beállítva. Az SSMS állapotsávja megjeleníti a tényleges sorok számát.

     • Más ügyfélalkalmazások esetében előfordulhat, hogy több sor tartalmának összefűzésével kódra van szükség a hosszú eredmények egyetlen érvényes JSON-sztringbe való újrakombinálásához. Egy C#-alkalmazás kódjára példa: JSON-kimenet használata C#-ügyfélalkalmazásban.

       

2. Az eredmények JSON-objektumok tömbjeként vannak formázva.

   • A JSON-tömb elemeinek száma megegyezik a SELECT utasítás eredményében szereplő sorok számával (a FOR JSON záradék alkalmazása előtt).

   • A SELECT utasítás eredményeinek minden sora (a FOR JSON záradék alkalmazása előtt) külön JSON-objektum lesz a tömbben.

   • A SELECT utasítás eredményeinek minden oszlopa (a FOR JSON záradék alkalmazása előtt) a JSON-objektum tulajdonságává válik.

3. Az oszlopok nevei és értékei a JSON-szintaxis szerint vannak elkerülve. További információért lásd: Hogyan fordítja el a FOR JSON a speciális és vezérlő karaktereket.

Example

Íme egy példa, amely bemutatja, hogy a FOR JSON záradék hogyan formázta a JSON-kimenetet.

Lekérdezési eredmények

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

JSON-kimenet

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

Kapcsolódó tartalom

• Hogyan konvertálja a JSON az SQL Server-adattípusokat JSON-adattípusokká?
• Hogyan kezeli az FOR JSON a speciális és vezérlő karaktereket
• Videó: A JSON mint híd a NoSQL és a relációs világok között
• SELECT - FOR záradék (Transact-SQL)
• A FOR JSON-kimenet használata az SQL Database Engine-ben és az ügyfélalkalmazásokban