« 索引 API 删除 API »
Elastic 文档 ›Elasticsearch 指南 [8.14] ›REST API ›文档 API

获取 API

编辑

获取 API编辑

从索引中检索指定的 JSON 文档。

resp = client.get(
    index="my-index-000001",
    id="0",
)
print(resp)
response = client.get(
  index: 'my-index-000001',
  id: 0
)
puts response
GET my-index-000001/_doc/0

请求编辑

GET <index>/_doc/<_id>

HEAD <index>/_doc/<_id>

GET <index>/_source/<_id>

HEAD <index>/_source/<_id>

先决条件编辑

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

描述编辑

使用 GET 检索文档及其源或存储字段，这些字段来自特定索引。使用 HEAD 验证文档是否存在。您可以使用 _source 资源仅检索文档源或验证其是否存在。

实时编辑

默认情况下，get API 是实时的，不受索引刷新率（数据何时对搜索可见）的影响。在请求存储字段（参见 stored_fields 参数）且文档已更新但尚未刷新时，get API 将不得不解析和分析源以提取存储字段。为了禁用实时 GET，可以将 realtime 参数设置为 false。

源筛选编辑

默认情况下，get 操作返回 _source 字段的内容，除非您使用了 stored_fields 参数或 _source 字段被禁用。您可以使用 _source 参数关闭 _source 检索。

resp = client.get(
    index="my-index-000001",
    id="0",
    _source="false",
)
print(resp)
response = client.get(
  index: 'my-index-000001',
  id: 0,
  _source: false
)
puts response
GET my-index-000001/_doc/0?_source=false

如果您只需要 _source 中的一个或两个字段，请使用 _source_includes 或 _source_excludes 参数来包含或过滤掉特定字段。这对于大型文档特别有用，在大型文档中，部分检索可以节省网络开销。这两个参数都接受以逗号分隔的字段列表或通配符表达式。示例

resp = client.get(
    index="my-index-000001",
    id="0",
    _source_includes="*.id",
    _source_excludes="entities",
)
print(resp)
response = client.get(
  index: 'my-index-000001',
  id: 0,
  _source_includes: '*.id',
  _source_excludes: 'entities'
)
puts response
GET my-index-000001/_doc/0?_source_includes=*.id&_source_excludes=entities

如果您只想指定包含项，可以使用更短的表示法

resp = client.get(
    index="my-index-000001",
    id="0",
    _source="*.id",
)
print(resp)
response = client.get(
  index: 'my-index-000001',
  id: 0,
  _source: '*.id'
)
puts response
GET my-index-000001/_doc/0?_source=*.id
路由编辑

如果在索引期间使用路由，则还需要指定路由值才能检索文档。例如

resp = client.get(
    index="my-index-000001",
    id="2",
    routing="user1",
)
print(resp)
response = client.get(
  index: 'my-index-000001',
  id: 2,
  routing: 'user1'
)
puts response
GET my-index-000001/_doc/2?routing=user1

此请求获取 id 为 2 的文档，但它是根据用户进行路由的。如果未指定正确的路由，则不会获取文档。

首选项编辑

控制在哪个分片副本上执行 get 请求的 preference。默认情况下，操作在分片副本之间随机分配。

可以将 preference 设置为

_local
如果可能，操作将优先在本地分配的分片上执行。
自定义（字符串）值
自定义值将用于保证对相同自定义值使用相同的分片。这有助于在遇到不同刷新状态的不同分片时“跳跃值”。示例值可以是类似于 Web 会话 ID 或用户名的东西。
刷新编辑

可以将 refresh 参数设置为 true，以便在 get 操作之前刷新相关分片并使其可搜索。将它设置为 true 应该在仔细考虑和验证这不会对系统造成沉重负载（并减慢索引速度）之后进行。

分布式编辑

get 操作被哈希到一个特定的分片 ID 中。然后它被重定向到该分片 ID 内的某个副本，并返回结果。副本是该分片 ID 组内的主分片及其副本。这意味着我们拥有的副本越多，GET 扩展性就越好。

版本控制支持编辑

您可以使用 version 参数仅在文档的当前版本等于指定版本时才检索文档。

