コレクション

  • [アーティクル]

Azure Cosmos DB は、ドキュメント、グラフ、キー値のデータ モデルをサポートするグローバルに分散されたマルチモデル データベースです。 このセクションの内容は、REST を介して SQL API を使用してコレクション リソースを作成、クエリ、および管理するための内容です。

REST API では、データベース アカウントのリソースに対する基本的な CRUD 操作がサポートされています。 コレクションは、JSON ドキュメントおよび関連の JavaScript アプリケーション ロジック、つまりストアド プロシージャ、トリガー、およびユーザー定義関数のコンテナーです。 このトピックでは、ドキュメント コレクションの管理に使用される REST 操作の概要について説明します。

注意

これらの API リファレンス記事では、Azure Cosmos DB データ プレーン API を使用してリソースを作成する方法について説明します。 データ プレーン API を使用すると、Cosmos DB SDK と同様に、インデックス作成ポリシー、パーティション キーなどの基本的なオプションを構成できます。 すべての Azure Cosmos DB リソースの完全な機能サポートが必要な場合は、 Cosmos DB リソース プロバイダーを使用することをお勧めします。

コレクションは、Azure Cosmos DB のコンテナーにマップされます。 したがって、課金対象エンティティであり、コストは、1 秒あたりの要求ユニット数で表されるプロビジョニングされたスループットによって決まります。 コレクションは、1 つ以上のパーティション/サーバーにまたがる場合があり、スループットの観点からスケールアップとスケールダウンが可能です。 コレクションは、Azure Cosmos DB によって 1 つ以上の物理サーバーに自動的にパーティション分割されます。

コレクションはシステム リソースであるため、固定スキーマが含まれます。 コレクションの URI パスは、 リソース モデルの colls によって表されます。

次の例は、コレクションの JSON 定義を示しています。

{  
  "id": "testcoll",  
  "indexingPolicy": {  
    "indexingMode": "consistent",  
    "automatic": true,  
    "includedPaths": [  
      {  
        "path": "/*",  
        "indexes": [  
          {  
            "kind": "Range",  
            "dataType": "String",  
            "precision": -1  
          },  
          {  
            "kind": "Range",  
            "dataType": "Number",  
            "precision": -1  
          }  
        ]  
      }  
    ],  
    "excludedPaths": []  
  },  
  "partitionKey": {  
    "paths": [  
      "/AccountNumber"  
    ],  
    "kind": "Hash"  
  },  
  "_rid": "PD5DALigDgw=",  
  "_ts": 1459200611,  
  "_self": "dbs/PD5DAA==/colls/PD5DALigDgw=/",  
  "_etag": "\"00005900-0000-0000-0000-56f9a2630000\"",  
  "_docs": "docs/",  
  "_sprocs": "sprocs/",  
  "_triggers": "triggers/",  
  "_udfs": "udfs/",  
  "_conflicts": "conflicts/"  
}
プロパティ 説明
id これは、新しいコレクションを識別する一意の名前です。
indexingPolicy コレクションのインデックス作成ポリシー設定です。
partitionKey コレクションのパーティション分割構成設定です。
_解消 これは、システムによって生成されるプロパティです。 リソース ID (_rid) は、リソース モデル上のリソース スタックごとに階層化された一意識別子です。 アクセス許可リソースの配置およびナビゲーションのために内部的に使用されます。
_Ts これは、システムによって生成されるプロパティです。 リソースの最終更新タイムスタンプを示します。 値は、タイムスタンプです。
_自己 これは、システムによって生成されるプロパティです。 リソースの一意のアドレス指定が可能な URI です。
_Etag これは、オプティミスティック コンカレンシー制御に必要なリソース etag を表すシステム生成プロパティです。
_ドキュメント ドキュメント リソースのアドレス指定可能パスを指定するシステム生成プロパティです。
_Sprocs ストアド プロシージャ (sprocs) リソースのアドレス指定可能パスを指定するシステム生成プロパティです。
_トリガー トリガー リソースのアドレス指定可能パスを指定するシステム生成プロパティです。
_Udf これは、ユーザー定義関数 (udfs) リソースのアドレス指定可能パスを指定するシステム生成プロパティです。
_競合 競合するリソースのアドレス指定可能パスを指定するシステム生成プロパティです。 コレクション内のリソースに対する操作で競合が発生した場合は、ユーザーが競合の URI パスに GET を実行して、競合しているリソースを検査することができます。

