› ›

搜索 API

搜索 API编辑

搜索包含一个或多个查询，这些查询被组合并发送到 Elasticsearch。与搜索查询匹配的文档将返回在响应的 hits 或 搜索结果 中。

搜索还可以包含用于更好地处理其查询的附加信息。例如，搜索可以限制在特定索引中，或者只返回特定数量的结果。

您可以使用搜索 API 来搜索和聚合存储在 Elasticsearch 数据流或索引中的数据。API 的 query 请求体参数接受用查询 DSL 编写的查询。

运行搜索编辑

以下请求使用 match 查询搜索 my-index-000001。此查询匹配 user.id 值为 kimchy 的文档。

response = client.search(
  index: 'my-index-000001',
  body: {
    query: {
      match: {
        'user.id' => 'kimchy'
      }
    }
  }
)
puts response

GET /my-index-000001/_search
{
  "query": {
    "match": {
      "user.id": "kimchy"
    }
  }
}

API 响应在 hits.hits 属性中返回与查询匹配的前 10 个文档。

{
  "took": 5,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1.3862942,
    "hits": [
      {
        "_index": "my-index-000001",
        "_id": "kxWFcnMByiguvud1Z8vC",
        "_score": 1.3862942,
        "_source": {
          "@timestamp": "2099-11-15T14:12:12",
          "http": {
            "request": {
              "method": "get"
            },
            "response": {
              "bytes": 1070000,
              "status_code": 200
            },
            "version": "1.1"
          },
          "message": "GET /search HTTP/1.1 200 1070000",
          "source": {
            "ip": "127.0.0.1"
          },
          "user": {
            "id": "kimchy"
          }
        }
      }
    ]
  }
}

常见搜索选项编辑

您可以使用以下选项自定义搜索。

查询 DSL
查询 DSL 支持各种查询类型，您可以将它们混合匹配以获得所需的结果。查询类型包括

布尔和其他复合查询，它们允许您组合查询并根据多个条件匹配结果
词条级查询用于过滤和查找精确匹配
全文查询，通常用于搜索引擎
地理和空间查询

聚合
您可以使用搜索聚合来获取搜索结果的统计信息和其他分析。聚合可以帮助您回答以下问题：

我服务器的平均响应时间是多少？
我网络上用户访问最多的 IP 地址是什么？
按客户计算的总交易收入是多少？

搜索多个数据流和索引
您可以使用逗号分隔的值和类似 grep 的索引模式在同一个请求中搜索多个数据流和索引。您甚至可以提升来自特定索引的搜索结果。请参阅搜索多个数据流和索引。

分页搜索结果
默认情况下，搜索只返回前 10 个匹配的命中。要检索更多或更少的文档，请参阅分页搜索结果。

检索选定字段
搜索响应的 hits.hits 属性包含每个命中的完整文档 _source。要仅检索 _source 或其他字段的子集，请参阅检索选定字段。

排序搜索结果
默认情况下，搜索命中按 _score 排序，这是一个相关性评分，用于衡量每个文档与查询的匹配程度。要自定义这些评分的计算，请使用 script_score 查询。要按其他字段值对搜索命中进行排序，请参阅排序搜索结果。

运行异步搜索
Elasticsearch 搜索旨在快速运行大量数据，通常在几毫秒内返回结果。因此，搜索默认情况下是同步的。搜索请求将在返回响应之前等待完整的结果。

但是，对于跨大型数据集或多个集群的搜索，完整结果可能需要更长时间。

为了避免长时间等待，您可以改为运行异步或 async 搜索。一个异步搜索允许您立即检索长时间运行搜索的部分结果，并在稍后获取完整结果。

定义仅在查询中存在的字段编辑

您可以定义运行时字段，这些字段仅作为搜索查询的一部分存在，而不是索引您的数据然后搜索它。您可以在搜索请求中指定一个 runtime_mappings 部分来定义运行时字段，该字段可以选择包含一个 Painless 脚本。

例如，以下查询定义了一个名为 day_of_week 的运行时字段。包含的脚本根据 @timestamp 字段的值计算星期几，并使用 emit 返回计算出的值。

查询还包含一个词条聚合，它在 day_of_week 上运行。