在内部，Elasticsearch 将旧文档标记为已删除，并添加了一个全新的文档。旧版本的文档不会立即消失，尽管您将无法访问它。Elasticsearch 在后台清理已删除的文档，因为您会继续索引更多数据。

路径参数编辑

<index>
（必需，字符串）包含文档的索引的名称。
<_id>
（必需，字符串）文档的唯一标识符。

查询参数编辑

preference
（可选，字符串）指定应在哪个节点或分片上执行操作。默认情况下为随机。
realtime
（可选，布尔值）如果为 true，则请求是实时的，而不是近实时的。默认为 true。参见 实时。
refresh
（可选，布尔值）如果为 true，则请求在检索文档之前刷新相关分片。默认为 false。
routing
（可选，字符串）用于将操作路由到特定分片的自定义值。
stored_fields
（可选，字符串）要在响应中包含的 存储字段 的逗号分隔列表。
_source
（可选，字符串）是否返回 _source 字段，或返回字段列表。
_source_excludes

（可选，字符串）要从响应中排除的 源字段 的逗号分隔列表。

您还可以使用此参数从 _source_includes 查询参数中指定的子集中排除字段。

如果 _source 参数为 false，则忽略此参数。

_source_includes

（可选，字符串）要包含在响应中的 源字段 的逗号分隔列表。

如果指定此参数，则仅返回这些源字段。您可以使用 _source_excludes 查询参数从该子集中排除字段。

如果 _source 参数为 false，则忽略此参数。

version
（可选，整数）用于并发控制的显式版本号。指定的版本必须与文档的当前版本匹配，请求才能成功。
version_type
（可选，枚举）特定版本类型：external、external_gte。

响应主体编辑

_index
文档所属索引的名称。
_id
文档的唯一标识符。
_version
文档版本。每次更新文档时都会递增。
_seq_no
为索引操作分配给文档的序列号。序列号用于确保旧版本的文档不会覆盖新版本。参见 乐观并发控制。
_primary_term
为索引操作分配给文档的主项。参见 乐观并发控制。
found
指示文档是否存在：true 或 false。
_routing
显式路由（如果设置）。
_source
如果 found 为 true，则包含以 JSON 格式化的文档数据。如果 _source 参数设置为 false 或 stored_fields 参数设置为 true，则将其排除。
_fields
如果 stored_fields 参数设置为 true 且 found 为 true，则包含存储在索引中的文档字段。

示例编辑

检索 my-index-000001 索引中 _id 为 0 的 JSON 文档

resp = client.get(
    index="my-index-000001",
    id="0",
)
print(resp)
response = client.get(
  index: 'my-index-000001',
  id: 0
)
puts response
GET my-index-000001/_doc/0

API 返回以下结果

{
  "_index": "my-index-000001",
  "_id": "0",
  "_version": 1,
  "_seq_no": 0,
  "_primary_term": 1,
  "found": true,
  "_source": {
    "@timestamp": "2099-11-15T14:12:12",
    "http": {
      "request": {
        "method": "get"
      },
      "response": {
        "status_code": 200,
        "bytes": 1070000
      },
      "version": "1.1"
    },
    "source": {
      "ip": "127.0.0.1"
    },
    "message": "GET /search HTTP/1.1 200 1070000",
    "user": {
      "id": "kimchy"
    }
  }
}

检查 _id 为 0 的文档是否存在

resp = client.exists(
    index="my-index-000001",
    id="0",
)
print(resp)
response = client.exists(
  index: 'my-index-000001',
  id: 0
)
puts response
HEAD my-index-000001/_doc/0

如果文档存在，Elasticsearch 返回状态代码 200 - OK，如果不存在，则返回 404 - Not Found。

仅获取源字段编辑

使用 <index>/_source/<id> 资源仅获取文档的 _source 字段。例如

resp = client.get_source(
    index="my-index-000001",
    id="1",
)
print(resp)
response = client.get_source(
  index: 'my-index-000001',
  id: 1
)
puts response
GET my-index-000001/_source/1

您可以使用源筛选参数来控制返回的 _source 的哪些部分

