JSON kullanmaya başlama - Cosmos DB'de sorgu dili (Azure ve Doku'da)

Şunlara uygulanır: ✅ Azure Cosmos DB for NoSQL, ✅ Cosmos DB in Microsoft Fabric

Sorgu dilinin merkezinde JavaScript Nesne Gösterimi (JSON) ile çalışma vardır. Öğeler JSON olarak depolanır ve tüm sorgular, ifadeler ve türler JSON verileriyle çalışacak şekilde tasarlanmıştır. JSON hakkında daha fazla bilgi için bkz. resmi JSON belirtimi.

Bu bağlamda JSON hakkında bilmeniz gereken bazı önemli şeyler şunlardır:

JSON nesneleri her zaman ile { başlar ve ile }biter.
Özellikler birbirinin içinde iç içe yerleştirilebilir.
Özellik değerleri diziler olabilir.
Özellik adları büyük/küçük harfe duyarlıdır.
Özellik adları, boşluklar veya özel karakterlerle bile herhangi bir dize olabilir.

İç içe özellikler

Nokta gösterimini kullanarak iç içe JSON özelliklerine erişebilirsiniz. Bu, çoğu programlama dilindeki özelliklere erişme gibi çalışır.

İşte iç içe JSON içeren örnek bir belge:

[
  {
    "name": "Heatker Women's Jacket",
    "category": "apparel",
    "slug": "heatker-women-s-jacket",
    "sizes": [
      {
        "key": "s",
        "description": "Small"
      }
    ],
    "metadata": {
      "link": "https://www.adventure-works.com/heatker-women-s-jacket/68719520138.p"
    }
  }
]

Ardından sorgularınızda aynı iç içe özellikleri yansıtabilirsiniz:

SELECT
  p.name,
  p.category,
  p.metadata.link
FROM
  products p
WHERE
  p.name = "Heatker Women's Jacket"

Ve şu beklenen çıkışı elde edersiniz:

[
  {
    "name": "Heatker Women's Jacket",
    "category": "apparel",
    "link": "https://www.adventure-works.com/heatker-women-s-jacket/68719520138.p"
  }
]

Diziler ve kümeler

JSON dizileri destekler ve sorgularınızda bunlarla çalışabilirsiniz. Belirli bir öğeye erişmek için dizideki konumunu kullanın.

Önceki bölümdeki aynı örneği kullanarak dizinini kullanarak dizideki bir öğeye erişebiliriz. Örneğin, dizideki ilk öğeye erişmek istiyorsak, sorgu dilindeki diziler için sıfır tabanlı bir dizin sistemi olduğundan dizinini kullanırız0:

SELECT
  p.name,
  p.sizes[0].description AS defaultSize
FROM
  products p
WHERE
  p.name = "Heatker Women's Jacket"

Bu sorgu aşağıdaki JSON nesnesine neden olur:

[
  {
    "name": "Heatker Women's Jacket",
    "defaultSize": "Small"
  }
]

Şimdi daha büyük bir diziye sahip bir örneği ele alalım:

[
  {
    "name": "Vencon Kid's Coat",
    "category": "apparel",
    "slug": "vencon-kid-s-coat",
    "colors": [
      "cardinal",
      "disco"
    ],
    "sizes": [
      {
        "key": "m",
        "description": "Medium"
      },
      {
        "key": "l",
        "description": "Large"
      },
      {
        "key": "xl",
        "description": "Extra Large"
      }
    ]
  }
]

Genellikle, bir dizideki tüm öğelerle çalışmak için bir alt sorgu veya kendi kendine birleştirme kullanmak istersiniz. Örneğin, her rengi ayrı bir satır olarak almak için:

SELECT
  p.name,
  c AS color
FROM
  products p
JOIN
  c IN p.colors
WHERE
  p.name = "Vencon Kid's Coat"

Bu da aşağıdaki gibi bir JSON dizisine neden olur:

[
  {
    "name": "Vencon Kid's Coat",
    "color": "cardinal"
  },
  {
    "name": "Vencon Kid's Coat",
    "color": "disco"
  }
]

Dizide belirli bir değerin mevcut olup olmadığını denetlemek için, anahtar sözcüğünden sonra filtredeki diziyi WHERE kullanabilirsiniz. Bu örnekte, dizinin öğelerini filtrelemek için bir alt sorgu kullanılır:

