› › ›

API проверки

Проверяет потенциально ресурсоёмкий запрос без его выполнения.

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

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

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

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

(Необязательно, строка) Оператор по умолчанию для запроса со строковым запросом: И или ИЛИ. По умолчанию 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.

Примеры

resp = client.bulk(
    index="my-index-000001",
    refresh=True,
    operations=[
        {
            "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!"
        }
    ],
)
print(resp)

response = client.bulk(
  index: 'my-index-000001',
  refresh: true,
  body: [
    {
      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!'
    }
  ]
)
puts response

const response = await client.bulk({
  index: "my-index-000001",
  refresh: "true",
  operations: [
    {
      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!",
    },
  ],
});
console.log(response);

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!"}

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

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

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

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

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

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

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

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

resp = client.indices.validate_query(
    index="my-index-000001",
    query={
        "bool": {
            "must": {
                "query_string": {
                    "query": "*:*"
                }
            },
            "filter": {
                "term": {
                    "user.id": "kimchy"
                }
            }
        }
    },
)
print(resp)

response = client.indices.validate_query(
  index: 'my-index-000001',
  body: {
    query: {
      bool: {
        must: {
          query_string: {
            query: '*:*'
          }
        },
        filter: {
          term: {
            'user.id' => 'kimchy'
          }
        }
      }
    }
  }
)
puts response

const response = await client.indices.validateQuery({
  index: "my-index-000001",
  query: {
    bool: {
      must: {
        query_string: {
          query: "*:*",
        },
      },
      filter: {
        term: {
          "user.id": "kimchy",
        },
      },
    },
  },
});
console.log(response);

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 некорректно парсится в дату:

resp = client.indices.validate_query(
    index="my-index-000001",
    query={
        "query_string": {
            "query": "@timestamp:foo",
            "lenient": False
        }
    },
)
print(resp)

response = client.indices.validate_query(
  index: 'my-index-000001',
  body: {
    query: {
      query_string: {
        query: '@timestamp:foo',
        lenient: false
      }
    }
  }
)
puts response

const response = await client.indices.validateQuery({
  index: "my-index-000001",
  query: {
    query_string: {
      query: "@timestamp:foo",
      lenient: false,
    },
  },
});
console.log(response);

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

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

Параметр explain

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

resp = client.indices.validate_query(
    index="my-index-000001",
    explain=True,
    query={
        "query_string": {
            "query": "@timestamp:foo",
            "lenient": False
        }
    },
)
print(resp)

response = client.indices.validate_query(
  index: 'my-index-000001',
  explain: true,
  body: {
    query: {
      query_string: {
        query: '@timestamp:foo',
        lenient: false
      }
    }
  }
)
puts response

const response = await client.indices.validateQuery({
  index: "my-index-000001",
  explain: "true",
  query: {
    query_string: {
      query: "@timestamp:foo",
      lenient: false,
    },
  },
});
console.log(response);

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, который будет выполнен.

resp = client.indices.validate_query(
    index="my-index-000001",
    rewrite=True,
    query={
        "more_like_this": {
            "like": {
                "_id": "2"
            },
            "boost_terms": 1
        }
    },
)
print(resp)

response = client.indices.validate_query(
  index: 'my-index-000001',
  rewrite: true,
  body: {
    query: {
      more_like_this: {
        like: {
          _id: '2'
        },
        boost_terms: 1
      }
    }
  }
)
puts response

const response = await client.indices.validateQuery({
  index: "my-index-000001",
  rewrite: "true",
  query: {
    more_like_this: {
      like: {
        _id: "2",
      },
      boost_terms: 1,
    },
  },
});
console.log(response);

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, чтобы получить ответ со всех доступных фрагментов.

resp = client.indices.validate_query(
    index="my-index-000001",
    rewrite=True,
    all_shards=True,
    query={
        "match": {
            "user.id": {
                "query": "kimchy",
                "fuzziness": "auto"
            }
        }
    },
)
print(resp)

response = client.indices.validate_query(
  index: 'my-index-000001',
  rewrite: true,
  all_shards: true,
  body: {
    query: {
      match: {
        'user.id' => {
          query: 'kimchy',
          fuzziness: 'auto'
        }
      }
    }
  }
)
puts response

const response = await client.indices.validateQuery({
  index: "my-index-000001",
  rewrite: "true",
  all_shards: "true",
  query: {
    match: {
      "user.id": {
        query: "kimchy",
        fuzziness: "auto",
      },
    },
  },
});
console.log(response);

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