説明（Explain）

Explain API

特定のドキュメントがクエリに一致する理由（または一致しない理由）に関する情報を返します。

Python

resp = client.explain(
   index="my-index-000001",
   id="0",
   query={
   "match": {
   "message": "elasticsearch"
   }
   },
)
print(resp)

Ruby

response = client.explain(
  index: 'my-index-000001',
  id: 0,
  body: {
   query: {
   match: {
   message: 'elasticsearch'
   }
   }
  }
)
puts response

Js

const response = await client.explain({
  index: "my-index-000001",
  id: 0,
  query: {
   match: {
   message: "elasticsearch",
   },
  },
});
console.log(response);

Console

GET /my-index-000001/_explain/0
{
  "query" : {
   "match" : { "message" : "elasticsearch" }
  }
}

Request

GET /<index>/_explain/<id>

POST /<index>/_explain/<id>

Prerequisites

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

Description

explain APIは、クエリと特定のドキュメントに対するスコアの説明を計算します。これにより、ドキュメントが特定のクエリに一致するかどうかの有用なフィードバックを得ることができます。

Path parameters

• <id>
• （必須、整数）ドキュメントIDを定義します。
• <index>
• （必須、文字列）リクエストを制限するために使用されるインデックス名。
  このパラメータには、単一のインデックス名のみを指定できます。

Query parameters

• analyzer
• （オプション、文字列）クエリ文字列に使用するアナライザー。
  このパラメータは、qクエリ文字列パラメータが指定されている場合にのみ使用できます。
• analyze_wildcard
• （オプション、Boolean）trueの場合、ワイルドカードおよびプレフィックスクエリが分析されます。デフォルトはfalseです。
  このパラメータは、qクエリ文字列パラメータが指定されている場合にのみ使用できます。
• default_operator
• （オプション、文字列）クエリ文字列クエリのデフォルトオペレーター：ANDまたはOR。デフォルトはORです。
  このパラメータは、qクエリ文字列パラメータが指定されている場合にのみ使用できます。
• df
• （オプション、文字列）クエリ文字列にフィールドプレフィックスが指定されていない場合に使用するデフォルトのフィールド。
  このパラメータは、qクエリ文字列パラメータが指定されている場合にのみ使用できます。
• lenient
• （オプション、Boolean）trueの場合、クエリ文字列内の形式ベースのクエリ失敗（数値フィールドにテキストを提供するなど）は無視されます。デフォルトはfalseです。
  このパラメータは、qクエリ文字列パラメータが指定されている場合にのみ使用できます。
• preference
• （オプション、文字列）操作を実行するノードまたはシャードを指定します。デフォルトはランダムです。
• q
• （オプション、文字列）Luceneクエリ文字列構文のクエリ。
• stored_fields
• （オプション、文字列）レスポンスに返す保存されたフィールドのカンマ区切りリスト。
• routing
• （オプション、文字列）特定のシャードに操作をルーティングするために使用されるカスタム値。
• _source
• （オプション、文字列）_sourceフィールドを返すかどうか、または返すフィールドのリスト。
• _source_excludes
• （オプション、文字列）レスポンスから除外するソースフィールドのカンマ区切りリスト。
  このパラメータを使用して、_source_includesクエリパラメータで指定されたサブセットからフィールドを除外することもできます。
  _sourceパラメータがfalseの場合、このパラメータは無視されます。
• _source_includes
• （オプション、文字列）レスポンスに含めるソースフィールドのカンマ区切りリスト。
  このパラメータが指定されている場合、これらのソースフィールドのみが返されます。_source_excludesクエリパラメータを使用して、このサブセットからフィールドを除外できます。
  _sourceパラメータがfalseの場合、このパラメータは無視されます。

Request body

• query
• （オプション、クエリオブジェクト）Query DSLを使用して検索定義を定義します。

Examples

Python

resp = client.explain(
   index="my-index-000001",
   id="0",
   query={
   "match": {
   "message": "elasticsearch"
   }
   },
)
print(resp)

Ruby

response = client.explain(
  index: 'my-index-000001',
  id: 0,
  body: {
   query: {
   match: {
   message: 'elasticsearch'
   }
   }
  }
)
puts response

Js

const response = await client.explain({
  index: "my-index-000001",
  id: 0,
  query: {
   match: {
   message: "elasticsearch",
   },
  },
});
console.log(response);

Console

GET /my-index-000001/_explain/0
{
  "query" : {
   "match" : { "message" : "elasticsearch" }
  }
}

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

Console-Result

{
   "_index":"my-index-000001",
   "_id":"0",
   "matched":true,
   "explanation":{
   "value":1.6943598,
   "description":"weight(message:elasticsearch in 0) [PerFieldSimilarity], result of:",
   "details":[
   {
   "value":1.6943598,
   "description":"score(freq=1.0), computed as boost * idf * tf from:",
   "details":[
   {
   "value":2.2,
   "description":"boost",
   "details":[]
   },
   {
   "value":1.3862944,
   "description":"idf, computed as log(1 + (N - n + 0.5) / (n + 0.5)) from:",
   "details":[
   {
   "value":1,
   "description":"n, number of documents containing term",
   "details":[]
   },
   {
   "value":5,
   "description":"N, total number of documents with field",
   "details":[]
   }
   ]
   },
   {
   "value":0.5555556,
   "description":"tf, computed as freq / (freq + k1 * (1 - b + b * dl / avgdl)) from:",
   "details":[
   {
   "value":1.0,
   "description":"freq, occurrences of term within document",
   "details":[]
   },
   {
   "value":1.2,
   "description":"k1, term saturation parameter",
   "details":[]
   },
   {
   "value":0.75,
   "description":"b, length normalization parameter",
   "details":[]
   },
   {
   "value":3.0,
   "description":"dl, length of field",
   "details":[]
   },
   {
   "value":5.4,
   "description":"avgdl, average length of field",
   "details":[]
   }
   ]
   }
   ]
   }
   ]
   }
}

qパラメータを介してクエリを指定するより簡単な方法もあります。指定されたqパラメータの値は、query_stringクエリが使用されたかのように解析されます。explain APIでのqパラメータの使用例：

Python

resp = client.explain(
   index="my-index-000001",
   id="0",
   q="message:search",
)
print(resp)

Ruby

response = client.explain(
  index: 'my-index-000001',
  id: 0,
  q: 'message:search'
)
puts response

Js

const response = await client.explain({
  index: "my-index-000001",
  id: 0,
  q: "message:search",
});
console.log(response);

Console

GET /my-index-000001/_explain/0?q=message:search

APIは前のリクエストと同じ結果を返します。