Update By Query API · my-elasticsearch-cn

# 根據查詢API更新 `_update_by_query`的最簡單的用法只是對索引中的每個文檔執行更新，而不會更改源。這對于[收集新的屬性](#picking-up-a-new-property)或其他在線映射更改非常有用。這是API： ``` POST twitter/_update_by_query?conflicts=proceed ``` 他將返回類如下的信息： ``` { "took" : 147, "timed_out": false, "updated": 120, "deleted": 0, "batches": 1, "version_conflicts": 0, "noops": 0, "retries": { "bulk": 0, "search": 0 }, "throttled_millis": 0, "requests_per_second": -1.0, "throttled_until_millis": 0, "total": 120, "failures" : [ ] } ``` `_update_by_query`在啟動時獲取索引的快照，并使用內部版本控制對其進行索引。這意味著如果文檔在拍攝快照和處理索引請求之間發生變化，則會發生版本沖突。當版本匹配文檔被更新并且版本號增加。 > 注意 > > 由于內部版本控制不支持值`0`作為有效的版本號，版本等于零的文檔無法使用`_update_by_query`進行更新，并且會使請求失敗。所有更新和查詢失敗導致`_update_by_query`中止并在響應失敗中返回。已執行的更新仍然堅持。換句話說，進程沒有回滾，只會中止。當第一個故障導致中止時，失敗批量請求返回的所有故障都會返回到故障元素中；因此，有可能會有不少失敗的實體。如果你想簡單地計算版本沖突，不會導致`_update_by_query`中止，你可以在url設置`conflicts=proceed`或在請求體設置`"conflicts": "proceed"`。第一個例子是這樣做，因為它只是嘗試接管在線映射更改，并且版本沖突只是意味著沖突的文檔在`_update_by_query`的開始與嘗試更新文檔的時間之間更新。這很好，因為該更新將獲取在線映射更新。返回到API格式，您可以將`_update_by_query`限制為單一類型。下面將只從`Twitter`的索引更新`tweet`類型的文件： ``` POST twitter/tweet/_update_by_query?conflicts=proceed ``` 您還可以使用[Query DSL](../Query_DSL.md)限制`_update_by_query`。下面將更新用戶`kimchy`的`twitter`索引中的所有文檔： ``` POST twitter/_update_by_query?conflicts=proceed { "query": { //① "term": { "user": "kimchy" } } } ``` ① 該查詢必須以與[Search API](../Search_APIs/Search.md)相同的方式作為`query`的值傳遞。您也可以以與搜索api相同的方式使用`q`參數。到目前為止，我們只是更新文檔而不改變它們的來源。這對于[收集新的屬性](#picking-up-a-new-property)來說真的很有用，但只有一半的樂趣。 `_update_by_query`支持腳本對象來更新文檔。這將增加所有`kimchy`的`tweets`上的`likes`字段： ``` POST twitter/_update_by_query { "script": { "inline": "ctx._source.likes++", "lang": "painless" }, "query": { "term": { "user": "kimchy" } } } ``` 就像[更新API](Update_API.md)一樣，您可以設置`ctx.op`來更改執行的操作： `noop` 如果您的腳本決定不必進行任何更改，請設置 `ctx.op ="noop"` 。這將導致`_update_by_query` 從其更新中忽略該文檔。這個沒有操作將被報告在[響應體](#response-body)的 `noop` 計數器上。 `delete` 如果您的腳本決定必須刪除該文檔，請設置`ctx.op="delete"`。刪除將在[響應體](#response-body)的 `deleted` 計數器中報告。將`ctx.op`設置為其他任何內容都是錯誤。在`ctx`中設置任何其他字段是一個錯誤。請注意，我們停止指定`conflict=proceed`。在這種情況下，我們希望版本沖突中止該過程，以便我們可以處理該故障。該API不允許您移動其觸摸的文檔，只需修改其來源。這是故意的！我們沒有規定將文檔從原始位置刪除。也可以一次性對多個索引和多個類型進行整體處理，就像搜索API一樣： ``` POST twitter,blog/tweet,post/_update_by_query ``` 如果您提供`routing`則將路由復制到滾動查詢，將進程限制為與該路由值匹配的分片： ``` POST twitter/_update_by_query?routing=1 ``` 默認情況下`_update_by_query`使用滾動批次數量為`1000`.您可以使用URL參數`scroll_size`更改批量大小： ``` POST twitter/_update_by_query?scroll_size=100 ``` `_update_by_query`也可以使用[Ingest Node](../Ingest_Node.md)功能來指定管道，如下所示： ``` PUT _ingest/pipeline/set-foo { "description" : "sets foo", "processors" : [ { "set" : { "field": "foo", "value": "bar" } } ] } POST twitter/_update_by_query?pipeline=set-foo ``` ## URL參數除了標準參數像`pretty`之外，“Update By Query API”還支持`refresh`、`wait_for_completion`、`wait_for_active_shards`、`timeout`以及`requests_per_second`。發送`refresh`將在更新請求完成時更新索引中的所有分片。這不同于 Index API 的`refresh`參數，只會導致接收到新數據的分片被索引。如果請求包含`wait_for_completion=false`，那么Elasticsearch將執行一些預檢檢查、啟動請求、然后返回一個任務，可以與[Tasks API](#docs-delete-by-query-task-api)一起使用來取消或獲取任務的狀態。Elasticsearch還將以`.tasks/task/${taskId}`作為文檔創建此任務的記錄。這是你可以根據是否合適來保留或刪除它。當你完成它時，刪除它可以讓Elasticsearch回收它使用的空間。 `wait_for_active_shards`控制在繼續請求之前必須有多少個分片必須處于活動狀態，詳見[這里](Index_API.md#index-wait-for-active-shards)。`timeout`控制每個寫入請求等待不可用分片變成可用的時間。兩者都能正確地在[Bulk API](Bulk_API.md)中工作。 `requests_per_second`可以設置為任何正數（1.4，6，1000等），來作為“delete-by-query”每秒請求數的節流閥數字，或者將其設置為`-1`以禁用限制。節流是在批量批次之間等待，以便它可以操縱滾動超時。等待時間是批次完成的時間與`request_per_second * requests_in_the_batch`的時間之間的差異。由于分批處理沒有被分解成多個批量請求，所以會導致Elasticsearch創建許多請求，然后等待一段時間再開始下一組。這是“突發”而不是“平滑”。默認值為-1。 ## 響應體 JSON響應類似如下： ``` { "took" : 639, "updated": 0, "batches": 1, "version_conflicts": 2, "retries": { "bulk": 0, "search": 0 } "throttled_millis": 0, "failures" : [ ] } ``` `took` ``` 從整個操作的開始到結束的毫秒數。 ``` `updated` ``` 成功更新的文檔數。 ``` `batches` ``` 通過查詢更新的滾動響應數量。 ``` `version_conflicts` ``` 根據查詢更新時，版本沖突的數量。 ``` `retries` ``` 根據查詢更新的重試次數。bluk 是重試的批量操作的數量，search 是重試的搜索操作的數量。 ``` `throttled_millis` ``` 請求休眠的毫秒數，與`requests_per_second`一致。 ``` `failures` ``` 失敗的索引數組。如果這是非空的，那么請求因為這些失敗而中止。請參閱 conflicts 來如何防止版本沖突中止操作。 ``` ## 配合Task API使用您可以使用[Task API](../Cluster_APIs/Task_Management_API.md)獲取任何正在運行的根據查詢修改請求的狀態： ``` GET _tasks?detailed=true&actions=*/update/byquery ``` 響應會類似如下： ``` { "nodes" : { "r1A2WoRbTwKZ516z6NEs5A" : { "name" : "r1A2WoR", "transport_address" : "127.0.0.1:9300", "host" : "127.0.0.1", "ip" : "127.0.0.1:9300", "attributes" : { "testattr" : "test", "portsfile" : "true" }, "tasks" : { "r1A2WoRbTwKZ516z6NEs5A:36619" : { "node" : "r1A2WoRbTwKZ516z6NEs5A", "id" : 36619, "type" : "transport", "action" : "indices:data/write/update/byquery", "status" : { //① "total" : 6154, "updated" : 3500, "created" : 0, "deleted" : 0, "batches" : 4, "version_conflicts" : 0, "noops" : 0, "retries": { "bulk": 0, "search": 0 } "throttled_millis": 0 }, "description" : "" } } } } } ``` ① 此對象包含實際狀態。它就像是響應json，重要的添加`total`字段。 `total`是重建索引希望執行的操作總數。您可以通過添加的`updated`、`created`和`deleted`的字段來估計進度。當它們的總和等于`total`字段時，請求將完成。使用任務id可以直接查找任務： ``` GET /_tasks/taskId:1 ``` 這個API的優點是它與`wait_for_completion=false`集成，以透明地返回已完成任務的狀態。如果任務完成并且`wait_for_completion=false`被設置，那么它將返回`results`或`error`字段。此功能的成本是`wait_for_completion=false`在`.tasks/task/${taskId}`創建的文檔，由你自己刪除該文件。 ## 配合取消任務API使用所有根據查詢修改都能使用[Task Cancel API](../Cluster_APIs/Task_Management_API.md)取消： ``` POST _tasks/task_id:1/_cancel ``` 可以使用上面的任務API找到`task_id`。取消應盡快發生，但可能需要幾秒鐘。上面的任務狀態API將繼續列出任務，直到它被喚醒取消自身。 ## 重置節流閥 `request_per_second`的值可以在通過查詢刪除時使用`_rethrottle` API更改： ``` POST _update_by_query/task_id:1/_rethrottle?requests_per_second=-1 ``` 可以使用上面的任務API找到task\_id。就像在`_update_by_query` API中設置它一樣，`request_per_second`可以是`-1`來禁用限制，或者任何十進制數字，如1.7或12，以節制到該級別。加速查詢的會立即生效，但是在完成當前批處理之后，減慢查詢的才會生效。這樣可以防止滾動超時。 ## 手動切片根據查詢修改支持[滾動切片](../Search_APIs/Request_Body_Search/Scroll.md#sliced-scroll)，您可以相對輕松地手動并行化處理： ``` POST twitter/_update_by_query { "slice": { "id": 0, "max": 2 }, "script": { "inline": "ctx._source['extra'] = 'test'" } } POST twitter/_update_by_query { "slice": { "id": 1, "max": 2 }, "script": { "inline": "ctx._source['extra'] = 'test'" } } ``` 您可以通過以下方式驗證： ``` GET _refresh POST twitter/_search?size=0&q=extra:test&filter_path=hits.total ``` 其結果一個合理的`total`像這樣： ``` { "hits": { "total": 120 } } ``` ## 自動切片你還可以讓根據查詢修改使用切片的`_uid`來自動并行的[滾動切片](../Search_APIs/Request_Body_Search/Scroll.md#sliced-scroll)。 ``` POST twitter/_update_by_query?refresh&slices=5 { "script": { "inline": "ctx._source['extra'] = 'test'" } } ``` 您可以通過以下方式驗證： ``` POST twitter/_search?size=0&q=extra:test&filter_path=hits.total ``` 其結果一個合理的`total`像這樣： ``` { "hits": { "total": 120 } } ``` 將`slices`添加到`_update_by_query`中可以自動執行上述部分中使用的手動過程，創建子請求，這意味著它有一些怪癖： - 您可以在[Task API](#docs-delete-by-query-task-api)中看到這些請求。這些子請求是具有`slices`請求任務的“子”任務。 - 獲取`slices`請求任務的狀態只包含已完成切片的狀態。 - 這些子請求可以單獨尋址，例如取消和重置節流閥。 - `slices`的重置節流閥請求將按相應的重新計算未完成的子請求。 - `slices`的取消請求將取消每個子請求。 - 由于`slices`的性質，每個子請求將不會獲得完全均勻的文檔部分。所有文件都將被處理，但有些片可能比其他片大。預期更大的切片可以有更均勻的分布。 - 帶有`slices`請求的`request_per_second`和`size`的參數相應的分配給每個子請求。結合上述關于分布的不均勻性，您應該得出結論，使用切片大小可能不會導致正確的大小文檔為`_update_by_query`。 - 每個子請求都會獲得源索引的略有不同的快照，盡管這些都是大致相同的時間。 ## 挑選切片數量在這一點上，我們圍繞要使用的`slices`數量提供了一些建議（比如手動并行化時，切片API中的`max`參數）： - 不要使用大的數字，`500`就能造成相當大的CPU抖動。 - 從查詢性能的角度來看，在源索引中使用分片數量的一些倍數更為有效。 - 在源索引中使用完全相同的分片是從查詢性能的角度來看效率最高的。 - 索引性能應在可用資源之間以`slices`數量線性擴展。 - 索引或查詢性能是否支配該流程取決于許多因素，如正在重建索引的文檔和進行`reindexing`的集群。 ## 收集新的屬性假設您創建了一個沒有動態映射的索引，用數據填充它，然后添加一個映射值來從數據中獲取更多的字段： ``` PUT test { "mappings": { "test": { "dynamic": false, //① "properties": { "text": {"type": "text"} } } } } POST test/test?refresh { "text": "words words", "flag": "bar" } POST test/test?refresh { "text": "words words", "flag": "foo" } PUT test/_mapping/test //② { "properties": { "text": {"type": "text"}, "flag": {"type": "text", "analyzer": "keyword"} } } ``` ① 這意味著新的字段將不會被索引，只存儲在\_source中。 - - - - - - ② 將更新映射以添加新的`flag`字段。要接收新的字段，你必須重新索引所有的文檔。搜索數據將找不到任何內容： ``` POST test/_search?filter_path=hits.total { "query": { "match": { "flag": "foo" } } } ``` ``` { "hits" : { "total" : 0 } } ``` 但是您可以發出`_update_by_query`請求來接收新映射： ``` POST test/_update_by_query?refresh&conflicts=proceed POST test/_search?filter_path=hits.total { "query": { "match": { "flag": "foo" } } } ``` ``` { "hits" : { "total" : 1 } } ``` 將字段添加到多字段時，您可以執行完全相同的操作。