索引接口 · my-elasticsearch-cn

# 索引API `Index API`通過往指定的索引庫輸入一個JSON文檔來添加或更新索引，讓文檔變得可搜索。以下示例將JSON文檔插入到叫 “twitter” 的索引庫中，ID 為`1`: ``` PUT twitter/tweet/1 { "user" : "kimchy", "post_date" : "2009-11-15T14:12:12", "message" : "trying out Elasticsearch" } ``` 上面的索引操作結果如下： ``` { "_shards" : { "total" : 2, "failed" : 0, "successful" : 2 }, "_index" : "twitter", "_type" : "tweet", "_id" : "1", "_version" : 1, "created" : true, "result" : created } ``` `_shards` 頭提供了有關索引操作的復制過程的信息。 ``` * `total` —— 標識有多少個分片拷貝被執行創建索引操作（包括主分片與副本分片）。 * `successful` —— 標識有多少個分片執行創建索引操作成功。 * `failed` —— 在存在失敗的情況下會返回一個操作失敗的分片數組列表。 ``` 在`successful`至少為`1`的情況下創建索引文檔操作才會成功。 > 注意 > > 當創建索引操作成功時，副本的分片有可能還沒開始做（默認情況下，只有主分片才是必須的，但是這個行為是可以[修改](#index-wait-for-active-shards)）。在這個場景中，`total`將等于基于`number_of_replicas`設置的所有分片數，`successful`將會等于已成功的分片數（主分片+副本分片）。如果沒有失敗的分片，`failed`將會為`0`。 ## 自動創建索引庫如果創建索引文檔時索引庫不存在，這會自動創建索引庫（參見手動[創建索引庫](../Indices_APIs/Create_Index.md)API），并且會根據動態類型`mapping`來創建索引庫的`type`（參見手動[添加映射](../Indices_APIs/Put_Mapping.md)API）。 `mapping`本身是非常靈活與格式自由的。新的字段或者是對象將會被自動添加到指定類型的`mapping`定義中。查看[映射](../Indices_APIs/Get_Mapping.md)部分以獲取有關映射定義的更多信息。可以通過在所有節點的配置文件中將`action.auto_create_index`設置為`false`來禁用自動創建索引庫。可以通過將`index.mapper.dynamic`設置為`false`作為索引設置來禁用自動映射創建。自動創建所以庫可以基于一定規則的黑白名單列表，例如，設置`action.auto_create_index` 為 `+aaa*,-bbb*,+ccc*,-*` （ `+`表示允許，`-`表示不允許）。 ## 版本控制每一個被索引的文檔都會給他一個版本號。分配的`version`編號會作為創建索引文檔返回結果的一部分。當版本號指定的時候，index API允許[樂觀并發控制](http://en.wikipedia.org/wiki/Optimistic_concurrency_control)。這將故意控制文檔的版本。一個好的版本控制用戶案例是執行事務`讀然后修改`。在指定`version`開始讀取文檔時，同時確保文檔不發生變化（讀操作在修改操作之后時，推薦設置`perference`為`_primary`）。例如： ``` PUT twitter/tweet/1?version=2 { "message" : "elasticsearch now has versioning support, double cool!" } ``` **注意**：版本控制是實時的，不受近實時查詢操作的影響。如果沒提供版本信息，這個操作的執行將不受到任何版本的檢查。默認情況下，內部版本號從1開始，并且根據每一次的更新、刪除操作來遞增。可選的是，版本號支持使用外部值（譬如在數據庫維護）。要開啟此功能，`version_type`需要被設置為`external`。提供的值必須是數字、長整型類型，且大于等于0小于9.2e+18。在使用外部版本控制時，系統檢查請求中傳遞文檔的版本號是否大于當前文檔的版本號，如果小于等于當前存儲的文檔版本號會有版本沖突，則會在創建索引文檔時返回失敗。 > 警告 > > 外部版本控制支持0是一個有效的版本號。它允許文檔的版本在與外部版本控制系統同步時從0開始，而不是1。它的副作用是在版本號為0的文檔不能使用[Update-By-Query API](Update_By_Query_API.md)更新以及不能使用[Delete-By-Query API](Delete_By_Query_API.md)刪除。一個好的作用是，只要使用源數據庫生成的版本號，在執行異步創建文檔索引時不需要維護嚴格順序。一個簡單的場景是，使用數據庫數據更新elasticsearch的索引，因為只有最新版本的數據將被使用，不管index操作是否出于什么原因執行亂序了。 ### 版本控制類型上面介紹過了`internal`與`external`，Elasticsearch在特殊的場景中還支持其它的類型。這是不同版本控制類型的概述. `internal` ``` 只能夠在指定的版本與存儲文檔的版本完全一致時創建文檔索引。 ``` `external`或`external_gt` ``` 如果給定版本嚴格高于存儲的文檔的版本或如果沒有現有文檔，則僅索引文檔。給定版本將用作新版本，并與新文檔一起存儲。提供的版本必須是非負長數字。 ``` `external_gte` ``` 如果給定版本高于或等于存儲的文檔的版本或如果沒有現有文檔，則僅索引文檔。給定版本將用作新版本，并與新文檔一起存儲。提供的版本必須是非負長數字。 ``` **注意：**`external_gte`版本類型適用于特殊場景，應謹慎使用。如果使用不正確，可能會導致數據丟失。還有一個選項，`force`已被被棄用，因為它可能導致主分片和副本分片出現不一致。 ## 操作類型 index操作還可以接受一個`op_type`參數來強制執行`create`操作，允許`put-if-absent`行為。在使用`create`創建文檔索引時，如果文檔已存在則會失敗。這是使用`op_type`參數的示例： ``` PUT twitter/tweet/1?op_type=create { "user" : "kimchy", "post_date" : "2009-11-15T14:12:12", "message" : "trying out Elasticsearch" } ``` 還有種通過uri指定`create`的方式 ``` PUT twitter/tweet/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/tweet/ { "user" : "kimchy", "post_date" : "2009-11-15T14:12:12", "message" : "trying out Elasticsearch" } ``` 操作將返回： ``` { "_shards" : { "total" : 2, "failed" : 0, "successful" : 2 }, "_index" : "twitter", "_type" : "tweet", "_id" : "6a8ca01c-7896-48e9-81cc-9f70661fcb32", "_version" : 1, "created" : true, "result": "created" } ``` ## 路由默認情況下，分片的位置——或路由（routing）——通過使用文檔的`id`值的哈希值來控制。對于更明確的控制，基于每個操作直接使用路由參數指定反饋給路由使用的散列函數的值。例如： ``` POST twitter/tweet?routing=kimchy { "user" : "kimchy", "post_date" : "2009-11-15T14:12:12", "message" : "trying out Elasticsearch" } ``` 在上面的示例中，"tweet" 文檔根據提供的路由參數發送到分片："kimchy" 。設置顯式映射時，可以選擇從文檔本身提取路由字段值`_routing`字段來指示索引操作。這在文檔解析花費額外的（非常小）成本。如果定義`_routing`映射并將其設置為必需，則如果未提供或提取不到路由值，則索引操作將失敗。 ## 分布式 index操作會根據路由信息（參見上面的路由章節）定向到主分片，并在主分片所在的實際節點上執行。在主分片操作完成后，如果有需要，會分布更新到可用的副本上。 ## 等待活動分片為了提高寫入系統的彈性，index操作可以配置為在繼續操作之前等待一定數量的活動分片副本。如果所需的活動分片副本數不可用，則寫操作必須等待并重試，直到必需的分片副本已啟動或發生超時為止。默認情況下，寫操作只等待主分片處于活動狀態，然后再繼續（`wait_for_active_shards=1`）。可以通過設置 `index.write.wait_for_active_shards` 來動態地在索引設置中覆蓋此默認值。要更改每個操作的此行為，可以使用 `wait_for_active_shards` 請求參數。有效值是不大于索引庫的所有分片總數的正整數（即`number_of_replicas+1`）。指定負值或者大于分片總數的數字將拋出錯誤。例如，假設我們有一個三個節點`A`、`B`和`C`的集群，我們創建一個索引，索引副本數設置為 `3` （會導致有`4`個分片，主分片加3個副本分片）。如果我們嘗試索引操作，默認情況下，操作將僅確保每個主分片在繼續之前可用。這意味著，在`A`托管主分片時，即使`B`和`C`停機，索引操作仍然將繼續，只會有一份數據保存。如果集群有3個活動節點啟動，這時每個節點都有一個分片的復制，這時對請求設置 `wait_for_active_shards` 為 `3` （并且所有3個節點都已啟動），則索引操作將在繼續之前需要 `3` 個活動分片，這是可以執行的。但如果我們將 `wait_for_active_shards` 設置為 `all` （或者 `4`，這是相同的），索引操作將不會繼續，因為索引中的沒有所有的4個分片處于活動狀態。該操作將超時，除非在集群中啟動新節點以托管分片的第四個副本。重要的是要注意，這個設置極大地減少了寫操作不寫入所需數量的分片副本的機會，但是它不能完全消除可能性，因為這種檢查在寫操作開始之前發生。一旦寫操作正在進行，復制仍然可能在任意數量的分片副本上失敗，但在主分片上仍然成功。寫操作響應的 `_shard` 部分顯示復制成功/失敗的分片副本的數量。 ``` { "_shards" : { "total" : 2, "failed" : 0, "successful" : 2 } } ``` ## 沖刷用來控制本次的修改能夠被搜索可見。參見：[refresh](refresh.html)。 ## Noop Updates 當使用index API更新文檔時，即使文檔沒有更改，也始終創建新版本的文檔。如果這不可接受，請使用將 `detect_noop` 設置為 `true` 的`_update` API 。此選項在index API上不可用，因為index api不提取舊源，并且無法將其與新源進行比較。沒有一個強制和快速的規則，當等待更新是不能接受的。它是許多因素的組合，例如數據源發送實際上是 noops 的更新的頻率，以及每秒多少查詢，elasticsearch 在接收更新時在分片上運行。 ## 超時執行索引操作時分配的主分片可能不可用。這種情況的一些原因可能是主分片當前正在從網關恢復或正在進行重分配。默認情況下，索引操作將在主分片上等待最多`1`分鐘，然后失敗并響應錯誤。 `timeout`參數可以用于顯式指定等待時間。以下是將其設置為`5`分鐘的示例： ``` PUT twitter/tweet/1?timeout=5m { "user" : "kimchy", "post_date" : "2009-11-15T14:12:12", "message" : "trying out Elasticsearch" } ``` > my note > > 樂觀并發控制 > 版本控制類型 version_type > elasticsearch 路由 > 操作類型 (兩種方式) > 等待活動分片 > Noop Updates