大家好，我是烤鴨：

? ? 今天分享的是官網(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ù)量。只要有一個(gè)成功，就認(rèn)為索引是操作成功的。

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

版本編輯

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

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

操作類(lèi)型編輯

索引操作還接受一個(gè)op_type類(lèi)型，它可以用來(lái)強(qiáng)制create操作，允許“put-if-absent”的行為。當(dāng)使用create?時(shí)，如果索引中已經(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" }

另一種寫(xiě)法：

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

自動(dòng)生成ID

可以在不指定ID的情況下執(zhí)行索引操作。在這種情況下，ID將自動(dòng)生成。此外，op_type?將被自動(dòng)設(shè)置為create。下面是一個(gè)例子（注意使用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是通過(guò)使用文件ID值的散列來(lái)控制的。對(duì)于更明確的控制，可以使用路由參數(shù)在每個(gè)操作基礎(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è)置顯式映射時(shí)，可選地使用_routing?字段來(lái)指示索引操作以從文檔本身中提取路由值。這樣（使用路由的方式）確實(shí)使得額外的文檔解析傳遞的成本非常低。如果定義了_routing?映射并設(shè)置required，則如果沒(méi)有提供或提取路由值，則索引操作將失敗。

分布式

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

等待active碎片

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

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

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

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

超時(shí)

當(dāng)執(zhí)行索引操作時(shí)，分配給執(zhí)行索引操作的主碎片可能不可用。一些原因可能是主碎片目前正在從網(wǎng)關(guān)恢復(fù)或進(jìn)行重新定位。默認(rèn)情況下，索引操作將等待主碎片1分鐘。timeout?參數(shù)可用于顯式指定它等待多長(zhǎng)時(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請(qǐng)求獲取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í)時(shí)
默認(rèn)情況下，get API是實(shí)時(shí)的，并且不受索引刷新率的影響（當(dāng)數(shù)據(jù)將成為搜索可見(jiàn)時(shí)）。如果文檔已被更新，但尚未刷新，則get API將在本地發(fā)出刷新調(diào)用以使文檔可見(jiàn)。這也會(huì)使其他文檔在可見(jiàn)性上發(fā)生變化。為了禁用實(shí)時(shí)特性，可以將realtime參數(shù)設(shè)置為false。

源過(guò)濾器

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

GET twitter/_doc/0?_source=false

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

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

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

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

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

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字段未被存儲(chǔ)，所以GET請(qǐng)求在試圖獲取stored_fields時(shí)忽略它。

還可以檢索元數(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字段可以通過(guò)stored_field?選項(xiàng)返回。所以不能返回對(duì)象字段，這樣的請(qǐng)求就會(huì)失敗。

直接獲取_source

使用/{index}/{type}/{id}/_source端點(diǎn)來(lái)獲取文檔的_source字段，而不必在其周?chē)砑尤魏蝺?nèi)容。例如：

GET twitter/_doc/1/_source

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

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

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

HEAD twitter/_doc/1/_source

路由

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

GET twitter/_doc/2?routing=user1

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

preference （偏好）

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

使用?"jumping values"?。簡(jiǎn)單的示例值類(lèi)似于Web session ID或用戶名。

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

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

版本支持

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

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

? ?1.? ?elasticsearch 6.x 部署 windows入門(mén)(一) 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的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

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