大家好，我是烤鴨：

? ? 今天分享的是官網(wǎng)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" }

????? ?結(jié)果：

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

_shards?：? 表示接收數(shù)據(jù)的碎片。

?total ： 碎片總量（執(zhí)行當(dāng)前操作的）。

?failed :? ? 操作失敗的碎片數(shù)量。只要有一個成功，就認(rèn)為索引是操作成功的。

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

版本編輯

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

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

操作類型編輯

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

下面是使用op_type參數(shù)的示例：

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的情況下執(zhí)行索引操作。在這種情況下，ID將自動生成。此外，op_type?將被自動設(shè)置為create。下面是一個例子（注意使用POST而不是PUT）：

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

結(jié)果：

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

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

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

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

分布式

索引操作根據(jù)其路由指向主碎片（參見上面的路由部分），并在包含該碎片的實(shí)際節(jié)點(diǎn)上執(zhí)行。在主碎片完成操作之后，如果需要，則將更新分發(fā)給可應(yīng)用的副本。

等待active碎片

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

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

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

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

超時

當(dāng)執(zhí)行索引操作時，分配給執(zhí)行索引操作的主碎片可能不可用。一些原因可能是主碎片目前正在從網(wǎng)關(guān)恢復(fù)或進(jìn)行重新定位。默認(rèn)情況下，索引操作將等待主碎片1分鐘。timeout?參數(shù)可用于顯式指定它等待多長時間。下面是將其設(shè)置為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數(shù)據(jù):
????????GET twitter/_doc/0????? ? 結(jié)果：
????????{"_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"} }上述結(jié)果包括了我們希望檢索的文檔的_index,?_type,?_id和?_version，包括文檔的實(shí)際_source（如果在響應(yīng)中found字段標(biāo)示）。

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

源過濾器

默認(rèn)情況下，get操作返回_source字段的內(nèi)容，除非您已經(jīng)使用stored_fields?參數(shù)，或者如果禁用了_source??字段?？梢酝ㄟ^使用_source?參數(shù)來關(guān)閉_source檢索：?? ?

GET twitter/_doc/0?_source=false

如果您只需要完整的_source內(nèi)容中的一個或兩個字段，則可以使用_source_include＆_source_exclude?參數(shù)來包含或過濾掉所需的部分。這對于在大型文檔中檢索部分內(nèi)容，是非常有效的，因?yàn)榭梢怨?jié)省網(wǎng)絡(luò)開銷。兩個參數(shù)都采用逗號分隔的字段或通配符表達(dá)式列表。例如：

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

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

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

現(xiàn)在新增一個文檔：

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

嘗試去檢索剛才生成的：

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

結(jié)果：

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

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

還可以檢索元數(shù)據(jù)字段，如_routing?字段：

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

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

直接獲取_source

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

GET twitter/_doc/1/_source

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

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

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

HEAD twitter/_doc/1/_source

路由

當(dāng)使用索引控制路由時，為了獲得文檔，還應(yīng)提供路由值。例如：

GET twitter/_doc/2?routing=user1

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

preference （偏好）

哪個碎片副本來執(zhí)行GET請求的preference。默認(rèn)情況下，操作是在碎片副本之間隨機(jī)進(jìn)行的。
preference可以設(shè)置為：
_primary
操作將只在主碎片上執(zhí)行。
_local
如果可能的話，操作將更傾向于在本地分配的碎片上執(zhí)行。
Custom (string) value(自定義字符串值)
自定義值將用于保證相同的碎片將用于相同的自定義值。這可以在不同刷新狀態(tài)下?lián)糁胁煌槠瑫r

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

刷新
refresh?參數(shù)可以設(shè)置為true?，以便在GET操作之前刷新相關(guān)碎片并使其可搜索。將其設(shè)置為true?應(yīng)經(jīng)過仔細(xì)思考和驗(yàn)證，這不會導(dǎo)致系統(tǒng)上的高負(fù)載（而減慢索引）。

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

版本支持

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

更多關(guān)于elasticsearch 6.x內(nèi)容：

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

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

? ? 3.? ?elasticsearch 6.x (三) linux 集群多節(jié)點(diǎn)部署

總結(jié)

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

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。