マルチ検索API

単一のAPIリクエストで複数の検索を実行します。

Python

  1. resp = client.msearch(
  2.    index="my-index-000001",
  3.    searches=[
  4.    {},
  5.    {
  6.    "query": {
  7.    "match": {
  8.    "message": "this is a test"
  9.    }
  10.    }
  11.    },
  12.    {
  13.    "index": "my-index-000002"
  14.    },
  15.    {
  16.    "query": {
  17.    "match_all": {}
  18.    }
  19.    }
  20.    ],
  21. )
  22. print(resp)

Ruby

  1. response = client.msearch(
  2.   index: 'my-index-000001',
  3.   body: [
  4.    {},
  5.    {
  6.    query: {
  7.    match: {
  8.    message: 'this is a test'
  9.    }
  10.    }
  11.    },
  12.    {
  13.    index: 'my-index-000002'
  14.    },
  15.    {
  16.    query: {
  17.    match_all: {}
  18.    }
  19.    }
  20.   ]
  21. )
  22. puts response

Js

  1. const response = await client.msearch({
  2.   index: "my-index-000001",
  3.   searches: [
  4.    {},
  5.    {
  6.    query: {
  7.    match: {
  8.    message: "this is a test",
  9.    },
  10.    },
  11.    },
  12.    {
  13.    index: "my-index-000002",
  14.    },
  15.    {
  16.    query: {
  17.    match_all: {},
  18.    },
  19.    },
  20.   ],
  21. });
  22. console.log(response);

コンソール

  1. GET my-index-000001/_msearch
  2. { }
  3. {"query" : {"match" : { "message": "this is a test"}}}
  4. {"index": "my-index-000002"}
  5. {"query" : {"match_all" : {}}}

リクエスト

GET /<target>/_msearch

前提条件

  • Elasticsearchのセキュリティ機能が有効になっている場合、ターゲットデータストリーム、インデックス、またはエイリアスに対してread インデックス権限を持っている必要があります。クロスクラスタ検索については、リモートクラスタを参照してください。

説明

マルチ検索APIは、単一のAPIリクエストから複数の検索を実行します。リクエストの形式はバルクAPI形式に似ており、改行区切りのJSON（NDJSON）形式を使用します。

構造は次のとおりです：

Js

  1. header\n
  2. body\n
  3. header\n
  4. body\n

この構造は、特定の検索が別のノードにリダイレクトされた場合の解析を減らすように特に最適化されています。

データの最終行は改行文字\nで終わる必要があります。各改行文字の前にはキャリッジリターン\rが付く場合があります。このエンドポイントにリクエストを送信する際は、Content-Typeヘッダーをapplication/x-ndjsonに設定する必要があります。

パスパラメータ

  • <target>
  • （オプション、文字列）検索するデータストリーム、インデックス、およびエイリアスのカンマ区切りリスト。
    このリストは、リクエストボディ内の検索がindexターゲットを指定しない場合のフォールバックとして機能します。
    ワイルドカード（*）式がサポートされています。クラスター内のすべてのデータストリームとインデックスを検索するには、このパラメータを省略するか、_allまたは*を使用します。

