Update API · my-elasticsearch-cn

# 更新API 更新API允許根據提供的腳本來更新文檔。操作從索引獲取文檔（通過分片并發的），運行腳本（具有可選腳本語言和參數），并將結果建立索引（也允許刪除或忽略該操作）。它使用版本控制來確保在“get”和“reindex”期間沒有發生更新。請注意，此操作仍然意味著文檔的完整重新索引，它只是刪除一些網絡往返，并減少`get`和`index`之間版本沖突的機會。需要啟用`_source`字段以使此功能正常工作。為了演示，我們創建一個簡單的文檔： ``` PUT test/type1/1 { "counter" : 1, "tags" : ["red"] } ``` ## 腳本更新現在，我們能執行以下腳本來遞增計數器： ``` POST test/type1/1/_update { "script" : { "inline": "ctx._source.counter += params.count", "lang": "painless", "params" : { "count" : 4 } } } ``` 我們可以在`tags`中添加一個`tag`（注意，如果`tags`存在，它將會添加它，由于它是一個列表）： ``` POST test/type1/1/_update { "script" : { "inline": "ctx._source.tags.add(params.tag)", "lang": "painless", "params" : { "tag" : "blue" } } } ``` 除`_source`外，以下變量可通過`ctx`映射獲得：`_index`、`_type`、`_id`、`_version`、`_routing`、`_parent`和`_now`（當前時間戳）。我們還可以在文檔中添加一個新的字段： ``` POST test/type1/1/_update { "script" : "ctx._source.new_field = \"value_of_new_field\"" } ``` 或者從文檔中刪除一個字段： ``` POST test/type1/1/_update { "script" : "ctx._source.remove(\"new_field\")" } ``` 我們甚至可以改變所執行的操作。這個例子中刪除文檔如果標簽字段包含`green`,否則什么也不做(`noop`)： ``` POST test/type1/1/_update { "script" : { "inline": "if (ctx._source.tags.contains(params.tag)) { ctx.op = \"delete\" } else { ctx.op = \"none\" }", "lang": "painless", "params" : { "tag" : "green" } } } ``` ## 根據部分文檔修改更新API還支持傳遞一個部分文檔，它將被合并到現有文檔中（簡單的遞歸合并，對象的內部合并，替換核心“鍵/值”和數組）。例如： ``` POST test/type1/1/_update { "doc" : { "name" : "new_name" } } ``` 如果指定了`doc`和`script`，則忽略`doc`。最好是將部分文檔的字段對放在腳本本身中。 ## 探測noop更新如果指定了`doc`，它的值將與現有的`_source`合并。默認情況下，不更改任何內容的更新會探測到它們不會更改任何內容并返回“result”：“noop”，如下所示： ``` POST test/type1/1/_update { "doc" : { "name" : "new_name" } } ``` 如果在發送請求之前`name`是`new_name`，則忽略整個更新請求。如果請求被忽略，則響應中的`result`元素返回`noop`。 ``` { "_shards": { "total": 0, "successful": 0, "failed": 0 }, "_index": "test", "_type": "type1", "_id": "1", "_version": 6, "result": noop } ``` 您可以通過設置“detect\_noop”為`false`來禁用此行為，如下所示： ``` POST test/type1/1/_update { "doc" : { "name" : "new_name" }, "detect_noop": false } ``` ## Upserts 如果文檔不存在，則將`upsert`的內容作為新的文檔插入。如果文檔確實存在，那么`script`將被執行： ``` POST test/type1/1/_update { "script" : { "inline": "ctx._source.counter += params.count", "lang": "painless", "params" : { "count" : 4 } }, "upsert" : { "counter" : 1 } } ``` ### scripted\_upsert 如果您希望無論文檔是否存在都運行腳本——即腳本處理初始化文檔替代`upsert`元素——則將`scripted_upsert`設置為`true`： ``` POST sessions/session/dh3sgudg8gsrgl/_update { "scripted_upsert":true, "script" : { "id": "my_web_session_summariser", "params" : { "pageViewEvent" : { "url":"foo.com/bar", "response":404, "time":"2014-01-01 12:32" } } }, "upsert" : {} } ``` ### doc\_as\_upsert 將`doc_as_upsert`設置為`true`而不是發送部分文檔加上`upsert`文檔，而將`doc`的內容用作`upsert`值： ``` POST test/type1/1/_update { "doc" : { "name" : "new_name" }, "doc_as_upsert" : true } ``` ## 參數更新操作支持如下查詢字符串參數： * retry\_on\_conflict在更新的獲取和索引階段之間，另一個進程可能已經更新了同一個文檔。默認情況下，更新將失敗并出現版本沖突異常。`retry_on_conflict`參數控制在最后拋出異常之前重試更新的次數。 * routing如果正在更新的文檔不存在，則使用路由將更新請求路由到正確的分片，并為`upsert`請求設置路由。不能用于更新現有文檔的路由。parent如果正在更新的文檔不存在，則父用于將更新請求路由到正確的分片，并為`upsert`請求設置父級。不能用于更新現有文檔的父級。如果指定了別名索引路由，則它將覆蓋父路由，并用于路由請求。 * timeout等待分片變為可用的超時時間。 * wait\_for\_active\_shards在進行更新操作之前，分片副本的數量需要處于活動狀態。詳見[這里](Index_API.md#index-wait-for-active-shards)。 * refresh控制此請求所做的更改對于搜索是可見的。參見[?refresh](refresh.html)。 * \_source允許控制在響應中是否和如何返回更新的源。默認情況下，不會返回更新的源。有關詳細信息，請參閱[source filtering](../Search_APIs/Request_Body_Search/Source_filtering.md)。 * version & version\_type更新API在內部使用Elasticsearch的版本控制支持，以確保在更新過程中文檔不會更改。您可以使用`version`參數指定僅當文檔的版本與指定的版本匹配時才應更新該文檔。通過將版本類型設置為`force`，您可以在更新后強制使用新版本的文檔（謹慎使用！`force`不保證文檔沒有更改）。 > > 注意 > > ## 更新API不支持外部版本控制 > > 更新API不支持外部版本控制（版本類型`external`＆`external_gte`），因為它會導致Elasticsearch版本號與外部系統不同步。使用[index API](Index_API.md)代替。 > my note > > script的使用