New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
« 计数 API 词项枚举 API »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›REST API ›搜索 API

验证 API

编辑

验证 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
Copy as curlTry in Elastic 

请求

编辑

GET /<目标>/_validate/<查询>

前提条件

编辑
  • 如果启用了 Elasticsearch 安全功能，你必须拥有目标数据流、索引或别名的 read 索引权限。

描述

编辑

验证 API 允许你验证一个可能开销很大的查询，但不执行它。该查询可以作为路径参数或在请求正文中发送。

路径参数

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

示例

编辑
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!"}
Copy as curlTry in Elastic 

当发送有效的查询时

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
Copy as curlTry in Elastic 

响应包含 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" }
      }
    }
  }
}
Copy as curlTry in Elastic 

在正文中发送的查询必须嵌套在 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
    }
  }
}
Copy as curlTry in Elastic 
{"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
    }
  }
}
Copy as curlTry in Elastic 

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
    }
  }
}
Copy as curlTry in Elastic 

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"
      }
    }
  }
}
Copy as curlTry in Elastic 

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 »