クエリパラメータ

  • allow_no_indices
  • （オプション、ブール値）falseの場合、リクエストは、ワイルドカード式、インデックスエイリアス、または_all値が欠落または閉じたインデックスのみをターゲットにする場合にエラーを返します。この動作は、リクエストが他のオープンインデックスをターゲットにしている場合でも適用されます。たとえば、foo*,bar*をターゲットにするリクエストは、fooで始まるインデックスがあるが、barで始まるインデックスがない場合にエラーを返します。
  • ccs_minimize_roundtrips
  • （オプション、ブール値）trueの場合、クロスクラスタ検索リクエストのために、コーディネーショングノードとリモートクラスタ間のネットワークラウンドトリップが最小限に抑えられます。デフォルトはtrueです。クロスクラスタ検索がネットワーク遅延を処理する方法を参照してください。
  • expand_wildcards
  • （オプション、文字列）ワイルドカードパターンが一致できるインデックスのタイプ。リクエストがデータストリームをターゲットにできる場合、この引数はワイルドカード式が隠れたデータストリームに一致するかどうかを決定します。カンマ区切りの値（open,hiddenなど）をサポートします。有効な値は次のとおりです：
    • all
    • すべてのデータストリームまたはインデックスに一致し、隠れたものを含みます。
    • open
    • オープンで非隠れたインデックスに一致します。また、非隠れたデータストリームにも一致します。
    • closed
    • クローズされた非隠れたインデックスに一致します。また、非隠れたデータストリームにも一致します。データストリームはクローズできません。
    • hidden
    • 隠れたデータストリームと隠れたインデックスに一致します。open、closed、またはその両方と組み合わせる必要があります。
    • none
    • ワイルドカードパターンは受け入れられません。
      デフォルトはopenです。
  • ignore_throttled
  • （オプション、ブール値）trueの場合、具体的、拡張された、またはエイリアスされたインデックスは凍結時に無視されます。デフォルトはtrueです。
    [7.16.0] 7.16.0で非推奨。
  • ignore_unavailable
  • （オプション、ブール値）falseの場合、リクエストは欠落またはクローズされたインデックスをターゲットにする場合にエラーを返します。デフォルトはfalseです。
  • max_concurrent_searches
  • （オプション、整数）マルチ検索APIが実行できる同時検索の最大数。デフォルトはmax(1, (# of data nodes * min(search thread pool size, 10)))です。
  • max_concurrent_shard_requests
  • （オプション、整数）各サブ検索リクエストがノードごとに実行する同時シャードリクエストの最大数。デフォルトは5です。
    このパラメータを使用して、リクエストがクラスターを過負荷にするのを防ぐことができます。たとえば、デフォルトのリクエストはクラスター内のすべてのデータストリームとインデックスにヒットします。ノードごとのシャード数が多い場合、これによりシャードリクエストの拒否が発生する可能性があります。
    特定のシナリオでは、並列性は同時リクエストを通じて達成されません。その場合、このパラメータの低い値はパフォーマンスの低下を引き起こす可能性があります。たとえば、非常に少数の同時検索リクエストが予想される環境では、このパラメータの高い値がパフォーマンスを向上させる可能性があります。
  • pre_filter_shard_size
  • （オプション、整数）検索リクエストが拡張されるシャードの数がしきい値を超える場合、クエリの書き換えに基づいて検索シャードを事前フィルタリングするためのプレフィルタラウンドトリップを強制するしきい値を定義します。このフィルタラウンドトリップは、たとえば、シャードがその書き換え方法に基づいてドキュメントに一致できない場合に、シャードの数を大幅に制限できます。すなわち、日付フィルタが一致するために必須であるが、シャードの境界とクエリが不連続である場合です。指定されていない場合、次の条件のいずれかが満たされると、プレフィルタフェーズが実行されます：
    • リクエストが128シャードをターゲットにします。
    • リクエストが1つ以上の読み取り専用インデックスをターゲットにします。
    • クエリの主なソートがインデックスフィールドをターゲットにします。
  • rest_total_hits_as_int
  • （オプション、ブール値）trueの場合、hits.totalはレスポンス内で整数として返されます。デフォルトはfalseで、オブジェクトが返されます。
  • routing
  • （オプション、文字列）検索操作を特定のシャードにルーティングするために使用されるカスタムルーティング値。
  • search_type
  • （オプション、文字列）返されたドキュメントのスコアリングにグローバルな用語およびドキュメント頻度を使用するかどうかを示します。
    オプションは次のとおりです：
    • query_then_fetch
    • （デフォルト）ドキュメントはシャードのローカルな用語およびドキュメント頻度を使用してスコアリングされます。これは通常は速いですが、正確性は低いです。
    • dfs_query_then_fetch
    • ドキュメントはすべてのシャードにわたるグローバルな用語およびドキュメント頻度を使用してスコアリングされます。これは通常は遅いですが、より正確です。
  • typed_keys
  • （オプション、ブール値）集約およびサジェスター名がレスポンス内でそれぞれのタイプによってプレフィックスされるべきかどうかを指定します。

リクエストボディ

リクエストボディには、改行区切りの検索<header>および検索<body>オブジェクトのリストが含まれています。

  • <header>
  • （必須、オブジェクト）検索を制限または変更するために使用されるパラメータ。
    このオブジェクトは各検索ボディに必要ですが、空（{}）または空行にすることができます。 
    1. -   `````allow_no_indices
    • （オプション、ブール値）trueの場合、ワイルドカード式または_all値が欠落またはクローズされたインデックスのみを取得する場合、リクエストはエラーを返しません。
      このパラメータは、欠落またはインデックスを指すエイリアスにも適用されます。
    • expand_wildcards
    • （オプション、文字列）ワイルドカードパターンが一致できるインデックスのタイプ。リクエストがデータストリームをターゲットにできる場合、この引数はワイルドカード式が隠れたデータストリームに一致するかどうかを決定します。カンマ区切りの値（open,hiddenなど）をサポートします。有効な値は次のとおりです：
      • all
      • すべてのデータストリームまたはインデックスに一致し、隠れたものを含みます。
      • open
      • オープンで非隠れたインデックスに一致します。また、非隠れたデータストリームにも一致します。
      • closed
      • クローズされた非隠れたインデックスに一致します。また、非隠れたデータストリームにも一致します。データストリームはクローズできません。
      • hidden
      • 隠れたデータストリームと隠れたインデックスに一致します。open、closed、またはその両方と組み合わせる必要があります。
      • none
      • ワイルドカードパターンは受け入れられません。
        デフォルトはopenです。
    • ignore_unavailable
    • （オプション、ブール値）trueの場合、欠落またはクローズされたインデックスからのドキュメントはレスポンスに含まれません。デフォルトはfalseです。
    • index
    • （オプション、文字列または文字列の配列）検索するデータストリーム、インデックス、およびエイリアス。ワイルドカード（*）をサポートします。複数のターゲットを配列として指定します。
      このパラメータが指定されていない場合、<target>リクエストパスパラメータがフォールバックとして使用されます。
    • preference
    • （オプション、文字列）検索を実行するために使用されるノードまたはシャード。デフォルトはランダムです。
    • request_cache
    • （オプション、ブール値）trueの場合、リクエストキャッシュはこの検索に使用できます。デフォルトはインデックスレベルの設定です。シャードリクエストキャッシュ設定を参照してください。
    • routing
    • （オプション、文字列）検索操作を特定のシャードにルーティングするために使用されるカスタムルーティング値。
    • search_type
    • （オプション、文字列）返されたドキュメントのスコアリングにグローバルな用語およびドキュメント頻度を使用するかどうかを示します。
      オプションは次のとおりです：
      • query_then_fetch
      • （デフォルト）ドキュメントはシャードのローカルな用語およびドキュメント頻度を使用してスコアリングされます。これは通常は速いですが、正確性は低いです。
      • dfs_query_then_fetch
      • ドキュメントはすべてのシャードにわたるグローバルな用語およびドキュメント頻度を使用してスコアリングされます。これは通常は遅いですが、より正確です。
  • <body>
  • （オプション、オブジェクト）検索リクエストのパラメータを含みます： 
    1. -   `````aggregations
    • （オプション、集約オブジェクト）検索中に実行したい集約。 集約を参照してください。
    • query
    • （オプション、クエリDSLオブジェクト）検索中に実行したいクエリ。このクエリに一致するヒットがレスポンスに返されます。
    • from
    • （オプション、整数）返されるヒットの開始オフセット。デフォルトは0です。
    • size
    • （オプション、整数）返すヒットの数。デフォルトは10です。

レスポンスボディ

  • responses
  • （配列）元のマルチ検索リクエストの順序に一致する各検索リクエストの検索レスポンスとステータスコードを含みます。特定の検索リクエストに完全な失敗があった場合、実際の検索レスポンスの代わりにerrorメッセージと対応するステータスコードを持つオブジェクトが返されます。

例

ヘッダーには、検索するデータストリーム、インデックス、およびエイリアスが含まれています。ヘッダーはまた、search_type、preference、およびroutingを示します。ボディには、典型的な検索ボディリクエスト（query、aggregations、from、sizeなどを含む）が含まれています。

Js

  1. $ cat requests
  2. {"index" : "test"}
  3. {"query" : {"match_all" : {}}, "from" : 0, "size" : 10}
  4. {"index" : "test", "search_type" : "dfs_query_then_fetch"}
  5. {"query" : {"match_all" : {}}}
  6. {}
  7. {"query" : {"match_all" : {}}}
  9. {"query" : {"match_all" : {}}}
  10. {"search_type" : "dfs_query_then_fetch"}
  11. {"query" : {"match_all" : {}}}

Js

  1. $ curl -H "Content-Type: application/x-ndjson" -XGET localhost:9200/_msearch --data-binary "@requests"; echo

注意：上記には、空のヘッダーの例が含まれています（コンテンツなしでも可能）これはサポートされています。

エンドポイントは、リクエストパス内のデータストリーム、インデックス、およびエイリアスに対して検索することも許可します。この場合、ヘッダーのindexパラメータで明示的に指定されない限り、デフォルトのターゲットとして使用されます。たとえば：

Python

  1. resp = client.msearch(
  2.    index="my-index-000001",
  3.    searches=[
  4.    {},
  5.    {
  6.    "query": {
  7.    "match_all": {}
  8.    },
  9.    "from": 0,
  10.    "size": 10
  11.    },
  12.    {},
  13.    {
  14.    "query": {
  15.    "match_all": {}
  16.    }
  17.    },
  18.    {
  19.    "index": "my-index-000002"
  20.    },
  21.    {
  22.    "query": {
  23.    "match_all": {}
  24.    }
  25.    }
  26.    ],
  27. )
  28. print(resp)

Ruby

  1. response = client.msearch(
  2.   index: 'my-index-000001',
  3.   body: [
  4.    {},
  5.    {
  6.    query: {
  7.    match_all: {}
  8.    },
  9.    from: 0,
  10.    size: 10
  11.    },
  12.    {},
  13.    {
  14.    query: {
  15.    match_all: {}
  16.    }
  17.    },
  18.    {
  19.    index: 'my-index-000002'
  20.    },
  21.    {
  22.    query: {
  23.    match_all: {}
  24.    }
  25.    }
  26.   ]
  27. )
  28. puts response

Js

  1. const response = await client.msearch({
  2.   index: "my-index-000001",
  3.   searches: [
  4.    {},
  5.    {
  6.    query: {
  7.    match_all: {},
  8.    },
  9.    from: 0,
  10.    size: 10,
  11.    },
  12.    {},
  13.    {
  14.    query: {
  15.    match_all: {},
  16.    },
  17.    },
  18.    {
  19.    index: "my-index-000002",
  20.    },
  21.    {
  22.    query: {
  23.    match_all: {},
  24.    },
  25.    },
  26.   ],
  27. });
  28. console.log(response);

コンソール

  1. GET my-index-000001/_msearch
  2. {}
  3. {"query" : {"match_all" : {}}, "from" : 0, "size" : 10}
  4. {}
  5. {"query" : {"match_all" : {}}}
  6. {"index" : "my-index-000002"}
  7. {"query" : {"match_all" : {}}}

上記は、リクエストボディ内でindexターゲットを定義しないすべてのリクエストに対してmy-index-000001インデックスに対して検索を実行します。最後の検索はmy-index-000002インデックスに対して実行されます。

search_typeは、すべての検索リクエストにグローバルに適用するために同様の方法で設定できます。

セキュリティ

詳細はURLベースのアクセス制御を参照してください。

部分的なレスポンス

迅速なレスポンスを確保するために、マルチ検索APIは1つ以上のシャードが失敗した場合に部分的な結果で応答します。詳細については、シャードの失敗を参照してください。

検索のキャンセル

マルチ検索は、標準のタスクキャンセルメカニズムを使用してキャンセルでき、リクエストを実行するために使用されるhttp接続がクライアントによって閉じられると自動的にキャンセルされます。リクエストを送信するhttpクライアントは、リクエストがタイムアウトまたは中止されたときに接続を閉じることが重要です。msearchリクエストをキャンセルすると、対応するすべてのサブ検索リクエストもキャンセルされます。