大家好，我是烤鴨：

? ? 今天分享的是官網6.x? ? 單一文檔(Single document APIs)APIs。

? ? 本文這是部分翻譯，如果想看全部的，還是建議閱讀官方api。鏈接：

? ? ?https://www.elastic.co/guide/en/elasticsearch/reference/current/docs.html

1.? ? 索引(index)API??

????? ? 添加或更新：（json格式）

PUT twitter/_doc/1 {"user" : "kimchy","post_date" : "2009-11-15T14:12:12","message" : "trying out Elasticsearch" }

????? ?結果：

{"_shards" : {"total" : 2,"failed" : 0,"successful" : 2},"_index" : "twitter","_type" : "_doc","_id" : "1","_version" : 1,"_seq_no" : 0,"_primary_term" : 1,"result" : "created" }

_shards?：? 表示接收數據的碎片。

?total ： 碎片總量（執行當前操作的）。

?failed :? ? 操作失敗的碎片數量。只要有一個成功，就認為索引是操作成功的。

當索引操作成功返回時，副本碎片可能不會全部啟動（默認情況下，僅需要主元素，但此行為可以更改）。在這種情況下，總數將等于基于副本數量設置的總數碎片，并且成功將等于碎片開始數量（主加副本）。如果沒有失敗，失敗將是0。

版本編輯

每個索引文檔都有一個版本號。關聯的版本號作為對索引API請求的響應的一部分返回。在指定版本參數時，索引API可選地允許樂觀并發控制。這將控制將要執行的操作的文檔版本。版本控制用例的一個很好的例子是執行事務讀然后更新。從最初讀取的文檔中指定一個版本，確保其間沒有發生任何更改（當為了更新而閱讀時，建議將preference?設置為_primary）。例如：

PUT twitter/_doc/1?version=2 {"message" : "elasticsearch now has versioning support, double cool!" }

操作類型編輯

索引操作還接受一個op_type類型，它可以用來強制create操作，允許“put-if-absent”的行為。當使用create?時，如果索引中已經存在該ID的文檔，則索引操作將失敗。

下面是使用op_type參數的示例：

PUT twitter/_doc/1?op_type=create {"user" : "kimchy","post_date" : "2009-11-15T14:12:12","message" : "trying out Elasticsearch" }

另一種寫法：

PUT twitter/_doc/1/_create {"user" : "kimchy","post_date" : "2009-11-15T14:12:12","message" : "trying out Elasticsearch" }

自動生成ID

可以在不指定ID的情況下執行索引操作。在這種情況下，ID將自動生成。此外，op_type?將被自動設置為create。下面是一個例子（注意使用POST而不是PUT）：

POST twitter/_doc/ {"user" : "kimchy","post_date" : "2009-11-15T14:12:12","message" : "trying out Elasticsearch" }

結果：

{"_shards" : {"total" : 2,"failed" : 0,"successful" : 2},"_index" : "twitter","_type" : "_doc","_id" : "W0tpsmIBdwcYyG50zbta","_version" : 1,"_seq_no" : 0,"_primary_term" : 1,"result": "created" } 路由

默認情況下，碎片放置或routing是通過使用文件ID值的散列來控制的。對于更明確的控制，可以使用路由參數在每個操作基礎上直接指定饋送到路由器使用的散列函數的值。例如：

POST twitter/_doc?routing=kimchy {"user" : "kimchy","post_date" : "2009-11-15T14:12:12","message" : "trying out Elasticsearch" } 在上面的示例中，基于提供的“kimchy”路由參數，將“_doc”文檔指引到碎片。

當設置顯式映射時，可選地使用_routing?字段來指示索引操作以從文檔本身中提取路由值。這樣（使用路由的方式）確實使得額外的文檔解析傳遞的成本非常低。如果定義了_routing?映射并設置required，則如果沒有提供或提取路由值，則索引操作將失敗。

分布式

索引操作根據其路由指向主碎片（參見上面的路由部分），并在包含該碎片的實際節點上執行。在主碎片完成操作之后，如果需要，則將更新分發給可應用的副本。

等待active碎片

