Validate API

クエリを実行せずに、潜在的に高コストなクエリを検証します。

Python

  1. resp = client.indices.validate_query(
  2.    index="my-index-000001",
  3.    q="user.id:kimchy",
  4. )
  5. print(resp)

Ruby

  1. response = client.indices.validate_query(
  2.   index: 'my-index-000001',
  3.   q: 'user.id:kimchy'
  4. )
  5. puts response

Js

  1. const response = await client.indices.validateQuery({
  2.   index: "my-index-000001",
  3.   q: "user.id:kimchy",
  4. });
  5. console.log(response);

Console

  1. GET my-index-000001/_validate/query?q=user.id:kimchy

Request

GET /<target>/_validate/<query>

Prerequisites

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

Description

validate APIを使用すると、クエリを実行せずに潜在的に高コストなクエリを検証できます。クエリは、パスパラメータまたはリクエストボディのいずれかとして送信できます。

Path parameters

  • <target>
  • （オプション、文字列）検索するデータストリーム、インデックス、およびエイリアスのカンマ区切りリスト。ワイルドカード（*）をサポートします。すべてのデータストリームまたはインデックスを検索するには、このパラメータを省略するか、*または_allを使用します。
  • query
  • （オプション、クエリオブジェクト）Query DSLを使用して検索定義を定義します。

Query parameters

  • all_shards
  • （オプション、ブール値）trueの場合、検証はインデックスごとに1つのランダムなシャードではなく、すべてのシャードで実行されます。デフォルトはfalseです。
  • allow_no_indices
  • （オプション、ブール値）falseの場合、リクエストは、ワイルドカード式、インデックスエイリアス、または_all値が欠落または閉じたインデックスのみをターゲットにする場合にエラーを返します。この動作は、リクエストが他のオープンインデックスをターゲットにしている場合でも適用されます。たとえば、foo*,bar*をターゲットにするリクエストは、fooで始まるインデックスがあるが、barで始まるインデックスがない場合にエラーを返します。
    デフォルトはfalseです。
  • analyzer
  • （オプション、文字列）クエリ文字列に使用するアナライザー。
    このパラメータは、qクエリ文字列パラメータが指定されている場合にのみ使用できます。
  • analyze_wildcard
  • （オプション、ブール値）trueの場合、ワイルドカードおよびプレフィックスクエリが分析されます。デフォルトはfalseです。
    このパラメータは、qクエリ文字列パラメータが指定されている場合にのみ使用できます。
  • default_operator
  • （オプション、文字列）クエリ文字列クエリのデフォルト演算子：ANDまたはOR。デフォルトはORです。
    このパラメータは、qクエリ文字列パラメータが指定されている場合にのみ使用できます。
  • df
  • （オプション、文字列）クエリ文字列にフィールドプレフィックスが指定されていない場合にデフォルトとして使用するフィールド。
    このパラメータは、qクエリ文字列パラメータが指定されている場合にのみ使用できます。
  • expand_wildcards
  • （オプション、文字列）ワイルドカードパターンが一致できるインデックスのタイプ。リクエストがデータストリームをターゲットにできる場合、この引数はワイルドカード式が隠れたデータストリームに一致するかどうかを決定します。カンマ区切りの値（open,hiddenなど）をサポートします。有効な値は：
    • all
    • すべてのデータストリームまたはインデックスに一致し、隠れたものも含まれます。
    • open
    • オープンで非隠れたインデックスに一致します。また、非隠れたデータストリームにも一致します。
    • closed
    • クローズドで非隠れたインデックスに一致します。また、非隠れたデータストリームにも一致します。データストリームはクローズできません。
    • hidden
    • 隠れたデータストリームおよび隠れたインデックスに一致します。open、closed、またはその両方と組み合わせる必要があります。
    • none
    • ワイルドカードパターンは受け付けられません。
  • explain
  • （オプション、ブール値）trueの場合、エラーが発生した場合に詳細情報が返されます。デフォルトはfalseです。
  • ignore_unavailable
  • （オプション、ブール値）falseの場合、欠落またはクローズされたインデックスをターゲットにする場合、リクエストはエラーを返します。デフォルトはfalseです。
  • lenient
  • （オプション、ブール値）trueの場合、クエリ文字列内の形式ベースのクエリ失敗（数値フィールドにテキストを提供するなど）は無視されます。デフォルトはfalseです。
    このパラメータは、qクエリ文字列パラメータが指定されている場合にのみ使用できます。
  • rewrite
  • （オプション、ブール値）trueの場合、実行される実際のLuceneクエリを示すより詳細な説明が返されます。デフォルトはfalseです。
  • q
  • （オプション、文字列）Luceneクエリ文字列構文のクエリ。

