Link Search Menu Expand Document Documentation Menu
文档

获取文档

1.0 版引入

将 JSON 文档添加到索引后，您可以使用获取文档 API 操作来检索文档的信息和数据。

端点

使用 GET 方法从特定索引中检索文档及其源或存储的字段。使用 HEAD 方法验证文档是否存在。

GET <index>/_doc/<_id>
HEAD <index>/_doc/<_id>

使用 _source 检索文档源或验证其是否存在。

GET <index>/_source/<_id>
HEAD <index>/_source/<_id>

路径参数

参数 类型 描述 必需
<index> 字符串 要从中检索文档的索引。 是
<_id> 字符串 要检索的文档的 ID。 是

查询参数

所有查询参数都是可选的。

参数 类型 描述
preference 字符串 指定从哪个分片检索结果的首选项。可用选项包括 _local，它指示操作从本地分配的分片副本中检索结果；以及分配给特定分片副本的自定义字符串值。默认情况下，OpenSearch 在随机分片上执行获取文档操作。
realtime 布尔型 指定操作是否应实时运行。如果为 false，操作将等待索引刷新以分析源来检索数据，这使得操作接近实时。默认值为 true。
refresh 布尔型 如果为 true，OpenSearch 会刷新分片，使获取操作对搜索结果可用。有效选项为 true、false 和 wait_for，它们指示 OpenSearch 在执行操作前等待刷新。默认值为 false。
路由 字符串 用于将操作路由到特定分片的值。
stored_fields 列表 一个逗号分隔的列表，包含应检索的索引中存储的字段。默认情况下不返回任何存储字段。
_source 字符串 是否在响应正文中包含 _source 字段。默认值为 true。
_source_excludes 字符串 要在查询响应中排除的源字段的逗号分隔列表。
_source_includes 字符串 要在查询响应中包含的源字段的逗号分隔列表。
version 整数 要返回的文档版本，必须与文档的当前版本匹配。
version_type 枚举 检索特定类型的文档。可用选项包括 external（如果指定版本号大于文档的当前版本，则检索文档）和 external_gte（如果指定版本号大于或等于文档的当前版本，则检索文档）。例如，要检索文档的版本 3，请使用 /_doc/1?version=3&version_type=external。

实时

OpenSearch 获取文档 API 默认实时运行，这意味着它会检索文档的最新版本，无论索引的刷新率或新数据变得可搜索的速度如何。但是，如果您为已更新但尚未刷新的文档请求存储字段（使用 stored_fields 参数），则获取文档 API 会解析并分析文档的源以提取这些存储字段。

要禁用实时行为并根据索引的上次刷新状态检索文档，请将 realtime 参数设置为 false。

源过滤

默认情况下，获取文档 API 返回请求文档的 _source 字段的全部内容。但是，您可以通过使用 _source URL 参数并将其设置为 false 来选择将 _source 字段从响应中排除，如下例所示：

GET test-index/_doc/0?_source=false

source 包含和排除

如果您只想从源中检索特定字段，请分别使用 _source_includes 或 _source_excludes 参数来包含或排除特定字段。这对于大型文档可能很有益，因为只检索所需字段可以减少网络开销。

这两个参数都接受逗号分隔的字段列表和通配符表达式，如下例所示，其中包含 *.play 的任何 _source 都包含在响应中，但具有 entities 字段的源被排除：

GET test-index/_doc/0?_source_includes=*.play&_source_excludes=entities

简写表示法

如果您只想包含某些字段而不需要排除任何字段，可以通过直接在 _source 参数中指定所需字段来使用更简短的表示法：

GET test-index/_doc/0?_source=*.id

路由

在 OpenSearch 中索引文档时，您可以指定一个 routing 值来控制文档的分片分配。如果在索引期间使用了路由，那么在使用获取文档 API 检索文档时，您必须提供相同的路由值，如下例所示：

GET test-index/_doc/1?routing=user1

此请求检索 ID 为 1 的文档，但它使用路由值“user1”来确定文档存储在哪个分片上。如果未指定正确的路由值，获取文档 API 将无法定位和获取请求的文档。

首选项

获取文档 API 允许您控制哪个分片副本处理请求。默认情况下，操作会在可用的分片副本之间随机分发。

但是，您可以指定一个首选项来影响副本选择。首选项可以设置为以下值之一：

  • _local：如果可能，操作会尝试在本地分配的分片副本上执行。这可以通过减少网络开销来提高性能。
  • 自定义（字符串）值：指定自定义字符串值可确保具有相同值的请求路由到同一组分片。这种一致性在管理处于不同刷新状态的分片时可能很有益，因为它可以防止在访问具有不同数据可见性的分片时可能出现的“跳跃值”。常见的做法是使用 Web 会话 ID 或用户名作为自定义值。

刷新

将 refresh 参数设置为 true 可在运行获取文档 API 操作之前强制刷新相关分片。这确保了最新的数据更改可以被搜索和被 API 可见。但是，应谨慎执行刷新，因为它可能会给系统带来沉重负担并降低索引性能。建议在启用 refresh 参数之前仔细评估数据新鲜度与系统负载之间的权衡。

分布式

运行获取文档 API 时，OpenSearch 首先根据文档 ID 计算哈希值，这决定了文档所在分片的特定 ID。然后操作被重定向到该分片 ID 组中的一个副本（包括主分片及其副本分片），并从该副本返回结果。

更多的分片副本数量可以提高 GET 操作的可伸缩性和性能，因为负载可以分布到多个副本分片上。这意味着随着副本数量的增加，您可以为获取文档 API 请求实现更好的伸缩性和吞吐量。

版本控制支持

使用 version 参数仅当文档的当前版本与指定版本号匹配时才检索文档。这对于确保数据一致性以及在处理版本化文档时防止冲突非常有用。

在内部，当OpenSearch中的文档更新时，原始版本会被标记为已删除，并添加一个新版本的文档。然而，原始版本并不会立即从系统中消失。虽然您无法通过“获取文档API”访问它，但随着您继续索引新数据，OpenSearch会在后台管理已删除文档版本的清理工作。

请求示例

以下示例请求检索名为1的文档信息。

GET sample-index1/_doc/1

示例响应

{
  "_index": "sample-index1",
  "_id": "1",
  "_version": 1,
  "_seq_no": 0,
  "_primary_term": 9,
  "found": true,
  "_source": {
    "text": "This is just some sample text."
  }
}

响应正文字段

字段 描述
_index 索引的名称。
_id 文档的 ID。
_version 文档的版本号。每次文档更改时都会更新。
_seq_no 文档被索引时分配的序列号。
primary_term 文档被索引时分配的主术语。
found 文档是否存在。
_routing 文档被路由到的分片。如果文档未路由到特定分片，则省略此字段。
_source 如果found为真，则包含文档的数据。如果_source在参数中设置为false或stored_fields设置为true，则省略此字段。
_fields 包含存储在索引中的文档数据。仅当stored_fields和found都为真时才返回。
剩余 350 字符

有问题？。

想做贡献？ 或 。