Get API · Elasticsearch 5.4 中文文档

# Get API 原文链接 :[https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-get.html](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-get.html) 译文链接 :[Get API](/display/Elasticsearch/Get+API) 贡献者 : [风轻云淡](/display/~wujian) **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 控制共享的副本去执行get请求的优先权。默认情况下，是在共享的副本中随机操作的。 `preference` 可以设置为： _primary 操作会在主要的共享副本执行。 _local 操作会优先在本地的共享副本执行 Custom(String)value 自定义值会被用来保证相同的共享副本使用相同的自定义值。这个帮助 "jumping values" 当不同的共享副本在不同的refresh states。这个值类似于web session id或者user name。 ## Refresh refresh 参数可以设置为true，为了使其能在get操作和使其可检索前刷新相关的共享副本。将其设置为true应该要谨慎，应为这将导致系统资源负载增大（也会减慢索引的创建）。 ## Distributed get操作会从一个指定的副本id得到散列值。然后会重定向到那个shard id的其中一个副本上并返回结果。副本是primary shard而且他的副本是在同一个shard id 组。这意味着副本数越多，GET的性能越好。 ## Versioning support 你可以使用 version 参数去检索 **document**，只有在当前的 version 和你指定的version 相同的情况下。这个特性同样适用于所有的 version types,当我们希望要检索的 **document **的version与我们指定的version相同。在内部，**Elasticsearch** 已经标记了已经删除的旧的 **document** 并且增加了新的 **document**。旧版本的 **document **不会马上出现，并且你也不能访问。**Elasticsearch** 会在后台清理已经删除的**document **以便可以索引更多的数据。