Formátujte výsledky dotazu jako JSON pomocí FOR JSON

Platí pro: SQL Server 2016 (13.x) a novější verze Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics (pouze bezserverový fond SQL)Koncový bod analýzy SQL ve službě Microsoft FabricSklad v Microsoft FabricSQL databáze v Microsoft Fabric

Naformátujte výsledky dotazu jako JSON nebo exportujte data z SQL Serveru jako JSON přidáním klauzule FOR JSON do příkazu SELECT. Pomocí klauzule FOR JSON zjednodušte klientské aplikace delegováním formátování výstupu JSON z aplikace na SQL Server.

Note

Rozšíření MSSQL pro Visual Studio Code může automaticky formátovat výsledky JSON (jak je vidět v tomto článku) místo zobrazení neformátovaného řetězce.

Ve službě Fabric Data Warehouse FOR JSON musí být posledním operátorem v dotazu, takže ho nemůžete použít v poddotazech.

Formátování výsledků dotazu

Při použití klauzule FOR JSON můžete explicitně zadat strukturu výstupu JSON nebo nechat strukturu příkazu SELECT určit výstup.

• Pokud chcete zachovat úplnou kontrolu nad formátem výstupu JSON, použijte FOR JSON PATH. Můžete vytvořit objekty obálky a vnořit složité vlastnosti.

• Pokud chcete formátovat výstup JSON automaticky na základě struktury příkazu SELECT, použijte FOR JSON AUTO.

Tady je příklad příkazu SELECT s klauzulí FOR JSON a jejím výstupem.

pro

Řízení výstupu pomocí příkazu FOR JSON PATH

V PATH režimu použijte syntaxi tečky (například Item.Price) k formátování vnořeného výstupu.

Tady je ukázkový dotaz, který používá režim PATH s klauzulí FOR JSON. Následující příklad také používá možnost ROOT k zadání pojmenovaného kořenového elementu.

Další informace o příkazu FOR JSON PATH

Podrobnější informace a příklady najdete v tématu Formátování vnořeného výstupu JSON s režimem PATH.

Syntaxe a použití najdete v tématu SELECT – KLAUZULE FOR.

pro JSON automatické

Výstup ovládacích prvků příkazů SELECT pomocí příkazu FOR JSON AUTO

V AUTO režimu určuje struktura příkazu SELECT formát výstupu JSON.

Ve výchozím nastavení výstup neobsahuje NULL hodnoty. Slouží INCLUDE_NULL_VALUES ke změně tohoto chování.

Tady je ukázkový dotaz, který používá režim AUTO s klauzulí FOR JSON.

SELECT name,
       surname
FROM emp
FOR JSON AUTO;

A tady je vrácený JSON.

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

Příklad s JOIN a NULL

Následující příklad SELECT...FOR JSON AUTO ukazuje, jak vypadají výsledky JSON, když existuje relace 1:N mezi daty z připojených tabulek.

Tento příklad také ukazuje, že hodnota null se ve vráceném formátu JSON nezobrazí. Toto výchozí chování ale můžete přepsat pomocí klíčového INCLUDE_NULL_VALUES slova v klauzuli FOR .

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

Dále je JSON, který generuje předchozí SELECT.

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

Další informace o volbě FOR JSON AUTO

Podrobnější informace a příklady najdete v tématu Automatické formátování výstupu JSON automaticky.

Syntaxe a použití najdete v tématu SELECT – KLAUZULE FOR.

Řízení dalších možností výstupu JSON

Pomocí následujících dodatečných FOR JSON možností můžete řídit výstup klauzule.

• ROOT

  Pokud chcete do výstupu JSON přidat jeden element nejvyšší úrovně, zadejte možnost ROOT. Pokud tuto možnost nezadáte, výstup JSON nemá kořenový prvek. Další informace najdete v tématu Přidání kořenového uzlu do výstupu JSON s možností ROOT.

• INCLUDE_NULL_VALUES

  Pokud chcete do výstupu JSON zahrnout hodnoty null, zadejte možnost INCLUDE_NULL_VALUES. Pokud tuto možnost nezadáte, výstup neobsahuje vlastnosti JSON pro NULL hodnoty ve výsledcích dotazu. Další informace naleznete v tématu Zahrnutí hodnot Null v JSON – volba INCLUDE_NULL_VALUES.

• WITHOUT_ARRAY_WRAPPER

  Pokud chcete ve výchozím nastavení odebrat hranaté závorky, které obklopují výstup JSON klauzule FOR JSON, zadejte možnost WITHOUT_ARRAY_WRAPPER. Tato možnost slouží k vygenerování jednoho objektu JSON jako výstupu z výsledku s jedním řádkem. Pokud tuto možnost nezadáte, výstup JSON se naformátuje jako pole – to znamená, že výstup je uzavřený v hranatých závorkách. Další informace naleznete v Odebrání hranatých závorek z JSON – možnost WITHOUT_ARRAY_WRAPPER.

Výstup klauzule FOR JSON

Výstup klauzule FOR JSON má následující charakteristiky:

1. Sada výsledků obsahuje jeden sloupec.

   • Malá sada výsledků může obsahovat jeden řádek.
   • Velká sada výsledků rozdělí dlouhý řetězec JSON napříč více řádky.

     • Sql Server Management Studio (SSMS) ve výchozím nastavení zřetězí výsledky do jednoho řádku, když je nastavení výstupu Výsledky do mřížky. Stavový řádek SSMS zobrazuje skutečný počet řádků.

     • Jiné klientské aplikace mohou vyžadovat, aby kód rekombinoval dlouhé výsledky do jednoho platného řetězce JSON zřetězením obsahu více řádků. Příklad tohoto kódu v aplikaci jazyka C# najdete v tématu Použití výstupu FOR JSON v klientské aplikaci jazyka C#.

       

2. Výsledky jsou formátovány jako pole objektů JSON.

   • Počet prvků v poli JSON odpovídá počtu řádků ve výsledcích příkazu SELECT (před použití klauzule FOR JSON).

   • Každý řádek ve výsledcích příkazu SELECT (před použitím klauzule FOR JSON) se stane samostatným objektem JSON v poli.

   • Každý sloupec ve výsledcích příkazu SELECT (před použití klauzule FOR JSON) se stane vlastností objektu JSON.

3. Názvy sloupců i jejich hodnoty se eskapují podle syntaxe JSON. Další informace naleznete v tématu Jak FOR JSON nahrazuje speciální znaky a řídicí znaky.

Example

Tady je příklad, který ukazuje, jak klauzule FOR JSON formátuje výstup JSON.

Výsledky dotazu

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

Výstup 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"
}]

Související obsah

• Jak FOR JSON převádí datové typy SQL Serveru na datové typy JSON
• Jak FOR JSON escapuje speciální znaky a řídicí znaky
• Video: JSON jako most mezi NoSQL a relačními světy
• SELECT – klauzule FOR (Transact-SQL)
• Použití výstupu FOR JSON v databázovém stroji SQL a v klientských aplikacích