SELECT VALUE
  p.name
FROM
  products p
WHERE
  EXISTS(SELECT VALUE
    c
  FROM
    c IN p.sizes
  WHERE
    c.description LIKE "%Large")

Bu sorgu, örneğindeki öğeyi içeren düz bir JSON dize dizisiyle sonuç verir:

[
  ...,
  "Vencon Kid's Coat"
  ...
]

Son olarak, birden çok özelliği birleştirerek diziler oluşturabilirsiniz. Bu örnekte, dizi oluşturmak için birden çok özellik birleştirilir metadata :

SELECT
  p.name,
  [
    p.category,
    p.slug,
    p.metadata.link
  ] AS metadata
FROM
  products p
WHERE
  p.name = "Heatker Women's Jacket"

[
  {
    "name": "Heatker Women's Jacket",
    "metadata": [
      "apparel",
      "heatker-women-s-jacket",
      "https://www.adventure-works.com/heatker-women-s-jacket/68719520138.p"
    ]
  }
]

Yineleme

Sorgu dili, kaynaktaki anahtar sözcüğünü kullanarak IN JSON dizileri üzerinde yinelemeyi FROM destekler.

Şu örnek veri kümesini göz önünde bulundurun:

[
  {
    "name": "Pila Swimsuit",
    "colors": [
      "regal-blue",
      "rose-bud-cherry"
    ],
    "sizes": [
      {
        "key": "m",
        "description": "Medium"
      },
      {
        "key": "l",
        "description": "Large"
      },
      {
        "key": "xl",
        "description": "Extra Large"
      }
    ]
  },
  {
    "name": "Makay Bikini",
    "colors": [
      "starship"
    ],
    "sizes": [
      {
        "key": "s",
        "description": "Small"
      },
      {
        "key": "m",
        "description": "Medium"
      },
      {
        "key": "l",
        "description": "Large"
      }
    ]
  }
]

Bu ilk örnek, her ürün için özelliği üzerinde colors yineleme gerçekleştirmek için anahtar sözcüğünü kullanırIN:

SELECT
  *
FROM
  p IN p.colors

[
  "regal-blue",
  "rose-bud-cherry",
  "starship"
]

Yan tümcesini WHERE kullanarak dizideki tek tek girişleri de filtreleyebilirsiniz. Bu örnekte özelliği sizes filtrelenmiştir:

SELECT
  p.key
FROM
  p IN p.sizes
WHERE
  p.description LIKE "%Large"

[
  {
    "key": "l"
  },
  {
    "key": "xl"
  },
  {
    "key": "l"
  }
]

Aynı IN anahtar sözcüğü kullanarak bir dizi yinelemesinin sonucu üzerinde toplama yapabilirsiniz. Bu örnekte sorgu, kapsayıcıdaki tüm öğeler arasında toplanmış etiketlerin sayısını döndürür:

SELECT VALUE
  COUNT(1)
FROM
  p IN p.sizes

Uyarı

Yineleme için anahtar sözcüğünü IN kullanırken, dizi dışındaki özellikleri filtreleyemez veya yansıtamazsınız. Bunun yerine , kendi kendine birleşimleri kullanırsınız.

Null ve tanımlanmamış değerler

Belgede bir özellik yoksa değeri olur undefined. Bir özellik varsa ancak olarak nullayarlandıysa, bu açıkça ayarlanmış bir değerdir. ile undefined arasındaki null fark, sorgularda karışıklığa neden olabilecek önemli bir ayrımdır.

Örneğin, özellik hiçbir zaman tanımlanmadığından bu JSON nesnesinin özelliği için sku değeri undefined olacaktır:

[
  {
    "name": "Witalica helmet",
    "category": "gear",
  }
]

Özellik henüz bir değerle null ayarlanmadığından bu JSON nesnesinin değeri aynı özellik için olacaktır:

[
  {
    "name": "Witalica helmet",
    "category": "gear",
    "sku": null
  }
]

Bu durumları denetlemek için yerleşik işlevler vardır:

IS_NULL bir özelliğin olup nullolmadığını denetler.
IS_DEFINED bir özelliğin var olup olmadığını denetler (değil undefined).

