搜索（gRPC）

3.0 版本引入

这是一项实验性功能，不建议在生产环境中使用。有关该功能的进展更新或您想留下反馈，请参阅相关的GitHub issue。

gRPC 搜索 API 提供了一个高性能的二进制接口，用于通过 gRPC 使用协议缓冲区运行查询。它复制了 HTTP 搜索 API 的功能，同时受益于 protobuf 类型契约和 gRPC 传输。gRPC API 是低延迟、高吞吐量应用的理想选择。

先决条件

要提交 gRPC 请求，您必须在客户端拥有 protobuf 集合。有关获取 protobuf 的方法，请参阅使用 gRPC API。

gRPC 服务和方法

gRPC 文档 API 位于 SearchService 中。

您可以通过调用 SearchService 中的 Search gRPC 方法来提交搜索请求。该方法接受一个 SearchRequest 并返回一个 SearchResponse。

目前，仅支持以下基本查询：match_all、term、terms 和 match_none。未来的版本将支持更多查询类型。

请求字段

gRPC 搜索 API 支持以下请求字段。

SearchRequest 字段

SearchRequest 消息接受以下字段。所有字段都是可选的。

字段	Protobuf 类型	描述
`index`	`repeated string`	要搜索的索引列表。如果未提供，则默认为所有索引。
`source`	`SourceConfigParam`	控制响应中是否返回完整的 `_source`、不返回 `_source`，或仅返回 `_source` 中的特定字段。
`source_excludes`	`repeated string`	要从 `_source` 中排除的字段。如果 `source` 为 `false`，则忽略。
`source_includes`	`repeated string`	要包含在 `_source` 中的字段。如果 `source` 为 `false`，则忽略。
`allow_no_indices`	`bool`	是否忽略不匹配任何索引的通配符。默认为 `true`。
`allow_partial_search_results`	`bool`	是否在出错或超时时返回部分结果。默认为 `true`。
`analyze_wildcard`	`bool`	是否分析通配符/前缀查询。默认为 `false`。
`分析器`	`字符串`	与 `q` 查询字符串一起使用的分析器。
`batched_reduce_size`	`int32`	在节点上要减少的分片数量。默认为 `512`。
`cancel_after_time_interval`	`字符串`	请求将被取消的时间。默认为 `-1`。
`ccs_minimize_roundtrips`	`bool`	是否最小化节点和远程集群之间的往返次数。默认为 `true`。
`default_operator`	`运算符`	查询字符串的默认运算符。有效值为 `AND` 或 `OR`。默认为 `OR`。
`df`	`字符串`	不带字段前缀的查询字符串的默认字段。
`docvalue_fields`	`repeated string`	要作为 doc values 返回的字段。
`expand_wildcards`	`repeated` `ExpandWildcard`	指定通配符表达式可以匹配的索引类型。有效值为 `all`（匹配任何索引）、`open`（匹配开放的非隐藏索引）、`closed`（匹配关闭的非隐藏索引）、`hidden`（匹配隐藏索引）和 `none`（拒绝通配符表达式）。默认为 `open`。
`explain`	`bool`	是否返回文档得分计算详情。默认为 `false`。
`from`	`int32`	分页结果的起始索引。默认为 `0`。
`ignore_throttled`	`bool`	在解析别名时是否忽略冻结索引。默认为 `true`。
`ignore_unavailable`	`bool`	是否忽略不可用的索引或分片。默认为 `false`。
`include_named_queries_score`	`bool`	是否包含命名查询的得分。默认为 `false`。
`lenient`	`bool`	是否接受查询中的格式错误。默认为 `false`。
`max_concurrent_shard_requests`	`int32`	每个节点的并发分片请求数。默认为 `5`。
`phase_took`	`bool`	是否返回阶段级别的 `took` 值。默认为 `false`。
`pre_filter_shard_size`	`int32`	触发按分片大小进行预过滤的阈值。默认为 `128`。
`preference`	`字符串`	查询执行的分片或节点偏好设置。
`q`	`字符串`	采用 Lucene 语法的查询字符串。
`request_cache`	`bool`	是否使用请求缓存。默认为索引的设置。
`rest_total_hits_as_int`	`bool`	是否将总匹配数作为整数返回。默认为 `false`。
`路由`	`repeated string`	用于将请求路由到特定分片的值。
`scroll`	`字符串`	为滚动保持搜索上下文存活的时间量。
`search_pipeline`	`字符串`	要使用的搜索管道名称。
`search_type`	`SearchType`	计算相关性得分的方法。有效值为 `QUERY_THEN_FETCH` 和 `DFS_QUERY_THEN_FETCH`。默认为 `QUERY_THEN_FETCH`。
`seq_no_primary_term`	`bool`	是否返回序列号和主术语。
`size`	`int32`	要返回的结果数量。
`sort（排序）`	`repeated` `SortOrder`	排序结果所依据的字段和方向。
`stats`	`repeated string`	与请求关联用于日志记录的标签。
`stored_fields`	`repeated string`	要包含在响应中的存储字段列表。
`suggest_field`	`字符串`	生成建议所依据的字段。
`suggest_mode`	`SuggestMode`	建议模式（例如，`always`、`missing`、`popular`）。
`suggest_size`	`int32`	要返回的建议数量。
`suggest_text`	`字符串`	用于生成建议的输入文本。
`terminate_after`	`int32`	在提前终止前要处理的最大匹配文档数（命中数）。默认为 `0`。
`timeout`	`字符串`	等待查询执行的最大时间量。默认为 `1m`。
`track_scores`	`bool`	是否返回文档得分。默认为 `false`。
`track_total_hits`	`TrackHits`	是否包含总命中元数据。
`typed_keys`	`bool`	是否在聚合和建议键中包含类型信息。默认为 `true`。
`verbose_pipeline`	`bool`	是否为搜索管道启用详细模式。
`version`	`bool`	是否在响应中返回文档版本。
`request_body`	`SearchRequestBody`	主要的搜索请求负载，包括查询和过滤器。

