ElasticSearch 6.3版本 Document APIs之Index API(索引API)

Index API(索引API) 在特定索引中添加或更新類型化的JSON文檔，使其可搜尋。e.g.将JSON文檔插入到“twitter”索引中，名為“_doc"且ID為1的類型下： PUT twitter/_doc/1 { "user":"kimchy", "post_date":"2009-11-15T14:12:12", "message":"trying out Elasticsearch" } 操作結果如下： { “_ shards”：{ “total”：2， “failed”：0，“success”： 2 }， “_ index” ：“twitter”，“_ type”：“_ doc”， “ _ id ”：“1”， “ _version“：1， ”_ seq_no“：0， ”_ primary_term“：1， ”result“：”created“ } 其中，_shards報頭提供關于索引操作的複制過程資訊：

• total - 訓示應執行索引操作的分片副本（主分片和副本分片）的數量；
• successful - 表示索引操作成功的分片副本數；
• failed - 在副本分片上索引操作失敗的情況下包含複制相關錯誤的數組。

索引操作成功的情況successful至少為1。

索引操作成功傳回時，可能無法全部啟動副本分片（預設情況下，隻需要主分區，但可以更改此行為）。在這種情況下， total 将等于基于number_of_replicas設定的總分片successful 數，并且将等于已啟動的分片數（主要副本和副本）。如果沒有失敗，則為failed 0。

自動建立索引 之前未建立索引，則索引操作會自動建立索引，并自動為特定類型建立動态類型映射。

可以通過在所有節點的配置檔案中設定action.auto_create_index 禁用自動建立，通過将per-index設定index.mapper.dynamic為false索引設定可禁用自動映射建立。

自動索引建立可包括基于模式的白/黑清單，如設定action.auto_create_index為+aaa*，-bbb*，+ccc*，-*（+表示允許，-表示不允許）。

版本控制 每個索引文檔都有一個版本号version，索引API允許在指定參數時進行樂觀并發控制version。e.g. PUT twitter/_doc/1?version=2 { "message":"elasticsearch now has versioning support , double cool !" } 注：版本控制是完全實時的，并且不受搜尋操作的近實時方面的影響。如果未提供版本，則執行該操作而不進行任何版本檢查。

預設情況下，使用從1開始的内部版本控制，并随每次更新而增加，包括删除。版本号也可以用外部值進行補充（如在資料庫中維護）。要啟用此功能，version_type設為external。提供的值必須是數字長度大于或等于0，小于約9.2e+18。使用外部版本類型時，系統會檢查傳遞給索引請求的版本号是否大于目前存儲文檔的版本，而不是檢查比對的版本号。如果為true，則将索引文檔并使用新版本号；若提供的值小于或等于存儲文檔版本号，則發生版本沖突，索引操作失敗。

WARNING：外部版本控制支援值0作為有效版本号。這允許版本與外部版本控制系統同步，其中版本号從零而不是一開始。它具有副作用，版本号等于零的文檔既不能使用Update-By-Query API更新，也不能使用Delete By Query API删除，隻要它們的版本号等于零即可。

一個好的副作用是，隻要使用源資料庫中的版本号，就不需要維護由于源資料庫更改而執行的異步索引操作的嚴格排序。如果使用外部版本控制，即使使用資料庫中的資料更新Elasticsearch索引的簡單情況也會簡化，因為如果索引操作由于某種原因而無序，則僅使用最新版本。

版本類型 不同版本類型及其語義概述： internal：若給定的版本與存儲文檔版本相同，則僅索引文檔。

external or external_gt：若給定版本嚴格高于存儲文檔版本或沒有現有文檔，則僅索引文檔。給定版本用作新版本，并與新文檔一起存儲，提供的版本必須是非負長号。

external_gte：僅在給定版本等于或高于存儲文檔的版本時索引文檔。若沒有現有文檔，操作也将成功。給定版本将用作新版本，并将與新文檔一起存儲。提供版本必須是非負長号。

注：external_gte版本類型适用于特殊用例，使用不當會導緻資料丢失。還有另一個選項，force已被棄用，因為它可能導緻主分片和副本分片發散。

操作類型 索引操作還接受op_type可用于強制create操作的操作，允許“put-if-absent"行為。當create使用時，如果該ID在文檔中的索引已經存在，索引操作将失敗。e.g. PUT twitter/_doc/1?op_type=create { "user" : "kimchy", "post_date" : "2009-11-15T14:12:12", "message" : "trying out Elasticsearch" } 另一個指定選項create是使用以下URI：（此方法在ES6.3版本中不适用，官方文檔暫時未修正18.7.9） PUT twitter/_doc/1/_create { "user" : "kimchy", "post_date" : "2009-11-15T14:12:12", "message" : "trying out Elasticsearch" }

自動ID生成 不指定id情況下執行索引操作，将自動生成id。op_type将自動設定為create。e.g.(注意使用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值的散列進行控制。更明确的控制通過使用routing參數在每個操作基礎上指定輸入到路由器使用的散列函數的值。e.g. POST twitter/_doc?routing=kimchy { "user" : "kimchy", "post_date" : "2009-11-15T14:12:12", "message" : "trying out Elasticsearch" } 上述示例中，“_doc”文檔根據提供的routing參數路由到分片：“kimchy”

設定顯示映射時，_routing可選擇使用該字段訓示索引操作從文檔本身提取路由值。若_routing映射已定義并設定為required，則若未提供或提取路由值，則索引操作将失敗。

Noop更新編輯 使用索引api更新文檔時，即使文檔未更改，也始終會建立新版本的文檔。如果這是不可接受的，請使用設定為true 的_updateapi detect_noop。索引api上沒有此選項，因為索引api不會擷取舊源，也無法将其與新源進行比較。

關于何時不接受noop更新，沒有一條硬性規定。它是許多因素的組合，例如您的資料源發送實際noops更新的頻率以及Elasticsearch在接收更新時在分片上運作的每秒查詢數。

逾時編輯 執行索引操作時，配置設定用于執行索引操作的主分片可能不可用。造成這種情況的一些原因可能是主分片目前正在從網關恢複或正在進行重定位。預設情況下，索引操作将在主分片上等待最多1分鐘，然後失敗并響應錯誤。該timeout參數可用于顯式指定等待的時間。以下是将其設定為5分鐘的示例： PUT twitter/_doc/1?timeout=5m { "user" : "kimchy", "post_date" : "2009-11-15T14:12:12", "message" : "trying out Elasticsearch" }