Her ikisini de şu şekilde de kontrol edebilirsiniz:

SELECT
  IS_DEFINED(p.sku) AS isSkuDefined,
  IS_NULL(p.sku) AS isSkuDefinedButNull
FROM
  products p

Köşeli ayraç gösterimi

Çoğu örnek özellikleri belirtmek için noktalı gösterimi kullansa da köşeli ayraç gösterimini kullanarak her zaman aynı özellikleri belirtebilirsiniz.

Şimdi özelliğin değeri metadata olarak iç içe nesne içeren basit bir nesneyle başlayalım:

[
  {
    "name": "Hikomo Sandals",
    "metadata": {
      "link": "https://www.adventure-works.com/hikomo-sandals/68719519305.p"
    }
  }
]

Bu nesne için, nokta ve köşeli ayraç gösterimi birleşimlerini kullanarak özelliğine üç farklı şekilde başvurabilirizmetadata.link:

SELECT
  p.metadata.link AS metadataLinkDotNotation,
  p["metadata"]["link"] AS metadataLinkBracketNotation,
  p.metadata["link"] AS metadataLinkMixedNotation
FROM
  products p
WHERE
  p.name = "Hikomo Sandals"

[
  {
    "metadataLinkDotNotation": "https://www.adventure-works.com/hikomo-sandals/68719519305.p",
    "metadataLinkBracketNotation": "https://www.adventure-works.com/hikomo-sandals/68719519305.p",
    "metadataLinkMixedNotation": "https://www.adventure-works.com/hikomo-sandals/68719519305.p"
  }
]

İpucu

Özellik adında boşluklar, özel karakterler varsa veya ayrılmış bir sözcükle eşleşiyorsa, özelliği belirtmek için köşeli ayraç gösterimi kullanmanız gerekir.

JSON ifadeleri

JSON nesnelerini doğrudan sorgu sonuçlarınızda oluşturabilirsiniz. Örnek olarak bu JSON dizisiyle başlayalım:

[
  {
    "name": "Diannis Watch",
    "category": "apparel",
    "detailCategory": "apparel-accessories-watches",
    "slug": "diannis-watch",
    "sku": "64801",
    "price": 98,
    "quantity": 159
  },
  {
    "name": "Confira Watch",
    "category": "apparel",
    "detailCategory": "apparel-accessories-watches",
    "slug": "confira-watch",
    "sku": "64800",
    "price": 105,
    "quantity": 193
  }
]

En basit söz dizimini kullanarak, bir NoSQL sorgusunda açılı ayraçlar ({/}) ve eklenmiş JSON söz dizimini kullanarak göreli olarak düz bir JSON nesnesinin özellik adlarını etkileyebilirsiniz:

SELECT {
  "brandName": p.name,
  "department": p.category
}
FROM
  products p
WHERE
  p.detailCategory = "apparel-accessories-watches"

[
  {
    "$1": {
      "brandName": "Diannis Watch",
      "department": "apparel"
    }
  },
  {
    "$1": {
      "brandName": "Confira Watch",
      "department": "apparel"
    }
  }
]

Önceki örnekte, açık bir ad tanımlanmadığı için sonucun $1 çıkarım adı vardı. Bu sonraki örnekte, sonuç bir diğer ad kullanılarak tanımlanan açık bir ada product sahiptir:

SELECT {
  "brandName": p.name,
  "department": p.category
} AS product
FROM
  products p
WHERE
  p.detailCategory = "apparel-accessories-watches"

[
  {
    "product": {
      "brandName": "Diannis Watch",
      "department": "apparel"
    }
  },
  {
    "product": {
      "brandName": "Confira Watch",
      "department": "apparel"
    }
  }
]

Alternatif olarak, sonuç bir SELECT VALUE deyimdeki VALUE anahtar sözcük kullanılarak düzleştirilebilir:

SELECT VALUE {
  "brandName": p.name,
  "department": p.category
}
FROM
  products p
WHERE
  p.detailCategory = "apparel-accessories-watches"

[
  {
    "brandName": "Diannis Watch",
    "department": "apparel"
  },
  {
    "brandName": "Confira Watch",
    "department": "apparel"
  }
]

