FOR JSON ile sorgu sonuçlarını JSON olarak biçimlendirme

Şunlar için geçerlidir: SQL Server 2016 (13.x) ve sonraki sürümler Azure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics (yalnızca sunucusuz SQL havuzu)Microsoft Fabric'te SQL analitik uç noktasıMicrosoft Fabric'te depo veritabanıMicrosoft Fabric'te SQL veritabanı

FOR JSON yan tümcesini bir SELECT deyimine ekleyerek sorgu sonuçlarını JSON olarak biçimlendirin veya SQL Server'dan verileri JSON olarak dışarı aktarın. Uygulamadan JSON çıktısını biçimlendirme görevini SQL Server'a devrederek istemci uygulamalarını basitleştirmek için FOR JSON yan tümcesini kullanın.

Note

Azure Data Studio, bu makalede gösterildiği gibi JSON sonuçlarını otomatik olarak biçimlendirdiğinden JSON sorguları için önerilen sorgu düzenleyicisidir. SQL Server Management Studio biçimlendirilmemiş bir dize görüntüler.

Fabric Veri Ambarı'nda sorgudaki FOR JSON son işleç olmalıdır ve bu nedenle alt sorgularda izin verilmemektedir.

Sorgu sonuçlarını biçimlendirme

FOR JSON yan tümcesini kullandığınızda, JSON çıkışının yapısını açıkça belirleyebilir veya SELECT deyiminin yapısının çıkışı belirlemesine izin verebilirsiniz.

• JSON çıkışının biçimi üzerinde tam denetim sahibi olmak için FOR JSON PATHkullanın. Sarmalayıcı nesneleri oluşturabilir ve karmaşık özellikleri iç içe yerleştirebilirsiniz.

• JSON çıkışını SELECT deyiminin yapısına göre otomatik olarak biçimlendirmek için FOR JSON AUTOkullanın.

aşağıda SELECT yan tümcesi ve çıktısı olan bir FOR JSON deyimi örneği verilmiştir.

for JSON'un nasıl çalıştığını gösteren

için

FOR JSON PATH ile çıkışı denetleme

PATH modunda, iç içe çıkışı biçimlendirmek için nokta söz dizimini (örneğin, Item.Price) kullanabilirsiniz.

İşte PATH modunu FOR JSON yan tümcesiyle kullanan bir örnek sorgu. Aşağıdaki örnek, adlandırılmış bir kök öğe belirtmek için ROOT seçeneğini de kullanır.

FOR JSON çıktısının akış diyagramı.

FOR JSON PATH hakkında daha fazla bilgi

Daha ayrıntılı bilgi ve örnekler için bkz. PATH Modu ile İç İçe JSON Çıktısını Biçimlendirme.

Söz dizimi ve kullanımı için bkz. SELECT - FOR Yan Tümcesi (Transact-SQL).

için

SELECT deyimi FOR JSON AUTO ile çıkışı denetler

AUTO modunda, SELECT deyiminin yapısı JSON çıkışının biçimini belirler.

Varsayılan olarak, NULL değerleri çıkışa dahil değildir. Bu davranışı değiştirmek için INCLUDE_NULL_VALUES kullanabilirsiniz.

İşte AUTO modunu FOR JSON yan tümcesiyle kullanan bir örnek sorgu.

SELECT name, surname
FROM emp
FOR JSON AUTO;

İşte döndürülen JSON.

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

JOIN ve NULL örneği

Aşağıdaki SELECT...FOR JSON AUTO örneği, birleştirilmiş tablolardaki veriler arasında 1:çok ilişkisi olduğunda JSON sonuçlarının nasıl göründüğünü gösteren bir görüntü içerir.

Döndürülen JSON'dan null değerin olmaması da gösterilmiştir. Ancak, INCLUDE_NULL_VALUES yan tümcesinde FOR anahtar sözcüğünü kullanarak bu varsayılan davranışı geçersiz kılabilirsiniz.

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

Ve sonraki, önceki SELECT tarafından çıktısı verilen JSON'dır.

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

FOR JSON AUTO hakkında daha fazla bilgi

Daha ayrıntılı bilgi ve örnekler için bkz. JSON Çıkışını AUTO Modu ile Otomatik Olarak Biçimlendirme.

