SQL クエリの使用を開始するGetting started with SQL queries

適用対象: SQL API

Azure Cosmos DB SQL API アカウントでは、次の 2 つの方法でデータを読み取ることができます。In Azure Cosmos DB SQL API accounts, there are two ways to read data:

ポイントの読み取り - 1 つの 項目 ID およびパーティション キーにおいてキーと値の参照を行うことができます。Point reads - You can do a key/value lookup on a single item ID and partition key. 項目 ID とパーティション キーの組み合わせがキーであり、項目自体は値です。The item ID and partition key combination is the key and the item itself is the value. 1 KB のドキュメントの場合、ポイントの読み取りには通常 1 個の要求ユニットが必要で、待機時間は 10 ミリ秒未満です。For a 1 KB document, point reads typically cost 1 request unit with a latency under 10 ms. ポイントの読み取りでは、1 つの項目が返されます。Point reads return a single item.

以下に、各 SDK で ポイントの読み取り を実行する方法の例を示します。Here are some examples of how to do Point reads with each SDK:

SQL クエリ - 構造化照会言語 (SQL) (Structured Query Language) を JSON クエリ言語として使用してクエリを記述することで、データを照会できます。SQL queries - You can query data by writing queries using the Structured Query Language (SQL) as a JSON query language. 照会には常に 2.3 個以上の要求ユニットが必要で、通常はポイントの読み取りよりも待機時間が長く、その変動も大きくなります。Queries always cost at least 2.3 request units and, in general, will have a higher and more variable latency than point reads. クエリを使用すると、多くの項目を返すことができます。Queries can return many items.

Azure Cosmos DB の読み取り負荷の高いワークロードのほとんどは、ポイント読み取りと SQL クエリの両方を組み合わせて使用します。Most read-heavy workloads on Azure Cosmos DB use a combination of both point reads and SQL queries. 1 つの項目のみを読み取る必要がある場合、クエリを使用するよりもポイントの読み取りを実行するほうが、少ないユニット数で高速に読み取ることができます。If you just need to read a single item, point reads are cheaper and faster than queries. ポイントの読み取りでは、クエリ エンジンを使用してデータにアクセスする必要がなく、データを直接読み取ることができます。Point reads don't need to use the query engine to access data and can read the data directly. もちろん、すべてのワークロードでポイントの読み取りを使用してデータを排他的に読み取ることはできません。この場合、SQL をクエリ言語として使用し、スキーマに依存しないインデックス設定を行うことで、データに柔軟にアクセスできます。Of course, it's not possible for all workloads to exclusively read data using point reads, so support of SQL as a query language and schema-agnostic indexing provide a more flexible way to access your data.

以下に、各 SDK で SQL クエリ を実行する方法の例を示します。Here are some examples of how to do SQL queries with each SDK:

このドキュメントの残りの部分では、Azure Cosmos DB で SQL クエリの記述を開始する方法について説明します。The remainder of this doc shows how to get started writing SQL queries in Azure Cosmos DB. SQL クエリは、SDK または Azure portal を使用して実行できます。SQL queries can be run through either the SDK or Azure portal.

サンプル データのアップロードUpload sample data

SQL API Cosmos DB アカウントで、データ エクスプローラーを開き、Families というコンテナーを作成します。In your SQL API Cosmos DB account, open the Data Explorer to create a container called Families. 作成した後、データ構造のブラウザーを使用してそれを検索し、開きます。After the it is created, use the data structures browser, to find and open it. Families コンテナーでは、コンテナーの名前のすぐ下に Items オプションが表示されます。In your Families container, you will see the Items option right below the name of the container. このオプションを開くと、画面の中央にあるメニュー バーに "新しい項目" を作成するためのボタンが表示されます。Open this option and you'll see a button, in the menu bar in center of the screen, to create a 'New Item'. この機能を使用して、下の JSON 項目を作成します。You will use this feature to create the JSON items below.

JSON 項目を作成するCreate JSON items