為了提高對系統的寫入的性能，索引操作可以被配置為，在進行操作之前，等待一定數量的活動碎片副本。如果所需的active碎片副本數不可用，則寫入操作必須等待并重試，直到所需碎片已開始或超時。默認情況下，寫入操作在執行之前只等待主碎片變成active（i.e.?wait_for_active_shards=1）。可以通過設置index.write.wait_for_active_shards來動態地在索引設置中修改此默認值。為了改變每種操作的行為，可以使用wait_for_active_shards請求參數。

有效值是全部或任何正整數，與索引中每個碎片的配置拷貝總數（number_of_replicas+1）。指定大于碎片副本數量的負值或數字將引發錯誤。 （翻譯注:?wait_for_active_shards 這個值不能是負的，也不能大于副本數量。)

例如，假設我們有一個三個節點的集群，A、B和C，并且我們創建一個索引index，其中副本的數量設置為3個（導致4個碎片副本，比節點多一個副本）。如果我們嘗試索引操作，默認情況下，操作將只確保每個碎片的主副本在執行之前可用。這意味著，即使B和C掛掉了，并且A托管主碎片副本，索引操作仍然只繼續執行，雖然只有一個數據副本。如果wait_for_active_shards?被設置在請求到3（并且所有3個節點都是可用的），那么索引在操作之前將需要3個active?碎片副本，需要滿足的要求是，由于在集群中有3個活動節點，每個都持有碎片的副本。但是，如果我們將wait_for_active_shards碎片設置為all（或4，一個意思），則索引操作不會繼續進行，因為在索引中的每個碎片的(副本)，所有4個副本不都是active。除非在集群中出現新節點來管理碎片的第四副本，否則操作將超時。
重要的是要注意，寫入操作有時不會把數據寫到足夠數量的碎片副本，這種設置大大降低了這種可能，但因為該檢查發生在寫入操作開始之前，也不能完全消除可能。一旦寫入操作正在進行，復制仍可能在任何碎片的其他副本上失敗，但在主副本上仍然成功。寫入操作響應的_shards部分表示了復制 成功/失敗 的碎片副本的數量。
{"_shards" : {"total" : 2,"failed" : 0,"successful" : 2} } NOOP????更新
當使用索引API更新文檔時，即使文檔沒有更改，也總是創建文檔的新版本。如果這是不可接受的，使用?_update?API時，將detect_noop設置為true。這個參數在索引API上是不可用的，因為索引API沒有獲取舊的源，并且無法將它與新的源進行比較。

當NOOP 更新不能使用時，沒有一個固定的原因。這是很多因素的組合，比如你的數據源發送多個更新是真的noops的頻率，es每秒在碎片上運行多少個查詢結果用于update數據。

超時

當執行索引操作時，分配給執行索引操作的主碎片可能不可用。一些原因可能是主碎片目前正在從網關恢復或進行重新定位。默認情況下，索引操作將等待主碎片1分鐘。timeout?參數可用于顯式指定它等待多長時間。下面是將其設置為5分鐘的示例：

PUT twitter/_doc/1?timeout=5m {"user" : "kimchy","post_date" : "2009-11-15T14:12:12","message" : "trying out Elasticsearch" }

2.?? ?獲取（GET）API?

? get請求獲取json數據:
????????GET twitter/_doc/0????? ? 結果：
????????{"_index" : "twitter","_type" : "_doc","_id" : "0","_version" : 1,"found": true,"_source" : {"user" : "kimchy","date" : "2009-11-15T14:12:12","likes": 0,"message" : "trying out Elasticsearch"} }上述結果包括了我們希望檢索的文檔的_index,?_type,?_id和?_version，包括文檔的實際_source（如果在響應中found字段標示）。

API還允許使用HEAD檢查文檔的存在，例如： HEAD twitter/_doc/0實時
默認情況下，get API是實時的，并且不受索引刷新率的影響（當數據將成為搜索可見時）。如果文檔已被更新，但尚未刷新，則get API將在本地發出刷新調用以使文檔可見。這也會使其他文檔在可見性上發生變化。為了禁用實時特性，可以將realtime參數設置為false。

源過濾器

默認情況下，get操作返回_source字段的內容，除非您已經使用stored_fields?參數，或者如果禁用了_source??字段。可以通過使用_source?參數來關閉_source檢索：?? ?

GET twitter/_doc/0?_source=false

