開始使用 SQL 查詢

適用於: SQL API

在 Azure Cosmos DB SQL API 帳戶中,有兩種方式可以讀取資料:

點讀取:您可以在單一項目識別碼和分割區索引鍵進行索引鍵/值查閱。 項目識別碼和資料分割索引鍵組合是索引鍵,而項目本身是值。 若是 1 KB 文件,點讀取通常花費 1 個要求單位,延遲低於 10 毫秒。 點讀取傳回單一完整項目,而不是局部項目或特定欄位。

以下是如何使用每個 SDK 來執行端點讀取的一些範例:

SQL 查詢:您可以使用結構化查詢語言 (SQL) 做為 JSON 查詢語言撰寫查詢來查詢資料。 查詢一律會花費至少 2.3 個要求單位,而且通常會有比點讀取更高且更有變化的延遲。 查詢可能會傳回許多項目。

Azure Cosmos DB 上大部分的大量讀取工作負載都會使用點讀取和 SQL 查詢的組合。 如果您只需要讀取單一項目,則點讀取比查詢更便宜且更快速。 點讀取不需要使用查詢引擎來存取資料,且可以直接讀取資料。 當然,並非所有工作負載都能使用點讀取來獨佔讀取資料,因此支援 SQL 做為查詢語言以及不限結構描述的索引編制,可提供更有彈性的方式來存取您的資料。

以下是如何使用每個 SDK 來執行 SQL 查詢的一些範例:

本文件的其餘部分將說明如何開始在 Azure Cosmos DB 中撰寫 SQL 查詢。 您可以透過 SDK 或 Azure 入口網站來執行 SQL 查詢。

上傳範例資料

在 SQL API Cosmos DB 帳戶中,開啟資料總管以建立名為 Families 的容器。 建立容器之後,請使用資料結構瀏覽器來尋找並加以開啟。 在您的 Families 容器中,您會在容器的名稱下方看到 Items 選項。 開啟此選項,您隨即會在畫面中央的功能表列中看到一個按鈕,以建立「新項目」。 您將使用這項功能來建立下列 JSON 項目。

建立 JSON 項目

下列 2 個 JSON 項目是 Andersen 和 Wakefield 系列的相關文件。 其中包括家長、子女及其寵物、位址和註冊資訊。

第一個項目包含字串、數字、布林值、陣列和巢狀屬性:

{
  "id": "AndersenFamily",
  "lastName": "Andersen",
  "parents": [
     { "firstName": "Thomas" },
     { "firstName": "Mary Kay"}
  ],
  "children": [
     {
         "firstName": "Henriette Thaulow",
         "gender": "female",
         "grade": 5,
         "pets": [{ "givenName": "Fluffy" }]
     }
  ],
  "address": { "state": "WA", "county": "King", "city": "Seattle" },
  "creationDate": 1431620472,
  "isRegistered": true
}

第二個項目會使用 givenNamefamilyName,而不是 firstNamelastName

{
  "id": "WakefieldFamily",
  "parents": [
      { "familyName": "Wakefield", "givenName": "Robin" },
      { "familyName": "Miller", "givenName": "Ben" }
  ],
  "children": [
      {
        "familyName": "Merriam",
        "givenName": "Jesse",
        "gender": "female",
        "grade": 1,
        "pets": [
            { "givenName": "Goofy" },
            { "givenName": "Shadow" }
        ]
      },
      {
        "familyName": "Miller",
         "givenName": "Lisa",
         "gender": "female",
         "grade": 8 }
  ],
  "address": { "state": "NY", "county": "Manhattan", "city": "NY" },
  "creationDate": 1431620462,
  "isRegistered": false
}

查詢 JSON 項目

嘗試對 JSON 資料執行一些查詢,以了解 Azure Cosmos DB SQL 查詢語言的一些重要部分。

下列查詢會傳回 id 欄位符合 AndersenFamily 的項目。 因為這是 SELECT * 查詢,所以查詢的輸出會是完整的 JSON 項目。 如需有關 SELECT 語法的詳細資訊,請參閱 SELECT 語句

    SELECT *
    FROM Families f
    WHERE f.id = "AndersenFamily"

查詢結果為:

    [{
        "id": "AndersenFamily",
        "lastName": "Andersen",
        "parents": [
           { "firstName": "Thomas" },
           { "firstName": "Mary Kay"}
        ],
        "children": [
           {
               "firstName": "Henriette Thaulow", "gender": "female", "grade": 5,
               "pets": [{ "givenName": "Fluffy" }]
           }
        ],
        "address": { "state": "WA", "county": "King", "city": "Seattle" },
        "creationDate": 1431620472,
        "isRegistered": true
    }]

下列查詢會將 JSON 輸出重新格式化為不同的圖形。 當地址所在城市與省/市的相同時,查詢會投射具有兩個所選欄位 (NameCity) 的新 JSON Family 物件。 "NY, NY" 符合此案例。

    SELECT {"Name":f.id, "City":f.address.city} AS Family
    FROM Families f
    WHERE f.address.city = f.address.state

查詢結果為:

    [{
        "Family": {
            "Name": "WakefieldFamily",
            "City": "NY"
        }
    }]

下列查詢會傳回家族中 id 符合 WakefieldFamily 的小孩名字,並依城市排序。

    SELECT c.givenName
    FROM Families f
    JOIN c IN f.children
    WHERE f.id = 'WakefieldFamily'
    ORDER BY f.address.city ASC

結果為:

    [
      { "givenName": "Jesse" },
      { "givenName": "Lisa"}
    ]

備註

上述範例顯示 Cosmos DB 查詢語言的幾個層面:

  • 因為 SQL API 的處理對象是 JSON 值,所以其處理的是樹狀形式的實體,而不是資料列和資料行。 您可以參考任何任意深度的樹狀節點,例如 Node1.Node2.Node3…..Nodem,類似於 ANSI SQL 中 <table>.<column> 的兩部分參考。

  • 因為查詢語言適用於無結構描述資料,所以類型系統必須動態地繫結。 相同的運算式可能會對不同的項目產生不同的類型。 查詢的結果會是有效的 JSON 值,但不保證會是固定的結構描述。

  • Azure Cosmos DB 只支援嚴謹的 JSON 項目。 類型系統和運算式僅限於處理 JSON 類型。 如需詳細資訊,請參閱 JSON 規格 \(英文\)。

  • Cosmos 容器是 JSON 項目的無結構描述集合。 容器項目內及跨容器項目的關係,會透過內含項目以隱含方式擷取,而不是透過主索引鍵和外部索引鍵關係來擷取。 這項功能對於 Azure Cosmos DB 中的聯結所述項目內聯結很重要。

後續步驟