GET /my-index-000001/_search
{
  "runtime_mappings": {
    "day_of_week": {
      "type": "keyword",
      "script": {
        "source":
        """emit(doc['@timestamp'].value.dayOfWeekEnum
        .getDisplayName(TextStyle.FULL, Locale.ROOT))"""
      }
    }
  },
  "aggs": {
    "day_of_week": {
      "terms": {
        "field": "day_of_week"
      }
    }
  }
}

响应包含基于 day_of_week 运行时字段的聚合。在 buckets 下是一个值为 Sunday 的 key。查询根据在 day_of_week 运行时字段中定义的脚本动态计算了此值，而无需索引该字段。

{
  ...
  ***
  "aggregations" : {
    "day_of_week" : {
      "doc_count_error_upper_bound" : 0,
      "sum_other_doc_count" : 0,
      "buckets" : [
        {
          "key" : "Sunday",
          "doc_count" : 5
        }
      ]
    }
  }
}

搜索超时编辑

默认情况下，搜索请求不会超时。请求将在返回响应之前等待来自每个分片的完整结果。

虽然异步搜索旨在用于长时间运行的搜索，但您也可以使用 timeout 参数来指定您希望等待每个分片完成的持续时间。每个分片在指定的时间段内收集命中。如果在时间段结束时收集未完成，Elasticsearch 将仅使用到那时为止累积的命中。搜索请求的整体延迟取决于搜索所需的碎片数量和并发碎片请求的数量。

response = client.search(
  index: 'my-index-000001',
  body: {
    timeout: '2s',
    query: {
      match: {
        'user.id' => 'kimchy'
      }
    }
  }
)
puts response

GET /my-index-000001/_search
{
  "timeout": "2s",
  "query": {
    "match": {
      "user.id": "kimchy"
    }
  }
}

要为所有搜索请求设置集群范围的默认超时，请使用集群设置 API 配置 search.default_search_timeout。如果请求中没有传递 timeout 参数，则将使用此全局超时持续时间。如果全局搜索超时在搜索请求完成之前过期，则将使用任务取消取消请求。 search.default_search_timeout 设置默认为 -1（无超时）。

搜索取消编辑

您可以使用任务管理 API 取消搜索请求。当您的客户端 HTTP 连接关闭时，Elasticsearch 也会自动取消搜索请求。我们建议您设置您的客户端，以便在搜索请求中止或超时时关闭 HTTP 连接。

跟踪总命中编辑

通常，在不访问所有匹配项的情况下无法准确计算总命中数，这对于匹配大量文档的查询来说成本很高。 track_total_hits 参数允许您控制如何跟踪总命中数。鉴于通常有足够的命中数下限，例如“至少有 10000 个命中”，默认设置为 10,000。这意味着请求将准确地计算总命中数，直到 10,000 个命中。如果您不需要超过某个阈值后的准确命中数，这是一个很好的权衡，可以加快搜索速度。

当设置为 true 时，搜索响应将始终准确地跟踪与查询匹配的命中数（例如，当 track_total_hits 设置为 true 时，total.relation 将始终等于 "eq"）。否则，搜索响应中 "total" 对象中返回的 "total.relation" 将确定如何解释 "total.value"。值为 "gte" 表示 "total.value" 是与查询匹配的总命中的下限，值为 "eq" 表示 "total.value" 是准确的计数。

response = client.search(
  index: 'my-index-000001',
  body: {
    track_total_hits: true,
    query: {
      match: {
        'user.id' => 'elkbee'
      }
    }
  }
)
puts response

GET my-index-000001/_search
{
  "track_total_hits": true,
  "query": {
    "match" : {
      "user.id" : "elkbee"
    }
  }
}

... 返回

{
  "_shards": ...
  "timed_out": false,
  "took": 100,
  "hits": {
    "max_score": 1.0,
    "total" : {
      "value": 2048,    
      "relation": "eq"  
    },
    "hits": ...
  }
}

	与查询匹配的总命中数。
	计数是准确的（例如，`"eq"` 表示等于）。

也可以将 track_total_hits 设置为整数。例如，以下查询将准确地跟踪与查询匹配的总命中数，最多 100 个文档