Examples

Python

  1. resp = client.bulk(
  2.    index="my-index-000001",
  3.    refresh=True,
  4.    operations=[
  5.    {
  6.    "index": {
  7.    "_id": 1
  8.    }
  9.    },
  10.    {
  11.    "user": {
  12.    "id": "kimchy"
  13.    },
  14.    "@timestamp": "2099-11-15T14:12:12",
  15.    "message": "trying out Elasticsearch"
  16.    },
  17.    {
  18.    "index": {
  19.    "_id": 2
  20.    }
  21.    },
  22.    {
  23.    "user": {
  24.    "id": "kimchi"
  25.    },
  26.    "@timestamp": "2099-11-15T14:12:13",
  27.    "message": "My user ID is similar to kimchy!"
  28.    }
  29.    ],
  30. )
  31. print(resp)

Ruby

  1. response = client.bulk(
  2.   index: 'my-index-000001',
  3.   refresh: true,
  4.   body: [
  5.    {
  6.    index: {
  7.    _id: 1
  8.    }
  9.    },
  10.    {
  11.    user: {
  12.    id: 'kimchy'
  13.    },
  14.    "@timestamp": '2099-11-15T14:12:12',
  15.    message: 'trying out Elasticsearch'
  16.    },
  17.    {
  18.    index: {
  19.    _id: 2
  20.    }
  21.    },
  22.    {
  23.    user: {
  24.    id: 'kimchi'
  25.    },
  26.    "@timestamp": '2099-11-15T14:12:13',
  27.    message: 'My user ID is similar to kimchy!'
  28.    }
  29.   ]
  30. )
  31. puts response

Js

  1. const response = await client.bulk({
  2.   index: "my-index-000001",
  3.   refresh: "true",
  4.   operations: [
  5.    {
  6.    index: {
  7.    _id: 1,
  8.    },
  9.    },
  10.    {
  11.    user: {
  12.    id: "kimchy",
  13.    },
  14.    "@timestamp": "2099-11-15T14:12:12",
  15.    message: "trying out Elasticsearch",
  16.    },
  17.    {
  18.    index: {
  19.    _id: 2,
  20.    },
  21.    },
  22.    {
  23.    user: {
  24.    id: "kimchi",
  25.    },
  26.    "@timestamp": "2099-11-15T14:12:13",
  27.    message: "My user ID is similar to kimchy!",
  28.    },
  29.   ],
  30. });
  31. console.log(response);

Console

  1. PUT my-index-000001/_bulk?refresh
  2. {"index":{"_id":1}}
  3. {"user" : { "id": "kimchy" }, "@timestamp" : "2099-11-15T14:12:12", "message" : "trying out Elasticsearch"}
  4. {"index":{"_id":2}}
  5. {"user" : { "id": "kimchi" }, "@timestamp" : "2099-11-15T14:12:13", "message" : "My user ID is similar to kimchy!"}

有効なクエリが送信された場合：

Python

  1. resp = client.indices.validate_query(
  2.    index="my-index-000001",
  3.    q="user.id:kimchy",
  4. )
  5. print(resp)

Ruby

  1. response = client.indices.validate_query(
  2.   index: 'my-index-000001',
  3.   q: 'user.id:kimchy'
  4. )
  5. puts response

Js

  1. const response = await client.indices.validateQuery({
  2.   index: "my-index-000001",
  3.   q: "user.id:kimchy",
  4. });
  5. console.log(response);

Console

  1. GET my-index-000001/_validate/query?q=user.id:kimchy

レスポンスにはvalid:trueが含まれます：

Console-Result

  1. {"valid":true,"_shards":{"total":1,"successful":1,"failed":0}}

クエリはリクエストボディ内でも送信できます：

Python

  1. resp = client.indices.validate_query(
  2.    index="my-index-000001",
  3.    query={
  4.    "bool": {
  5.    "must": {
  6.    "query_string": {
  7.    "query": "*:*"
  8.    }
  9.    },
  10.    "filter": {
  11.    "term": {
  12.    "user.id": "kimchy"
  13.    }
  14.    }
  15.    }
  16.    },
  17. )
  18. print(resp)

