Elasticsearch专题精讲—— REST APIs —— Document APIs —— Multi get (mget) API

REST APIs —— Document APIs —— Multi get (mget) API

https://www.elastic.co/guide/en/elasticsearch/reference/8.8/docs-multi-get.html#docs-multi-get

Retrieves multiple JSON documents by ID.

按 ID 检索多个 JSON 文档。

        curl -X GET "localhost:9200/_mget?pretty" -H 'Content-Type: application/json' -d'
        {
          "docs": [
            {
              "_index": "my-index-000001",
              "_id": "1"
            },
            {
              "_index": "my-index-000001",
              "_id": "2"
            }
          ]
        }'
    

1、Request（请求）

https://www.elastic.co/guide/en/elasticsearch/reference/8.8/docs-multi-get.html#docs-multi-get-api-request

        GET /_mget

        GET/_ mget
        
        GET /< index>/_mget
        
        GET /< index>/_mget

2、Prerequisites（先决条件）

https://www.elastic.co/guide/en/elasticsearch/reference/8.8/docs-multi-get.html#docs-multi-get-api-prereqs

If the Elasticsearch security features are enabled, you must have the read index privilege for the target index or index alias.

如果启用了 Elasticsearch 安全特性，则必须拥有目标索引或索引别名的读索引特权（https://www.elastic.co/guide/en/elasticsearch/reference/8.8/security-privileges.html#privileges-list-indices）。

3、Description（描述）

https://www.elastic.co/guide/en/elasticsearch/reference/8.8/docs-update-by-query.html#docs-update-by-query-api-desc

You use mget to retrieve multiple documents from one or more indices. If you specify an index in the request URI, you only need to specify the document IDs in the request body.

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

我理解意思是说： 假设你想从索引 "my_index" 中获取文档 ID 为 "1", "2", "3" 的三个文档，你可以使用 Elasticsearch 的 Multi Get API。对于这种情况，HTTP请求的格式如下所示：

        POST /my_index/_mget
        {
            "ids" : ["1", "2", "3"]
        }
    

其中，请求 URL 中的 "_mget" 表示调用 Multi Get API，请求体中的 "ids" 参数指定了待查询的文档 ID 列表。 返回的响应会包含每一个文档的详细信息，例如文档内容、元数据等。使用 Mget API，可以一次性获取多个文档，从而提高查询效率。

当你想从多个索引中获取文档时，可以使用 Multi Get API，并且在请求 URL 中指定索引名。此时，请求主体可以省略，因为所有的信息都可以在请求 URI 中进行指定。 例如，如果你想从两个不同的索引 "my_index_1" 和 "my_index_2" 中获取文档 ID 为 "1", "2", "3" 的三个文档，可以通过以下 HTTP 请求：

        POST /my_index_1,my_index_2/_mget
        {
            "ids" : ["1", "2", "3"]
        }        
    

其中，请求中的索引名 "my_index_1" 和 "my_index_2" 被指定在 URL 中，而请求主体中的 "ids" 参数仍然指定了待查询的文档 ID。此时，Elasticsearch 会在两个索引中查询符合条件的文档，并将结果返回给客户端。

4、Security（安全）

https://www.elastic.co/guide/en/elasticsearch/reference/8.8/docs-multi-get.html#mget-security

See URL-based access control.

请参见基于 URL 的访问控制（https://www.elastic.co/guide/en/elasticsearch/reference/8.8/api-conventions.html#api-url-access-control）。

5、Partial responses（部分回答）

https://www.elastic.co/guide/en/elasticsearch/reference/8.8/docs-multi-get.html#multi-get-partial-responses

To ensure fast responses, the multi get API responds with partial results if one or more shards fail. See Shard failures for more information.

为了确保快速响应，multi get API在一个或多个分片失败时会响应部分结果。有关Shard failures的更多信息，请参见相关文档。（https://www.elastic.co/guide/en/elasticsearch/reference/8.8/docs-replication.html#shard-failures）。

6、Get documents by ID（凭 ID 获取 documents）

https://www.elastic.co/guide/en/elasticsearch/reference/8.8/docs-multi-get.html#mget-ids

If you specify an index in the request URI, only the document IDs are required in the request body:

如果在请求 URI 中指定了一个索引，那么在请求主体中只需要文档 ID:

        curl -X GET "localhost:9200/my-index-000001/_mget?pretty" -H 'Content-Type: application/json' -d'
        {
          "docs": [
            {
              "_id": "1"
            },
            {
              "_id": "2"
            }
          ]
        }'
    