SearchRequestBody 字段

SearchRequestBody 消息接受以下字段。所有字段都是可选的。

字段	Protobuf 类型	描述
`collapse`	`FieldCollapse`	按字段对结果进行分组。每组只返回顶部文档。
`explain`	`bool`	返回匹配文档的评分解释。
`ext`	`ObjectMap`	特定于插件的元数据，例如，用于 RAG 等扩展。
`from`	`int32`	分页结果的起始索引。默认为 `0`。
`highlight`	`Highlight`	在结果片段中高亮显示匹配的术语。
`track_total_hits`	`TrackHits`	是否返回总命中数。
`indices_boost`	`repeated` `NumberMap`	以 `<index>: <boost>` 格式表示的每个索引的提升乘数。
`docvalue_fields`	`repeated` `FieldAndFormat`	使用文档值返回的字段，可选地进行格式化。
`min_score`	浮点型	文档包含在结果中所需的最低得分。
`post_filter`	`QueryContainer`	在应用聚合后过滤命中。
`profile`	`bool`	启用性能分析以分析查询性能。
`search_pipeline`	`字符串`	要应用的搜索管道名称。
`verbose_pipeline`	`bool`	在搜索管道中启用详细日志记录。
`query`	`QueryContainer`	用于搜索的查询领域特定语言 (DSL)。
`rescore`	`repeated` `Rescore`	重新排序前 N 个命中以提高精确度。
`script_fields`	`map<string,` `ScriptField>`	其值由脚本计算的自定义字段。
`search_after`	`repeated` `FieldValue`	使用上一页的值进行基于游标的分页。
`size`	`int32`	要返回的结果数量。默认为 `10`。
`slice`	`SlicedScroll`	将滚动上下文拆分为切片以进行并行处理。
`sort（排序）`	`repeated` `SortCombinations`	排序规则（例如，按字段、得分或自定义顺序）。
`source`	`SourceConfig`	控制响应中是否返回完整的 `_source`、不返回 `_source`，或仅返回 `_source` 中的特定字段。
`fields`	`repeated` `FieldAndFormat`	要返回的附加字段，带格式选项。
`suggest`	`Suggester`	用于自动完成或更正的建议查询。
`terminate_after`	`int32`	在提前终止前要处理的最大匹配文档数（命中数）。默认为 `0`。
`timeout`	`字符串`	等待查询执行的最大时间量。
`track_scores`	`bool`	是否在结果中返回文档得分。
`include_named_queries_score`	`bool`	是否包含命名查询的得分。
`version`	`bool`	是否在响应中包含文档版本。
`seq_no_primary_term`	`bool`	是否包含每个命中的序列号和主术语。
`stored_fields`	`repeated string`	要返回的存储字段（除非重新启用，否则不包括 `_source`）。
`pit`	`PointInTimeReference`	用于搜索固定快照的时间点引用。
`stats`	`repeated string`	与请求关联的标签或日志字段。
`derived`	`map<string,` `DerivedField>`	响应中动态计算的字段。

