› › ›

API проверки запроса

Проверяет потенциально затратный запрос, не выполняя его.

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

Запрос

GET /<target>/_validate/<query>

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

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

Описание

API проверки позволяет проверить потенциально затратный запрос, не выполняя его. Запрос можно отправить либо в качестве параметра пути, либо в теле запроса.

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

<target>: (Необязательный, строка) Список потоков данных, индексов и псевдонимов для поиска, разделённых запятыми. Поддерживаются подстановочные знаки (*). Для поиска по всем потокам данных или индексам опустите этот параметр или используйте * или _all.
query: (Необязательный, объект запроса) Определяет определение поиска с помощью Query DSL.

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

all_shards

(Необязательный, Булево) Если true, проверка выполняется на всех фрагментах вместо одного случайного фрагмента на индекс. По умолчанию 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.

Примеры

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

При отправке корректного запроса:

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

Ответ содержит valid:true:

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

Запрос также можно отправить в теле запроса:

GET my-index-000001/_validate/query
{
  "query" : {
    "bool" : {
      "must" : {
        "query_string" : {
          "query" : "*:*"
        }
      },
      "filter" : {
        "term" : { "user.id" : "kimchy" }
      }
    }
  }
}

Запрос, отправляемый в теле, должен быть вложен в ключ query, как и в случае с API поиска.

Если запрос некорректен, valid будет false. В данном случае запрос некорректен, так как Elasticsearch знает, что поле post_date должно быть типом даты из-за динамического отображения, и foo не правильно анализируется как дата:

GET my-index-000001/_validate/query
{
  "query": {
    "query_string": {
      "query": "@timestamp:foo",
      "lenient": false
    }
  }
}

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

Параметр объяснения

Параметр explain может быть указан для получения более подробной информации о причинах сбоя запроса:

GET my-index-000001/_validate/query?explain=true
{
  "query": {
    "query_string": {
      "query": "@timestamp:foo",
      "lenient": false
    }
  }
}

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

{
  "valid" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "failed" : 0
  },
  "explanations" : [ {
    "index" : "my-index-000001",
    "valid" : false,
    "error" : "my-index-000001/IAEc2nIXSSunQA_suI0MLw] QueryShardException[failed to create query:...failed to parse date field [foo]"
  } ]
}

Параметр rewrite

Когда запрос корректен, объяснение по умолчанию — строковое представление этого запроса. При установке параметра rewrite на true, объяснение более подробное, показывающее фактический запрос Lucene, который будет выполнен.

GET my-index-000001/_validate/query?rewrite=true
{
  "query": {
    "more_like_this": {
      "like": {
        "_id": "2"
      },
      "boost_terms": 1
    }
  }
}

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

{
   "valid": true,
   "_shards": {
      "total": 1,
      "successful": 1,
      "failed": 0
   },
   "explanations": [
      {
         "index": "my-index-000001",
         "valid": true,
         "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"
      }
   ]
}

Параметры rewrite и all_shards

По умолчанию запрос выполняется только на одном фрагменте, который выбирается случайным образом. Подробное объяснение запроса может зависеть от того, какой фрагмент обрабатывается, и поэтому может различаться в разных запросах. Поэтому в случае переписывания запроса следует использовать параметр all_shards для получения ответа со всех доступных фрагментов.

GET my-index-000001/_validate/query?rewrite=true&all_shards=true
{
  "query": {
    "match": {
      "user.id": {
        "query": "kimchy",
        "fuzziness": "auto"
      }
    }
  }
}

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

{
  "valid": true,
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "explanations": [
    {
      "index": "my-index-000001",
      "shard": 0,
      "valid": true,
      "explanation": "(user.id:kimchi)^0.8333333 user.id:kimchy"
    }
  ]
}

© 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/7.17/search-validate.html