› › ›

API Explain

Возвращает информацию о том, почему конкретный документ соответствует (или не соответствует) запросу.

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

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

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

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

Запрос

GET /<index>/_explain/<id>

POST /<index>/_explain/<id>

Предварительные условия

Если включены функции безопасности Elasticsearch, у вас должны быть read права на доступ к индексу для целевого индекса.

Описание

API explain вычисляет объяснение оценки для запроса и конкретного документа. Это может предоставить полезную обратную связь о том, соответствует ли документ конкретному запросу или нет.

Параметры пути

<id>

(Обязательно, целое число) Определяет идентификатор документа.

<index>

(Обязательно, строка) Имена индексов, используемые для ограничения запроса.

Для этого параметра можно указать только одно имя индекса.

Параметры запроса

analyzer

(Необязательно, строка) Анализатор, используемый для строки запроса.

Этот параметр можно использовать только при указании параметра строки запроса q.

analyze_wildcard

(Необязательно, логическое значение) Если true, выполняются анализ wildcard и prefix запросов. По умолчанию false.

Этот параметр можно использовать только при указании параметра строки запроса q.

default_operator

(Необязательно, строка) Оператор по умолчанию для запроса строки: AND или OR. По умолчанию OR.

Этот параметр можно использовать только при указании параметра строки запроса q.

df

(Необязательно, строка) Поле, используемое по умолчанию, когда в строке запроса не указано префикс поля.

Этот параметр можно использовать только при указании параметра строки запроса q.

lenient

(Необязательно, логическое значение) Если true, ошибки запроса, основанные на формате (например, предоставление текста числовому полю) в строке запроса, будут игнорироваться. По умолчанию false.

Этот параметр можно использовать только при указании параметра строки запроса q.

preference

(Необязательно, строка) Указывает узел или фрагмент, на котором должно выполняться действие. По умолчанию случайный.

q

(Необязательно, строка) Запрос в синтаксисе строки запроса Lucene.

stored_fields

(Необязательно, строка) Список хранимых полей, которые должны быть возвращены в ответе (разделенные запятыми).

routing

(Необязательно, строка) Пользовательское значение, используемое для маршрутизации операций на определённый фрагмент.

_source

(Необязательно, строка) True или false, чтобы вернуть поле _source или нет, или список полей для возврата.

_source_excludes

(Необязательно, строка) Список полей _source, которые нужно исключить из ответа (разделенные запятыми).

Вы также можете использовать этот параметр для исключения полей из подмножества, указанного в параметре запроса _source_includes.

Если параметр _source равен false, этот параметр игнорируется.

_source_includes

(Необязательно, строка) Список полей _source, которые нужно включить в ответ (разделенные запятыми).

Если этот параметр указан, возвращаются только эти поля _source. Вы можете исключить поля из этого подмножества, используя параметр запроса _source_excludes.

Если параметр _source равен false, этот параметр игнорируется.

Тело запроса

query: (Необязательно, объект запроса) Определяет поисковый запрос с использованием DSL запросов.

Примеры

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

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

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

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

API возвращает следующий ответ:

{
   "_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. Пример использования параметра q в API explain:

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

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

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

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

API возвращает тот же результат, что и предыдущий запрос.

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/search-explain.html

спецификации, руководства, описания, API

free hit counter