> For the complete documentation index, see [llms.txt](https://xiaoxiami.gitbook.io/elasticsearch/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://xiaoxiami.gitbook.io/elasticsearch/ji-chu/33-apis/342wen-dang-apis-document-apis/huo-53d6-pi-liang-huo-53d6-3e-wen-dang.md).

# 获取/批量获取->文档

## Get API 获取文档API

**get api**允许从一个基于其id的 **index**中获取一个 JSON格式的**document**，下面的示例是从一个在名称为tweet的 **type** 下的id为1，名称为twitter的 **index** 中获取一个JSON格式的 **document**。

```
curl -XGET 'http://localhost:9200/twitter/tweet/1'
```

以上 get 操作的结果如下

```
{
    "_index" : "twitter",
    "_type" : "tweet",
    "_id" : "1",
    "_version" : 1,
    "found": true,
    "_source" : {
        "user" : "kimchy",
        "postDate" : "2009-11-15T14:12:12",
        "message" : "trying out Elasticsearch"
    }
}
```

以上结果包括 **document** 的 \_index，\_type，\_id以及\_version等我们想要检索的，包括实际的 \_source 如果它可以被发现（相应结果中的found字段）

API还可以检查**document**是否使用 HEAD，例如：

```
curl -XHEAD -i 'http://localhost:9200/twitter/tweet/1'
```

### Realtime

默认情况下，get API 是实时的，而且它不受**index**刷新频率的影响（当数据对search操作可见）。如果**document**已经修改完但没还有刷新，get API将会执行 in-place刷新操作使得**document**可见。这也会导致其他**docuemnt**发生改变。若要禁止 GET的实时操作，可以设置 **realtime**参数为false。

### Option Type

get API允许`_type 作为可选参数，设置它为_all可以从所有的匹配的type中获取第一个docuemnt。`

### Source filtering

默认情况下，get 操作返回 \_source字段的内容，除非你使用stored\_fields参数或\_source字段是禁止的。你可以使用\_source参数来关闭\_source检索。

```
curl -XGET 'http://localhost:9200/twitter/tweet/1?_source=false'
```

如果你只需要从完整的 \_source中获取一个或两个字段，你可以使用\_source\_include&`_source_exclude`参数用来包含或过滤其他部分。这个功能很有用在大文件 **document** 部分检索的时候可以节省网络开销。所有的参数可以用普通的分隔符连接或者通配符表达式。示例如下：

```
curl -XGET 'http://localhost:9200/twitter/tweet/1?_source_include=*.id&_source_exclude=entities'
```

如果你只是想要指定包含的，你可以使用比较剪短的表达式：

```
curl -XGET 'http://localhost:9200/twitter/tweet/1?_source=*.id,retweeted'
```

### Stored Fields

get 操作允许指定一系列的stored 字段，这些字段将会被返回通过传递stored\_fields参数。如果请求的字段没有被储存，将会被忽略。参考以下示例：

```
PUT twitter
{
   "mappings": {
      "tweet": {
         "properties": {
            "counter": {
               "type": "integer",
               "store": false
            },
            "tags": {
               "type": "keyword",
               "store": true
            }
         }
      }
   }
}
```

现在我们可以添加 document：

```
PUT twitter/tweet/1
{
    "counter" : 1,
    "tags" : ["red"]
}
```

1.尝试去检索：

```
GET twitter/tweet/1?stored_fields=tags,counter
```

以上get操作的结果是：

```
{
   "_index": "twitter",
   "_type": "tweet",
   "_id": "1",
   "_version": 1,
   "found": true,
   "fields": {
      "tags": [
         "red"
      ]
   }
}
```

从 **document**中获取的字段的值通常是array。由于counter字段没有存储，当尝试获取stored\_fields时get会将其忽略。

可以对元数据字段进行检索，比如\_routing和\_parent：

```
PUT twitter/tweet/2?routing=user1
{
    "counter" : 1,
    "tags" : ["white"]
}

GET twitter/tweet/2?routing=user1&stored_fields=tags,counter
```

以上get操作的结果是：

```
{
   "_index": "twitter",
   "_type": "tweet",
   "_id": "2",
   "_version": 1,
   "_routing": "user1",
   "found": true,
   "fields": {
      "tags": [
         "white"
      ]
   }
}
```

只有leaf的字段可以通过stored\_field选项返回。所以object字段无法返回并且这个请求会失败

### Generated fields

如果在索引和刷新过程中没有发生刷新操作，GET会访问transaction日志来获取 **document**。然而，一些字段只会在索引时创建。如果你尝试访问那些只有在创建索引时才会创建的字段，默认情况下会得到一个异常。你可以通过设置 **ignore\_errors\_on\_generated\_fields=true** 来忽略那些字段。

### Getting the \_source directly

使用/{index}/{type}/{id}/\_source 可以只获取 **document** 的\_source字段，不会有其他多余的内容，例如：

```
curl -XGET 'http://localhost:9200/twitter/tweet/1/_source'
```

你也可以使用过滤参数来控制\_source的哪些部分可以被返回：

```
curl -XGET 'http://localhost:9200/twitter/tweet/1/_source?_source_include=*.id&_source_exclude=entities'
```

注意，同样有一个HEAD变量来检测document \_source 是否存在。一个存在的 **document**不会有\_source，如果它在 **mapping** 里被禁止，例如：

```
curl -XHEAD -i 'http://localhost:9200/twitter/tweet/1/_source'
```

### Routing

当创建索引时想要控制路由，为了获取 **document**，routing 的值也因该提供，例如：

```
curl -XGET 'http://localhost:9200/twitter/tweet/1?routing=kimchy'
```

以上的操作会获取id为1的tweet，但是是基于用户被路由的。注意，如果没有设置正确的路由，将会导致 **document** 无法被获取。

## Preference <a href="#getapi-preference" id="getapi-preference"></a>

控制共享的副本去执行get请求的优先权。默认情况下，是在共享的副本中随机操作的。

`preference` 可以设置为：

**\_primary**

```
操作会在主要的共享副本执行。
```

**\_local**

操作会优先在本地的共享副本执行

**Custom(String)value**

自定义值会被用来保证相同的共享副本使用相同的自定义值。这个帮助 "jumping values" 当不同的共享副本在不同的refresh states。这个值类似于web session id或者user name。

## Refresh <a href="#getapi-refresh" id="getapi-refresh"></a>

refresh 参数可以设置为true，为了使其能在get操作和使其可检索前刷新相关的共享副本。将其设置为true应该要谨慎，应为这将导 致系统资源负载增大（也会减慢索引的创建）。

## Distributed <a href="#getapi-distributed" id="getapi-distributed"></a>

get操作会从一个指定的副本id得到散列值。然后会重定向到那个shard id的其中一个副本上并返回结果。副本是primary shard而且他的副本是在同一个shard id 组。这意味着副本数越多，GET的性能越好。

## Versioning support <a href="#getapi-versioningsupport" id="getapi-versioningsupport"></a>

你可以使用 version 参数去检索**document**，只有在当前的 version 和你指定的version 相同的情况下。这个特性同样适用于所有的 version types,当我们希望要检索的 **document** 的version与我们指定的version相同。

在内部，**Elasticsearch**已经标记了已经删除的旧的 **document**并且增加了新的 **document**。旧版本的 **document** 不会马上出现，并且你也不能访问。**Elasticsearch**会在后台清理已经删除的**document** 以便可以索引更多的数据。

## Multi Get API 批量获取文档API

多 GET API 允许基于索引，类型（可选）和ID（也可能路由）获取多个文档。响应包括获取的 `docs` 列表，每个文件的结构都类似于 GET API 提供文件的结构。下面是一个例子：

```
curl 'localhost:9200/_mget' -d '{
    "docs" : [
        {
            "_index" : "test",
            "_type" : "type",
            "_id" : "1"
        },
        {
            "_index" : "test",
            "_type" : "type",
            "_id" : "2"
        }
    ]
}'
```

`mget`也可以针对一个索引（在 body 体中不需要）：

```
curl 'localhost:9200/test/_mget' -d '{
    "docs" : [
        {
            "_type" : "type",
            "_id" : "1"
        },
        {
            "_type" : "type",
            "_id" : "2"
        }
    ]
}'
```

类型如下：

```
curl 'localhost:9200/test/type/_mget' -d '{
    "docs" : [
        {
            "_id" : "1"
        },
        {
            "_id" : "2"
        }
    ]
}'
```

在这种情况下，id 可以被用作发起简单的请求：

```
curl 'localhost:9200/test/type/_mget' -d '{
    "ids" : ["1", "2"]
}'
```

### 可选类型

该 MGET API 允许`_type`是可选的。将其设置为 `_all 或`空，以获取第一个文档匹配所有类型的ID。

如果不设置类型，许多文件共享相同的 `_id`，你最终将只得到第一个匹配的文件。

例如，如果你有文件1包含 typeA 和 typeB ，那么下面的请求会给你同一个文档两次：

```
curl 'localhost:9200/test/_mget' -d '{
    "ids" : ["1", "1"]
}'
```

你需要在这种情况下，明确设置`_type`：

```
GET /test/_mget/
{
  "docs" : [
        {
            "_type":"typeA",
            "_id" : "1"
        },
        {
            "_type":"typeB",
            "_id" : "1"
        }
    ]
}
```

### Source filtering

默认情况下，`_source`将为每个文档返回（如果储存）。类似于 GET API，你可以检索的只是部分 `_source`使用的 `_source`参数。您还可以使用URL参数 `_source`，`_source_include`及`_source_exclude 来指定`默认值。例如：

```
curl 'localhost:9200/_mget' -d '{
    "docs" : [
        {
            "_index" : "test",
            "_type" : "type",
            "_id" : "1",
            "_source" : false
        },
        {
            "_index" : "test",
            "_type" : "type",
            "_id" : "2",
            "_source" : ["field3", "field4"]
        },
        {
            "_index" : "test",
            "_type" : "type",
            "_id" : "3",
            "_source" : {
                "include": ["user"],
                "exclude": ["user.location"]
            }
        }
    ]
}'
```

### Fields

通过每个文档来可以指定具体存储字段，类似于 Get API 中 stored\_fields 参数。例如：

```
curl 'localhost:9200/_mget' -d '{
    "docs" : [
        {
            "_index" : "test",
            "_type" : "type",
            "_id" : "1",
            "stored_fields" : ["field1", "field2"]
        },
        {
            "_index" : "test",
            "_type" : "type",
            "_id" : "2",
            "stored_fields" : ["field3", "field4"]
        }
    ]
}'
```

或者，可以指定 `stored_fields`作为默认值被应用到所有文件中来查询字符串参数。

```
curl 'localhost:9200/test/type/_mget?stored_fields=field1,field2' -d '{
    "docs" : [
        {
            "_id" : "1"  # 1
        },
        {
            "_id" : "2",
            "stored_fields" : ["field3", "field4"] # ２
        }
    ]
}'
```

| 1 | 返回 `field1`和 `field2` |
| - | --------------------- |
| 2 | 返回 `field3`和 `field4` |

### Generated fields

见 “[Generated fields](https://www.elastic.co/guide/en/elasticsearch/reference/5.2/docs-get.html#generated-fields)”

### Routing

您也可以指定 routing 作为参数：

```
curl 'localhost:9200/_mget?routing=key1' -d '{
    "docs" : [
        {
            "_index" : "test",
            "_type" : "type",
            "_id" : "1",
            "_routing" : "key2"
        },
        {
            "_index" : "test",
            "_type" : "type",
            "_id" : "2"
        }
    ]
}'
```

在这个例子中，文件 `test/type/2`将从对应于 routing ＝ `key1 的分片中获取。`但文件 `test/type/1`将被从对应于 routing ＝ `key1 的分片中获取。`

### 安全

见 [*URL-based access control*](https://www.elastic.co/guide/en/elasticsearch/reference/5.2/url-access-control.html)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://xiaoxiami.gitbook.io/elasticsearch/ji-chu/33-apis/342wen-dang-apis-document-apis/huo-53d6-pi-liang-huo-53d6-3e-wen-dang.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.