如果您只需要完整的_source內容中的一個或兩個字段，則可以使用_source_include＆_source_exclude?參數來包含或過濾掉所需的部分。這對于在大型文檔中檢索部分內容，是非常有效的，因為可以節省網絡開銷。兩個參數都采用逗號分隔的字段或通配符表達式列表。例如：

GET twitter/_doc/0?_source_include=*.id&_source_exclude=entities

如果只想指定包含，則可以使用更短的符號：

GET twitter/_doc/0?_source=*.id,retweeted 存儲字段
get操作允許指定一個存儲字段的集合，這些字段將通過stored_fields?參數返回。如果所請求的字段未被存儲，它們將被忽略。例如，考慮下面的映射： PUT twitter {"mappings": {"_doc": {"properties": {"counter": {"type": "integer","store": false},"tags": {"type": "keyword","store": true}}}} }

現在新增一個文檔：

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

嘗試去檢索剛才生成的：

GET twitter/_doc/1?stored_fields=tags,counter

結果：

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

從文檔本身獲取的字段值總是作為數組返回。由于counter字段未被存儲，所以GET請求在試圖獲取stored_fields時忽略它。

還可以檢索元數據字段，如_routing?字段：

PUT twitter/_doc/2?routing=user1 {"counter" : 1,"tags" : ["white"] } 或者： GET twitter/_doc/2?routing=user1&stored_fields=tags,counter 結果：
{"_index": "twitter","_type": "_doc","_id": "2","_version": 1,"_routing": "user1","found": true,"fields": {"tags": ["white"]} }

此外，只有leaf字段可以通過stored_field?選項返回。所以不能返回對象字段，這樣的請求就會失敗。

直接獲取_source

使用/{index}/{type}/{id}/_source端點來獲取文檔的_source字段，而不必在其周圍添加任何內容。例如：

GET twitter/_doc/1/_source

還可以使用相同的source filtering參數來控制將返回的_source?的哪些部分：

GET twitter/_doc/1/_source?_source_include=*.id&_source_exclude=entities'

注意，還存在一個用于_source?端點的HEAD?變量，以有效地測試文檔源的存在。如果在映射中被禁用，則現有文檔將不具有源。

HEAD twitter/_doc/1/_source

路由

當使用索引控制路由時，為了獲得文檔，還應提供路由值。例如：

GET twitter/_doc/2?routing=user1

以上將得到id是2的twitter，但會基于用戶路由。注意，發出一個沒有正確路由的get請求導致文檔不你能獲取。

preference （偏好）

哪個碎片副本來執行GET請求的preference。默認情況下，操作是在碎片副本之間隨機進行的。
preference可以設置為：
_primary
操作將只在主碎片上執行。
_local
如果可能的話，操作將更傾向于在本地分配的碎片上執行。
Custom (string) value(自定義字符串值)
自定義值將用于保證相同的碎片將用于相同的自定義值。這可以在不同刷新狀態下擊中不同碎片時

使用?"jumping values"?。簡單的示例值類似于Web session ID或用戶名。

刷新
refresh?參數可以設置為true?，以便在GET操作之前刷新相關碎片并使其可搜索。將其設置為true?應經過仔細思考和驗證，這不會導致系統上的高負載（而減慢索引）。

分布式
get操作被hash成一個特定的碎片ID。它被重定向到該碎片ID中的一個副本，并返回結果。在該碎片ID組中副本就是的主碎片及其副本。這意味著我們將擁有更多的副本，我們將有更大的范圍。

版本支持

只有當當前版本等于指定的版本時，才可以使用version?參數檢索文檔。這種行為對于所有版本類型都是相同的，除了版本類型為FORCE?，FORCE?一直在檢索文檔。請注意，FORCE版本類型被棄用。
在內部，es 已經標記舊文檔被刪除，并添加了一個全新的文檔。舊版本的文檔不會立即消失，盡管你不能訪問它。當繼續給更多數據添加索引時，es會在后臺清除已刪除的文檔。

更多關于elasticsearch 6.x內容：

? ?1.? ?elasticsearch 6.x 部署 windows入門(一) spingboot連接

? ? 2.???elasticsearch 6.x linux部署(二) kibana x-pack 安裝

? ? 3.? ?elasticsearch 6.x (三) linux 集群多節點部署

總結

以上是生活随笔為你收集整理的elasticsearch 6.x (四) 单一文档 API 介绍和使用 index和get API的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。