› › ›

验证 API

验证 API编辑

验证可能开销很大的查询，而不执行它。

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

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

请求编辑

GET /<target>/_validate/<query>

先决条件编辑

如果启用了 Elasticsearch 安全功能，则您必须对目标数据流、索引或别名具有 read 索引权限。

描述编辑

验证 API 允许您验证可能开销很大的查询，而不执行它。查询可以作为路径参数发送，也可以在请求正文中发送。

路径参数编辑

<target>: （可选，字符串）要搜索的数据流、索引和别名的逗号分隔列表。支持通配符 (*)。要搜索所有数据流或索引，请省略此参数或使用 * 或 _all。
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 查询字符串语法的查询。

示例编辑

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

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

当发送有效查询时

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

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

响应包含 valid:true

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

查询也可以在请求正文中发送

response = client.indices.validate_query(
  index: 'my-index-000001',
  body: {
    query: {
      bool: {
        must: {
          query_string: {
            query: '*:*'
          }
        },
        filter: {
          term: {
            'user.id' => 'kimchy'
          }
        }
      }
    }
  }
)
puts 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* 无法正确解析为日期

response = client.indices.validate_query(
  index: 'my-index-000001',
  body: {
    query: {
      query_string: {
        query: '@timestamp:foo',
        lenient: false
      }
    }
  }
)
puts 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 参数以获取有关查询失败原因的更多详细信息

response = client.indices.validate_query(
  index: 'my-index-000001',
  explain: true,
  body: {
    query: {
      query_string: {
        query: '@timestamp:foo',
        lenient: false
      }
    }
  }
)
puts 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 查询。

response = client.indices.validate_query(
  index: 'my-index-000001',
  rewrite: true,
  body: {
    query: {
      more_like_this: {
        like: {
          _id: '2'
        },
        boost_terms: 1
      }
    }
  }
)
puts 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 参数从所有可用分片获取响应。

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

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

« 计数 API 术语枚举 API »