Daha da ileri giderek, JSON söz dizimini kullanarak sonuç JSON nesnesini özgün öğede açıkça tanımlanmayabilecek dizileri, alt nesneleri ve diğer JSON yapılarını içerecek şekilde "yeniden şekillendirebilirsiniz". bu teknik, istemci uygulaması temel alınan veriyle eşleşmeyen belirli bir şemada veri bekliyorsa kullanışlıdır.

Bu JSON şemasını göz önünde bulundurun, örneğin:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "required": [
    "id",
    "category",
    "financial"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "category": {
      "type": "object",
      "properties": {
        "department": {
          "type": "string"
        },
        "section": {
          "type": "string"
        }
      },
      "required": [
        "department"
      ]
    },
    "inventory": {
      "type": "object",
      "properties": {
        "stock": {
          "type": "number"
        }
      }
    },
    "financial": {
      "type": "object",
      "properties": {
        "listPrice": {
          "type": "number"
        }
      },
      "required": [
        "listPrice"
      ]
    }
  }
}

Bu şema, şu biçimde yapılandırılmış bir JSON nesnesine izin verir:

[
  {
    "id": "[string]",
    "name": "[string]",
    "category": {
      "department": "[string]",
      "section": "[string]"
    },
    "inventory": {
      "stock": [number]
    },
    "financial": {
      "listPrice": [number]
    }
  }
]

Bu NoSQL sorgusu, özgün nesneyi[s] bu yeni şemayla uyumlu olacak şekilde yeniden eşler:

SELECT VALUE {
  "id": p.sku,
  "name": p.name,
  "category": {
    "department": p.category,
    "section": p.detailCategory
  },
  "inventory": {
    "stock": p.quantity
  },
  "financial": {
    "listPrice": p.price
  }
}
FROM
  products p
WHERE
  p.detailCategory = "apparel-accessories-watches"

[
  {
    "id": "64801",
    "name": "Diannis Watch",
    "category": {
      "department": "apparel",
      "section": "apparel-accessories-watches"
    },
    "inventory": {
      "stock": 159
    },
    "financial": {
      "listPrice": 98
    }
  },
  {
    "id": "64800",
    "name": "Confira Watch",
    "category": {
      "department": "apparel",
      "section": "apparel-accessories-watches"
    },
    "inventory": {
      "stock": 193
    },
    "financial": {
      "listPrice": 105
    }
  }
]

Kapsayıcı diğer adları

Varsayılan olarak, anahtar sözcüğünden FROM sonra kullanılan terim sorgunun hedefi olan kapsayıcıya başvurur. Terimin kendisi, kapsayıcının adıyla eşleşmesi için DEĞİlDİr .

Örneğin, kapsayıcının adı productsise, bu sorgulardan herhangi biri sorunsuz çalışır ve bu kapsayıcı sorgunun hedefi olduğu sürece kapsayıcıya başvururproducts:

SELECT
  products.id
FROM
  products

SELECT
  p.id
FROM
  p

SELECT
  items.id
FROM
  items

SELECT
  targetContainer.id
FROM
  targetContainer

NoSQL sorgunuzu daha kısa hale getirmek için kapsayıcı adını daha kısa bir adla adlandırmak yaygın bir seçenektir. Diğer ad oluşturma şu anahtar sözcük kullanılarak AS yapılabilir:

SELECT
  p.id
FROM
  products AS p

Sorgu dilinin, diğer adın anahtar sözcük olmadan hedef kapsayıcı başvurusundan hemen sonra tanımlanabildiği AS bir kısaltma söz dizimi de vardır. Bu kısaltma işlev olarak anahtar sözcüğünü AS kullanmaya eşdeğerdir:

SELECT
  p.id
FROM
  products p

Özellik diğer adları

Sonuçlarınızdaki alanları aynı AS anahtar sözcükle tanımlarken diğer adlar kullanarak da yeniden adlandırabilirsiniz. Sonraki birkaç örnek için şu örnek verileri göz önünde bulundurun:

[
  {
    "name": "Oceabelle Scarf",
    "detailCategory": "apparel-accessories-scarfs-and-socks",
    "metadata": {
      "link": "https://www.adventure-works.com/oceabelle-scarf/68719522190.p"
    }
  },
  {
    "name": "Shinity Socks",
    "detailCategory": "apparel-accessories-scarfs-and-socks",
    "metadata": {
      "link": "https://www.adventure-works.com/shinity-socks/68719522161.p"
    }
  },
  {
    "name": "Horric Socks",
    "detailCategory": "apparel-accessories-scarfs-and-socks",
    "metadata": {
      "link": "https://www.adventure-works.com/horric-socks/68719522177.p"
    }
  }
]