Söz dizimi ve kullanımı için bkz. SELECT - FOR Yan Tümcesi (Transact-SQL).

Diğer JSON çıkış seçeneklerini denetleme

Aşağıdaki ek seçenekleri kullanarak FOR JSON yan tümcesinin çıkışını denetleyin.

• ROOT

  JSON çıkışına tek ve en üst düzey bir öğe eklemek için ROOT seçeneğini belirtin. Bu seçeneği belirtmezseniz, JSON çıkışının kök öğesi yoktur. Daha fazla bilgi için bkz. KÖK Seçeneği ile JSON Çıkışına Kök Düğüm Ekleme.

• INCLUDE_NULL_VALUES

  JSON çıkışına null değerler eklemek için INCLUDE_NULL_VALUES seçeneğini belirtin. Bu seçeneği belirtmezseniz, çıktı sorgu sonuçlarındaki NULL değerleri için JSON özelliklerini içermez. Daha fazla bilgi için bkz. JSON'a Null Değerler Ekleme - INCLUDE_NULL_VALUES Seçenek.

• WITHOUT_ARRAY_WRAPPER

  FOR JSON yan tümcesinin JSON çıkışını çevreleyen köşeli ayraçları varsayılan olarak kaldırmak için WITHOUT_ARRAY_WRAPPER seçeneğini belirtin. Tek satırlı bir sonuçtan çıkış olarak tek bir JSON nesnesi oluşturmak için bu seçeneği kullanın. Bu seçeneği belirtmezseniz, JSON çıkışı bir dizi olarak biçimlendirilir, yani çıkış köşeli ayraç içine alınır. Daha fazla bilgi için bkz. Köşeli Ayraçları JSON'dan Kaldırma - WITHOUT_ARRAY_WRAPPER Seçeneği.

FOR JSON yan tümcesinin çıkışı

FOR JSON yan tümcesinin çıkışı aşağıdaki özelliklere sahiptir:

1. Sonuç kümesi tek bir sütun içerir.

   • Küçük bir sonuç kümesi tek bir satır içerebilir.
   • Büyük bir sonuç kümesi, uzun JSON dizesini birden çok satıra böler.

     • Varsayılan olarak, SQL Server Management Studio (SSMS), çıkış ayarı Sonuçları Kılavuzaolduğunda, sonuçları tek bir satırda birleştirir. SSMS durum çubuğunda gerçek satır sayısı görüntülenir.

     • Diğer istemci uygulamaları, kodun birden çok satırın içeriğini birleştirerek uzun sonuçları tek, geçerli bir JSON dizesine yeniden birleştirmesini gerektirebilir. C# uygulamasında bu kodun bir örneği için bkz. C# istemci uygulamasında FOR JSON çıktısının kullanımı.

       

2. Sonuçlar bir JSON nesneleri dizisi olarak biçimlendirilir.

   • JSON dizisindeki öğe sayısı, SELECT deyiminin sonuçlarındaki satır sayısına eşittir (FOR JSON yan tümcesi uygulanmadan önce).

   • SELECT deyiminin sonuçlarındaki her satır (FOR JSON yan tümcesi uygulanmadan önce) dizide ayrı bir JSON nesnesine dönüşür.

   • SELECT deyiminin sonuçlarındaki her sütun (FOR JSON yan tümcesi uygulanmadan önce) JSON nesnesinin özelliğine dönüşür.

3. Hem sütunların adları hem de değerleri JSON söz dizimine göre kaçıştırılır. Daha fazla bilgi için bkz. FOR JSON özel karakterlerden ve denetim karakterlerinden nasıl kurtulur?

Example

aşağıda, FOR JSON yan tümcesinin JSON çıkışını nasıl biçimlendirdiğini gösteren bir örnek verilmiştir.

Sorgu sonuçları

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

JSON çıkışı

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

İlgili içerik

• FOR JSON, SQL Server veri türlerini JSON veri türlerine nasıl dönüştürür
• FOR JSON özel karakterlerden ve denetim karakterlerinden nasıl kaçınıyor?
• Video: NoSQL ile ilişkisel dünyalar arasında köprü olarak JSON
• SELECT - FOR Yan Tümcesi (Transact-SQL)
• SQL Veritabanı Altyapısı'nda ve istemci uygulamalarında FOR JSON çıkışını kullanma