共用方式為

在 Azure Cosmos DB for NoSQL 中使用 JSON

  • 發行項

適用於：NoSQL

在 Azure Cosmos DB for NoSQL 中，會將項目儲存為 JSON。 類型系統和運算式僅限於處理 JSON 類型。 如需詳細資訊，請參閱 JSON 規格 \(英文\)。

我們會摘要說明使用 JSON 的一些重要層面：

  • JSON 物件一律會以 { 的左大括弧開頭，並以 } 的右大括弧結束
  • 您可以讓 JSON 屬性彼此以巢狀形式放在一起
  • JSON 屬性值可以是陣列
  • JSON 屬性名稱會區分大小寫
  • JSON 屬性名稱可以是任何字串值 (包括空格或非字母的字元)

巢狀屬性

您可以使用點 (.) 存取子來存取巢狀 JSON。 您可以在查詢中，利用與使用任何其他屬性相同的方式來使用巢狀 JSON 屬性。

以下是具有巢狀 JSON 的文件：

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

在此案例中，sku、colors 和 sizes 屬性全都以巢狀形式放在 metadata 屬性內。 name 屬性也巢狀於 manufacturer 屬性內。

第一個範例會投影三個巢狀屬性。

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

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

使用陣列 (英文)

除了巢狀屬性，JSON 也支援陣列。 使用陣列時，您可以參考其位置來存取陣列中的特定元素。

此範例會存取位於特定位置的陣列元素。

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

不過，在大部分情況下，您會在使用陣列時，使用子查詢或自我聯結。

例如，以下查詢使用潛在陣列值和交叉聯結來傳回多個排列。

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

另一個範例是，查詢也可以搭配使用 EXISTS 與子查詢。

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

Null 和未定義之間的差異

如果項目中未定義屬性，則其值為 undefined。 值為 null 的屬性必須明確定義並獲派 null 值。

Azure Cosmos DB for NoSQL 針對 null 和 undefined 屬性支援兩種實用的類型檢查系統函數：

  • IS_NULL - 檢查屬性值是否為 null。
  • IS_DEFINED - 檢查是否已定義或 undefined 屬性值。

以下範例查詢會檢查容器中每個項目上的兩個欄位。

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

如需通用運算子和其 null 和 undefined 值行為的詳細資訊，請參閱相等和比較運算子。

JSON 中的保留關鍵字和特殊字元

您可以使用加上引號的屬性運算子 [] 來存取屬性。 例如，SELECT c.grade 與 SELECT c["grade"] 彼此相等。 在逸出包含空格、特殊字元的屬性，或具有和 SQL 關鍵字或保留字相同的名稱時，此語法很有用。

例如，以下查詢會使用幾種不同的方法來參考屬性。

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

JSON 運算式

查詢投影支援 JSON 運算式和語法。

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

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

在此範例中，SELECT 子句會建立 JSON 物件。 因為此範例未提供索引鍵，所以子句會使用隱含引數變數名稱 $<index-number>。

此範例會明確地命名相同的欄位。

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

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

或者，查詢可以壓平合併物件，以避免命名或者，查詢可以扁平化 物件，以避免命名冗餘欄位。

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

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

別名值

您可以在查詢中明確使用值的別名。 如果查詢具有兩個同名的屬性，請使用別名來為這其中一個或兩個屬性重新命名，使其在投影的結果中變得更為明確。

範例

用於別名處理的 AS 關鍵字是選用項目，如下列範例所示。

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

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

具有保留關鍵字或特殊字元的別名值

您無法使用別名，將值投影為具有空格、特殊字元或保留字的屬性名稱。 例如，如果您想要將值的投影變更為具有空格的屬性名稱，您可以使用 JSON 運算式。

以下是範例：

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

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

相關內容