Bu ilk örnekte, özelliğin metadataLink değeri için metadata.link diğer ad kullanılır:

SELECT
  p.name,
  p.metadata.link AS metadataLink
FROM
  products p

[
  {
    "name": "Oceabelle Scarf",
    "metadataLink": "https://www.adventure-works.com/oceabelle-scarf/68719522190.p"
  },
  {
    "name": "Shinity Socks",
    "metadataLink": "https://www.adventure-works.com/shinity-socks/68719522161.p"
  },
  {
    "name": "Horric Socks",
    "metadataLink": "https://www.adventure-works.com/horric-socks/68719522177.p"
  }
]

Önemli

Bir değeri boşluk, özel karakter veya ayrılmış sözcükle özellik adı olarak yansıtmak için diğer ad kullanamazsınız. Örneğin, bir değerin yansıtmasını boşluklu bir özellik adıyla değiştirmek istiyorsanız, bir JSON ifadesi kullanmanız gerekir.

Örneğin

SELECT VALUE {
  "product name": p.name,
  "from": p.metadata.link,
  "detail/category": p.detailCategory
}
FROM
  products p
WHERE
  p.detailCategory = "apparel-accessories-scarfs-and-socks"

[
  {
    "product name": "Oceabelle Scarf",
    "from": "https://www.adventure-works.com/oceabelle-scarf/68719522190.p",
    "detail/category": "apparel-accessories-scarfs-and-socks"
  },
  {
    "product name": "Shinity Socks",
    "from": "https://www.adventure-works.com/shinity-socks/68719522161.p",
    "detail/category": "apparel-accessories-scarfs-and-socks"
  },
  {
    "product name": "Horric Socks",
    "from": "https://www.adventure-works.com/horric-socks/68719522177.p",
    "detail/category": "apparel-accessories-scarfs-and-socks"
  }
]

NoSQL sorgusu aynı ada sahip iki özelliğe sahipse, diğer adları kullanarak özelliklerin birini veya her ikisini de yeniden adlandırarak öngörülen sonuçta belirsiz olmasını sağlayın.

Bu örnek verileri göz önünde bulundurun:

[
  {
    "name": "Oceabelle Scarf",
    "detailCategory": "apparel-accessories-scarfs-and-socks",
    "sizes": [
      {
        "key": "s"
      },
      ...
    ],
    "tags": [
      ...
    ]
  },
  {
    "name": "Shinity Socks",
    "detailCategory": "apparel-accessories-scarfs-and-socks",
    "sizes": [
      ...
      {
        "key": "10"
      },
      ...
    ],
    "tags": [
      ...
      {
        "key": "length"
      }
    ]
  },
  {
    "name": "Horric Socks",
    "detailCategory": "apparel-accessories-scarfs-and-socks",
    "sizes": [
      ...
      {
        "key": "7"
      },
      ...
    ],
    "tags": [
      {
        "key": "fabric"
      },
      ...
    ]
  }
]

Uyarı

Bu örnek verilerde ve sorgu sonucunda, kısa süre için birden çok özellik ve değer kaldırıldı.

Bu NoSQL sorgusu, çapraz ürün sonucundaki ve p.tags[].key özelliklerini döndürürp.sizes[].key, ancak çakışmaları önlemek için her key özelliğin diğer adını verir:

SELECT
  p.name,
  s.key AS sizeKey,
  t.key AS tagKey
FROM
  products p
JOIN
  s IN p.sizes
JOIN
  t in p.tags
WHERE
  p.detailCategory = "apparel-accessories-scarfs-and-socks"

[
  {
    "name": "Oceabelle Scarf",
    "sizeKey": "s",
    "tagKey": "fabric"
  },
  ...
  {
    "name": "Shinity Socks",
    "sizeKey": "10",
    "tagKey": "length"
  },
  ...
  {
    "name": "Horric Socks",
    "sizeKey": "7",
    "tagKey": "fabric"
  }
]

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-11-19