QueryContainer 字段

QueryContainer 是所有支持的查询类型的入口点。

每个 QueryContainer 消息中**必须且只能**提供以下字段之一。

请注意，某些查询类型目前不受支持。目前仅支持 match_all、term、terms 和 match_none。

字段	Protobuf 类型	描述
`bool`	`BoolQuery`	一个布尔查询，使用 `AND`/`OR`/`NOT` 逻辑组合多个子句。必须是唯一设置的字段。
`boosting`	`BoostingQuery`	提升匹配正向查询的结果，并降低匹配负向查询的结果。必须是唯一设置的字段。
`constant_score`	`ConstantScoreQuery`	封装一个过滤器，并为所有匹配文档分配一个恒定的相关性得分。必须是唯一设置的字段。
`dis_max`	`DisMaxQuery`	返回匹配任一子句的文档。如果多个子句匹配，则使用最高得分。必须是唯一设置的字段。
`function_score`	`FunctionScoreQuery`	使用自定义函数调整结果的得分。必须是唯一设置的字段。
`exists`	`ExistsQuery`	匹配包含特定字段的文档。必须是唯一设置的字段。
`fuzzy`	`map<string,` `FuzzyQuery>`	匹配与搜索词相似的词元（模糊匹配）。只允许一个条目。必须是唯一设置的字段。
`ids`	`IdsQuery`	按 `_id` 值匹配文档。必须是唯一设置的字段。
`prefix（前缀）`	`map<string,` `PrefixQuery>`	匹配具有特定前缀的词元。只允许一个条目。必须是唯一设置的字段。
`range`	`map<string,` `RangeQuery>`	匹配指定范围内的词元。只允许一个条目。必须是唯一设置的字段。
`regexp`	`map<string,` `RegexpQuery>`	使用正则表达式匹配词元。只允许一个条目。必须是唯一设置的字段。
`term`	`map<string,` `TermQuery>`	匹配精确词元（无分析）。只允许一个条目。必须是唯一设置的字段。
`terms`	`TermsQueryField`	匹配包含字段中一个或多个指定词元的任何文档。必须是唯一设置的字段。
`terms_set`	`map<string,` `TermsSetQuery>`	匹配字段中包含最少数量精确词元的文档。只允许一个条目。必须是唯一设置的字段。
`wildcard`	`map<string,` `WildcardQuery>`	使用通配符模式匹配词元。只允许一个条目。必须是唯一设置的字段。
`match`	`map<string,` `MatchQueryTypeless>`	对文本或精确值字段进行全文匹配。只允许一个条目。必须是唯一设置的字段。
`match_bool_prefix`	`map<string,` `MatchBoolPrefixQuery>`	在布尔型查询中匹配完整单词和前缀。只允许一个条目。必须是唯一设置的字段。
`match_phrase`	`map<string,` `MatchPhraseQuery>`	按顺序匹配精确短语。只允许一个条目。必须是唯一设置的字段。
`match_phrase_prefix`	`map<string,` `MatchPhrasePrefixQuery>`	匹配一个短语，其中最后一个词被视为前缀。只允许一个条目。必须是唯一设置的字段。
`multi_match`	`MultiMatchQuery`	使用单个查询字符串搜索多个字段。必须是唯一设置的字段。
`query_string`	`QueryStringQuery`	解析作为单个字符串编写的高级查询。必须是唯一设置的字段。
`simple_query_string`	`SimpleQueryStringQuery`	一种比 `query_string` 语法更宽松的替代方案。忽略无效语法。必须是唯一设置的字段。
`间隔 (intervals)`	`map<string,` `IntervalsQuery>`	根据位置/邻近度匹配词项。只允许一个条目。必须是唯一设置的字段。
`knn`	`map<string,` `KnnField>`	对向量字段执行 k-NN 查询。只允许一个条目。必须是唯一设置的字段。
`match_all`	`MatchAllQuery`	匹配索引中的所有文档。必须是唯一设置的字段。
`match_none`	`MatchNoneQuery`	不匹配任何文档。必须是唯一设置的字段。
`script_score`	`ScriptScoreQuery`	使用脚本应用自定义评分。必须是唯一设置的字段。
`nested`	`NestedQuery`	包装一个针对嵌套字段的查询。必须是唯一设置的字段。