resp = client.get_source(
    index="my-index-000001",
    id="1",
    _source_includes="*.id",
    _source_excludes="entities",
)
print(resp)
response = client.get_source(
  index: 'my-index-000001',
  id: 1,
  _source_includes: '*.id',
  _source_excludes: 'entities'
)
puts response
GET my-index-000001/_source/1/?_source_includes=*.id&_source_excludes=entities

您可以将 HEAD 与 _source 端点一起使用，以有效地测试文档 _source 是否存在。如果在 映射 中禁用了文档的源，则该源不可用。

resp = client.exists_source(
    index="my-index-000001",
    id="1",
)
print(resp)
response = client.exists_source(
  index: 'my-index-000001',
  id: 1
)
puts response
HEAD my-index-000001/_source/1
获取存储字段编辑

使用 stored_fields 参数指定要检索的存储字段集。任何未存储的请求字段都将被忽略。例如，考虑以下映射

resp = client.indices.create(
    index="my-index-000001",
    body={
        "mappings": {
            "properties": {
                "counter": {"type": "integer", "store": False},
                "tags": {"type": "keyword", "store": True},
            }
        }
    },
)
print(resp)
response = client.indices.create(
  index: 'my-index-000001',
  body: {
    mappings: {
      properties: {
        counter: {
          type: 'integer',
          store: false
        },
        tags: {
          type: 'keyword',
          store: true
        }
      }
    }
  }
)
puts response
PUT my-index-000001
{
   "mappings": {
       "properties": {
          "counter": {
             "type": "integer",
             "store": false
          },
          "tags": {
             "type": "keyword",
             "store": true
          }
       }
   }
}

现在我们可以添加一个文档

resp = client.index(
    index="my-index-000001",
    id="1",
    body={"counter": 1, "tags": ["production"]},
)
print(resp)
response = client.index(
  index: 'my-index-000001',
  id: 1,
  body: {
    counter: 1,
    tags: [
      'production'
    ]
  }
)
puts response
PUT my-index-000001/_doc/1
{
  "counter": 1,
  "tags": [ "production" ]
}

然后尝试检索它

resp = client.get(
    index="my-index-000001",
    id="1",
    stored_fields=["tags", "counter"],
)
print(resp)
response = client.get(
  index: 'my-index-000001',
  id: 1,
  stored_fields: 'tags,counter'
)
puts response
GET my-index-000001/_doc/1?stored_fields=tags,counter

API 返回以下结果

{
   "_index": "my-index-000001",
   "_id": "1",
   "_version": 1,
   "_seq_no" : 22,
   "_primary_term" : 1,
   "found": true,
   "fields": {
      "tags": [
         "production"
      ]
   }
}

从文档本身获取的字段值始终作为数组返回。由于 counter 字段未存储，因此 get 请求会忽略它。

您还可以检索元数据字段，例如 _routing 字段

resp = client.index(
    index="my-index-000001",
    id="2",
    routing="user1",
    body={"counter": 1, "tags": ["env2"]},
)
print(resp)
response = client.index(
  index: 'my-index-000001',
  id: 2,
  routing: 'user1',
  body: {
    counter: 1,
    tags: [
      'env2'
    ]
  }
)
puts response
PUT my-index-000001/_doc/2?routing=user1
{
  "counter" : 1,
  "tags" : ["env2"]
}
resp = client.get(
    index="my-index-000001",
    id="2",
    routing="user1",
    stored_fields=["tags", "counter"],
)
print(resp)
response = client.get(
  index: 'my-index-000001',
  id: 2,
  routing: 'user1',
  stored_fields: 'tags,counter'
)
puts response
GET my-index-000001/_doc/2?routing=user1&stored_fields=tags,counter

API 返回以下结果

{
   "_index": "my-index-000001",
   "_id": "2",
   "_version": 1,
   "_seq_no" : 13,
   "_primary_term" : 1,
   "_routing": "user1",
   "found": true,
   "fields": {
      "tags": [
         "env2"
      ]
   }
}

只有叶子字段可以使用 stored_field 选项检索。无法返回对象字段——如果指定，请求将失败。

« 索引 API 删除 API »