response = client.search(
  index: 'my-index-000001',
  body: {
    track_total_hits: 100,
    query: {
      match: {
        'user.id' => 'elkbee'
      }
    }
  }
)
puts response

GET my-index-000001/_search
{
  "track_total_hits": 100,
  "query": {
    "match": {
      "user.id": "elkbee"
    }
  }
}

响应中的 hits.total.relation 将指示 hits.total.value 中返回的值是准确的 ("eq") 还是总计的下限 ("gte")。

例如，以下响应

{
  "_shards": ...
  "timed_out": false,
  "took": 30,
  "hits": {
    "max_score": 1.0,
    "total": {
      "value": 42,         
      "relation": "eq"     
    },
    "hits": ...
  }
}

	42 个文档与查询匹配
	并且计数是准确的 (`"eq"`)

... 表示返回的命中数在 total 中是准确的。

如果与查询匹配的命中总数大于 track_total_hits 中设置的值，则响应中的总命中数将表明返回的值是下限。

{
  "_shards": ...
  "hits": {
    "max_score": 1.0,
    "total": {
      "value": 100,         
      "relation": "gte"     
    },
    "hits": ...
  }
}

	至少有 100 个文档与查询匹配。
	这是一个下限 (`"gte"`)。

如果您根本不需要跟踪命中总数，可以通过将此选项设置为 false 来提高查询时间。

response = client.search(
  index: 'my-index-000001',
  body: {
    track_total_hits: false,
    query: {
      match: {
        'user.id' => 'elkbee'
      }
    }
  }
)
puts response

GET my-index-000001/_search
{
  "track_total_hits": false,
  "query": {
    "match": {
      "user.id": "elkbee"
    }
  }
}

... 返回

{
  "_shards": ...
  "timed_out": false,
  "took": 10,
  "hits": {             
    "max_score": 1.0,
    "hits": ...
  }
}

命中总数未知。

最后，您可以通过在请求中将 "track_total_hits" 设置为 true 来强制进行准确计数。

track_total_hits 参数允许您在命中计数准确性和性能之间进行权衡。通常，track_total_hits 的值越低，查询速度越快，false 返回最快的结果。将 track_total_hits 设置为 true 将导致 Elasticsearch 返回精确的命中计数，这可能会影响查询性能，因为它会禁用 Max WAND 优化。

快速检查匹配的文档edit

如果您只想了解是否有任何文档与特定查询匹配，可以将 size 设置为 0 以指示我们对搜索结果不感兴趣。您还可以将 terminate_after 设置为 1 以指示只要找到第一个匹配文档（每个分片），就可以终止查询执行。

response = client.search(
  q: 'user.id:elkbee',
  size: 0,
  terminate_after: 1
)
puts response

GET /_search?q=user.id:elkbee&size=0&terminate_after=1

terminate_after 始终在之后应用 post_filter，并在收集到足够多的命中后停止查询以及聚合执行。尽管聚合上的文档计数可能不反映响应中的 hits.total，因为聚合是在之前应用后过滤的。

响应将不包含任何命中，因为 size 被设置为 0。 hits.total 将等于 0，表示没有匹配的文档，或者大于 0，表示在查询提前终止时至少有这么多文档与查询匹配。此外，如果查询提前终止，则响应中的 terminated_early 标志将设置为 true。一些查询能够直接从索引统计信息中检索命中计数，这要快得多，因为它不需要执行查询。在这些情况下，不会收集任何文档，返回的 total.hits 将大于 terminate_after，并且 terminated_early 将设置为 false。

{
  "took": 3,
  "timed_out": false,
  "terminated_early": true,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped" : 0,
    "failed": 0
  },
  "hits": {
    "total" : {
        "value": 1,
        "relation": "eq"
    },
    "max_score": null,
    "hits": []
  }
}

响应中的 took 时间包含此请求处理所花费的毫秒数，从节点接收到查询后立即开始，直到完成所有与搜索相关的操作，并在将上述 JSON 返回给客户端之前。这意味着它包括在线程池中等待、在整个集群中执行分布式搜索以及收集所有结果所花费的时间。

« 搜索您的数据排序搜索结果 »