Ruby

  1. response = client.indices.validate_query(
  2.   index: 'my-index-000001',
  3.   body: {
  4.    query: {
  5.    bool: {
  6.    must: {
  7.    query_string: {
  8.    query: '*:*'
  9.    }
  10.    },
  11.    filter: {
  12.    term: {
  13.    'user.id' => 'kimchy'
  14.    }
  15.    }
  16.    }
  17.    }
  18.   }
  19. )
  20. puts response

Js

  1. const response = await client.indices.validateQuery({
  2.   index: "my-index-000001",
  3.   query: {
  4.    bool: {
  5.    must: {
  6.    query_string: {
  7.    query: "*:*",
  8.    },
  9.    },
  10.    filter: {
  11.    term: {
  12.    "user.id": "kimchy",
  13.    },
  14.    },
  15.    },
  16.   },
  17. });
  18. console.log(response);

Console

  1. GET my-index-000001/_validate/query
  2. {
  3.   "query" : {
  4.    "bool" : {
  5.    "must" : {
  6.    "query_string" : {
  7.    "query" : "*:*"
  8.    }
  9.    },
  10.    "filter" : {
  11.    "term" : { "user.id" : "kimchy" }
  12.    }
  13.    }
  14.   }
  15. }

ボディ内で送信されるクエリは、queryキー内にネストされている必要があります。これはsearch apiと同様に機能します。

クエリが無効な場合、validはfalseになります。ここで、クエリが無効である理由は、Elasticsearchがpost_dateフィールドが動的マッピングにより日付であるべきだと知っているためであり、fooは日付として正しく解析されません：

Python

  1. resp = client.indices.validate_query(
  2.    index="my-index-000001",
  3.    query={
  4.    "query_string": {
  5.    "query": "@timestamp:foo",
  6.    "lenient": False
  7.    }
  8.    },
  9. )
  10. print(resp)

Ruby

  1. response = client.indices.validate_query(
  2.   index: 'my-index-000001',
  3.   body: {
  4.    query: {
  5.    query_string: {
  6.    query: '@timestamp:foo',
  7.    lenient: false
  8.    }
  9.    }
  10.   }
  11. )
  12. puts response

Js

  1. const response = await client.indices.validateQuery({
  2.   index: "my-index-000001",
  3.   query: {
  4.    query_string: {
  5.    query: "@timestamp:foo",
  6.    lenient: false,
  7.    },
  8.   },
  9. });
  10. console.log(response);

Console

  1. GET my-index-000001/_validate/query
  2. {
  3.   "query": {
  4.    "query_string": {
  5.    "query": "@timestamp:foo",
  6.    "lenient": false
  7.    }
  8.   }
  9. }

Console-Result

  1. {"valid":false,"_shards":{"total":1,"successful":1,"failed":0}}

