Link Search Menu Expand Document Documentation Menu
文档

验证查询

您可以使用验证查询 API 在不运行查询的情况下对其进行验证。查询可以作为路径参数发送，也可以包含在请求体中。

端点

验证查询 API 包含以下路径

GET <index>/_validate/query

路径参数

所有路径参数都是可选的。

参数 数据类型 描述
index 字符串 要验证查询所针对的索引。如果您没有在 URL 中指定索引或多个索引（或想覆盖单个搜索的 URL 值），您可以在此处包含它。示例包括 "logs-*" 和 ["my-store", "sample_data_ecommerce"]。
query 查询对象 使用 查询 DSL 的查询。

查询参数

下表列出了可用的查询参数。所有查询参数都是可选的。

参数 数据类型 描述
all_shards 布尔型 当 true 时，验证将针对 所有分片 而不是每个索引的一个分片运行。默认值为 false。
allow_no_indices 布尔型 是否忽略不匹配任何索引的通配符。默认值为 true。
allow_partial_search_results 布尔型 如果请求遇到错误或超时，是否返回部分结果。默认值为 true。
分析器 字符串 在查询字符串中使用的分析器。这应该只与 q 选项一起使用。
analyze_wildcard 布尔型 指定是否分析通配符和前缀查询。默认值为 false。
default_operator 字符串 指示字符串查询的默认运算符应为 AND 还是 OR。默认值为 OR。
df 字符串 如果查询字符串中未提供字段前缀，则为默认字段。
expand_wildcards 字符串 指定通配符表达式可以匹配的索引类型。支持逗号分隔值。有效值为 all（匹配任何索引）、open（匹配开放的、非隐藏的索引）、closed（匹配关闭的、非隐藏的索引）、hidden（匹配隐藏索引）和 none（拒绝通配符表达式）。默认值为 open。
explain 布尔型 是否返回关于 OpenSearch 如何计算 文档分数 的信息。默认值为 false。
ignore_unavailable 布尔型 指定是否在响应中包含缺失或关闭的索引，并在搜索请求期间忽略不可用的分片。默认值为 false。
lenient 布尔型 指定 OpenSearch 是否应忽略基于格式的查询失败（例如，由于查询文本字段为整数）。默认值为 false。
重写 (rewrite) 确定 OpenSearch 如何 重写 和评分多词查询。有效值为 constant_score、scoring_boolean、constant_score_boolean、top_terms_N、top_terms_boost_N 和 top_terms_blended_freqs_N。默认值为 constant_score。  
q 字符串 Lucene 字符串语法中的查询。

请求示例

以下示例请求使用通过 bulk 请求创建的名为 Hamlet 的索引

PUT hamlet/_bulk?refresh
{"index":{"_id":1}}
{"user" : { "id": "hamlet" }, "@timestamp" : "2099-11-15T14:12:12", "message" : "To Search or Not To Search"}
{"index":{"_id":2}}
{"user" : { "id": "hamlet" }, "@timestamp" : "2099-11-15T14:12:13", "message" : "My dad says that I'm such a ham."}

然后您可以使用验证查询 API 验证索引查询，如以下示例所示

GET hamlet/_validate/query?q=user.id:hamlet

查询也可以作为请求体发送，如以下示例所示

GET hamlet/_validate/query
{
  "query" : {
    "bool" : {
      "must" : {
        "query_string" : {
          "query" : "*:*"
        }
      },
      "filter" : {
        "term" : { "user.id" : "hamlet" }
      }
    }
  }
}

示例响应

如果查询通过验证，则响应指示查询为 true，如以下示例响应所示，其中 valid 参数为 true

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

如果查询未通过验证，则 OpenSearch 会响应查询为 false。以下示例请求查询包含在 hamlet 索引中未配置的动态映射

GET hamlet/_validate/query
{
  "query": {
    "query_string": {
      "query": "@timestamp:foo",
      "lenient": false
    }
  }
}

OpenSearch 的响应如下，其中 valid 参数为 false

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

某些查询参数也会影响响应中包含的内容。以下示例显示 Explain、Rewrite 和 all_shards 查询选项如何影响响应。

解释

explain 选项在 explanations 字段中返回有关查询失败的信息，如以下示例响应所示

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

重写

当请求中将 rewrite 选项设置为 true 时，explanations 选项显示以字符串形式执行的 Lucene 查询，如以下响应所示

{
   "valid": true,
   "_shards": {
      "total": 1,
      "successful": 1,
      "failed": 0
   },
   "explanations": [
      {
         "index": "",
         "valid": true,
         "explanation": "((user:hamlet^4.256753 play:hamlet^6.863601 play:romeo^2.8415773 plot:puck^3.4193945 plot:othello^3.8244398 ... )~4) -ConstantScore(_id:2) #(ConstantScore(_type:_doc))^0.0"
      }
   ]
}

重写和 all_shards

当 rewrite 和 all_shards 选项都设置为 true 时，验证查询 API 会响应所有可用分片的详细信息，而不是仅响应一个分片（默认），如以下响应所示

{
  "valid": true,
  "_shards": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "explanations": [
    {
      "index": "my-index-000001",
      "shard": 0,
      "valid": true,
      "explanation": "(user.id:hamlet)^0.6333333"
    }
  ]
}
剩余 350 字符

有问题？。

想贡献吗？或。