支持的查询

gRPC 搜索 API 支持以下查询。

以下所有示例都展示了可发送到 SearchService/Search gRPC 方法的有效请求负载。

匹配所有查询

一个 match_all 查询返回索引中的所有文档。例如，以下请求从索引中返回最多 50 个文档

{
  "request_body": {
    "query": {
      "match_all": {}
    },
    "size": 50
  }
}

词语查询

一个 term 查询匹配单个字段中的特定词项。例如，以下查询搜索包含单词 Rush 的标题

{
  "index": "my_index",
  "request_body": {
    "query": {
      "term": {
        "title": {
          "value": {
            "string_value": "Rush"
          },
          "case_insensitive": true
        }
      }
    }
  }
}

词项查询

一个 terms 查询匹配特定字段包含列表中任何值的文档。例如，以下查询搜索 ID 为 61809 和 61810 的行

{
 "request_body": {
   "query": {
     "terms": {
       "terms_lookup_field_string_array_map": {
         "line_id": {
           "string_array": {
             "string_array": [
               "61809",
                    "61810"
             ]
           }
         }
       }
     }
   }
 }
}

带有词项查找的词项查询

带 terms 查找的 terms 查询是 terms 查询的一种特殊形式，它允许您从集群中的另一个文档中获取用于过滤的词项，而不是直接在查询中指定它们。例如，以下请求匹配 students 索引中所有 id 与 enrolled 数组中某个值匹配的学生文档

{
  "request_body": {
    "query": {
      "terms": {
        "boost": 1.0,
        "terms_lookup_field_string_array_map": {
          "student_id": {
            "terms_lookup_field": {
              "index": "classes",
              "id": "101",
              "path": "enrolled"
            }
          }
        }
      }
    }
  }
}

不匹配任何查询

一个 match_none 查询不匹配任何文档

{
  "request_body": {
    "query": {
      "match_none": {}
    }
  }
}

响应字段

gRPC 搜索 API 提供以下响应字段。

SearchResponse 字段

下表列出了 SearchResponse 消息支持的字段。

字段	Protobuf 类型	描述
`response_body`	`ResponseBody`	搜索响应的实际负载。

ResponseBody 字段

ResponseBody 包含以下字段。

源文档以字节形式返回。使用 Base64 解码来读取 gRPC 响应中的 _source 字段。

字段	Protobuf 类型	描述
`took`	`int64`	处理搜索请求所花费的时间，单位为毫秒。
`timed_out`	`bool`	搜索是否超时。
`分片`	`ShardStatistics`	分片级别的成功/失败/总计元数据。
`phase_took`	`PhaseTook`	响应中的阶段级别 `took` 时间值。
`hits`	`HitsMetadata`	主要的文档结果和元数据。
`profile`	`分析`	查询执行的分析数据（调试/性能洞察）。
`fields`	`ObjectMap`	响应中的顶层键值字段结构（如果有）。

HitsMetadata 字段

HitsMetadata 对象包含有关搜索结果的信息，包括匹配文档的总数和单个文档匹配的数组。它包含以下字段。