[インデックス作成ポリシー] のプロパティ

プロパティ 説明
自動 自動インデックス作成が有効か無効かを示します。 既定値は True であるため、すべてのドキュメントにインデックスが作成されます。 値を False に 設定すると、インデックス作成パスを手動で構成できます。
indexingMode 既定では、インデックス作成モードは [一貫性] です。 つまり、インデックス作成は、ドキュメントの挿入、置換、または削除中に同期的に行われます。 非同期的にインデックスを作成するには、インデックス作成モードを [遅延] に設定します。
includedPaths インデックスが作成されるドキュメントのパスを含む配列。 既定では、2 つのパスが含まれます。/ パスは、すべてのドキュメント パスにインデックスを作成することを指定します。また、タイムスタンプ範囲比較のインデックスを作成する _ts パスです。
excludedPaths インデックスの作成から除外されるドキュメントのパスを含む配列です。

[インクルード パス] のプロパティ

プロパティ 説明
path インデックス作成の動作が適用されるパス。 インデックスのパスはルート (/) で始まり、通常、 ? ワイルドカード演算子で終わります。これは、プレフィックスに複数の可能な値があることを示します。 たとえば、SELECT * FROM Families F WHERE F.familyName = "Andersen" を処理するには、コレクションのインデックス ポリシーに /familyName/? の インデックスのパスを含める必要があります。