次の 2 つの JSON 項目は、Andersen と Wakefield 一家に関するドキュメントです。The following 2 JSON items are documents about the Andersen and Wakefield families. これには、親、子、ペット、住所、および登録情報が含まれます。They include parents, children and their pets, address, and registration information.

最初の項目には、文字列、数値、ブール値、配列、入れ子になったプロパティがあります。The first item has strings, numbers, Booleans, arrays, and nested properties:

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

2 つ目の項目は、firstNamelastName の代わりに givenNamefamilyName を使用します。The second item uses givenName and familyName instead of firstName and lastName:

{
  "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 項目のクエリを実行するQuery the JSON items

Azure Cosmos DB の SQL クエリ言語の重要な側面について理解するため、JSON データに対していくつかのクエリを実行してみます。Try a few queries against the JSON data to understand some of the key aspects of Azure Cosmos DB's SQL query language.

以下のクエリを実行すると、id フィールドが AndersenFamily に一致する項目が返されます。The following query returns the items where the id field matches AndersenFamily. SELECT * クエリであるため、クエリの出力は完全な JSON 項目になります。Since it's a SELECT * query, the output of the query is the complete JSON item. SELECT 構文の詳細については、SELECT ステートメントに関するページを参照してください。For more information about SELECT syntax, see SELECT statement.

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

クエリ結果:The query results are:

    [{
        "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 出力を異なる形式に変更します。The following query reformats the JSON output into a different shape. このクエリは、住所の都市が州と同じ場合に、2 つの選択したフィールド (NameCity) を持つ JSON Family オブジェクトをプロジェクションします。The query projects a new JSON Family object with two selected fields, Name and City, when the address city is the same as the state. "NY, NY" はこのケースに一致します。"NY, NY" matches this case.

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

クエリ結果:The query results are:

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

次のクエリでは、idWakefieldFamily と一致する家族の子どもの名がすべて都市順に返されます。The following query returns all the given names of children in the family whose id matches WakefieldFamily, ordered by city.

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

結果は次のようになります。The results are:

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

解説Remarks

上記の例は、Cosmos DB クエリ言語のいくつかの側面を示しています。The preceding examples show several aspects of the Cosmos DB query language:

  • SQL API は JSON 値に対して機能するので、行と列ではなくツリー形式のエンティティを処理します。Since SQL API works on JSON values, it deals with tree-shaped entities instead of rows and columns. Node1.Node2.Node3…..Nodem のように任意の深さのツリーのノードを参照でき、ANSI SQL での <table>.<column> の 2 項目参照に似ています。You can refer to the tree nodes at any arbitrary depth, like Node1.Node2.Node3…..Nodem, similar to the two-part reference of <table>.<column> in ANSI SQL.

  • クエリ言語はスキーマレス データを操作するため、型システムを動的にバインドする必要があります。Because the query language works with schemaless data, the type system must be bound dynamically. 同じ式でも、項目が異なれば異なる型が導出される場合があります。The same expression could yield different types on different items. クエリ結果は有効な JSON 値ですが、固定スキーマの場合でも有効とは限りません。The result of a query is a valid JSON value, but isn't guaranteed to be of a fixed schema.

  • Azure Cosmos DB は厳密な JSON 項目だけをサポートします。Azure Cosmos DB supports strict JSON items only. 型システムおよび式は、JSON 型のみを扱うように制限されます。The type system and expressions are restricted to deal only with JSON types. 詳細については、JSON の仕様に関する記事を参照してください。For more information, see the JSON specification.

  • Cosmos コンテナーは、JSON 項目のスキーマなしのコレクションです。A Cosmos container is a schema-free collection of JSON items. コンテナー項目内および項目全体の関係は、含有関係によって暗黙的にキャプチャされ、主キーと外部キーの関係ではキャプチャされません。The relations within and across container items are implicitly captured by containment, not by primary key and foreign key relations. この機能は、この記事で後述する項目間結合に重要です。This feature is important for the intra-item joins discussed later in this article.

次のステップNext steps