字段	Protobuf 类型	描述
`total`	`TotalHits`	关于匹配文档总数的元数据（值 + 关系）。
`max_score`	`MaxScore`	返回命中项的最高相关性得分（可能为 `null`）。
`hits`	`repeated` `Hit`	匹配文档的实际列表。每个命中项包括 `index`、`id`、`score` 和 `source` 等核心字段，以及其他可选字段。

命中字段

每个 Hit 代表查询匹配的单个文档，并包含以下字段。

字段	Protobuf 类型	描述
`index`	`字符串`	包含返回文档的索引名称。
`id`	`字符串`	文档在索引中的唯一 ID。
`score`	`Score`	命中项的相关性得分。
`解释`	`Explanation`	关于 `_score` 如何计算的文本解释。
`fields`	`ObjectMap`	文档字段值。
`highlight`	`map<string,` `StringArray>`	每个命中项的突出显示字段和片段。
`inner_hits`	`map<string,` `InnerHitsResult>`	来自不同作用域的匹配嵌套文档，它们有助于整体查询结果。
`matched_queries`	`repeated string`	匹配文档的查询名称列表。
`nested`	`NestedIdentity`	命中项源自的内部嵌套对象的路径。
`ignored`	`repeated string`	被忽略字段的列表。
`ignored_field_values`	`map<string,` `StringArray>`	文档原始 JSON 中未经处理的原始值。
`shard`	`字符串`	检索到命中项的分片 ID。
`node`	`字符串`	检索到命中项的节点 ID。
`路由`	`字符串`	用于自定义分片路由的路由值。
`source`	`bytes（字节）`	Base64 编码的 `_source` 文档。
`seq_no`	`int64`	序列号（用于索引历史和版本控制）。
`primary_term`	`int64`	主词项号（用于乐观并发控制）。
`version`	`int64`	文档版本号。
`sort（排序）`	`repeated` `FieldValue`	用于结果排序的排序值。
`meta_fields`	`ObjectMap`	文档的元数据值。

source 经过 Base64 编码，必须解码才能获取 JSON 文档。

示例响应

{
  "responseBody": {
    "took": "64",
    "timedOut": false,
    "shards": {
      "successful": 1,
      "total": 1
    },
    "hits": {
      "total": {
        "totalHits": {
          "relation": "TOTAL_HITS_RELATION_EQ",
          "value": "1"
        }
      },
      "hits": [
        {
          "index": "my_index",
          "id": "3",
          "score": {
            "floatValue": 1
          },
          "source": "eyAidGl0bGUiOiAiUnVzaCIsICJ5ZWFyIjogMjAxM30=",
          "metaFields": {}
        }
      ],
      "maxScore": {
        "floatValue": 1
      }
    }
  }
}

Java gRPC 客户端示例

以下示例展示了一个 Java 客户端程序，它提交一个示例搜索词项查询 gRPC 请求，然后打印搜索响应中返回的命中数

import org.opensearch.protobufs.*;
import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;

public class SearchClient {
    public static void main(String[] args) {
        ManagedChannel channel = ManagedChannelBuilder.forAddress("localhost", 9400)
            .usePlaintext()
            .build();

        SearchServiceGrpc.SearchServiceBlockingStub stub = SearchServiceGrpc.newBlockingStub(channel);

        Query query = Query.newBuilder()
            .setTerm(TermQuery.newBuilder().setField("director").setValue("Nolan"))
            .build();

        SearchRequest request = SearchRequest.newBuilder()
            .addIndex("movies")
            .setQuery(query)
            .setSize(5)
            .build();

        SearchResponse response = stub.search(request);
        System.out.println("Found hits: " + response.getHits().getTotal());
        channel.shutdown();
    }
}

先决条件
gRPC 服务和方法
请求字段
支持的查询
响应字段
示例响应
Java gRPC 客户端示例

此页面有帮助吗？

✔ 是 ✖ 否

告诉我们原因

剩余 350 字符

有问题？在 OpenSearch 论坛上提问。

想贡献？编辑此页面或创建问题。