Index API · Elasticsearch 5.4 中文文檔

# Index API 原文鏈接 : [https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html) 譯文鏈接 : [http://www.apache.wiki/display/Elasticsearch/Index+API](http://www.apache.wiki/display/Elasticsearch/Index+API) 貢獻者 : [小瑤](/display/~chenyao)，[ApacheCN](/display/~apachecn)，[Apache中文網](/display/~apachechina) 索引 **API** 在特定索引中 **add** ( 添加?) 或 **update?**( 更新?) **a typed JSON document** ( 類型化的?**JSON**?文檔?)，使其可搜索。以下示例將 **JSON** 文檔插入到 **“twitter”** 索引中，**ID** 為**1** ： ``` curl -XPUT 'localhost:9200/twitter/tweet/1?pretty' -H 'Content-Type: application/json' -d' { "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 header** 提供有關索引操作的復制過程的信息。 * **total** - 指示應對多少 **shard copies?**( 分片副本?)（ **primary** ( 主?)分片和 **replica** ( 副本?) 分片）執行索引操作。 * **successful** - 表示索引操作成功的分片副本的數量。 * **failed** - 在索引操作在副本碎片上失敗的情況下包含與復制相關的錯誤的數組。在 **successful** 至少為 **1** 的情況下索引操作成功。注意當索引操作 **successful** 返回時，可能不會全部啟動副本碎片（默認情況下，只需要主索引，但可以更改此行為）。在這種情況下， **total** 將等于基于 **number_of_replicas** 設置的總分片，并且 **successful** 將等于已啟動的分片數（主副本和副本）。如果沒有失敗， **failed** 將是 0 。 ## automatic index creation ( 自動創建索引 ) 如果索引操作尚未創建，則索引操作自動創建索引（**check out** 用于手動創建索引的?**[create index API](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-create-index.html)**），并且如果尚未創建，則自動為特定類型創建 **dynamic type mapping**( 動態類型映射?)（**check out?[put mapping](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-put-mapping.html)?API** 用于手動創建類型映射）。 **mapping** ( 映射?) 本身非常靈活，并且是 **schema-free**?( 無模式的?)。**New fields** ( 新字段?) 和 **objects**?( 對象?)將自動添加到指定類型的映射定義。查看[映射部分](https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html)以獲取有關映射定義的更多信息。可以通過在所有節點的配置文件中將?**action.auto_create_index** 設置為 **false** 來禁用自動創建索引。可以通過將?**index.mapper.dynamic** 設置為 **false** 為每個索引作為索引設置來禁用自動映射創建。自動索引創建可以包括 **?a pattern based white/black list** ( 基于模式的白/黑列表?)，例如，設置 **action.auto_create_index?to?+aaa*,-bbb*,+ccc*,-* ?**（ **+** 表示允許，**-** 表示不允許）。 ## Versioning ( 版本控制 ) 每個索引文檔都有一個版本號。相關的版本號作為對索引 **API** 請求的響應的一部分返回。索引 **API** 可選地允許在指定 **version** 參數時進行 **optimistic concurrency control** ( 樂觀并發控制?)。這將控制要對其執行操作的文檔的版本。一個用于版本控制的用例的好例子是 **performing a** **transactional read-then-update** ( 執行事務讀取然后更新?) 。從初始讀取的文檔指定版本可以確保在此期間沒有發生更改（當為了更新而讀取時，建議將 **preference** ( 偏好?) 設置為 **_primary**）。例如： ``` curl -XPUT 'localhost:9200/twitter/tweet/1?version=2&pretty' -H 'Content-Type: application/json' -d' { "message" : "elasticsearch now has versioning support, double cool!" } ' ``` 注意：版本控制是完全實時的，并且不受搜索操作的 **near real time**( 近實時?) 方面的影響。如果沒有提供版本，則在沒有任何版本檢查的情況下執行操作。默認情況下，使用從 **1** 開始的內部版本控制，每個 **update** ( 更新?)，包括 **deletes** ( 刪除?)。可選地，版本號可以用外部值（例如，如果在數據庫中維護）來補充。要啟用此功能，?**version_type** 應該設置為?**external** 。提供的值必須是大于或者等于 **0** 且小于大約 **9.2e+18** 的數字長值。當使用 **external version type** ( 外部版本類型?) 時，系統檢查傳遞給索引請求的版本號是否大于當前存儲的文檔的版本，而不是檢查匹配的版本號。如果為 **true** ，則文檔將被索引并使用新的版本號。如果提供的值小于或等于存儲的文檔的版本號，則會出現版本沖突，并且索引操作將失敗。警告外部版本支持值 **0** 作為有效的版本號。這允許版本與外部版本系統同步，其中版本號從零開始而不是從 **1** 開始。它的副作用是，版本號等于 **0** 的文檔既不能使用 **[Update-By-Query API](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-update-by-query.html)**?更新，也不能使用 **[Delete By Query API](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-delete-by-query.html)** 刪除，只要他們的版本號等于 0 。一個好的作用是，不需要維護作為對源數據庫的改變的結果執行的異步索引操作的嚴格排序，只要使用來自源數據庫的版本號。即使使用外部版本控制也可以簡化使用數據庫中的數據更新彈性搜索索引的簡單情況，因為如果索引操作因為某種原因而出現故障，將只使用最新版本。 ### Version types ( 版本類型 )? 在上邊解釋的 **internal ?**( 內部?)?和 **external** ( 外部?)?版本類型旁邊，**Elasticsearch** 還支持特定用例的其他類型。這里是不同版本類型及其語義的概述。 **internal** 僅在給定版本與存儲的文檔的版本相同時索引文檔。 **external?或?external_gt** 如果給定版本嚴格高于存儲的文檔的版本或如果沒有現有文檔，則僅索引文檔。給定版本將用作新版本，并與新文檔一起存儲。提供的版本必須是 **non-negative long number** ( 非負長數字?) 。 **external_gte?** 如果給定版本等于或者高于存儲的文檔的版本，則僅索引文檔。如果沒有現有文檔，操作也將成功。給定版本將用作新版本，并與新文檔一起存儲。提供的版本必須是 **non-negative long number** ( 非負長數字?)。注意： **?external_gte** 版本類型適用于特殊用例，應謹慎使用。如果使用不正確，可能會導致數據丟失。還有一個選項，**force** ，它也被棄用，因為它可能導致主分片和副本分片。 ## Operation type ( 操作類型 ) 索引操作還接受可用于強制創建操作的 **op_type**，允許 **"put-if-absent"** 行為。使用 **create** 時，如果索引中已存在該標識的文檔，索引操作將失敗。下面是使用 **op_type** 參數的示例： ``` curl -XPUT 'localhost:9200/twitter/tweet/1?op_type=create&pretty' -H 'Content-Type: application/json' -d' { "user" : "kimchy", "post_date" : "2009-11-15T14:12:12", "message" : "trying out Elasticsearch" } ' ``` 指定 **create** 的另一個選項是使用以下 **uri** ： ``` curl -XPUT 'localhost:9200/twitter/tweet/1/_create?pretty' -H 'Content-Type: application/json' -d' { "user" : "kimchy", "post_date" : "2009-11-15T14:12:12", "message" : "trying out Elasticsearch" } ' ``` ## automatic ID generation ( 自動 ID 生成 ) 可以在不指定 **ID** 的情況下執行索引操作。在這種情況下，將自動生成 **id** 。此外，**op_type** 將自動設置為 **create** 。這里是一個例子（注意 **POST** 使用，而不是 **PUT**）： ``` curl -XPOST 'localhost:9200/twitter/tweet/?pretty' -H 'Content-Type: application/json' -d' { "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 ( 路由信息 ) 默認情況下，分片 **placement ?**( 展示位置?)——或 **routing** ( 路由?) ——通過使用文檔的 **id** 值的哈希值來控制。對于更明確的控制，饋送到由路由使用的散列函數的值可以使用路由參數基于每個操作直接指定。例如： ``` curl -XPOST 'localhost:9200/twitter/tweet?routing=kimchy&pretty' -H 'Content-Type: application/json' -d' { "user" : "kimchy", "post_date" : "2009-11-15T14:12:12", "message" : "trying out Elasticsearch" } ' ``` 在上面的示例中，**"tweet"** 文檔根據提供的 **routing parameter** ( 路由參數?)?發送到 **shard ( 分片?) ："kimchy"** 。設置 **up explicit mapping**( 顯式映射?) 時，可以選擇使用 **_routing** 字段來指示索引操作從文檔本身提取路由值。這是在額外的文檔解析通過的（非常小）成本。如果定義 **_routing** 映射并將其設置為必需，則如果未提供或提取路由值，則索引操作將失敗。 ## Parnets & Children? 通過在索引時指定其父級，可以索引子文檔。例如： ``` curl -XPUT 'localhost:9200/blogs?pretty' -H 'Content-Type: application/json' -d' { "mappings": { "tag_parent": {}, "blog_tag": { "_parent": { "type": "tag_parent" } } } } ' curl -XPUT 'localhost:9200/blogs/blog_tag/1122?parent=1111&pretty' -H 'Content-Type: application/json' -d' { "tag" : "something" } ' ``` 對子文檔建立索引時，**routing value** ( 路由值?) 會自動設置為與其父代相同，除非使用路由參數顯式指定路由值。 ## Distributed ( 分布式 ) 索引操作基于其路由定向到 **primary shard?**( 主分片?) （參見上面的路由部分），并在包含此分片的實際節點上執行。在主分片完成操作后，如果需要，將更新分發到適用的副本。 ## wait for active shards ( 等待活動分片 ) 為了提高寫入系統的 **resiliency** ( 彈性?)，索引操作可以配置為在繼續操作之前等待一定數量的活動分片副本。如果所需的活動分片副本數不可用，則寫操作必須等待并重試，直到必需的分片副本已啟動或發生超時為止。默認情況下，寫操作只等待主分片處于活動狀態，然后再繼續（**wait_for_active_shards=1**）。可以通過設置**?index.write.wait_for_active_shards** 來動態地在索引設置中覆蓋此默認值。要更改每個操作的此行為，可以使用?**wait_for_active_shards** 請求參數。有效值是所有或任何正整數，直到索引中每個分片的配置副本的總數（即 **number_of_replicas+1**）。指定負值或者大于分片副本數的數字將拋出錯誤。例如，假設我們有一個三個節點A，B和C的集群，我們創建一個索引，索引副本數設置為 3 （導致 4 個 **shard** 副本，比節點多一個副本）。如果我們嘗試索引操作，默認情況下，操作將僅確保每個分片的主副本在繼續之前可用。這意味著，即使 B 和 C 下降，并且 A 托管主分片副本，索引操作仍然將繼續只有一個數據副本。如果對請求設置?wait_for_active_shards 設置為 3 （并且所有3個節點都已啟動），則索引操作將在繼續之前需要 3 個活動分片副本，這是應該滿足的要求，因為在集群有3個活動節點，每個節點有一個碎片的副本。但是，如果我們將?**wait_for_active_shards** 設置為 all （或者 4，這是相同的），索引操作將不會繼續，因為索引中的每個碎片的所有的 4 個副本沒有處于活動狀態。該操作將超時，除非在集群中啟動新節點以托管分片的第四個副本。重要的是要注意，這個設置極大地減少了寫操作不寫入所需數量的分片副本的機會，但是它不能完全消除可能性，因為這種檢查在寫操作開始之前發生。一旦寫操作正在進行，復制仍然可能在任意數量的 **shard** 副本上失敗，但在主數據庫上仍然成功。寫操作響應的 **_shard** 部分顯示復制成功/失敗的分片副本的數量。 ``` { "_shards" : { "total" : 2, "failed" : 0, "successful" : 2 } } ``` ## Refresh ( 刷新 ) 控制此請求所做的更改對搜索可見。請參閱[?刷新](https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-refresh.html)?。 ## Noop Updates 當使用索引 **API** 更新文檔時，即使文檔沒有更改，也始終創建新版本的文檔。如果這不可接受，請使用將?**detect_noop** 設置為 **true** 的**_update** **API** 。此選項在索引 **API** 上不可用，因為索引 **api**? **doesn’t fetch the old source** ( 不提取舊源?)，并且無法將其與 **new source** ( 新源?) 進行比較。沒有一個強制和快速的規則，當 **noop** 更新是不能接受的。它是許多因素的組合，例如數據源發送實際上是 **noops** 的更新的頻率，以及每秒多少查詢，**elasticsearch** 在接收更新時在分片上運行。 ## Timeout ( 超時 ) 執行索引操作時分配的 **primary shard**?( 主分片?) 可能不可用。這種情況的一些原因可能是主分片當前正在從 **gateway?**( 網關?) 恢復或正在進行重定位。默認情況下，索引操作將在主分片上等待最多 **1** 分鐘，然后失敗并響應錯誤。 **timeout** 參數可以用于顯式指定等待時間。以下是將其設置為 **5** 分鐘的示例： ``` curl -XPUT 'localhost:9200/twitter/tweet/1?timeout=5m&pretty' -H 'Content-Type: application/json' -d' { "user" : "kimchy", "post_date" : "2009-11-15T14:12:12", "message" : "trying out Elasticsearch" } ' ```