« 按查询更新 API 批量 API »
Elastic 文档 ›Elasticsearch 指南 [8.14] ›REST API ›文档 API

多重获取 (mget) API

编辑

多重获取 (mget) API编辑

通过 ID 检索多个 JSON 文档。

response = client.mget(
  body: {
    docs: [
      {
        _index: 'my-index-000001',
        _id: '1'
      },
      {
        _index: 'my-index-000001',
        _id: '2'
      }
    ]
  }
)
puts response
GET /_mget
{
  "docs": [
    {
      "_index": "my-index-000001",
      "_id": "1"
    },
    {
      "_index": "my-index-000001",
      "_id": "2"
    }
  ]
}

请求编辑

GET /_mget

GET /<index>/_mget

先决条件编辑

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

描述编辑

您可以使用 mget 从一个或多个索引中检索多个文档。如果在请求 URI 中指定了索引，则只需在请求正文中指定文档 ID。

安全编辑

请参阅基于 URL 的访问控制。

部分响应编辑

为了确保快速响应，如果一个或多个分片失败，则多重获取 API 会使用部分结果进行响应。有关更多信息，请参阅分片故障。

路径参数编辑

<index>
（可选，字符串）在指定 ids 时，或 docs 数组中的文档未指定索引时，要从中检索文档的索引名称。

查询参数编辑

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

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

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

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

_source_includes

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

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

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

请求正文编辑

docs

（可选，数组）您要检索的文档。如果在请求 URI 中未指定索引，则为必填项。您可以为每个文档指定以下属性

_id
（必填，字符串）唯一的文档 ID。
_index
（可选，字符串）包含文档的索引。如果在请求 URI 中未指定索引，则为必填项。
routing
（可选，字符串）文档所在主分片的键。如果在索引期间使用了路由，则为必填项。
_source

（可选，布尔值）如果为 false，则排除所有 _source 字段。默认为 true。

source_include
（可选，数组）要从 _source 字段中提取并返回的字段。
source_exclude
（可选，数组）要从返回的 _source 字段中排除的字段。
_stored_fields
（可选，数组）您要检索的存储字段。
ids
（可选，数组）您要检索的文档的 ID。当在请求 URI 中指定了索引时允许使用。

响应正文编辑

响应包括一个 docs 数组，该数组包含按请求中指定的顺序排列的文档。返回的文档的结构类似于获取 API 返回的结构。如果在获取特定文档时出现故障，则会在文档的位置包含错误。

示例编辑

按 ID 获取文档编辑

如果在请求 URI 中指定了索引，则在请求正文中只需要文档 ID

response = client.mget(
  index: 'my-index-000001',
  body: {
    docs: [
      {
        _id: '1'
      },
      {
        _id: '2'
      }
    ]
  }
)
puts response
GET /my-index-000001/_mget
{
  "docs": [
    {
      "_id": "1"
    },
    {
      "_id": "2"
    }
  ]
}

您可以使用 ids 元素来简化请求

response = client.mget(
  index: 'my-index-000001',
  body: {
    ids: [
      '1',
      '2'
    ]
  }
)
puts response
GET /my-index-000001/_mget
{
  "ids" : ["1", "2"]
}

过滤源字段编辑

默认情况下，会为每个文档返回 _source 字段（如果已存储）。使用 _source 和 _source_include 或 source_exclude 属性来过滤要为特定文档返回哪些字段。您可以在请求 URI 中包含 _source、_source_includes 和 _source_excludes 查询参数，以指定在没有针对每个文档的说明时要使用的默认值。

例如，以下请求为文档 1 设置 _source 为 false 以完全排除源，从文档 2 中检索 field3 和 field4，并从文档 3 中检索 user 字段，但过滤掉 user.location 字段。

response = client.mget(
  body: {
    docs: [
      {
        _index: 'test',
        _id: '1',
        _source: false
      },
      {
        _index: 'test',
        _id: '2',
        _source: [
          'field3',
          'field4'
        ]
      },
      {
        _index: 'test',
        _id: '3',
        _source: {
          include: [
            'user'
          ],
          exclude: [
            'user.location'
          ]
        }
      }
    ]
  }
)
puts response
GET /_mget
{
  "docs": [
    {
      "_index": "test",
      "_id": "1",
      "_source": false
    },
    {
      "_index": "test",
      "_id": "2",
      "_source": [ "field3", "field4" ]
    },
    {
      "_index": "test",
      "_id": "3",
      "_source": {
        "include": [ "user" ],
        "exclude": [ "user.location" ]
      }
    }
  ]
}

获取存储字段编辑

使用 stored_fields 属性指定要检索的存储字段集。任何请求的未存储字段都将被忽略。您可以在请求 URI 中包含 stored_fields 查询参数，以指定在没有针对每个文档的说明时要使用的默认值。

例如，以下请求从文档 1 中检索 field1 和 field2，并从文档 2 中检索 field3 和 field4

response = client.mget(
  body: {
    docs: [
      {
        _index: 'test',
        _id: '1',
        stored_fields: [
          'field1',
          'field2'
        ]
      },
      {
        _index: 'test',
        _id: '2',
        stored_fields: [
          'field3',
          'field4'
        ]
      }
    ]
  }
)
puts response
GET /_mget
{
  "docs": [
    {
      "_index": "test",
      "_id": "1",
      "stored_fields": [ "field1", "field2" ]
    },
    {
      "_index": "test",
      "_id": "2",
      "stored_fields": [ "field3", "field4" ]
    }
  ]
}

以下请求默认从所有文档中检索 field1 和 field2。这些默认字段将为文档 1 返回，但会被覆盖为为文档 2 返回 field3 和 field4。

response = client.mget(
  index: 'test',
  stored_fields: 'field1,field2',
  body: {
    docs: [
      {
        _id: '1'
      },
      {
        _id: '2',
        stored_fields: [
          'field3',
          'field4'
        ]
      }
    ]
  }
)
puts response
GET /test/_mget?stored_fields=field1,field2
{
  "docs": [
    {
      "_id": "1"
    },
    {
      "_id": "2",
      "stored_fields": [ "field3", "field4" ]
    }
  ]
}

指定文档路由编辑

如果在索引期间使用了路由，则需要指定路由值以检索文档。例如，以下请求从对应于路由键 key1 的分片中获取 test/_doc/2，并从对应于路由键 key2 的分片中获取 test/_doc/1。

response = client.mget(
  routing: 'key1',
  body: {
    docs: [
      {
        _index: 'test',
        _id: '1',
        routing: 'key2'
      },
      {
        _index: 'test',
        _id: '2'
      }
    ]
  }
)
puts response
GET /_mget?routing=key1
{
  "docs": [
    {
      "_index": "test",
      "_id": "1",
      "routing": "key2"
    },
    {
      "_index": "test",
      "_id": "2"
    }
  ]
}
« 按查询更新 API 批量 API »