Praca z plikiem JSON w usłudze Azure Cosmos DB for NoSQL

2025-06-11

DOTYCZY: NoSQL

W usłudze Azure Cosmos DB for NoSQL elementy są przechowywane jako dane JSON. System typów i wyrażenia są ograniczone do obsługi tylko typów JSON. Aby uzyskać więcej informacji, zobacz specyfikację JSON.

Podsumujemy niektóre ważne aspekty pracy z plikiem JSON:

Obiekty JSON zawsze zaczynają się od lewego nawiasu klamrowego { i kończą się prawym nawiasem klamrowym }
Właściwości JSON mogą być zagnieżdżone wzajemnie
Wartości właściwości JSON mogą być tablicami
W nazwach właściwości JSON jest rozróżniana wielkość liter
Nazwa właściwości JSON może być dowolną wartością ciągu (w tym spacjami lub znakami, które nie są literami)

Właściwości zagnieżdżone

Dostęp do zagnieżdżonego kodu JSON można uzyskać przy użyciu metody dostępu kropkowego (.). W zapytaniach można używać zagnieżdżonych właściwości JSON w taki sam sposób, jak w przypadku innych właściwości.

Oto dokument z zagnieżdżonym JSON-em:

{
  "name": "Teapo rainbow surfboard",
  "manufacturer": {
    "name": "AdventureWorks"
  },
  "releaseDate": null,
  "metadata": {
    "sku": "72109",
    "colors": [
      "cruise",
      "picton-blue"
    ],
    "sizes": {
      "small": {
        "inches": 76,
        "feet": 6.33333
      },
      "large": {
        "inches": 92,
        "feet": 7.66667
      }
    }
  }
}

W tym przypadku, właściwości sku, colors i sizes są wszystkie zagnieżdżone we właściwości metadata. Właściwość name jest zagnieżdżona także w właściwości manufacturer.

Ten pierwszy przykład przedstawia trzy zagnieżdżone właściwości.

SELECT
    p.manufacturer.name,
    p.metadata.sku,
    p.metadata.sizes.small.inches AS size
FROM
    products p

[
  {
    "name": "AdventureWorks",
    "sku": "72109",
    "size": 76
  }
]

Praca z tablicami

Oprócz właściwości zagnieżdżonych kod JSON obsługuje również tablice. Podczas pracy z tablicami można uzyskać dostęp do określonego elementu w tablicy, odwołując się do jego położenia.

Ten przykład uzyskuje dostęp do elementu tablicy na określonej pozycji.

SELECT
    p.name,
    p.metadata.colors
FROM
    products p
WHERE
    p.metadata.colors[0] NOT LIKE "%orange%"

[
  {
    "name": "Teapo rainbow surfboard",
    "colors": [
      "cruise",
      "picton-blue"
    ]
  }
]

W większości przypadków podczas pracy z tablicami należy jednak użyć podzapytania lub samosprzężenia .

Oto zapytanie, które zwraca wiele permutacji przy użyciu potencjalnych wartości tablicy i sprzężenia krzyżowego,

SELECT
    p.name,
    c AS color
FROM
    products p
JOIN
    c IN p.metadata.colors

[
  {
    "name": "Teapo rainbow surfboard",
    "color": "cruise"
  },
  {
    "name": "Teapo rainbow surfboard",
    "color": "picton-blue"
  }
]

W innym przykładzie zapytanie może być również używane EXISTS z podzapytaniem.

SELECT VALUE
    p.name
FROM
    products p
WHERE
    EXISTS (SELECT VALUE 
        c
    FROM
        c IN p.metadata.colors
    WHERE
        c LIKE "%picton%")

[
  "Teapo rainbow surfboard"
]

Różnica między null a undefined

Jeśli właściwość nie jest zdefiniowana w elemencie, jego wartość to undefined. Właściwość z wartością null musi być jawnie zdefiniowana i mieć przypisaną wartość null.

Usługa Azure Cosmos DB dla NoSQL obsługuje dwie przydatne funkcje systemowe do sprawdzania typów dla właściwości null oraz undefined.

IS_NULL — sprawdza, czy wartość właściwości to null.
IS_DEFINED — sprawdza, czy wartość właściwości jest zdefiniowana lub undefined.