The explain parameter

  3. #### Python
  5. ``````python
  6. resp = client.indices.validate_query(
  7.    index="my-index-000001",
  8.    explain=True,
  9.    query={
  10.    "query_string": {
  11.    "query": "@timestamp:foo",
  12.    "lenient": False
  13.    }
  14.    },
  15. )
  16. print(resp)
  17. `

Ruby

  1. response = client.indices.validate_query(
  2.   index: 'my-index-000001',
  3.   explain: true,
  4.   body: {
  5.    query: {
  6.    query_string: {
  7.    query: '@timestamp:foo',
  8.    lenient: false
  9.    }
  10.    }
  11.   }
  12. )
  13. puts response

Js

  1. const response = await client.indices.validateQuery({
  2.   index: "my-index-000001",
  3.   explain: "true",
  4.   query: {
  5.    query_string: {
  6.    query: "@timestamp:foo",
  7.    lenient: false,
  8.    },
  9.   },
  10. });
  11. console.log(response);

Console

  1. GET my-index-000001/_validate/query?explain=true
  2. {
  3.   "query": {
  4.    "query_string": {
  5.    "query": "@timestamp:foo",
  6.    "lenient": false
  7.    }
  8.   }
  9. }

APIは次のレスポンスを返します：

Console-Result

  1. {
  2.   "valid" : false,
  3.   "_shards" : {
  4.    "total" : 1,
  5.    "successful" : 1,
  6.    "failed" : 0
  7.   },
  8.   "explanations" : [ {
  9.    "index" : "my-index-000001",
  10.    "valid" : false,
  11.    "error" : "my-index-000001/IAEc2nIXSSunQA_suI0MLw] QueryShardException[failed to create query:...failed to parse date field [foo]"
  12.   } ]
  13. }

The rewrite parameter

クエリが有効な場合、説明はそのクエリの文字列表現にデフォルト設定されます。rewriteがtrueに設定されている場合、説明は実行される実際のLuceneクエリを示すより詳細なものになります。

Python

  1. resp = client.indices.validate_query(
  2.    index="my-index-000001",
  3.    rewrite=True,
  4.    query={
  5.    "more_like_this": {
  6.    "like": {
  7.    "_id": "2"
  8.    },
  9.    "boost_terms": 1
  10.    }
  11.    },
  12. )
  13. print(resp)

Ruby

  1. response = client.indices.validate_query(
  2.   index: 'my-index-000001',
  3.   rewrite: true,
  4.   body: {
  5.    query: {
  6.    more_like_this: {
  7.    like: {
  8.    _id: '2'
  9.    },
  10.    boost_terms: 1
  11.    }
  12.    }
  13.   }
  14. )
  15. puts response

Js

  1. const response = await client.indices.validateQuery({
  2.   index: "my-index-000001",
  3.   rewrite: "true",
  4.   query: {
  5.    more_like_this: {
  6.    like: {
  7.    _id: "2",
  8.    },
  9.    boost_terms: 1,
  10.    },
  11.   },
  12. });
  13. console.log(response);

Console

  1. GET my-index-000001/_validate/query?rewrite=true
  2. {
  3.   "query": {
  4.    "more_like_this": {
  5.    "like": {
  6.    "_id": "2"
  7.    },
  8.    "boost_terms": 1
  9.    }
  10.   }
  11. }

APIは次のレスポンスを返します：

Console-Result

  1. {
  2.    "valid": true,
  3.    "_shards": {
  4.    "total": 1,
  5.    "successful": 1,
  6.    "failed": 0
  7.    },
  8.    "explanations": [
  9.    {
  10.    "index": "my-index-000001",
  11.    "valid": true,
  12.    "explanation": "((user:terminator^3.71334 plot:future^2.763601 plot:human^2.8415773 plot:sarah^3.4193945 plot:kyle^3.8244398 plot:cyborg^3.9177752 plot:connor^4.040236 plot:reese^4.7133346 ... )~6) -ConstantScore(_id:2)) #(ConstantScore(_type:_doc))^0.0"
  13.    }
  14.    ]
  15. }

Rewrite and all_shards parameters

デフォルトでは、リクエストはランダムに選択された単一のシャードで実行されます。クエリの詳細な説明は、どのシャードがヒットしているかによって異なる場合があり、リクエストごとに異なる可能性があります。したがって、クエリの書き換えの場合、all_shardsパラメータを使用して、すべての利用可能なシャードからのレスポンスを取得する必要があります。

Python

  1. resp = client.indices.validate_query(
  2.    index="my-index-000001",
  3.    rewrite=True,
  4.    all_shards=True,
  5.    query={
  6.    "match": {
  7.    "user.id": {
  8.    "query": "kimchy",
  9.    "fuzziness": "auto"
  10.    }
  11.    }
  12.    },
  13. )
  14. print(resp)

Ruby

  1. response = client.indices.validate_query(
  2.   index: 'my-index-000001',
  3.   rewrite: true,
  4.   all_shards: true,
  5.   body: {
  6.    query: {
  7.    match: {
  8.    'user.id' => {
  9.    query: 'kimchy',
  10.    fuzziness: 'auto'
  11.    }
  12.    }
  13.    }
  14.   }
  15. )
  16. puts response

Js

  1. const response = await client.indices.validateQuery({
  2.   index: "my-index-000001",
  3.   rewrite: "true",
  4.   all_shards: "true",
  5.   query: {
  6.    match: {
  7.    "user.id": {
  8.    query: "kimchy",
  9.    fuzziness: "auto",
  10.    },
  11.    },
  12.   },
  13. });
  14. console.log(response);

Console

  1. GET my-index-000001/_validate/query?rewrite=true&all_shards=true
  2. {
  3.   "query": {
  4.    "match": {
  5.    "user.id": {
  6.    "query": "kimchy",
  7.    "fuzziness": "auto"
  8.    }
  9.    }
  10.   }
  11. }

APIは次のレスポンスを返します：

Console-Result

  1. {
  2.   "valid": true,
  3.   "_shards": {
  4.    "total": 1,
  5.    "successful": 1,
  6.    "failed": 0
  7.   },
  8.   "explanations": [
  9.    {
  10.    "index": "my-index-000001",
  11.    "shard": 0,
  12.    "valid": true,
  13.    "explanation": "(user.id:kimchi)^0.8333333 user.id:kimchy"
  14.    }
  15.   ]
  16. }