New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
« Index API Delete API »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›REST APIs ›文档 API

Get API

编辑

Get API

编辑

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

resp = client.get(
    index="my-index-000001",
    id="0",
)
print(resp)
response = client.get(
  index: 'my-index-000001',
  id: 0
)
puts response
const response = await client.get({
  index: "my-index-000001",
  id: 0,
});
console.log(response);
GET my-index-000001/_doc/0
Copy as curlTry in Elastic 

请求

编辑

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。

源过滤

编辑

默认情况下，除非您使用了 stored_fields 参数或 _source 字段被禁用，否则 get 操作会返回 _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
const response = await client.get({
  index: "my-index-000001",
  id: 0,
  _source: "false",
});
console.log(response);
GET my-index-000001/_doc/0?_source=false
Copy as curlTry in Elastic 

如果您只需要 _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
const response = await client.get({
  index: "my-index-000001",
  id: 0,
  _source_includes: "*.id",
  _source_excludes: "entities",
});
console.log(response);
GET my-index-000001/_doc/0?_source_includes=*.id&_source_excludes=entities
Copy as curlTry in Elastic 

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

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
const response = await client.get({
  index: "my-index-000001",
  id: 0,
  _source: "*.id",
});
console.log(response);
GET my-index-000001/_doc/0?_source=*.id
Copy as curlTry in Elastic 

路由

编辑

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

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
const response = await client.get({
  index: "my-index-000001",
  id: 2,
  routing: "user1",
});
console.log(response);
GET my-index-000001/_doc/2?routing=user1
Copy as curlTry in Elastic 

此请求获取 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 字段的 true 或 false，或要返回的字段列表。
_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
const response = await client.get({
  index: "my-index-000001",
  id: 0,
});
console.log(response);
GET my-index-000001/_doc/0
Copy as curlTry in Elastic 

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
const response = await client.exists({
  index: "my-index-000001",
  id: 0,
});
console.log(response);
HEAD my-index-000001/_doc/0
Copy as curlTry in Elastic 

如果文档存在，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
const response = await client.getSource({
  index: "my-index-000001",
  id: 1,
});
console.log(response);
GET my-index-000001/_source/1
Copy as curlTry in Elastic 

您可以使用源过滤参数来控制返回 _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
const response = await client.getSource({
  index: "my-index-000001",
  id: 1,
  _source_includes: "*.id",
  _source_excludes: "entities",
});
console.log(response);
GET my-index-000001/_source/1/?_source_includes=*.id&_source_excludes=entities
Copy as curlTry in Elastic 

您可以使用带有 _source 端点的 HEAD 来有效地测试文档 _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
const response = await client.existsSource({
  index: "my-index-000001",
  id: 1,
});
console.log(response);
HEAD my-index-000001/_source/1
Copy as curlTry in Elastic 

获取存储字段

编辑

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

resp = client.indices.create(
    index="my-index-000001",
    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
const response = await client.indices.create({
  index: "my-index-000001",
  mappings: {
    properties: {
      counter: {
        type: "integer",
        store: false,
      },
      tags: {
        type: "keyword",
        store: true,
      },
    },
  },
});
console.log(response);
PUT my-index-000001
{
   "mappings": {
       "properties": {
          "counter": {
             "type": "integer",
             "store": false
          },
          "tags": {
             "type": "keyword",
             "store": true
          }
       }
   }
}
Copy as curlTry in Elastic 

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

resp = client.index(
    index="my-index-000001",
    id="1",
    document={
        "counter": 1,
        "tags": [
            "production"
        ]
    },
)
print(resp)
response = client.index(
  index: 'my-index-000001',
  id: 1,
  body: {
    counter: 1,
    tags: [
      'production'
    ]
  }
)
puts response
const response = await client.index({
  index: "my-index-000001",
  id: 1,
  document: {
    counter: 1,
    tags: ["production"],
  },
});
console.log(response);
PUT my-index-000001/_doc/1
{
  "counter": 1,
  "tags": [ "production" ]
}
Copy as curlTry in Elastic 

然后尝试检索它

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
const response = await client.get({
  index: "my-index-000001",
  id: 1,
  stored_fields: "tags,counter",
});
console.log(response);
GET my-index-000001/_doc/1?stored_fields=tags,counter
Copy as curlTry in Elastic 

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",
    document={
        "counter": 1,
        "tags": [
            "env2"
        ]
    },
)
print(resp)
response = client.index(
  index: 'my-index-000001',
  id: 2,
  routing: 'user1',
  body: {
    counter: 1,
    tags: [
      'env2'
    ]
  }
)
puts response
const response = await client.index({
  index: "my-index-000001",
  id: 2,
  routing: "user1",
  document: {
    counter: 1,
    tags: ["env2"],
  },
});
console.log(response);
PUT my-index-000001/_doc/2?routing=user1
{
  "counter" : 1,
  "tags" : ["env2"]
}
Copy as curlTry in Elastic 
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
const response = await client.get({
  index: "my-index-000001",
  id: 2,
  routing: "user1",
  stored_fields: "tags,counter",
});
console.log(response);
GET my-index-000001/_doc/2?routing=user1&stored_fields=tags,counter
Copy as curlTry in Elastic 

API 返回以下结果

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

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

« Index API Delete API »