1. Get API

原文链接 :https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-get.html

译文链接 :Get 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'

1.1. Realtime

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

1.2. Option Type

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

1.3. 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'

1.4. 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字段无法返回并且这个请求会失败

1.5. Generated fields

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

1.6. 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'

1.7. Routing

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

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

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

1.8. Preference

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

preference 可以设置为：

_primary

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

_local

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

Custom(String)value

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

1.9. Refresh

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

1.10. Distributed

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

1.11. Versioning support

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

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

Get API