Azure Cosmos DB の JavaScript クエリ API

適用対象: SQL API

Azure Cosmos DB の SQL API を使用してクエリを発行することに加えて、Cosmos DB のサーバー側の SDK を使用すると、JavaScript インターフェイスを使用して Cosmos DB ストアド プロシージャやトリガーで最適化されたクエリを実行できます。 この JavaScript インターフェイスの使用では、SQL 言語を意識する必要はありません。 JavaScript クエリ API では、述語関数を一連の関数呼び出しに渡すことでクエリをプログラムで構築できます。構文は ECMAScript5 のアレイ ビルトインや Lodash のような人気の JavaScript ライブラリでおなじみのものです。 クエリは JavaScript ランタイムによって解析され、Azure Cosmos DB のインデックスを使用して効率的に実行されます。

サポートされている JavaScript 関数

Function 説明
chain() ... .value([callback] [, options]) 連鎖呼び出しを開始します。連鎖呼び出しは value() で終わる必要があります。
filter(predicateFunction [, options] [, callback]) 入力ドキュメントを結果セットに含めたり除外したりするために、true/false を返す述語関数を使用して入力をフィルター処理します。 この関数の動作は SQL の WHERE 句に似ています。
flatten([isShallow] [, options] [, callback]) 各入力項目の配列を結合し、一次元配列にします。 この関数の動作は LINQ の SelectMany に似ています。
map(transformationFunction [, options] [, callback]) 各入力項目を JavaScript オブジェクトまたは値にマッピングする変換関数によって返される射影を適用します。 この関数の動作は SQL の SELECT 句に似ています。
pluck([propertyName] [, options] [, callback]) この関数は map のショートカット版で、各入力項目から 1 つのプロパティの値を抽出します。
sortBy([predicate] [, options] [, callback]) 指定された述語を使用して、入力ドキュメント ストリーム内のドキュメントを昇順で並べ替え、ドキュメントの新しいセットを生成します。 この関数の動作は SQL の ORDER BY 句に似ています。
sortByDescending([predicate] [, options] [, callback]) 指定された述語を使用して、入力ドキュメント ストリーム内のドキュメントを降順で並べ替え、ドキュメントの新しいセットを生成します。 この関数の動作は SQL の ORDER BY x DESC 句に似ています。
unwind(collectionSelector, [resultSelector], [options], [callback]) 内部配列との自己結合を実行し、両側からの結果をタプルとして結果プロジェクションに追加します。 たとえば、person ドキュメントと person.pets を結合すると、[person, pet] タプルが生成されます。 これは、.NET LINK の SelectMany に似ています。

述語またはセレクター関数の中に含まれるとき、次の JavaScript コンストラクトは自動的に最適化され、Azure Cosmos DB インデックスで直接実行されます。

  • 単純演算子: = + - * / % | ^ & == != === !=== < > <= >= || && << >> >>>! ~
  • オブジェクト リテラルを含むリテラル: {}
  • var、return

次の JavaScript コンストラクトは Azure Cosmos DB インデックスに対して最適化されません。

  • 制御フロー (if、for、while など)
  • 関数呼び出し

詳細については、Cosmos DB のサーバー側 JavaScript のドキュメントを参照してください。

SQL と JavaScript のチート シート

次の表はさまざまな SQL クエリとそれに対応する JavaScript クエリをまとめたものです。 SQL クエリと同様に、プロパティ (item.id など) では大文字と小文字が区別されます。

注意

__ (2 つのアンダースコア) は JavaScript クエリ API を使用する場合の getContext().getCollection() のエイリアスです。

SQL JavaScript クエリ API 説明
SELECT *
FROM docs
__.map(function(doc) {
    return doc;
});
結果的にすべてのドキュメントがそのまま生成されます (継続トークンで改ページ調整されます)。
SELECT
   docs.id、
   docs.message AS msg、
   docs.actions
FROM docs
__.map(function(doc) {
    return {
        id: doc.id,
        msg: doc.message,
        actions:doc.actions
    };
});
すべてのドキュメントから ID、メッセージ (エイリアスは msg)、アクションを射影します。
SELECT *
FROM docs
WHERE
   docs.id="X998_Y998"
__.filter(function(doc) {
    return doc.id ==="X998_Y998";
});
述語に id = "X998_Y998" を指定して、ドキュメントに対してクエリします。
SELECT *
FROM docs
WHERE
   ARRAY_CONTAINS(docs.Tags, 123)
__.filter(function(x) {
    return x.Tags && x.Tags.indexOf(123) > -1;
});
Tags プロパティを持つドキュメントに対してクエリします。Tags は値 123 を含む配列です。
SELECT
   docs.id、
   docs.message AS msg
FROM docs
WHERE
   docs.id="X998_Y998"
__.chain()
    .filter(function(doc) {
        return doc.id ==="X998_Y998";
    })
    .map(function(doc) {
       return {
            id: doc.id,
            msg: doc.message
       };
    })
.value();
述語に id = "X998_Y998" を指定してドキュメントに対してクエリし、ID とメッセージ (エイリアスは msg) を射影します。
SELECT VALUE tag
FROM docs
JOIN tag IN docs.Tags
ORDER BY docs._ts
__.chain()
    .filter(function(doc) {
        return doc.Tags && Array.isArray(doc.Tags);
    })
    .sortBy(function(doc) {
        return doc._ts;
    })
    .pluck("Tags")
    .flatten()
    .value()
配列プロパティ Tags のあるドキュメントをフィルター処理し、生成されたドキュメントを _ts タイムスタンプ システム プロパティで並べ替え、射影して Tags 配列を一次元配列にします。

次のステップ

Azure Cosmos DB でストアド プロシージャ、トリガー、およびユーザー定義関数を記述および使用する方法および概念について学習します。