You can use the ids element to simplify the request:

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

        curl -X GET "localhost:9200/my-index-000001/_mget?pretty" -H 'Content-Type: application/json' -d'
        {
          "ids" : ["1", "2"]
        }'        

7、Filter source fields（source 过滤）

https://www.elastic.co/guide/en/elasticsearch/reference/8.8/docs-multi-get.html#mget-source-filtering

By default, the _source field is returned for every document (if stored). Use the _source and _source_include or source_exclude attributes to filter what fields are returned for a particular document. You can include the _source, _source_includes, and _source_excludes query parameters in the request URI to specify the defaults to use when there are no per-document instructions.

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

我理解意思是说： 在 Elasticsearch 中，每个文档都由多个字段组成，其中有一个特殊的字段叫做 _source ，它存储了原始的文档内容。当我们使用 Multi Get API 从多个文档中获取数据时，默认情况下，对于每个文档都会返回其对应的 _source 字段。但是，如果我们只需要获取某些字段，可以使用 _source_include 或 source_exclude 参数来过滤需要返回的字段。例如，我们可以使用以下语句来获取特定文档的部分字段：

        GET /my_index/_doc/1?_source_includes=field1,field2

上述语句将返回 id 为 1 的文档中的“field1”和“field2”字段。相反，如果我们想排除部分字段，可以使用 _source_exclude 参数。例如，以下语句将返回特定文档中除了“field3”和“field4”之外的所有字段：

        GET /my_index/_doc/1?_source_exclude=field3,field4
    

需要注意的是，如果在请求 URI 或请求主体中没有为每个文档指定 _source、_source_include 和 _source_exclude 参数，则将使用默认设置。可以使用请求 URI 中的 _source、_source_include 和 _source_exclude 查询参数来指定默认设置。例如：

        GET /my_index/_doc/1?_source&source_include=field1,field2
    

上述语句指定了默认设置，每个文档都将返回其对应的 _source 字段，并且返回的 _source 字段中仅包含“field1”和“field2”字段。

For example, the following request sets _source to false for document 1 to exclude the source entirely, retrieves field3 and field4 from document 2, and retrieves the user field from document 3 but filters out the user.location field.

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

        curl -X GET "localhost:9200/_mget?pretty" -H 'Content-Type: application/json' -d'
        {
          "docs": [
            {
              "_index": "test",
              "_id": "1",
              "_source": false
            },
            {
              "_index": "test",
              "_id": "2",
              "_source": [ "field3", "field4" ]
            },
            {
              "_index": "test",
              "_id": "3",
              "_source": {
                "include": [ "user" ],
                "exclude": [ "user.location" ]
              }
            }
          ]
        }'

8、Get stored fields（获取存储区域）

https://www.elastic.co/guide/en/elasticsearch/reference/8.8/docs-multi-get.html#mget-fields

Use the stored_fields attribute to specify the set of stored fields you want to retrieve. Any requested fields that are not stored are ignored. You can include the stored_fields query parameter in the request URI to specify the defaults to use when there are no per-document instructions.

使用 stored_fields 属性指定要检索的存储字段集合。如果请求的字段没有存储，则会被忽略。您可以在请求 URI 中包含 stored_fields 查询参数，以指定没有每个文档指令时使用的默认值。

For example, the following request retrieves field1 and field2 from document 1, and field3 and field4 from document 2:

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

                    curl -X GET "localhost:9200/_mget?pretty" -H 'Content-Type: application/json' -d'
                    {
                      "docs": [
                        {
                          "_index": "test",
                          "_id": "1",
                          "stored_fields": [ "field1", "field2" ]
                        },
                        {
                          "_index": "test",
                          "_id": "2",
                          "stored_fields": [ "field3", "field4" ]
                        }
                      ]
                    }'  
    

9、Get stored fields（获取存储区域）

https://www.elastic.co/guide/en/elasticsearch/reference/8.8/docs-multi-get.html#mget-routing

If routing is used during indexing, you need to specify the routing value to retrieve documents. For example, the following request fetches test/_doc/2 from the shard corresponding to routing key key1, and fetches test/_doc/1 from the shard corresponding to routing key key2.

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

        curl -X GET "localhost:9200/_mget?routing=key1&pretty" -H 'Content-Type: application/json' -d'
        {
          "docs": [
            {
              "_index": "test",
              "_id": "1",
              "routing": "key2"
            },
            {
              "_index": "test",
              "_id": "2"
            }
          ]
        }'