インデックスのパスは * ワイルドカード演算子を使用して、プレフィックスの後ろに続くパスの動作を再帰的に指定することもできます。 たとえば、/payload/* を使用して、インデックス作成からペイロード プロパティの下にあるすべてのものを含めることができます。
dataType インデックス作成の動作が適用されるデータ型です。 String、Number、Point、Polygon、LineString のいずれかを指定できます。 ブール値と null 値は自動的にインデックスが作成されます
kind インデックスの種類です。 ハッシュ インデックスは等値比較に役立ちますが、 Range インデックスは等値、範囲比較、並べ替えに役立ちます。 空間 インデックスは、空間クエリに役立ちます。
有効桁数 (precision) インデックスの有効桁数。 最大有効桁数の場合は -1、 Number の場合は 1 から 8、 String の場合は 1 から 100 に設定できます。 Point、Polygon、LineString のデータ型には適用されません。

[除外されたパス] のプロパティ

プロパティ 説明
path インデックス作成から除外されるパス。 インデックス パスはルート (/) で始まり、通常は * ワイルドカード演算子で終わる。 たとえば、/payload/* を使用して、ペイロード プロパティの下に属するものをすべてインデックス作成から除外できます。

[パーティション キー] のプロパティ

プロパティ 説明
path コレクション内のデータをパーティション分割できるパスの配列。 パスには、ワイルドカードまたは末尾のスラッシュを含めてはいけません。 たとえば、JSON プロパティ "AccountNumber" は "/AccountNumber" として指定されます。 配列には 1 つの値のみを含む必要があります。
kind パーティション分割に使用されるアルゴリズム。 Hash のみがサポートされています。

インデックス作成ポリシー

ドキュメントがコレクションに追加されると、Cosmos DB は既定でドキュメントのインデックスを自動的に作成するため、ドキュメントのクエリを実行できます。 インデックス作成のポリシーはコレクション レベルで構成します。 インデックス作成ポリシーがコレクション レベルで設定されるため、データベース内の各コレクションでインデックス作成ポリシーが異なることがあります。

コレクションのインデックス作成ポリシーでは、次のオプションを指定できます。

  • 自動: コレクションですべてのドキュメントのインデックスを自動的に作成するかどうかを選択できます。 既定では、すべてのドキュメントのインデックスが自動的に作成されますが、これを無効にすることができます。 自動インデックス作成が無効になっている場合、自己リンクまたは ID を使用したクエリでのみドキュメントにアクセスできます。

  • インデックス作成モード: 同期 (整合性)、非同期 (遅延) インデックス更新、インデックス作成なし (なし) のいずれかを選択できます。 既定では、インデックスはコレクション内のドキュメントに対する挿入、置換、または削除の操作が実行されるたびに同期的に更新されます。 この更新により、クエリはドキュメントの読み取りと同じ整合性レベルを受け入れ、インデックスが追いつくのを遅延なく実行できます。

  • インデックスの種類と有効桁数: インデックス エントリに使用される型またはスキームは、インデックスのストレージとパフォーマンスに直接影響します。 スキームの精度が高いほど、クエリは一般的に高速になります。 ただし、インデックスのストレージのオーバーヘッドも大きくなります。 低い精度を選択すると、クエリ実行時により多くのドキュメントを処理する必要があることを意味しますが、ストレージのオーバーヘッドは小さくなります。

  • インデックス パス: ドキュメント内で、インデックス作成に含めるか除外する必要があるパスを選択できます。これにより、クエリ パターンが事前にわかっている場合に、書き込みパフォーマンスが向上し、インデックス ストレージが低下する可能性があります。

次の表に、いくつかのインデックスのパスのサンプルと、クエリ内で使用する方法を示します。

プロパティ 説明
/* コレクションの既定のパス。 再帰的で、ドキュメント ツリー全体に適用されます。
/prop/? 次のようなクエリを処理するために必要なインデックスのパス (ハッシュまたは範囲の各種類)。

SELECT * FROM collection c WHERE c.prop = "value"

SELECT * FROM collection c WHERE c.prop > 5

SELECT * FROM collection c ORDER BY c.prop
/"prop"/* 指定されたラベルの下のすべてのパスのインデックスのパス。 次のクエリで動作します。

SELECT * FROM collection c WHERE c.prop = "value"

SELECT * FROM collection c WHERE c.prop.subprop > 5

SELECT * FROM collection c WHERE c.prop.subprop.nextprop = "value"

SELECT * FROM collection c ORDER BY c.prop
/props/[]/? などのスカラーの配列に対して反復クエリと JOIN クエリを処理するために必要なインデックス パス

["a", "b", "c"]:

SELECT tag FROM tag IN collection.props WHERE tag = "value"

SELECT tag FROM collection c JOIN tag IN c.props WHERE tag > 5
/props/[]/subprop/? などのオブジェクトの配列に対するイテレーションと JOIN クエリを処理するために必要なインデックス パス

[{subprop: "a"}, {subprop: "b"}]:

SELECT tag FROM tag IN collection.props WHERE tag.subprop = "value"

SELECT tag FROM collection c JOIN tag IN c.props WHERE tag.subprop = "value"
/prop/subprop/? 次のクエリを処理するために必要なインデックスのパス (ハッシュまたは範囲の各種類)。

SELECT * FROM collection c WHERE c.prop.subprop = "value"

SELECT * FROM collection c WHERE c.prop.subprop > 5

SELECT * FROM collection c ORDER BY c.prop.subprop

Cosmos DB インデックス作成ポリシーの詳細については、「Cosmos DB インデックス作成ポリシー」を参照してください。 REST API ドキュメントの作成のため、すべての例で自動インデックス作成を使用します。

オファーとパフォーマンス レベル

コレクションが作成されると、作成されたコレクションを参照する Offer リソースも作成されます。 オファー リソースには、1 秒あたりの要求ユニット数と 1 分あたりの要求ユニット数のコレクション スループットに関する構成情報が含まれています。

コレクションのパフォーマンス レベルは、[オファーの置換] を使用して変更できます。

タスク

ドキュメント コレクションでは、次の操作を実行できます。