Oto przykładowe zapytanie sprawdzające dwa pola w każdym elemencie w kontenerze.

SELECT
    IS_NULL(p.releaseDate) AS isReleaseDateNull,
    IS_DEFINED(p.releaseDate) AS isReleaseDateDefined,
    IS_NULL(p.retirementDate) AS isRetirementDateNull,
    IS_DEFINED(p.retirementDate) AS isRetirementDateDefined
FROM
    products p

[
  {
    "isReleaseDateNull": true,
    "isReleaseDateDefined": true,
    "isRetirementDateNull": false,
    "isRetirementDateDefined": false
  }
]

Aby uzyskać więcej informacji o typowych operatorach i ich zachowaniu dla null i undefined wartości, zobacz operatory równości i porównania.

Zastrzeżone słowa kluczowe i znaki specjalne w formacie JSON

Dostęp do właściwości można uzyskać przy użyciu operatora właściwości w cudzysłowie []. Na przykład elementy SELECT c.grade i SELECT c["grade"] są równoważne. Ta składnia jest przydatna do ucieczki właściwości zawierającej spacje, znaki specjalne lub ma taką samą nazwę jak słowo kluczowe SQL lub słowo zarezerwowane.

Oto zapytanie, które odwołuje się do właściwości na kilka różnych sposobów.

SELECT
    p.manufacturer.name AS dotNotationReference,
    p["manufacturer"]["name"] AS bracketReference,
    p.manufacturer["name"] AS mixedReference
FROM
    products p

[
  {
    "dotNotationReference": "AdventureWorks",
    "bracketReference": "AdventureWorks",
    "mixedReference": "AdventureWorks"
  }
]

Wyrażenia JSON

Projekcja zapytań obsługuje wyrażenia i składnię JSON.

SELECT {
    "productName": p.name,
    "largeSizeInFeet": p.metadata.sizes.large.feet
}
FROM
    products p

[
  {
    "$1": {
      "productName": "Teapo rainbow surfboard",
      "largeSizeInFeet": 7.66667
    }
  }
]

W tym przykładzie klauzula SELECT tworzy obiekt JSON. Ponieważ w przykładzie nie podano żadnego klucza, klauzula używa niejawnej nazwy $<index-number>zmiennej argumentu .

W tym przykładzie wyraźnie nazywa się to samo pole.

SELECT {
    "productName": p.name,
    "largeSizeInFeet": p.metadata.sizes.large.feet
} AS product
FROM
    products p

[
  {
    "product": {
      "productName": "Teapo rainbow surfboard",
      "largeSizeInFeet": 7.66667
    }
  }
]

Alternatywnie zapytanie może spłaszczać obiekt, aby uniknąć nazewnictwa nadmiarowego pola.

SELECT VALUE {
    "productName": p.name,
    "largeSizeInFeet": p.metadata.sizes.large.feet
}
FROM
    products p

[
  {
    "productName": "Teapo rainbow surfboard",
    "largeSizeInFeet": 7.66667
  }
]

Wartości aliasu

Możesz jawnie aliasować wartości w zapytaniach. Jeśli zapytanie ma dwie właściwości o tej samej nazwie, użyj aliasu, aby zmienić nazwę jednej lub obu właściwości, aby były one uściślane w przewidywanym wyniku.

Przykłady

Słowo AS kluczowe używane do aliasowania jest opcjonalne, jak pokazano w poniższym przykładzie.

SELECT
    p.name,
    p.metadata.sku AS modelNumber
FROM
    products p

[
  {
    "name": "Teapo rainbow surfboard",
    "modelNumber": "72109"
  }
]

Wartości aliasów z zastrzeżonymi słowami kluczowymi lub znakami specjalnymi

Nie można używać aliasu do projekcji wartości jako nazwy właściwości z spacją, znakiem specjalnym lub słowem zarezerwowanym. Jeśli na przykład chcesz zmienić sposób projekcji wartości tak, aby użyć nazwy właściwości ze spacją, możesz użyć wyrażenia JSON.

Oto przykład:

SELECT VALUE {
    "Product's name | ": p.name,
    "Model number => ": p.metadata.sku
}
FROM
    products p

[
  {
    "Product's name | ": "Teapo rainbow surfboard",
    "Model number => ": "72109"
  }
]