說明

本來是找幾個章節學習一下，后來發現內部嵌套太多，官方擴展很容易，先部分整理出來，后續要慢慢找工作了，慢慢更新吧

筆記地址

文檔說明
8.6官方文檔
最新版本

單機模式: docker compose搭建elk 8.6.2

集群模式:使用docker compose 部署Elasticsearch 9.0.4集群 + kibana

使用最新版的進行學習,按照重要程度進行學習,先學習重要的

快速開始

get-started

基礎知識

Index basics

索引是Elasticsearch存儲的基本單元.是名稱或者別名唯一標識的文檔的集合.所有的搜索和查詢都要基于這個唯一標識.

索引組成

1. 文檔 (Documents)

使用json文檔的形式序列化和存儲數據.文檔是一組字段,每個字段包含一個名稱和值.每個文檔都有唯一的ID,可以自己指定或者由Elasticsearch自動生成.

示例:

{"_index": "my-first-elasticsearch-index","_id": "DyFpo5EBxE8fzbb95DOa","_version": 1,"_seq_no": 0,"_primary_term": 1,"found": true,"_source": {"email": "john@smith.com","first_name": "John","last_name": "Smith","info": {"bio": "Eco-warrior and defender of the weak","age": 25,"interests": ["dolphins","whales"]},"join_date": "2024/05/01"}
}

2. 元數據字段(Metadata fields)

元數據字段是存儲有關文檔信息的系統字段.在Elasticsearch中元數據字段的名稱都以_開頭.

例如 :

• _index : 存儲文檔的索引名稱
• _id : 文檔的ID,在索引里面文檔的id是唯一的

3. 映射和數據類型(Mappings and data types)

每個索引都有一個映射或模式,用于說明如何對文檔中的字段進行索引.映射定義了索引的類型、字段的索引方式以及存儲方式.

PUT /semantic-index

文檔操作(Document)

Document

批量創建或者刪除文檔 (Bulk index or delete documents)

語法 :

PUT /{index}/_bulk
POST /{index}/_bulk
PUT /_bulk
POST /_bulk

例如:多種操作

注意如果是kibana數據批量請求,數據放到同一行,如果是curl,數據最后一行多個換行符,下面一般情況下使用kibana的格式

POST /_bulk?pretty
{"index":{"_index":"test","_id":"1"}}{"field1":"value1"}{"delete":{"_index":"test","_id":"2"}}{"create":{"_index":"test","_id":"3"}}{"field1":"value3"}{"update":{"_index":"test","_id":"1"}}{"doc":{"field2":"value2"}}

批量update 可以使用retry_on_conflict 指定版本沖突重試次數

POST /_bulk?pretty
{ "update" : {"_id" : "1", "_index" : "index1", "retry_on_conflict" : 3} }{ "doc" : {"field" : "value"} }{ "update" : { "_id" : "0", "_index" : "index1", "retry_on_conflict" : 3} }{ "script" : { "source": "ctx._source.counter += params.param1", "lang" : "painless", "params" : {"param1" : 1}}, "upsert" : {"counter" : 1}}{ "update" : {"_id" : "2", "_index" : "index1", "retry_on_conflict" : 3} }{ "doc" : {"field" : "value"}, "doc_as_upsert" : true }{ "update" : {"_id" : "3", "_index" : "index1", "_source" : true} }{ "doc" : {"field" : "value"} }{ "update" : {"_id" : "4", "_index" : "index1"} }{ "doc" : {"field" : "value"}, "_source": true}

只查看失敗的信息,使用filter_path=items.*.error進行過濾

POST /_bulk?filter_path=items.*.error
{ "index" : { "_index" : "test", "_id" : "1" } }{ "field1" : "value1" }{ "delete" : { "_index" : "test", "_id" : "2" } }{ "create" : { "_index" : "test", "_id" : "3" } }{ "field1" : "value3" }{ "update" : {"_id" : "1", "_index" : "test"} }{ "doc" : {"field2" : "value2"} }

運行POST /_bulk以執行包含索引和創建操作且帶有dynamic_templates參數的批量請求。根據dynamic_templates參數，該批量請求會創建兩個類型為geo_point的新字段work_location和home_location。然而，raw_location字段是使用默認的動態映射規則創建的，在這種情況下，由于它在JSON文檔中是以字符串形式提供的，因此被創建為文本字段。

POST /_bulk
{ "index" : { "_index" : "my_index", "_id" : "1", "dynamic_templates": {"work_location": "geo_point"}} }{ "field" : "value1", "work_location": "41.12,-71.34", "raw_location": "41.12,-71.34"}{ "create" : { "_index" : "my_index", "_id" : "2", "dynamic_templates": {"home_location": "geo_point"}} }{ "field" : "value2", "home_location": "41.12,-71.34"}

在單個請求中執行多個 index、create、delete 或 update 操作,可以減少開銷,提高索引速度.

如果開啟了權限功能,需要的權限說明

• create操作: create_doc、create、index、 write index權限;數據流只支持create操作
• index操作: create、index或write index權限;
• delete操作: delete、write index權限;
• update操作: index或write index權限;
• 批量API自動創建數據流或索引:auto_configure、create_index或者manage index權限;
• 使用refresh讓批量操作對搜索結果可見:maintenance或manage index權限;

數據流自動創建需要啟用數據流匹配的索引模版

如果在批量請求的路徑上指定了index，那么在所有沒有指明_index的操作中都會使用這個索引

Elasticsearch默認將HTTTP請求設置最大大小為100MB，因此在請求的時候必須保證請求小于這個大小。

樂觀并發控制 Optimistic concurrency control

批量API調用的每個index和delete在各自的動作和Meta數據行中包含if_seq_no和if_primary_term參數，使用if_seq_no和if_primary_term參數根據現有文檔最后一次修改來控制操作的運行方法。

版本控制（version）

每個批量操作都可以包含版本值。會根據_version映射自動匹配索引或者刪除操作。也支持version_type操作

路由 Routing

每個批量操作都支持routing字段，會根據_routing映射自動匹配對應的索引或者刪除操作

數據流不支持自定義路由除非在模版中啟用 allow_custom_routing設置創建的

等待活動分片 Wait for active shards

在進行批量調用的時候，可以指定wait_for_active_shards參數，以要求在開始處理批量請求之前至少有多少個分片副本處于活動狀態。

刷新 Refresh

控制什么時候可以搜索到這個請求所做的更改

只有接受批量請求的分片才會受到刷新的影響，refresh=wait_for
可以禁用刷新，以提高批量請求的索引吞吐量。

參考文檔

路徑參數 Path parameters

• index String 必須
  批量操作必須包含data stream或者索引或別名

查詢參數

• include_source_error Boolean
  分析發生錯誤的時候錯誤消息是否包含源文檔

• list_executed_pipelines Boolean
  true的時候響應包含每個索引或創建運行的管道

• pipeline String
  用于預處理傳入文檔的管道標識符。如果指定了默認的提取管道，則將該值設置為_none會關閉此請求的默認提取管道。如果配置了最終管道，則一直會保持運行。

refresh String

如果true,Elasticsearch會刷新受影響的分片，只對搜索可見。如果是wait_for，等待刷新以使這個操作可以提供搜索。如果是false，就不刷新。

routing String

用于將操作路由到也定的分片的自定義值

_source Boolean，String，Array[String]

是否返回 _source字段，或者要返回的字段列表。

_source_excludes String,Array[String]

從響應中排除的源字段。也可以從_source_includes查詢參數中指定的子集中排除字段。如果_source是false，就會忽略這個參數。

_source_includes String,Array[String]

要包含著響應中的源字段的列表。如果使用這個字段，就會僅返回這些源字段。也可以使用_source_excludes，在子集中繼續排除，如果_source是false，就會忽略這個參數。

timeout String

每個操作等待下一個操作的時間；自動索引創建、動態映射更新和等待活動分片。默認值是1min，保證Elasticsearch值失敗之親啊的至少等待超時。實際時間可能會更長，當發生多個等待的時候。

可以設置值是 0 代表不等待, -1 一直等待

wait_for_active_shards Number | string

批量操作必須等待至少多少個分片副本處于活動狀態。可以設置為all或者任意正整數,最大是索引中分片副本數(number_of_replicas+1),默認是1,等待每個主分片處于活動狀態.

require_alias Boolean

true 代表必須是索引的別名

require_data_stream Boolean

true 代表操作的目標必須是數據流(已經存在或創建)

Body Object Required

OperationContainer Object

index Object

• _id: String
• _index: String
• routing: String
• if_primary_term: Number
• if_seq_no: Number
• version: Number
• version_type: String 值可以是 internal, external, external_gte, force
• dynamic_templates: Object 從字段全名匹配的動態模板,如果不存在就使用這個模版,如果已經存在就不處理.
  dynamic_templates attribute Object
  String
• pipeline String
  用于預處理傳入文檔的管道標識符。如果指定了默認的提取管道，則將該值設置為_none會關閉此請求的默認提取管道。如果配置了最終管道，則一直會保持運行。
• require_alias Boolean . true 代表必須是索引的別名,默認false

create Object
跟index 完全一樣

• _id: String
• _index: String
• routing: String
• if_primary_term: Number
• if_seq_no: Number
• version: Number
• version_type: String 值可以是 internal, external, external_gte, force
• dynamic_templates: Object 從字段全名匹配的動態模板,如果不存在就使用這個模版,如果已經存在就不處理.
  dynamic_templates attribute Object
  String
• pipeline String
  用于預處理傳入文檔的管道標識符。如果指定了默認的提取管道，則將該值設置為_none會關閉此請求的默認提取管道。如果配置了最終管道，則一直會保持運行。
• require_alias Boolean . true 代表必須是索引的別名,默認false

update Object
多出這個字段

• retry_on_conflict: Number 版本沖突重試的次數
  其他基本一樣的字段
• _id: String
• _index: String
• routing: String
• if_primary_term: Number
• if_seq_no: Number
• version: Number
• version_type: String 值可以是 internal, external, external_gte, force
• pipeline String
  用于預處理傳入文檔的管道標識符。如果指定了默認的提取管道，則將該值設置為_none會關閉此請求的默認提取管道。如果配置了最終管道，則一直會保持運行。
• require_alias Boolean . true 代表必須是索引的別名,默認false

delete Object

• _id: String
• _index: String
• routing: String
• if_primary_term: Number
• if_seq_no: Number
• version: Number
• version_type: String 值可以是 internal, external, external_gte, force

Responses

200

• errors Boolean Required .如果是true,批量請求中有一個或多個操作失敗
• items Array[Object] Required. 每個操作響應的結果,按照提交請求順序
  attribute 如下
  • _id string | null
  • _index string Required
  • status number Required . http請求狀態碼
  • failure_store String. 值可能出現的范圍:[not_applicable_or_unknown | used | not_enabled | failed ]
  • error Object,包含屬性
    • reason string | null . 錯誤信息
    • stack_trace string 錯誤堆棧,error_trace=true的時候才會有
    • caused_by Object. 請求失敗詳細原因
    • root_cause Array[Object] . 請求失敗的原因和詳細信息。
  • _primary_term number. 操作成功的時候有值,操作的主分片的任期號
  • result string. 操作的結果,值可能出現的范圍:[created | updated | deleted ]
  • _seq_no number
  • _shards Object.
    • failed number Required
    • successful number Required
    • total number Required
    • failures Array[Object]
    • skipped number
  • _version number
  • forced_refresh boolean
  • get Object.
    • fields object
    • found boolean Required
    • _seq_no number
    • _primary_term number
    • _routing string
    • _source object
  • took number Required
  • ingest_took number

Create a new document in the index 創建文檔

格式

POST /{index}/_create/{id}
PUT /{index}/_create/{id}

使用_creat的時候需要保證{id}不存在,如果存在,則返回409錯誤

示例

PUT my-index-000001/_create/1
{"@timestamp": "2099-11-15T13:12:00","message": "GET /search HTTP/1.1 200 1070000","user": {"id": "kimchy"}
}

如果啟用了安全功能,執行的時候需要對目標數據流、索引或者索引別名有索引權限

• POST /{index}/_create/{id}: 創建文檔必須要有create_doc,create,index或write index的權限
• 如果要自動創建索引或者數據流,必須要有auto_config,create_index或manage權限
  自動創建數據流需要啟用數據流的匹配索引模版

Automatically create data streams and indices 自動創建數據流或者索引

如果請求的目標不存在,并且有與具有data_stream定義的索引模版匹配,則索引操作自動創建數據流.
如果目標不存在,沒有與之匹配的數據流模版,那么就會自動創建索引,并應用任何匹配的索引模版
如果不存在映射,索引操作會創建動態映射.默認情況,新的字段和對象會自添加到映射中.

自動創建索引由action.auto_create_index控制,true可以創建任意索引,false是禁止, 可以使用多個逗號分割的模式,使用 + 或 - 前綴來標記允許或禁用模式.直接使用列表代表不允許.

action.auto_create_index 只影響索引的自動創建,不影響數據流的創建

Routing 路由

默認情況下分片的位置(或者路由)是使用文檔的ID值的散列來控制.對于顯示的控制,可以使用routing參數來顯式控制,直接指定路由器使用的hash函數的值.
在使用顯示映射時,可以使用_routing參數來指定索引操作從文檔中獲取路由值,但是需要額外解析文檔(代價也比較小).如果定義了_routing設置,并且設置為必須,如果沒有提供或提取路由值,那么索引操作就會失敗.

數據流不支持自定義路由,除非是在模版中使用allow_custom_routing創建的

Distributed 分布式

索引操作根據主分片的路由定位到主分片,并且在該分片的實際節點上執行.在主分片完成操作后,如果需要,把更新分發到合適的副本.

Active shards 激活分片

為了提高系統的寫入的彈性,可以將索引的操作配置為在操作之前等待一定數量的活動分片副本.如果沒有達到數量,寫入操作必須等待或者重試,直到需要的分片副本已經啟動或發送超時.默認情況下寫操作只會等待主分片處于活動狀態后才會繼續(wait_for_active_shards是1).可以通過index.write.wait_for_active_shards參數進行覆蓋配置配置.也可以直接在請求中攜帶參數wait_for_active_shards

有效值范圍是索引中每個分片配置的副本總數(number_of_replicas + 1)以內的所有或任意正整數.如果是負值或者大于分片副本數就會報錯.

這個設置會降低寫入操作的未寫入所需分片副本的可能性,但是不能消除,因為這個檢查發生在寫操作之前,在寫操作完成之后,復制可能在任何數量的分片副本上失敗,但是主分仍然是成功的,響應結果中_shards部分顯示復制成功和失敗的分片副本數量.

No operation (noop) update

在使用API更新文檔的時候,如果文檔沒有改變,也總是會創建文檔的新副本,如果不能接受,那么在使用 _update API的時候設置detect_noop為true.但是創建文檔的時候這個選項是不可用的,因為沒有舊的 文檔,就不能進行比較.

Versioning 版本控制

每個被索引的文檔都有一個版本號。默認情況下使用內部版本控制，從1開始，隨著每次更新（包括刪除）遞增。版本號也可以使用外部的值，這個時候應該把version_type設置為external。提供的值必須大于等于0小于9.2e+18的長整型數值.

版本控制是完全實時的，搜索是近實時的，如果沒有提供版本，那么就不會進行任何版本檢查

當使用外部版本類型時，系統檢查傳遞給索引請求的版本號是否大于當前存儲文檔的版本。如果大于，對文檔進行索引并且使用新的版本號。如果小于或者等于，就會發生版本沖突，索引操作失敗。

PUT my-index-000001/_doc/1?version=2&version_type=external
{"user": {"id": "elkbee"}
}

上面的示例會正常執行，但是當重復執行的時候，因為提供的版本號不大于當前文檔的版本，就會出現版本沖突，http 409狀態

Path parameters路徑參數

• index String Required
  目標數據流或者索引的名稱，如果目標不存在，并且與具有*定義的索引模版名稱或者模式匹配，則此請求將會創建數據流。如果目標不存在，且與數據流模版不匹配，則此請求會創建索引

• id String Required
  文檔的唯一標識。如果需要自動生成文檔id，可以生路id字段進行創建如 POST /<target>/_doc/并省略這個參數。

Query parameters 查詢參數

• if_primary_term Number
  只有在主分片任期（primary term）與請求中的值完全匹配的時候，才會執行這次操作，否則拒絕。
• if_seq_no Number
  僅當文檔具有此序號時才執行此操作
• include_source_on_error Boolean
  當值為ture，當索引文檔出現解析錯誤（parsing error）的時候，錯誤消息會包含整個文檔的_source內容
  當值為false，錯誤信息不包含_source，只顯示錯誤原因。

為什么有這個選項，1. 方便調試，2. 安全考慮，文檔中有敏感信息，可以設置為false，3. 性能考慮可以設置為false減少響應數據量

• op_type String
  設置為create，僅當文檔不存在的時候索引文檔，如果指定了_id的文檔已經存在了，索引操作將失敗。操作跟 <index>/_create一致。如果指定了文檔的id，則參數默認為index。否則默認為create。如果請求的目標是數據流，則需要op_type為create
  取值 為 【 index ｜ create 】，分別代表覆蓋任何已經存在的文檔，僅索引不存在的文檔。
• pipeline String
  用于預處理傳入文檔的管道標識符。如果指定了默認的提取管道，則將該值設置為_none會關閉此請求的默認提取管道。如果配置了最終管道，則一直會保持運行。
• refresh String
  如果true,Elasticsearch會刷新受影響的分片，只對搜索可見。如果是wait_for，等待刷新以使這個操作可以提供搜索。如果是false，就不刷新。
• routing String
  用于將操作路由到也定的分片的自定義值
• timeout String
  請求等待以下操作的時間；自動索引創建、動態映射更新和等待活動分片。默認值是1min，保證Elasticsearch值失敗之親啊的至少等待超時。實際時間可能會更長，當發生多個等待的時候。

可以設置值是 0 代表不等待, -1 一直等待

• version Number
  跟之前的一樣是非負的長整數
• version_type String
  值可以是
  • internal, 內部控制，從1開始，每次更新或刪除時遞增
  • external, 版本高于文檔版本或者文檔不存在的時候才能編輯文檔
  • external_gte, 版本高于或等于文檔版本或者文檔不存在的時候才能編輯文檔，需要謹慎使用，可能會導致數據丟失
  • force 已經棄用，因為可能導致 主分片和副本分片分離
• wait_for_active_shards Number | string
  批量操作必須等待至少多少個分片副本處于活動狀態。可以設置為all或者任意正整數,最大是索引中分片副本數(number_of_replicas+1),默認是1,等待每個主分片處于活動狀態.
• require_alias Boolean
  true 代表必須是索引的別名
• require_data_stream Boolean
  true 代表操作的目標必須是數據流(已經存在或創建)

Body Object Required

Responses

200

• _id String Required
• _index String Required
• status number Required . http請求狀態碼
  • failure_store String. 值可能出現的范圍:[not_applicable_or_unknown | used | not_enabled | failed ]
  • error Object,包含屬性
    • reason string | null . 錯誤信息
    • stack_trace string 錯誤堆棧,error_trace=true的時候才會有
    • caused_by Object. 請求失敗詳細原因
    • root_cause Array[Object] . 請求失敗的原因和詳細信息。
  • _primary_term number. 操作成功的時候有值,操作的主分片的任期號
  • result string. 操作的結果,值可能出現的范圍:[created | updated | deleted | not_found | noop]
  • _seq_no number
  • _shards Object.
    • failed number Required
    • successful number Required
    • total number Required
    • failures Array[Object]
    • skipped number
  • _version number
  • forced_refresh boolean

示例

PUT my-index-000001/_create/1
{"@timestamp": "2099-11-15T13:12:00","message": "GET /search HTTP/1.1 200 1070000","user": {"id": "kimchy"}
}

響應

{"_index": "my-index-000001","_id": "1","_version": 4,"result": "created","_shards": {"total": 2,"successful": 2,"failed": 0},"_seq_no": 3,"_primary_term": 1
}

Get a document by its ID 根據id獲取文檔

格式

GET /{index}/_doc/<id>

從索引中獲取文檔

默認情況下是實時的,不受刷新率影響.在使用stored_fields參數請求存儲字段并且文檔已經更新但尚未刷新的情況下，API必須解析和分析源以存儲字段.如果需要關閉可以把realtime參數設置為false.

Source filtering
默認情況下,API返回_source字段的內容,除非使用了stored_fields或者_source字段被關閉,可以使用_source來關閉

GET /my-index-000001/_doc/1?_source=false

如果只需要其中的幾個字段可以使用_source_includes或_source_excludes 來包含或者過濾掉某些字段.對于檢索可以節省網絡開銷,對于大型文檔很有作用,都是逗號分割的字段或者表達式.

GET my-index-000001/_doc/0?_source_includes=*.id&_source_excludes=entities
GET my-index-000001/_doc/0?_source=*.id

Routing 路由

如果在索引期間使用路由，則還需要指定路由值以檢索文檔

GET my-index-000001/_doc/2?routing=user1

此請求獲取ID為2的文檔，但它是根據用戶路由的。如果未指定正確的路由，則不會獲取文檔。但是如果分片是一樣的時候也是可以獲取數據的

Distribute 分布式
GET操作被散列到分片Id上，然后這個分片的所有副本都可以返回結果。也意味著副本越多，GET請求的伸縮性就越好。

Version Support 版本控制支持
當文檔版本等于當前查詢指定的版本，才能檢索出文檔
在更新的時候，在內部Elasticsearch舊文檔被標記為刪除，并添加新文檔，即使無法訪問他，舊的文檔也不會立即消失，Elasticsearch會在后臺清理已經刪除的文檔，同時索引更多的數據。

Required authorization

索引的read權限

Path parameters 路徑參數

• index String required 索引名稱
• id String required 文檔唯一標識

Query parameters 查詢參數

• preference String 首選項
  應該在哪個節點或分片上執行，默認再分片和副本間隨機變化
  如果設置為_local,則操作優先中本地分配的分片上執行。如果設置為自定義值，則該值用于確保相同的自定義值用于相同的分片，有助于在不同的刷新狀態下訪問不同分片時進行“跳躍值”操作。例如可以使用web session ID或者用戶名。
• realtime boolean
  true的時候請求是實時的，而不是近實時的。
• refresh Boolean
  如果是true，會在請求檢索文檔之前刷新相關分片。需要考慮并確認這個操作不會給系統造成過重負載。
• routing String
  用于將操作路由到特定分片的自定義值
• _source Boolean | String | Array[String]
  標識返回是否包含_source字段（true或false）或列出要返回的字段
• _source_excludes String | Array[String]
  從響應中排除的源字段。也可以從_source_includes查詢參數中指定的子集中排除字段。如果_source是false，就會忽略這個參數。
• _source_exclude_vectors Boolean 在9.2.0版本中添加
  是否應從_source排除向量
• _source_includes String,Array[String]
  要包含著響應中的源字段的列表。如果使用這個字段，就會僅返回這些源字段。也可以使用_source_excludes，在子集中繼續排除，如果_source是false，就會忽略這個參數。
• stored_fields String|Array[String]
  以逗號分隔存儲的字段列表，作為命中的一部分返回。如果沒有指定字段，那么響應中不包含任何存儲字段。如果指定了這個字段，則_source字段默認為false。使用stored_fields只能檢索葉子字段。不能返回對象字段；如果指定對象字段就會請求失敗。
• version Number 版本號
  用于并發控制的版本號，當文檔版本等于當前查詢指定的版本，才能檢索出文檔
• version_type String
  值可以是
  • internal, 內部控制，從1開始，每次更新或刪除時遞增
  • external, 版本高于文檔版本或者文檔不存在的時候才能編輯文檔
  • external_gte, 版本高于或等于文檔版本或者文檔不存在的時候才能編輯文檔，需要謹慎使用，可能會導致數據丟失
  • force 已經棄用，因為可能導致 主分片和副本分片分離

Response 響應

200

• _index String Boolean Required
• fields Object 如果 stored_fields 參數設置為 true ，并且 found 為 true ，則它包含存儲在索引中的文檔字段。
• _ignored Array[String]
• found Boolean Required
• _primary_term Number 索引分配給文檔的主要標識符
• _routing String 顯示路由[如果設置]
• _seq_no Number
• _source Object 如果found是true，則包含json格式的文檔數據，如果_source參數設置為false或者stored_fields是true，就排除這個參數
• _version 版本號

示例

GET my-index-000001/_doc/1?stored_fields=tags,counter

響應

{"_index": "my-index-000001","_id": "1","_version": 4,"_seq_no": 3,"_primary_term": 1,"found": true
}

Create or Update a document in an index

格式

POST /{index}/_doc/{id}
POST /{index}/_doc
PUT /{index}/_doc/{id}

將 JSON 文檔添加到指定的數據流或索引，并使其可搜索。如果目標是索引且文檔已存在，則請求會更新文檔并增加其版本。

不能使用此API發送數據流現有文檔的更新請求。

如果啟用了安全功能。就需要對目標數據流，索引或索引別名具有以下的索引權限：

• 使用 PUT /<target>/_doc/<_id> 請求格式添加或者覆蓋文檔，必須要有create、index或write索引權限
• 使用 POST /<target>/_doc/ 請求格式添加文檔，必須要有create、create_doc、index或write索引權限
• 如果需要自動創建數據流或者索引，必須要有auto_config、create_index或者manage 索引權限

自動創建數據流需要啟用數據流的匹配索引模版

索引成功返回時，副本分片可能不是完全啟動的，可以通過參數 wait_for_active_shards 修改默認行為。

Automatically create data streams and indices 自動創建數據流和索引

如果請求的目標不存在，并且有data_stream定義的索引模版匹配，索引會自動創建數據流

如果目標不存在，并且沒有數據流模版匹配，就會自動創建索引，并且應用任何匹配的索引模版

如果不存在映射，索引會自動創建映射，默認情況下，新字段會添加到映射里面

自動創建索引由action.auto_create_index控制,true可以創建任意索引,false是禁止, 可以使用多個逗號分割的模式,使用 + 或 - 前綴來標記允許或禁用模式.直接使用列表代表不允許.

action.auto_create_index 只影響索引的自動創建,不影響數據流的創建

optimistic concurrency control 樂觀并發控制

索引可以設置為有條件的，并且僅當對文檔的最后一次分配修改了if_seq_no和if_primary_term參數指定的序列號和主術語（primary term）才會執行索引操作。如果檢測到不匹配，就會導致VersionConflictException并且狀態碼409。

Routing 路由

默認情況下分片的位置(或者路由)是使用文檔的ID值的散列來控制.對于顯示的控制,可以使用routing參數來顯式控制,直接指定路由器使用的hash函數的值.
在使用顯示映射時,可以使用_routing參數來指定索引操作從文檔中獲取路由值,但是需要額外解析文檔(代價也比較小).如果定義了_routing設置,并且設置為必須,如果沒有提供或提取路由值,那么索引操作就會失敗.

數據流不支持自定義路由除非在模版中啟用 allow_custom_routing設置創建的

Distributed 分布式

索引操作根據主分片的路由定位到主分片,并且在該分片的實際節點上執行.在主分片完成操作后,如果需要,把更新分發到合適的副本.

Active shards 激活分片

為了提高系統的寫入的彈性,可以將索引的操作配置為在操作之前等待一定數量的活動分片副本.如果沒有達到數量,寫入操作必須等待或者重試,直到需要的分片副本已經啟動或發送超時.默認情況下寫操作只會等待主分片處于活動狀態后才會繼續(wait_for_active_shards是1).可以通過index.write.wait_for_active_shards參數進行覆蓋配置配置.也可以直接在請求中攜帶參數wait_for_active_shards

No operation (noop) update

在使用API更新文檔的時候,如果文檔沒有改變,也總是會創建文檔的新副本,如果不能接受,那么在使用 _update API的時候設置detect_noop為true.但是創建文檔的時候這個選項是不可用的,因為沒有舊的 文檔,就不能進行比較.

每個被索引的文檔都有一個版本號。默認情況下使用內部版本控制，從1開始，隨著每次更新（包括刪除）遞增。版本號也可以使用外部的值，這個時候應該把version_type設置為external。提供的值必須大于等于0小于9.2e+18的長整型數值.

版本控制是完全實時的，搜索是近實時的，如果沒有提供版本，那么就不會進行任何版本檢查

當使用外部版本類型時，系統檢查傳遞給索引請求的版本號是否大于當前存儲文檔的版本。如果大于，對文檔進行索引并且使用新的版本號。如果小于或者等于，就會發生版本沖突，索引操作失敗。

PUT my-index-000001/_doc/1?version=2&version_type=external
{"user": {"id": "elkbee"}
}

上面的示例會正常執行，但是當重復執行的時候，因為提供的版本號不大于當前文檔的版本，就會出現版本沖突，http 409狀態

Path parameters 路徑參數

• index String 必須
  要定位的數據流或者索引的名稱，如果目標不存在，并且與具有data_stream定義的索引模版的名稱或者通配符（*）模式匹配，則此請求就會創建數據流。如果模版不存在，且沒有對應的數據流模版，那么就會創建索引。可以使用解析索引檢查索引是否存在。
• id String required
  文檔的唯一標識。如果需要自動生成文檔id，可以生路id字段進行創建如 POST /<target>/_doc/并省略這個參數。

Query parameters 查詢參數

• if_primary_term Number
  只有在主分片任期（primary term）與請求中的值完全匹配的時候，才會執行這次操作，否則拒絕。
• if_seq_no Number
  僅當文檔具有此序號時才執行此操作
• include_source_on_error Boolean
  當值為ture，當索引文檔出現解析錯誤（parsing error）的時候，錯誤消息會包含整個文檔的_source內容
  當值為false，錯誤信息不包含_source，只顯示錯誤原因。

為什么有這個選項，1. 方便調試，2. 安全考慮，文檔中有敏感信息，可以設置為false，3. 性能考慮可以設置為false減少響應數據量

• op_type String
  設置為create，僅當文檔不存在的時候索引文檔，如果指定了_id的文檔已經存在了，索引操作將失敗。操作跟 <index>/_create一致。如果指定了文檔的id，則參數默認為index。否則默認為create。如果請求的目標是數據流，則需要op_type為create
  取值 為 【 index ｜ create 】，分別代表覆蓋任何已經存在的文檔，僅索引不存在的文檔。
• pipeline String
  用于預處理傳入文檔的管道標識符。如果指定了默認的提取管道，則將該值設置為_none會關閉此請求的默認提取管道。如果配置了最終管道，則一直會保持運行。
• refresh String
  如果true,Elasticsearch會刷新受影響的分片，只對搜索可見。如果是wait_for，等待刷新以使這個操作可以提供搜索。如果是false，就不刷新。
• routing String
  用于將操作路由到也定的分片的自定義值
• timeout String
  請求等待以下操作的時間；自動索引創建、動態映射更新和等待活動分片。默認值是1min，保證Elasticsearch值失敗之親啊的至少等待超時。實際時間可能會更長，當發生多個等待的時候。

可以設置值是 0 代表不等待, -1 一直等待

• version Number
  跟之前的一樣是非負的長整數
• version_type String
  值可以是
  • internal, 內部控制，從1開始，每次更新或刪除時遞增
  • external, 版本高于文檔版本或者文檔不存在的時候才能編輯文檔
  • external_gte, 版本高于或等于文檔版本或者文檔不存在的時候才能編輯文檔，需要謹慎使用，可能會導致數據丟失
  • force 已經棄用，因為可能導致 主分片和副本分片分離
• wait_for_active_shards Number | string
  批量操作必須等待至少多少個分片副本處于活動狀態。可以設置為all或者任意正整數,最大是索引中分片副本數(number_of_replicas+1),默認是1,等待每個主分片處于活動狀態.
• require_alias Boolean
  true 代表必須是索引的別名
• require_data_stream Boolean
  true 代表操作的目標必須是數據流(已經存在或創建)

Body Required

Object

Responses

200

• _id String Required
• _index String Required
• _primary_term number. 操作成功的時候有值,操作的主分片的任期號
• result string. 操作的結果,值可能出現的范圍:[created | updated | deleted | not_found | noop]
• _seq_no number
• _shards Object.
  • failed number Required
  • successful number Required
  • total number Required
  • failures Array[Object]
    • index String
    • node String
    • reason Object Required
      • type String Required
      • reason String | Null
      • stack_trace String
      • cased_by Object
      • root_cause Array[Object]
      • suppressed Array[Object]
    • shard Number Required
    • status String
  • skipped number
• _version number
• forced_refresh boolean

Delete a document 刪除文檔

格式

DELETE /{index}/_doc/{id}

從索引中刪除文檔

注意：不能直接將刪除請求發送到數據流，要刪除數據流中的文檔，必須是包含該文檔支持的索引為目標

Optimistic concurrency control 樂觀并發控制

刪除可以設置為有條件的，并且僅當對文檔的最后一次分配修改了if_seq_no和if_primary_term參數指定的序列號和主術語（primary term）才會執行索引操作。如果檢測到不匹配，就會導致VersionConflictException并且狀態碼409。

Versioning 版本控制

每個被索引的文檔都有一個版本號。刪除文檔的時候，可以指定版本，以確保嘗試刪除的相關文檔實際上正在被刪除，并且在此期間沒有更該。在文檔上的每個寫入操作（包括刪除）都會導致版本遞增。已刪除的文檔的版本號在刪除后短時間仍然可用，以便控制并發。已經刪除的文檔保持可用時間有index.gc_deletes索引設置決定。

Routing 路由

如果在索引期間指定了路由，則還需要指定路由才能刪除文檔。
如果_routing映射設置為required并且未指定路由值，那么執行刪除文檔的時候會拋出RoutingMissException并拒絕請求。

DELETE /my-index-000001/_doc/1?routing=shard-1

這個請求就會刪除ID為1的文檔，但是會根據用戶指定的路由，如果指定的路由不正確，就不會刪除。

Distributed 分布式

刪除操作hash到對應的分片ID,然后重定向到這個分片的.在主分片完成操作后,如果需要,把更新分發到對應分片副本.

Required authorization 所需權限

• Index privileges： delete

Path parameters 路徑參數

• index String Required
• id String Required

Query parameters 查詢參數

• if_primary_term Number 主分片版本號一致才執行
• if_seq_no Number 當文檔的序列化是這個值的時候才執行
• refresh String
  如果為 true，Elasticsearch 將刷新受影響的分片，使此作對搜索可見。如果 wait_for，它會等待刷新以使此作對搜索可見。如果為 false，則刷新不執行任何作。
• routing String
  用于將路由到特定分片的自定義值。
• timeout String
  等待活動分片的時間段
  參數適用于在刪除操作運行的時候分配給執行操作的主分片可能不可用的情況。造成這種情況的一般原因是主分片正在從存儲中恢復或正在重定位。默認情況下，時間是1min，然后會失敗響應錯誤。
  可以使用 0 代表不等待, -1 一直等待
• version Number
  用于并發控制的顯式版本號。它必須與文檔的當前版本匹配，請求才能成功。
• version_type String
  值可以是
  • internal, 內部控制，從1開始，每次更新或刪除時遞增
  • external, 版本高于文檔版本或者文檔不存在的時候才能編輯文檔
  • external_gte, 版本高于或等于文檔版本或者文檔不存在的時候才能編輯文檔，需要謹慎使用，可能會導致數據丟失
  • force 已經棄用，因為可能導致 主分片和副本分片分離
• wait_for_active_shards Number | string
  批量操作必須等待至少多少個分片副本處于活動狀態。可以設置為all或者任意正整數,最大是索引中分片副本數(number_of_replicas+1),默認是1,等待每個主分片處于活動狀態.

Response

200

• _id String Required
• _index String Required
• _primary_term Number 分配給索引的主分片的年代號 【自己翻譯的，主分片在變更的時候這序號會遞增，防止數據變臟】
• result String Required 值是 create、updated、deleted、not_found、noop
• _seq_no Number
• _shards Object Object
  • failed Number Required
  • successful Number Required
  • total Number Required
  • failures Array[object]
    • index String
    • node String
    • reason Object Required
      • type String Required
      • reason String | Null
      • stack_trace String
      • cased_by Object
      • root_cause Array[Object]
      • suppressed Array[Object]
      • shard Number Required
      • status String
    • skipped number
• _version number
• forced_refresh boolean

DELETE /my-index-000001/_doc/1

{"_shards": {"total": 2,"failed": 0,"successful": 2},"_index": "my-index-000001","_id": "1","_version": 2,"_primary_term": 1,"_seq_no": 5,"result": "deleted"
}

Check a document 檢查文檔【是否存在】

格式

HEAD /{index}/_doc/{id}

檢測文檔是否存在，例如檢查_id為0的文檔是否存在

HEAD my-index-000001/_doc/0

如果文檔存在就會返回狀態碼200，不存在返回狀態碼404

Version support 版本控制

當且版本等于指定版本的時候才會返回

在內部，Elasticsearch將舊的版本設置為已刪除，并且添加一個全新的文檔。舊文檔的版本不會立即消失，盡管無法訪問他。Elasticsearch會在后臺清理已經刪除的文檔。

Path parameter 路徑參數

• index String Required 以逗號分割的數據流，索引和別名列表。支持通配符（*）
• id String Required 文檔的唯一標識

Query parameter 查詢參數

• preference String
  應在哪個節點或分片上執行。默認情況在分片和副本之間隨機。
  如果設置為_local,則操作優先中本地分配的分片上執行。如果設置為自定義值，則該值用于確保相同的自定義值用于相同的分片，有助于在不同的刷新狀態下訪問不同分片時進行“跳躍值”操作。例如可以使用web session ID或者用戶名。
• realtime boolean
  true的時候請求是實時的，而不是近實時的。
• refresh Boolean
  如果是true，會在請求檢索文檔之前刷新相關分片。需要考慮并確認這個操作不會給系統造成過重負載。
• routing String
  用于將操作路由到特定分片的自定義值
• _source Boolean | String | Array[String]
  標識返回是否包含_source字段（true或false）或列出要返回的字段
• _source_excludes String | Array[String]
  從響應中排除的源字段。也可以從_source_includes查詢參數中指定的子集中排除字段。如果_source是false，就會忽略這個參數。
• _source_exclude_vectors Boolean 在9.2.0版本中添加
  是否應從_source排除向量
• _source_includes String,Array[String]
  要包含著響應中的源字段的列表。如果使用這個字段，就會僅返回這些源字段。也可以使用_source_excludes，在子集中繼續排除，如果_source是false，就會忽略這個參數。
• stored_fields String|Array[String]
  以逗號分隔存儲的字段列表，作為命中的一部分返回。如果沒有指定字段，那么響應中不包含任何存儲字段。如果指定了這個字段，則_source字段默認為false。使用stored_fields只能檢索葉子字段。不能返回對象字段；如果指定對象字段就會請求失敗。
• Version Number 版本號
  用于并發控制的版本號，當文檔版本等于當前查詢指定的版本，才能檢索出文檔
• version_type String
  值可以是
  • internal, 內部控制，從1開始，每次更新或刪除時遞增
  • external, 版本高于文檔版本或者文檔不存在的時候才能編輯文檔
  • external_gte, 版本高于或等于文檔版本或者文檔不存在的時候才能編輯文檔，需要謹慎使用，可能會導致數據丟失
  • force 已經棄用，因為可能導致 主分片和副本分片分離

Response 響應

200

Delete document 刪除文檔

格式

POST /{index}/_delete_by_query

刪除指定查詢匹配的文檔

如果啟用了Elasticsearch安全功能，必須對目標數據流、索引和別名具有以下索引權限

• read
• delete 或 write
  可以使用與查詢一樣的語法在請求URI或者請求正文中指定查詢條件。當提交通過查詢刪除文檔的請求時，Elasticsearch會開始處理獲取數據流或索引的快照，并使用內部版本控制刪除匹配的文檔。如果文檔在快照和處理刪除之間發生改變，則會導致版本沖突，并且刪除失敗。

注意版本等于0的文檔無法使用“通過查詢刪除”刪除，因為內部版本控制不支持0作為有效版本號

在處理刪除查詢請求時，Elasticsearch會按順序執行多個搜索請求，以查找要刪除的所有匹配文檔。對每批匹配文檔執行批量刪除請求。如果搜索或批量刪除請求被拒絕，則請求最多重試10次，并且重試的時間間隔會按照指數退避（exponential backoff）方式遞增。如果達到最大重試次數，就會停止處理，并在響應中返回所有失敗的請求。任何成功刪除的請求仍會保留，不會回退。

你可以通過 conflicts 參數設置為 proceed，選擇在遇到版本沖突（version conflicts）時繼續執行并統計沖突數量，而不是立即停止并返回錯誤。如果選擇計算版本沖突，那么這個刪除操作可能會嘗試從數據源刪除的文檔數會超過max_docs限制，直到成功刪除了max_docs個文檔或者已經遍歷所有文檔。

Throttling delete requests 限制刪除請求

如果要控制查詢刪除的批量刪除請求的速率，可以把requests_per_second設置為任何正十進制數字。這會為每個批次填充等待時間以限制速率。將requests_per_second設置為-1可以禁用限制。

限制使用批處理之間的等待時間，以便可以為內部scroll請求提供一個超時，該超時將請求等待時間（padding time）考慮在內.填充時間是batch size除以requests_per_second與寫入所花費的時間之間的差值。默認情況下，批量處理大小為1000條數據，如果將requests_per_second設置為500：

target_time = 1000 / 500 （per second = 2 seconds）
wait_time = target_time - write_time = 2 seconds - 0.5 seconds = 1.5 seconds

由于批次是作為單個_bulk,因此大批量會導致Elasticsearch創建許多請求，并且在開發下一組之前等待。這個是突發而不是平滑。

Slicing 切片

按查詢刪除支持切片并滾動以并行化刪除過程。這樣可以提高效率，并提供一種將請求分解為更小部分的便捷方法。

將切片設置為auto,允許Elasticsearch選擇要使用的切片（slice）數量。此設置將每個分片(shard)分配一個切片，但是有最大限制。如果有多個源數據流或索引，他將根據分片數量最少的索引或底層索引（backing index）來選擇切片數量。將切片添加到“通過查詢刪除”作為創建子請求，因此他有一些特殊的行為。

• 可以在任務API中查看這些請求，這些子請求是具有切片的請求的任務的子任務
• 獲取具有切片請求的任務狀態僅包含已經完成的切片的狀態
• 這些子請求（sub-requests）是可以單獨訪問/操作的，比如可以單獨取消他們，或者重新調整他們的限速（rethrottling）
• 重新限流請求 slices將按比例重新限流未完成的子請求
• 取消slices將取消每個子請求
• 由于slices的性質，每個子請求不會得到完全均勻的文檔分配，所有文檔都將被處理，但是某些切片會比別的切片更大。預期較大的切片會有更均勻的分布。
• 在帶有slices的請求中，參數 requests_per_second和 max_doc將按比例分配給每個子請求。結合之前關于分配可能不均勻這一點，你應該得出結論，使用max_docs和slices結合可能不能導致恰好刪除 max_docs整個文檔。
• 每個子請求都會得到data stream或索引略有不同的快照，盡管這些快照是在大約相同時間獲取的。

如果你是手動切片或者以其他方式調整自動切片，需要注意下面幾點

• 查詢性能在切片數量等于索引或底層索引的分片數量的時候最高。如果數字很大（例如500），應該選擇比較小的數字，因為過多的 slices會影響性能，將slices的數量設置為高于分片的數量的值通常不會提高效率，反而會增加額外開銷。
• 刪除性能隨可用資源的切片數量線性提高

查詢性能還是刪除性能在運行時占主導地位，取決于重新索引的文檔和集群資源

Cancel a delete by query operation 取消刪除查詢操作

任何刪除查詢操作都可以通過API進行取消

POST _tasks/r1A2WoRbTwKZ516z6NEs5A:36619/_cancel

可以通過獲取任務的API來找到任務ID.
取消操作應該迅速完成，但是可能需要幾秒執行時間。獲取任務狀態的API會繼續列出通過刪除查詢的任務，直達該任務檢查到自己已經被取消并且自動終止。

Required authorization 需要授權

• Index privileges： read、delete

Path parameters 路徑參數

• index String|Array[String] Required

要搜索的數據流、索引和索引別名的逗號分割列表，支持通配符（*），要搜索所有數據流或索引，可以省略參數或使用*或者使用 _all

Query parameters 查詢參數

• allow_no_indices Boolean
  如果是false,當任何通配符表達式、索引別名或_all值僅針對缺失或已經關閉的索引時，，請求返回錯誤。即使請求針對其他開放索引，規則也適用。如果一個索引是以 foo 開頭，但是沒有以 bar 開頭的索引，那么針對 foo*,bar* 請求將會返回錯誤.
• analyzer String 分析器
  用于查詢字符串的分析器，當且僅當指定了 q查詢字符串參數時才可以使用。
• analyze_wildcard Boolean
  如果是 true則分析通配符和前綴查詢。當且僅當指定了 q查詢字符串參數時才可以使用。
• conflicts String
  如果通過查詢刪除的時候遇見版本沖突該怎么辦：abort 還是 proceed
  Supported values include 支持的值包括
  • abort：如果存在沖突，就停止重新索引
  • proceed： 即使純真沖突也繼續重新索引
• default_operator String
  查詢字符串默認運算符：AND 或 OR 。當且僅當指定了 q查詢字符串參數時才可以使用。
• df String 當查詢的字符串中為提供字段前綴時，用作默認字段的字段。當且僅當指定了 q查詢字符串參數時才可以使用。
• expand_wildcards String ｜ Array[String] 通配符模式可以匹配的索引的類型。如果請求可以定位數據流。支持逗號分隔的值，eg open,hidden.支持的值包括：
  • all ： 匹配任何的數據流和索引，包含隱藏的數據流和索引
  • open： 匹配開放的非隱藏的索引和數據流
  • closed；匹配已關閉的非隱藏索引。也匹配任意非隱藏的數據流。數據流無法關閉。
  • hidden：匹配隱藏的數據流和隱藏的索引。必須與 open、close或 both結合使用
  • none: 不接受通配符表達式
• form Number 跳過指定數量的文檔
• ignore_unavailable Boolean：忽略不可用，如果是false,當請求針對缺失或關閉的索引時，返回錯誤。
• lenient Boolean：如果是true,查詢字符串基于格式的查詢失敗（例如，向數字字段提供文本）將被忽略。當且僅當指定了 q查詢字符串參數時才可以使用。
• max_docs Number ：需要處理的最大文檔數。默認所有文檔。如果設置小于或等于scroll_size值，則不會使用滾動來檢索操作的結果。
• preference String：執行操作的節點或分片，默認是隨機的
• refresh Boolean：
  如果為 true，Elasticsearch會在請求完成后刷新delete by查詢中涉及的所有分片。這個和delete API的refresh參數不同，后者僅刷新收到刪除請求的分片。并且這里不支持 wait_for。
• request_cache Boolean： 如果是true，表示請求中使用請求緩存。默認是索引級別的設置。
• requests_per_second Number：每秒請求數量，請求的限制（以每秒子請求數量計算）
• routing String：用于將操作路由到特定分片的自定義值。
• q String：Lucene 查詢字符串語法中的查詢。
• scroll String：保留搜索上下文以進行滾動的時間段，可以是 -1 或 0
• scroll_size Number：支持該操作的滾動請求的大小。
• search_timeout String：每次搜索請求的顯式超時時間，默認無超時。可以為0或-1
• search_type String: 搜索操作的類型。可以選query_then_fetch 和 dfs_query_then_fetch
  • query_then_fetch:文檔的打分是基于分片內的本地詞頻和文檔頻率來計算的。這種方式通常更快，但準確性較低
  • dfs_query_then_fetch：使用所有分片中的全局詞頻和文檔頻率對文檔進行評分。這種速度較慢，但更準確。
• slices Number｜String 切片數，可以為auto或數字（該任務應該劃分的切片數）
• sort Array[String] ：以逗號分隔的 <field>:<direction>的列表
• stats Array[String]:用于記錄和統計目的的請求的特定的tag
• terminate_after : 每個分片可收集的最大文檔數。如果查詢達到這個限制，Elasticsearch會提前終止查詢。Elasticsearch會在排序之前收集文檔。需要謹慎使用。Elasticsearch會將此參數應用與處理請求的每個分片。如果可能，請讓Elasticsearch自動執行提前終止。如果請求的目標數據流包含跨很多歌數據層的支持索引，請避免使用這個參數。
• timeout String：每個刪除請求等待活動分片的時間，可以為 -1 或 0
• version Boolean:如果是true則返回文檔版本作為匹配的一部分
• wait_for_active_shards Number|String
  繼續操作之前必須等待至少多少個分片副本處于活動狀態。可以設置為all或者任意正整數,最大是索引中分片副本數(number_of_replicas+1)。timeout值控制每個寫入win各位iu放入哪個粉絲不可用分片的可用時間,值可以是 all 或 index_setting.
• wait_for_completion Boolean
  如果是true,請求會被阻塞，直到操作完成。如果是 false,Elasticsearch會執行一些預檢查，啟動請求，并返回一個任務，可以使用該任務取消或獲取其狀態。Elasticsearch會在 .tasks/task/${taskId}中創建此任務的記錄作為文檔。完成任務后，可以刪除這個任務文檔，以便Elasticsearch回收空間。

Body Required

• max_docs Number： 要刪除的最大文檔數
• query Object：定義Elasticsearch查詢DSL對象
  參考文檔
• slice Object
  • field String：字段路徑或路徑數組。某些API支持在路徑中使用通配符來選擇多個字段
  • id String：Required
  • max Number：Required

Response

200

• batches Number：通過刪除查詢時，滾動查詢（scroll）返回的響應數量
• deleted Number：成功刪除的文檔數量
• failures Array[object]: 如果在過程中出現任何不可恢復的錯誤，就會包含一系列的失敗。如果數組不為空，那么請求由于這些失敗而異常結束。通過查詢刪除是通過批量實現的，任何失敗都會導致整個過程結束，但當前批次的全部失敗都會被收集到該數組，可以使用 conflict選項來方式由于版本沖突而重新索引的結束。
  • cause Object Required：請求失敗的成因和詳細信息，定義了所有錯誤類型的共有屬性，還提供了根據錯誤類型而變化的額外詳細信息。
    • type String Required：錯誤類型
    • reason String ｜ Null
    • stack_trace String ：服務器堆棧跟蹤。僅當請求中包含 error_trace=true參數時才顯示。
    • caused_by Object: 請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
    • root_cause Array｜Object：請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
    • suppressed Array[Object]: 請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
  • id String Required
  • index String Required
  • status Number Required
• noops Number：通過查詢刪除，這個字段的值是0。僅存在以便通過查詢刪除、通過查詢更新和重新索引API返回相同的結構響應。
• request_per_second Number：每秒請求數，通過查詢刪除期間每秒實際運行的請求數量
• retries Object：
  • bulk Number Required：重試的批量操作數量。
  • search Number Required：重試搜索操作的數量
• slice_id Number
• task String
• throttled String：一個持續時間。單位可以是 nanos、micros、ms、s、m、h和d。也可以使用沒有單位的 0 和 -1 表示沒有指定值。
• throttled_unit_millis Number:
• timed_out Boolean: 如果是true一些刪除查詢操作期間運行的請求超時了
• took Number：毫秒的時間單位
• total Number：成功處理的文檔數量
• version_conflicts Number：版本沖突數量

示例
刪除所有文檔

POST /my-index-000001,my-index-000002/_delete_by_query
{"query": {"match_all": {}}
}

刪除一個文檔

POST /my-index-000001,my-index-000002/_delete_by_query
{"query": {"term": {"user.id": "kimchy"}},"max_docs": 1
}

手動切片

POST /my-index-000001,my-index-000002/_delete_by_query
{"slice": {"id": 0,"max": 2},"query": {"range": {"http.response.bytes": {"lt": 2000000}}}
}

自動切片

POST my-index-000001/_delete_by_query?refresh&slices=5
{"query": {"range": {"http.response.bytes": {"lt": 2000000}}}
}

響應

{"took" : 147,"timed_out": false,"total": 119,"deleted": 119,"batches": 1,"version_conflicts": 0,"noops": 0,"retries": {"bulk": 0,"search": 0},"throttled_millis": 0,"requests_per_second": -1.0,"throttled_until_millis": 0,"failures" : [ ]
}

Throttle a deleted by query operation 限制刪除查詢操作

格式

POST /_delete_by_query/{task_id}/_rethrottle

更改刪除查詢請求數量修改，重新限流加速查詢立即生效，而重新限流減速查詢在完成當前批次之后生效，防止滾動超時。

Path parameters 路徑參數

• task_id String Required

Query parameters

• requests_per_second Number:請求的速率限制，以每秒的子請求數表示。如果要禁用速率限制可以設置為-1

Response

200

• node_failures Array[Object]
  請求失敗的詳細信息。此類定義了所有錯誤類型共有的屬性。此外，還提供了根據錯誤類型而變化的額外詳細信息。
  • type String Required：錯誤類型
  • reason String ｜ Null
  • stack_trace String ：服務器堆棧跟蹤。僅當請求中包含 error_trace=true參數時才顯示。
  • caused_by Object: 請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
  • root_cause Array｜Object：請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
  • suppressed Array[Object]: 請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
• task_failures Array[Object]
  • task_id Number Required
  • node_id String Required
  • status String Required
  • type String Required：錯誤類型
  • reason String ｜ Null
  • stack_trace String ：服務器堆棧跟蹤。僅當請求中包含 error_trace=true參數時才顯示。
  • caused_by Object: 請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
  • root_cause Array｜Object：請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
  • suppressed Array[Object]: 請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
• nodes Object: 節點按任務分組，如果 group by 設置為 node （默認值）
  • name String
  • transport_address String
  • host String 主機
  • ip String
  • roles Array[String]
  • attribute Object
  • tasks Object Required
    • action String Object
    • cancelled Boolean
    • cancellable Boolean Required
    • description String: 可讀文本，用于表示任務正在執行的搜索請求。例如 可能表示搜索任務正在執行的搜索請求。不同類型的任務有不同的描述。例如 _reindex 包含源和目標。或 _bulk僅包含請求數量和目標索引。但是有很多請求是空的描述，有些請求的描述信息比較難獲得且沒有什么幫助。
    • headers Object Required
    • id Number String
    • node String Required
    • running_time String 運行時間 一個持續時間。單位可以是 nanos 、 micros 、 ms (毫秒)、 s (秒)、 m (分鐘)、 h (小時) 和 d (天)。也接受沒有單位的 “0” 和表示未指定值的 “-1”。
    • running_time_in_nanos Number 運行時間的納秒數
    • start_time_in_millis Number 毫秒時間
    • status Object 任務內部的當前狀態，不同任務的狀態可能不同。 格式也可能有所不同。 雖然目標是保持特定任務的狀態在版本之間保持一致，但這并不總是可能的，因為有時實現方式會發生變化。 對于特定請求的狀態，字段可能會被移除，因此你在狀態上的任何解析在次要版本中可能會失效。
    • type String Required
    • parent_task_id String
  • tasks Array[Object] | Object
    • action String Object
      • cancelled Boolean
      • cancellable Boolean Required
      • description String: 可讀文本，用于表示任務正在執行的搜索請求。例如 可能表示搜索任務正在執行的搜索請求。不同類型的任務有不同的描述。例如 _reindex 包含源和目標。或 _bulk僅包含請求數量和目標索引。但是有很多請求是空的描述，有些請求的描述信息比較難獲得且沒有什么幫助。
      • headers Object Required
      • id Number String
      • node String Required
      • running_time String 運行時間 一個持續時間。單位可以是 nanos 、 micros 、 ms (毫秒)、 s (秒)、 m (分鐘)、 h (小時) 和 d (天)。也接受沒有單位的 “0” 和表示未指定值的 “-1”。
      • running_time_in_nanos Number 運行時間的納秒數
      • start_time_in_millis Number 毫秒時間
      • status Object 任務內部的當前狀態，不同任務的狀態可能不同。 格式也可能有所不同。 雖然目標是保持特定任務的狀態在版本之間保持一致，但這并不總是可能的，因為有時實現方式會發生變化。 對于特定請求的狀態，字段可能會被移除，因此你在狀態上的任何解析在次要版本中可能會失效。
      • type String Required
      • parent_task_id String

Get a document‘s source 獲取文檔源

格式

GET /{index}/_source/{id}

可以使用源過濾參數來控制返回 _source 的哪些部分

GET my-index-000001/_source/1/?_source_includes=*.id&_source_excludes=entities

_source 字段說明

Path parameters 路徑參數

• index String Required
• id String Required

Query parameters 查詢參數

• preference String 首選項
  應該在哪個節點或分片上執行，默認再分片和副本間隨機變化
  如果設置為_local,則操作優先中本地分配的分片上執行。如果設置為自定義值，則該值用于確保相同的自定義值用于相同的分片，有助于在不同的刷新狀態下訪問不同分片時進行“跳躍值”操作。例如可以使用web session ID或者用戶名。
• realtime boolean
  true的時候請求是實時的，而不是近實時的。
• refresh Boolean
  如果是true，會在請求檢索文檔之前刷新相關分片。需要考慮并確認這個操作不會給系統造成過重負載。
• routing String
  用于將操作路由到特定分片的自定義值
• _source Boolean | String | Array[String]
  標識返回是否包含_source字段（true或false）或列出要返回的字段
• _source_excludes String | Array[String]
  從響應中排除的源字段。也可以從_source_includes查詢參數中指定的子集中排除字段。如果_source是false，就會忽略這個參數。
• _source_exclude_vectors Boolean 在9.2.0版本中添加
  是否應從_source排除向量
• _source_includes String,Array[String]
  要包含著響應中的源字段的列表。如果使用這個字段，就會僅返回這些源字段。也可以使用_source_excludes，在子集中繼續排除，如果_source是false，就會忽略這個參數。
• stored_fields String|Array[String]
  以逗號分隔存儲的字段列表，作為命中的一部分返回。如果沒有指定字段，那么響應中不包含任何存儲字段。如果指定了這個字段，則_source字段默認為false。使用stored_fields只能檢索葉子字段。不能返回對象字段；如果指定對象字段就會請求失敗。
• version Number 版本號
  用于并發控制的版本號，當文檔版本等于當前查詢指定的版本，才能檢索出文檔
• version_type String
  值可以是
  • internal, 內部控制，從1開始，每次更新或刪除時遞增
  • external, 版本高于文檔版本或者文檔不存在的時候才能編輯文檔
  • external_gte, 版本高于或等于文檔版本或者文檔不存在的時候才能編輯文檔，需要謹慎使用，可能會導致數據丟失
  • force 已經棄用，因為可能導致 主分片和副本分片分離

Responses

200

Check for a document source

格式

HEAD /{index}/_source/{id}

檢查文檔源是否存在索引中

HEAD my-index-000001/_source/1

如果文檔在映射中禁用，則其源不可用。

Required authorization 所需權限

• index privileges: read

_source 字段說明

Path parameters 路徑參數

• index String Required
• id String Required

Query parameters 查詢參數

• preference String 首選項
  應該在哪個節點或分片上執行，默認再分片和副本間隨機變化
  如果設置為_local,則操作優先中本地分配的分片上執行。如果設置為自定義值，則該值用于確保相同的自定義值用于相同的分片，有助于在不同的刷新狀態下訪問不同分片時進行“跳躍值”操作。例如可以使用web session ID或者用戶名。
• realtime boolean
  true的時候請求是實時的，而不是近實時的。
• refresh Boolean
  如果是true，會在請求檢索文檔之前刷新相關分片。需要考慮并確認這個操作不會給系統造成過重負載。
• routing String
  用于將操作路由到特定分片的自定義值
• _source Boolean | String | Array[String]
  標識返回是否包含_source字段（true或false）或列出要返回的字段
• _source_excludes String | Array[String]
  從響應中排除的源字段。也可以從_source_includes查詢參數中指定的子集中排除字段。如果_source是false，就會忽略這個參數。
• _source_exclude_vectors Boolean 在9.2.0版本中添加
  是否應從_source排除向量
• _source_includes String,Array[String]
  要包含著響應中的源字段的列表。如果使用這個字段，就會僅返回這些源字段。也可以使用_source_excludes，在子集中繼續排除，如果_source是false，就會忽略這個參數。
• stored_fields String|Array[String]
  以逗號分隔存儲的字段列表，作為命中的一部分返回。如果沒有指定字段，那么響應中不包含任何存儲字段。如果指定了這個字段，則_source字段默認為false。使用stored_fields只能檢索葉子字段。不能返回對象字段；如果指定對象字段就會請求失敗。
• version Number 版本號
  用于并發控制的版本號，當文檔版本等于當前查詢指定的版本，才能檢索出文檔
• version_type String
  值可以是
  • internal, 內部控制，從1開始，每次更新或刪除時遞增
  • external, 版本高于文檔版本或者文檔不存在的時候才能編輯文檔
  • external_gte, 版本高于或等于文檔版本或者文檔不存在的時候才能編輯文檔，需要謹慎使用，可能會導致數據丟失
  • force 已經棄用，因為可能導致 主分片和副本分片分離

Responses

200

Get multiple documents 獲取多個文檔

格式

GET /_mget
POST /_mgetGET /{index}/_mget
POST /{index}/_mget

從一個或多個索引中通過 ID 獲取多個 JSON 文檔。如果在請求 URI 中指定了索引，則只需在請求體中指定文檔 ID。為確保快速響應，如果一個或多個分片失敗，此多獲取（mget）API 將返回部分結果。

Filter source fields 過濾源字段

默認情況下，每個文檔都會返回 _source 字段（如果存儲了）。使用 _source 和 _source_include 或 source_exclude 屬性來過濾特定文檔返回的字段。您可以在請求 URI 中包含 _source 、 _source_includes 和 _source_excludes 查詢參數，以指定在沒有每個文檔指令時使用的默認值。

Get stored fields 獲取存儲字段

使用 stored_fields 屬性來指定您要檢索的存儲字段集。任何未存儲的請求字段將被忽略。您可以在請求 URI 中包含 stored_fields 查詢參數，以指定在沒有每個文檔指令時使用的默認值。

Required authorization 所需權限

• index privileges: read

Path parameters 路徑參數

• id String Required
  檢索文檔時使用的索引名稱，當指定 ids 時，或者當 docs 數組中的文檔未指定索引時。

Query parameters 查詢參數

• preference String 首選項
  應該在哪個節點或分片上執行，默認再分片和副本間隨機變化
  如果設置為_local,則操作優先中本地分配的分片上執行。如果設置為自定義值，則該值用于確保相同的自定義值用于相同的分片，有助于在不同的刷新狀態下訪問不同分片時進行“跳躍值”操作。例如可以使用web session ID或者用戶名。
• realtime boolean
  true的時候請求是實時的，而不是近實時的。
• refresh Boolean
  如果是true，會在請求檢索文檔之前刷新相關分片。需要考慮并確認這個操作不會給系統造成過重負載。
• routing String
  用于將操作路由到特定分片的自定義值
• _source Boolean | String | Array[String]
  標識返回是否包含_source字段（true或false）或列出要返回的字段
• _source_excludes String | Array[String]
  從響應中排除的源字段。也可以從_source_includes查詢參數中指定的子集中排除字段。如果_source是false，就會忽略這個參數。
• _source_exclude_vectors Boolean 在9.2.0版本中添加
  是否應從_source排除向量
• _source_includes String,Array[String]
  要包含著響應中的源字段的列表。如果使用這個字段，就會僅返回這些源字段。也可以使用_source_excludes，在子集中繼續排除，如果_source是false，就會忽略這個參數。
• stored_fields String|Array[String]
  以逗號分隔存儲的字段列表，作為命中的一部分返回。如果沒有指定字段，那么響應中不包含任何存儲字段。如果指定了這個字段，則_source字段默認為false。使用stored_fields只能檢索葉子字段。不能返回對象字段；如果指定對象字段就會請求失敗。

Body Required

• docs Array[Object]
  您要檢索的文檔。如果請求 URI 中沒有指定索引，則必需。
  • _id String Required
  • _index String
  • routing String
  • _source Boolean | Object 如果是boolean 值包含 stored_fields、version、version_type
  • ids String | Array[String]

Response

200

• docs Array[Object] 響應包含一個 docs 數組，其中包含按請求中指定的順序排列的文檔。返回的文檔結構與 get API 返回的結構相似。如果獲取特定文檔時失敗，則用錯誤信息替換該文檔。
  如果是成功請求
  • _index String Required
  • fields Object : 如果 stored_fields 參數為true 且 found = true，就包含索引中存儲的文檔字段。
  • _ignored Array[String]
  • found Boolean Required
  • _id String Required
  • _primary_term number. 操作成功的時候有值,操作的主分片的任期號
  • _routing String 顯示路由
  • _seq_no Number
  • _source Object 如果 found 等于 true ，它包含格式為 JSON 的文檔數據。如果 _source 參數設置為 false 或 stored_fields 參數設置為 true ，則會被排除。
  • _version Number
    如果是失敗請求
  • type String Required：錯誤類型
  • reason String ｜ Null
  • stack_trace String ：服務器堆棧跟蹤。僅當請求中包含 error_trace=true參數時才顯示。
  • caused_by Object: 請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
  • root_cause Array｜Object：請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
  • suppressed Array[Object]: 請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
  • _id String Required
  • _index String Required

示例

GET /my-index-000001/_mget
{"docs": [{"_id": "1"},{"_id": "2"}]
}

根據id查詢

GET /my-index-000001/_mget
{"docs": [{"_id": "1"},{"_id": "2"}]
}

過濾_source字段

GET /_mget
{"docs": [{"_index": "test","_id": "1","_source": false},{"_index": "test","_id": "2","_source": [ "field3", "field4" ]},{"_index": "test","_id": "3","_source": {"include": [ "user" ],"exclude": [ "user.location" ]}}]
}

獲取 stored 字段

GET /_mget
{"docs": [{"_index": "test","_id": "1","stored_fields": [ "field1", "field2" ]},{"_index": "test","_id": "2","stored_fields": [ "field3", "field4" ]}]
}

文檔路由

GET /_mget?routing=key1
{"docs": [{"_index": "test","_id": "1","routing": "key2"},{"_index": "test","_id": "2"}]
}

Get Multiple term vectors 獲取多個詞向量

格式

GET /_mtermvectors
POST /_mtermvectors
GET /{index}/_mtermvectors
POST /{index}/_mtermvectors

使用單個請求獲取多個詞向量。您可以通過索引和 ID 指定現有文檔，或在請求正文中提供人工文檔。您可以在請求正文或請求 URI 中指定索引。響應包含一個 docs 數組，其中包含所有獲取的詞向量。每個元素具有 termvectors API 提供的結構。

Artificial documents 人工文檔

可以使用 mtermvectors API 來為請求體中的虛擬文檔生成詞向量（term vectors）。使用的映射（mapping）取決于指定的索引。

Required authority

• index privileges： read

Path parameter

• index String Required

Query parameter 查詢參數

• ids Array[String] 一系列用逗號分隔的文檔 ID。你必須將 ids 定義為參數，或在請求體中設置"ids"或"docs"
• fields String | Array[String] 一個逗號分隔的列表或通配符表達式，指定要在統計中包含的字段。如果沒有在 completion_fields 或 fielddata_fields 參數中提供特定的字段列表，則用作默認列表。
• field_statistics Boolean 如果 true ，響應將包括文檔計數、文檔頻率之和以及總詞頻之和。
• offsets Boolean 如果 true ，響應將包含詞項偏移量。
• payloads Boolean 如果 true ，響應將包含詞項負載。
• positions Boolean 如果 true ，響應將包含詞項位置。
• preference String 操作應在其上執行的節點或分片。默認情況下是隨機的。
• realtime Boolean 如果為 true，請求是實時而不是近實時的。
• routing String 用于將操作路由到特定分片的自定義值。
• term_statistics Boolean 如果為真，響應將包含詞頻和文檔頻。
• version Number 如果 true ，則將文檔版本作為命中的一部分返回。
• version_type String
  值可以是
  • internal, 內部控制，從1開始，每次更新或刪除時遞增
  • external, 版本高于文檔版本或者文檔不存在的時候才能編輯文檔
  • external_gte, 版本高于或等于文檔版本或者文檔不存在的時候才能編輯文檔，需要謹慎使用，可能會導致數據丟失
  • force 已經棄用，因為可能導致 主分片和副本分片分離

Body

• docs Array[Object]
  一個現有或人工文檔的數組。
  • _id String Required
  • _index String
  • doc Object
  • fields String | Array[String]
  • field_statistics Boolean 如果 true ，則響應包含文檔數量、文檔頻率之和以及總詞頻之和。 默認值是true
  • filter String | Array[String]
    • max_doc_freq Number 文檔中超過數量的詞語進行忽略。 默認無限制。
    • max_num_terms Number 每個字段必須返回的最大詞數量。默認25
    • max_term_freq Number 忽略源文檔中出現頻率超過此值的詞。 默認無限制。
    • max_word_length Number 超過此最大詞長度的詞將被忽略。 默認無限制（0 代表無限制）。
    • min_doc_freq Number 忽略在至少這么多文檔中未出現的術語。默認值1
    • min_term_freq Number 忽略源文檔中頻率低于此值的詞。默認值1
    • min_word_length Number 忽略長度低于此值的詞。默認值0
  • offsets Boolean 如果 true ，響應將包含詞項偏移量。,默認值true。
  • payloads Boolean 如果 true ，響應將包含詞項負載。默認值true。
  • positions Boolean 如果 true ，響應將包含詞項位置。默認值true。
  • routing String
  • term_statistics Boolean 如果為 true，響應將包含詞項頻率和文檔頻率。默認值為 false 。
  • version Number
    跟之前的一樣是非負的長整數
  • version_type String
    值可以是
    • internal, 內部控制，從1開始，每次更新或刪除時遞增
    • external, 版本高于文檔版本或者文檔不存在的時候才能編輯文檔
    • external_gte, 版本高于或等于文檔版本或者文檔不存在的時候才能編輯文檔，需要謹慎使用，可能會導致數據丟失
    • force 已經棄用，因為可能導致 主分片和副本分片分離
• ids Array[String] 如果在同一個索引中，可以使用簡化的語法通過文檔的 ID 指定文檔。

Responses

200

• docs Array[Object] Required
  • _id String Required
  • _index String
  • _version Number
  • took Number
  • found Boolean
  • term_vectors Object
    • field_statistics Object
      • doc_count Number Required
      • sum_doc_freq Number Required
      • sum_ttf Number Required
    • trems Object Required
  • error
    • type String Required：錯誤類型
    • reason String ｜ Null
    • stack_trace String ：服務器堆棧跟蹤。僅當請求中包含 error_trace=true參數時才顯示。
    • caused_by Object: 請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
    • root_cause Array｜Object：請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
    • suppressed Array[Object]: 請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。

示例

POST /my-index-000001/_mtermvectors
{"docs": [{"_id": "2","fields": ["message"],"term_statistics": true},{"_id": "1"}]
}

Get multiple term vectors

POST /my-index-000001/_mtermvectors
{"docs": [{"_id": "2","fields": ["message"],"term_statistics": true},{"_id": "1"}]
}

Simplified syntax

POST /my-index-000001/_mtermvectors
{"ids": [ "1", "2" ],"fields": ["message"],"term_statistics": true
}

虛擬文檔 Artificial documents

POST /_mtermvectors
{"docs": [{"_index": "my-index-000001","doc" : {"message" : "test test test"}},{"_index": "my-index-000001","doc" : {"message" : "Another test ..."}}]
}

Reindex documents 重新索引文檔

格式

POST /_reindex

將文檔從源復制到目標。您可以將所有文檔復制到目標索引，也可以重新索引文檔的子集。源可以是任何現有的索引、別名或數據流。目標必須與源不同。例如，您不能將數據流重新索引到自身。

重要提示：重新索引要求源中的所有文檔都必須啟用 _source 。在調用重新索引 API 之前，應配置目標。重新索引不會從源或其關聯模板復制設置。例如，映射、分片計數和副本必須提前配置。

如果啟用了 Elasticsearch 的安全功能，您必須擁有以下安全權限：

• 源數據流、索引或別名的 read 索引權限。
• 目標數據流、索引或索引別名的 write 索引權限。
• 要使用 reindex API 請求自動創建數據流或索引，您必須擁有目標數據流、索引或別名的 auto_configure 、 create_index 或 manage 索引權限。
• 如果從遠程集群進行重新索引， source.remote.user 必須具有 monitor 集群權限和 read 對源數據流、索引或別名的索引權限。

如果從遠程集群進行重新索引，你必須在 reindex.remote.whitelist 設置中明確允許遠程主機。自動數據流創建需要一個具有數據流啟用功能的匹配索引模板。

dest 元素可以像索引 API 一樣進行配置，以控制樂觀并發控制。省略 version_type 或將其設置為 internal 會導致 Elasticsearch 盲目地將文檔倒入目標位置，覆蓋任何具有相同 ID 的文檔。

將 version_type 設置為 external 會導致 Elasticsearch 保留源中的 version ，創建任何缺失的文檔，并更新目標中比源中舊版本的任何文檔。

將 op_type 設置為 create 會導致重新索引 API 僅在目標位置創建缺失的文檔。所有現有文檔將導致版本沖突。

注意：由于數據流是僅追加的，因此對目標數據流進行的任何重新索引請求都必須具有 op_type 為 create 。重新索引只能向目標數據流添加新文檔。它無法更新目標數據流中的現有文檔。

默認情況下，版本沖突會中止重新索引過程。如果存在沖突，要繼續重新索引，請將 conflicts 請求正文屬性設置為 proceed 。在這種情況下，響應將包含遇到的版本沖突計數。 conflicts 屬性不會影響其他錯誤類型的處理。此外，如果您選擇計算版本沖突，操作可能會嘗試從源重新索引比 max_docs 更多的文檔，直到它成功將 max_docs 個文檔索引到目標，或者它已經遍歷了源查詢中的每個文檔。

重新索引說明文檔

Query parameters

• refresh Boolean 如果 true ，請求將刷新受影響的分片，以使此操作對搜索可見。
• requests_per_second Number:請求的速率限制，以每秒的子請求數表示。默認沒有限制
• scroll String：保留搜索上下文以進行滾動的時間段，可以是 -1 或 0
• slices Number|String
  此任務應劃分為多少個片段。默認為單個片段，這意味著任務不會被劃分為子任務。
  Reindex 支持切片滾動來并行化 reindexing 過程。這種并行化可以提高效率，并提供一種方便的方式將請求分解成更小的部分。
  注意：從遠程集群進行 reindexing 不支持手動或自動切片。
  如果設置為 auto ，Elasticsearch 會選擇使用的切片數量。此設置將每個分片使用一個切片，直到達到某個限制。如果有多個源，它將根據具有最少分片的索引或后備索引來選擇切片數量。
• max_docs Number 重新索引的最大文檔數量。默認情況下，所有文檔都會被重新索引。如果該值小于或等于 scroll_size ，則不會使用滾動條來檢索操作結果。
  如果 conflicts 設置為 proceed ，重新索引操作可能會嘗試從源中重新索引比 max_docs 更多的文檔，直到它成功將 max_docs 個文檔索引到目標或已經遍歷了源查詢中的所有文檔。
• timeout String 每個索引等待自動索引創建、動態映射更新和等待活動分片的持續時間。默認情況下，Elasticsearch 在失敗前會等待至少一分鐘。實際等待時間可能會更長，尤其是在發生多次等待時。 可以取值 -1 或 0
• wait_for_active_shards Number | string
  批量操作必須等待至少多少個分片副本處于活動狀態。可以設置為all或者任意正整數,最大是索引中分片副本數(number_of_replicas+1),默認是1,等待每個主分片處于活動狀態.
• wait_for_completion Boolean 如果 true ，請求會阻塞直到操作完成。
• require_alias Boolean 如果 true ，目標必須是索引別名。

Body Required

• conflict String 值可以是 abort 或 proceed
• dest Object Required
  • index String Required
  • op_type String 值可以是 index 或 create
  • pipeline String 使用管道的名稱
  • routing String
  • version_type String 值是 internal 、 external 、 external_gte 或 force 。
• max_docs number 重新索引的最大文檔數量。默認情況下，所有文檔都會被重新索引。如果該值小于或等于 scroll_size ，則不會使用滾動來檢索操作的結果。如果 conflicts 設置為 proceed ，重新索引操作可能會嘗試從源重新索引比 max_docs 更多的文檔，直到它成功將 max_docs 個文檔索引到目標或已經遍歷了源查詢中的所有文檔。
• script Object
  • source String | Object
  • id String
  • params Object
  • lang String 值是 painless 、 expression 、 mustache 或 java 。
  • options Object
• size Number Required
  • index String | Array[String] Required
  • query Object DSL語言 一個定義查詢的 Elasticsearch 查詢 DSL（領域特定語言）對象。
  • remote Object
    • connect_timeout String 一個持續時間。單位可以是 nanos 、 micros 、 ms (毫秒)、 s (秒)、 m (分鐘)、 h (小時) 和 d (天)。也接受沒有單位的 “0” 和表示未指定值的 “-1”。
    • headers Object 包含請求頭部的對象。
    • host String Required
    • username String
    • password String
    • socket_timeout String 一個持續時間。單位可以是 nanos 、 micros 、 ms (毫秒)、 s (秒)、 m (分鐘)、 h (小時) 和 d (天)。也接受沒有單位的 “0” 和表示未指定值的 “-1”。
  • size Number 每批次要索引的文檔數量。 在從遠程位置索引時使用，以確保批次適合在堆內存緩沖區中，該緩沖區的默認最大大小為 100 MB。默認值為 1000 。
  • slice Object
    • field String 字段路徑或路徑數組。某些 API 支持路徑中的通配符來選擇多個字段。
    • id String Required
    • max Number Required
  • sort String|Object|Array[String|Object]
    如果是 String： 字段路徑或路徑數組。某些 API 支持路徑中的通配符來選擇多個字段。
    如果是 Object：
    • _score Object
      • order String 值是 asc 或 desc
    • _doc Object
      • order String 值是 asc 或 desc
    • _geo_distance Object
      • mode String 值是 min 、 max 、 sum 、 avg 或 median 。
      • distance_type 值為 arc 或 plane
      • ignore_unmapped Boolean
      • Order String 值為 asc 或 desc
      • unit String 值可以是 in 、 ft 、 yd 、 mi 、 nmi 、 km 、 m 、 cm 或 mm 。
      • nested Object
        • filter Object 使用DSL語言查詢
        • max_children Number
        • nested Object
        • path String Required 字段路徑或路徑數組。某些 API 支持路徑中的通配符來選擇多個字段。
    • _script Object
      • order String 值是 asc 或 desc
      • script Object
        • source
        • id String
        • params Object 指定作為變量傳遞到腳本中的任何命名參數。 使用參數而不是硬編碼的值來減少編譯時間。
        • lang
        • options Object
      • type String 值是 string ， number ，或 version 。
      • mode String 值是 min 、 max 、 sum 、 avg 或 median 。
      • nested Object
        • filter Object 使用DSL語言查詢
        • max_children Number
        • nested Object
        • path String Required 字段路徑或路徑數組。某些 API 支持路徑中的通配符來選擇多個字段。
      • _source String | Array[String]
      • runtime_mappings Object
        • fields Object
          對于類型 composite
          • type String Required 值是 boolean ， composite ， date ， double ， geo_point ， geo_shape ， ip ， keyword ， long ，或 lookup 。
        • fetch_fields Array[Object]
          對于類型 lookup
          • field String Required 字段路徑或路徑數組。某些 API 支持路徑中的通配符來選擇多個字段。
          • format String
        • format String date 類型運行時字段的自定義格式。
        • input_field String 字段路徑或路徑數組。某些 API 支持路徑中的通配符來選擇多個字段。
        • target_field String 字段路徑或路徑數組。某些 API 支持路徑中的通配符來選擇多個字段。
        • script Object
          • source String | Object
            如果是String：
            • id String
            • params Object 指定作為變量傳遞到腳本中的任何命名參數。 使用參數而不是硬編碼的值來減少編譯時間。
            • lang String 值是 painless 、 expression 、 mustache 或 java 。
            • options Object
            • type String 值是 boolean ， composite ， date ， double ， geo_point ， geo_shape ， ip ， keyword ， long ，或 lookup 。

Response 響應

200

• batches Number reindex 拉回的滾動響應的數量
• create Number 成功創建的文檔數量。
• deleted Number 成功刪除的文檔數量。
• failures Array[Object] 失敗記錄
  • type String Required
  • cause Object Required 請求失敗的原因和詳細信息。此類定義了所有錯誤類型共有的屬性。 額外還提供了取決于錯誤類型的詳細信息。
  • stack_trace String 服務器堆棧跟蹤。僅當請求中包含 error_trace=true 參數時才顯示。
  • cause_by Object 請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
  • root_cause Array｜Object：請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
  • suppressed Array[Object]: 請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
  • id String Required
  • index String Required
  • status Number Required
• noop Number 由于用于 reindex 的腳本對 ctx.op 返回了 noop 值而被忽略的文檔數量。
• retries Object
  • bulk Number Required 重試的批量操作數量。
  • search Number Required 重試的搜索操作數量
• requests_per_second Number 每秒有效運行的請求數量
• slice_id Number
• task String
• throttled_millis Number 毫秒的時間單位
• throttled_unit_millis Number 毫秒的時間單位
• timed_out Boolean 如果在重新索引期間任何請求超時，則為 true 。
• took Number 毫秒的時間單位
• total Number 成功處理的文檔數量。
• updated Number 成功更新的文檔數量。也就是說，在重新索引之前，已經存在具有相同 ID 的文檔。
• version_conflicts Number 發生版本沖突的數量。

示例

POST _reindex
{"source": {"index": ["my-index-000001", "my-index-000002"]},"dest": {"index": "my-new-index-000002"}
}

從多個源重建索引

POST _reindex
{"source": {"index": ["my-index-000001", "my-index-000002"]},"dest": {"index": "my-new-index-000002"}
}

使用Painless重建索引

POST _reindex
{"source": {"index": "metricbeat-*"},"dest": {"index": "metricbeat"},"script": {"lang": "painless","source": "ctx._index = 'metricbeat-' + (ctx._index.substring('metricbeat-'.length(), ctx._index.length())) + '-1'"}
}

隨機復制部分文檔重建索引

POST _reindex
{"max_docs": 10,"source": {"index": "my-index-000001","query": {"function_score" : {"random_score" : {},"min_score" : 0.9}}},"dest": {"index": "my-new-index-000001"}
}

重建索引的時候修改文檔

POST _reindex
{"source": {"index": "my-index-000001"},"dest": {"index": "my-new-index-000001","version_type": "external"},"script": {"source": "if (ctx._source.foo == 'bar') {ctx._version++; ctx._source.remove('foo')}","lang": "painless"}
}

遠程重建索引

POST _reindex
{"source": {"remote": {"host": "http://otherhost:9200","username": "user","password": "pass"},"index": "my-index-000001","query": {"match": {"test": "data"}}},"dest": {"index": "my-new-index-000001"}
}

手動切片

POST _reindex
{"source": {"index": "my-index-000001","slice": {"id": 0,"max": 2}},"dest": {"index": "my-new-index-000001"}
}

自動切片

OST _reindex?slices=5&refresh
{"source": {"index": "my-index-000001"},"dest": {"index": "my-new-index-000001"}
}

路由

POST _reindex
{"source": {"index": "source","query": {"match": {"company": "cat"}}},"dest": {"index": "dest","routing": "=cat"}
}

寫入管道

POST _reindex
{"source": {"index": "source"},"dest": {"index": "dest","pipeline": "some_ingest_pipeline"}
}

查詢重建索引

POST _reindex
{"source": {"index": "my-index-000001","query": {"term": {"user.id": "kimchy"}}},"dest": {"index": "my-new-index-000001"}
}

重建索引設定最大值

POST _reindex
{"max_docs": 1,"source": {"index": "my-index-000001"},"dest": {"index": "my-new-index-000001"}
}

選定字段重建索引

POST _reindex
{"source": {"index": "my-index-000001","_source": ["user.id", "_doc"]},"dest": {"index": "my-new-index-000001"}
}

重建索引的時候字段重命名

POST _reindex
{"source": {"index": "my-index-000001"},"dest": {"index": "my-new-index-000001"},"script": {"source": "ctx._source.tag = ctx._source.remove(\"flag\")"}
}

Throttle a reindex option 限制重建索引

格式

POST /_reindex/{task_id}/_rethrottle

更改特定 reindex 操作每秒的請求數量。例如：

POST _reindex/r1A2WoRbTwKZ516z6NEs5A:36619/_rethrottle?requests_per_second=-1

重新限流加速查詢的效果立即生效。重新限流減速查詢的效果將在完成當前批次后生效。這種行為可防止滾動超時。

Path parameters

task_id String Required 任務標識符，可以通過使用 tasks API 找到。

Query parameters

requests_per_second Number 這個請求在子請求每秒內的速率限制。它可以設置為 -1 來關閉速率限制，或者設置為任何小數如 1.7 或 12 來限制在該級別。

Responses

200

• nodes Object Required

Get term Vector information 獲取詞向量信息

格式

GET /{index}/_termvectors
POST /{index}/_termvectors
GET /{index}/_termvectors/{id}
POST /{index}/_termvectors/{id}

獲取特定文檔字段中術語的信息和統計數據。

您可以檢索索引中存儲的文檔或請求正文中傳遞的人工文檔的術語向量。您可以通過 fields 參數或向請求正文中添加字段來指定您感興趣的字段。例如：

GET /my-index-000001/_termvectors/1?fields=message

字段可以使用通配符指定，類似于多匹配查詢。

詞向量默認是實時，而不是近實時。這可以通過將 realtime 參數設置為 false 來更改。

您可以請求三種類型的值：term information, term statistics, and field statistics。默認情況下，所有字段都會返回所有詞信息和字段統計信息，但詞統計信息除外。

Term information

• term frequency in the field (always returned) 字段詞頻 一直返回
• term positions (positions: true) 詞位置
• start and end offsets (offsets: true) 起始和結束偏移量
• term payloads (payloads: true), as base64 encoded bytes 詞語載荷
  如果請求的信息未存儲在索引中，如果可能，它將實時計算。此外，即使文檔不存在于索引中，而是由用戶提供，也可以為這些文檔計算術語向量。

開始和結束偏移量假定使用 UTF-16 編碼。如果您想使用這些偏移量來獲取生成此標記的原始文本，您應該確保您從中獲取子字符串的字符串也使用 UTF-16 編碼。

Behaviour 行為

術語和字段統計信息不準確。已刪除的文檔不會被考慮。這些信息僅檢索請求文檔所在的分片。因此，術語和字段統計信息僅作為相對度量有用，而絕對數字在此上下文中沒有意義。默認情況下，當請求人工文檔的術語向量時，會隨機選擇一個分片來獲取統計信息。僅使用 routing 來命中特定分片。有關如何使用此 API 的詳細示例，請參閱鏈接文檔。
詞向量

Required authorization

• Index privileges: read

Path parameters

• index String Required
• id String Required

Query parameters

• fields String | Array[String] 一個逗號分隔的列表或通配符表達式，指定要在統計中包含的字段。如果沒有在 completion_fields 或 fielddata_fields 參數中提供特定的字段列表，則用作默認列表。
• field_statistics Boolean 如果 true ，響應將包括文檔計數、文檔頻率之和以及總詞頻之和。
• offsets Boolean 如果 true ，響應將包含詞項偏移量。
• payloads Boolean 如果 true ，響應將包含詞項負載。
• positions Boolean 如果 true ，響應將包含詞項位置。
• preference String 操作應在其上執行的節點或分片。默認情況下是隨機的。
• realtime Boolean 如果為 true，請求是實時而不是近實時的。
• routing String 用于將操作路由到特定分片的自定義值。
• term_statistics Boolean 如果為真，響應將包含詞頻和文檔頻。
• version Number 如果 true ，則將文檔版本作為命中的一部分返回。
• version_type String
  值可以是
  • internal, 內部控制，從1開始，每次更新或刪除時遞增
  • external, 版本高于文檔版本或者文檔不存在的時候才能編輯文檔
  • external_gte, 版本高于或等于文檔版本或者文檔不存在的時候才能編輯文檔，需要謹慎使用，可能會導致數據丟失
  • force 已經棄用，因為可能導致 主分片和副本分片分離

Body

• docs Array[Object]
  一個現有或人工文檔的數組。
  • _id String Required
  • _index String
  • doc Object
  • fields String | Array[String]
  • field_statistics Boolean 如果 true ，則響應包含文檔數量、文檔頻率之和以及總詞頻之和。 默認值是true
  • filter String | Array[String]
    • max_doc_freq Number 文檔中超過數量的詞語進行忽略。 默認無限制。
    • max_num_terms Number 每個字段必須返回的最大詞數量。默認25
    • max_term_freq Number 忽略源文檔中出現頻率超過此值的詞。 默認無限制。
    • max_word_length Number 超過此最大詞長度的詞將被忽略。 默認無限制（0 代表無限制）。
    • min_doc_freq Number 忽略在至少這么多文檔中未出現的術語。默認值1
    • min_term_freq Number 忽略源文檔中頻率低于此值的詞。默認值1
    • min_word_length Number 忽略長度低于此值的詞。默認值0
  • offsets Boolean 如果 true ，響應將包含詞項偏移量。,默認值true。
  • payloads Boolean 如果 true ，響應將包含詞項負載。默認值true。
  • positions Boolean 如果 true ，響應將包含詞項位置。默認值true。
  • routing String
  • term_statistics Boolean 如果為 true，響應將包含詞項頻率和文檔頻率。默認值為 false 。
  • version Number
    跟之前的一樣是非負的長整數
  • version_type String
    值可以是
    • internal, 內部控制，從1開始，每次更新或刪除時遞增
    • external, 版本高于文檔版本或者文檔不存在的時候才能編輯文檔
    • external_gte, 版本高于或等于文檔版本或者文檔不存在的時候才能編輯文檔，需要謹慎使用，可能會導致數據丟失
    • force 已經棄用，因為可能導致 主分片和副本分片分離

Responses

200

• found Boolean
• _id String Required
• _index String
• term_vectors Object
  • field_statistics Object
    • doc_count Number Required
    • sum_doc_freq Number Required
    • sum_ttf Number Required
  • trems Object Required
• error
  • type String Required：錯誤類型
  • reason String ｜ Null
  • stack_trace String ：服務器堆棧跟蹤。僅當請求中包含 error_trace=true參數時才顯示。
  • caused_by Object: 請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
  • root_cause Array｜Object：請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
  • suppressed Array[Object]: 請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
• took Number Required
• _version Number

Update a document 更新文檔

格式

POST /{index}/_update/{id}

通過運行腳本或傳遞部分文檔來更新文檔。

如果啟用了 Elasticsearch 的安全功能，您必須對目標索引或索引別名具有 index 或 write 索引權限。

腳本可以更新、刪除或跳過修改文檔。該 API 還支持傳遞部分文檔，該文檔將與現有文檔合并。要完全替換現有文檔，請使用 index API。此操作：

• 從索引中獲取文檔（與分片共存）。
• 運行指定的腳本。
• 對結果進行索引。

文檔仍需重新索引，但使用此 API 可以減少一些網絡往返次數，并降低 GET 操作和索引操作之間的版本沖突幾率。

使用此 API 必須啟用 _source 字段。除了 _source ，您可以通過 ctx 映射訪問以下變量： _index 、 _type 、 _id 、 _version 、 _routing 和 _now （當前時間戳）。有關部分更新、upsert 和腳本更新的使用示例，請參閱外部文檔。

Update a document

Required authorization

• Index privileges: write

Path parameters

• index String Required
• id String Required

Query parameters

• if_primary_term Number 主分片版本號一致才執行
• if_seq_no Number 當文檔的序列化是這個值的時候才執行
• include_source_on_error Boolean
  當值為ture，當索引文檔出現解析錯誤（parsing error）的時候，錯誤消息會包含整個文檔的_source內容
  當值為false，錯誤信息不包含_source，只顯示錯誤原因。
• lang String
• refresh String
  如果為 true，Elasticsearch 將刷新受影響的分片，使此作對搜索可見。如果 wait_for，它會等待刷新以使此作對搜索可見。如果為 false，則刷新不執行任何作。
• require_alias Boolean
  true 代表必須是索引的別名
• retry_on_conflict Number 發生沖突時操作應重試的次數。
• routing String 用于將操作路由到特定分片的自定義值。
• timeout String
  請求等待以下操作的時間；自動索引創建、動態映射更新和等待活動分片。默認值是1min，保證Elasticsearch值失敗之親啊的至少等待超時。實際時間可能會更長，當發生多個等待的時候。
  可以設置值是 0 代表不等待, -1 一直等待
• wait_for_active_shards Number | string
  批量操作必須等待至少多少個分片副本處于活動狀態。可以設置為all或者任意正整數,最大是索引中分片副本數(number_of_replicas+1),默認是1,等待每個主分片處于活動狀態.
• _source Boolean | String | Array[String]
  標識返回是否包含_source字段（true或false）或列出要返回的字段
• _source_excludes String | Array[String]
  從響應中排除的源字段。也可以從_source_includes查詢參數中指定的子集中排除字段。如果_source是false，就會忽略這個參數。
• _source_includes String,Array[String]
  要包含著響應中的源字段的列表。如果使用這個字段，就會僅返回這些源字段。也可以使用_source_excludes，在子集中繼續排除，如果_source是false，就會忽略這個參數。

Body Required

• detect_noop Boolean
  如果是true，當文檔沒有變化時，響應中的 result 被設置為 noop （無操作）。默認值是 true
• doc Object 對現有文檔的部分更新。如果同時指定了 doc 和 script ，則忽略 doc 。
• doc_as_upsert Boolean 如果 true ，則使用 ‘doc’ 的內容作為 ‘upsert’ 的值。注意：不支持使用 doc_as_upsert 與攝取管道一起使用。默認值 false
• script Object
  • source String | Object
    如果是String
    • id String
    • params Object 指定作為變量傳遞到腳本中的任何命名參數。 使用參數而不是硬編碼的值來減少編譯時間。
    • lang String 值是 painless 、 expression 、 mustache 或 java 。
    • options Object
• scripted_upsert Boolean 如果 true，無論文檔是否存在，都運行腳本。默認值 false。
• _source Boolean | Object 定義獲取源的方式。可以完全禁用獲取，或者可以過濾源。
  • exclude_vectors Boolean 如果 true ，返回的源中會排除向量字段。此選項優先于 includes ：即使向量字段與 includes 規則匹配，也會被排除。
  • excludes String | Array[String]
  • includes String | Array[String]
• upsert Object 如果文檔不存在，‘upsert’ 的內容將作為新文檔插入。如果文檔存在，將運行 ‘script’。

Responses

200

• _id String Required
• _index String Required
• _primary_term number. 操作成功的時候有值,操作的主分片的任期號
• result string. 操作的結果,值可能出現的范圍:[created | updated | deleted | not_found | noop]
• _seq_no number
• _shards Object.
  • failed number Required
  • successful number Required
  • total number Required
  • failures Array[Object]
    • index String
    • node String
    • reason Object Required
      • type String Required
      • reason String | Null
      • stack_trace String
      • cased_by Object
      • root_cause Array[Object]
      • suppressed Array[Object]
    • shard Number Required
    • status String
  • skipped number
• _version number
• forced_refresh boolean
• get Object
  • fields Object
  • found Boolean Required
  • _seq_no Number
  • _primary_term number. 操作成功的時候有值,操作的主分片的任期號
  • _routing String 路由
  • _source Object

示例

使用腳本來遞增計數器

POST test/_update/1
{"script" : {"source": "ctx._source.counter += params.count","lang": "painless","params" : {"count" : 4}}
}

腳本式 upsert。 當 scripted_upsert 設置為 true 時，無論文檔是否存在，腳本都會被執行。

POST test/_update/1
{"scripted_upsert": true,"script": {"source": """if ( ctx.op == 'create' ) {ctx._source.counter = params.count} else {ctx._source.counter += params.count}""","params": {"count": 4}},"upsert": {}
}

執行 doc 作為 upsert。
與其發送一個部分更新的 doc 加上一個單獨的 upsert 文檔，不如將 doc_as_upsert 設置為 true，這樣就會直接使用 doc 的內容作為 upsert 文檔。

POST test/_update/1
{"doc": {"name": "new_name"},"doc_as_upsert": true
}

使用腳本向一個標簽列表中添加標簽。在這個示例中，它只是一個普通列表，所以即使標簽已經存在，也會再次被添加。

POST test/_update/1
{"script": {"source": "ctx._source.tags.add(params.tag)","lang": "painless","params": {"tag": "blue"}}
}

腳本移除標簽

POST test/_update/1
{"script": {"source": "if (ctx._source.tags.contains(params.tag)) { ctx._source.tags.remove(ctx._source.tags.indexOf(params.tag)) }","lang": "painless","params": {"tag": "blue"}}
}

腳本添加字段

POST test/_update/1
{"script" : "ctx._source.new_field = 'value_of_new_field'"
}

腳本移除字段

POST test/_update/1
{"script" : "ctx._source.remove('new_field')"
}

移除子字段

POST test/_update/1
{"script": "ctx._source['my-object'].remove('my-subfield')"
}

運行POST test/_update/1來改變腳本內部執行的操作。例如，如果文檔的 tags 字段包含 “green”，這個請求會刪除該文檔，否則什么也不做（noop）。

POST test/_update/1
{"script": {"source": "if (ctx._source.tags.contains(params.tag)) { ctx.op = 'delete' } else { ctx.op = 'noop' }","lang": "painless","params": {"tag": "green"}}
}

執行部分更新，為已有文檔添加一個新字段。

POST test/_update/1
{"doc": {"name": "new_name"}
}

如果文檔存在執行腳本，如果不存在創建文檔

POST test/_update/1
{"script": {"source": "ctx._source.counter += params.count","lang": "painless","params": {"count": 4}},"upsert": {"counter": 1}
}    

Update documents 更新多個文檔

格式

POST /{index}/_update_by_query

更新符合指定查詢的文檔。如果沒有指定查詢，則對數據流或索引中的每個文檔執行更新，而不會修改源數據，這對于獲取映射更改很有用。
如果啟用了 Elasticsearch 安全功能，您必須對目標數據流、索引或別名具有以下索引權限：

• read
• index or write

可以在請求 URI 或請求體中指定查詢條件，使用與搜索 API 相同的語法。

當您提交通過查詢更新請求時，Elasticsearch 在開始處理請求時獲取數據流或索引的快照，并使用內部版本控制更新匹配的文檔。當版本匹配時，文檔會被更新并且版本號會遞增。如果在快照獲取和更新操作處理之間文檔發生變化，會導致版本沖突，操作失敗。您可以選擇計數版本沖突而不是停止并返回，通過將 conflicts 設置為 proceed 。請注意，如果您選擇計數版本沖突，操作可能會嘗試從源中更新比 max_docs 更多的文檔，直到它成功更新了 max_docs 個文檔或已經處理了源查詢中的每個文檔。

注意：版本等于 0 的文檔無法使用通過查詢更新，因為內部版本控制不支持 0 作為有效的版本號。

在處理通過查詢更新請求時，Elasticsearch 會依次執行多個搜索請求以查找所有匹配的文檔。對每批匹配的文檔執行批量更新請求。任何查詢或更新失敗都會導致通過查詢更新請求失敗，并且失敗情況會顯示在響應中。任何成功完成的更新請求仍然會保留，它們不會被回滾。

Refreshing shards 刷新分片

指定 refresh 參數會在請求完成后刷新所有分片。這與更新 API 的 refresh 參數不同，后者只會刷新接收請求的分片。與更新 API 不同，它不支持 wait_for 。

Running update by query asynchronously 異步執行通過查詢更新

如果請求包含 wait_for_completion=false ，Elasticsearch 會執行一些預檢，啟動請求，并返回一個任務，你可以使用該任務來取消或獲取任務狀態。Elasticsearch 將此任務記錄為 .tasks/task/${taskId} 中的一個文檔。

Waiting for active shards

wait_for_active_shards 控制在繼續處理請求之前，必須有多少個分片副本處于活躍狀態。詳細信息請參閱 wait_for_active_shards 。 timeout 控制每個寫請求等待不可用分片變得可用的時長。它們的工作方式與 Bulk API 中完全相同。通過查詢更新使用滾動搜索，因此你也可以指定 scroll 參數來控制搜索上下文保持活躍的時間，例如 ?scroll=10m 。默認值為 5 分鐘。

Throttling update requests 限制更新請求

要控制通過查詢更新操作批次的速度，可以將 requests_per_second 設置為任何正小數。這將向每個批次添加等待時間以限制速度。將 requests_per_second 設置為 -1 可關閉限速。

限速在批次之間使用等待時間，以便內部滾動請求可以有一個考慮請求填充的超時。填充時間是批次大小除以 requests_per_second 與寫入所花費時間的差值。默認情況下，批次大小為 1000，因此如果 requests_per_second 設置為 500 ：

target_time = 1000 / 500 per second = 2 seconds
wait_time = target_time - write_time = 2 seconds - 0.5 seconds = 1.5 seconds

由于批次作為單個 _bulk 請求發出，較大的批次大小會導致 Elasticsearch 創建許多請求并在開始下一批次之前等待。這是“突發”而不是“平滑”。

Slicing 切片

更新查詢支持切片滾動以并行化更新過程。這可以提高效率，并提供一種方便的方式將請求分解為更小的部分。

將切片設置為auto,允許Elasticsearch選擇要使用的切片（slice）數量。此設置將每個分片(shard)分配一個切片，但是有最大限制。如果有多個源數據流或索引，他將根據分片數量最少的索引或底層索引（backing index）來選擇切片數量。將切片添加到“通過查詢更新”作為創建子請求，因此他有一些特殊的行為。

• 可以在任務API中查看這些請求，這些子請求是具有切片的請求的任務的子任務
• 獲取具有切片請求的任務狀態僅包含已經完成的切片的狀態
• 這些子請求（sub-requests）是可以單獨訪問/操作的，比如可以單獨取消他們，或者重新調整他們的限速（rethrottling）
• 重新限流請求 slices將按比例重新限流未完成的子請求
• 取消slices將取消每個子請求
• 由于slices的性質，每個子請求不會得到完全均勻的文檔分配，所有文檔都將被處理，但是某些切片會比別的切片更大。預期較大的切片會有更均勻的分布。
• 在帶有slices的請求中，參數 requests_per_second和 max_doc將按比例分配給每個子請求。結合之前關于分配可能不均勻這一點，你應該得出結論，使用max_docs和slices結合可能不能導致恰好更新 max_docs整個文檔。
• 每個子請求都會得到data stream或索引略有不同的快照，盡管這些快照是在大約相同時間獲取的。

如果你是手動切片或者以其他方式調整自動切片，需要注意下面幾點

• 查詢性能在切片數量等于索引或底層索引的分片數量的時候最高。如果數字很大（例如500），應該選擇比較小的數字，因為過多的 slices會影響性能，將slices的數量設置為高于分片的數量的值通常不會提高效率，反而會增加額外開銷。
• 更新性能隨可用資源的切片數量線性提高

查詢性能還是更新性能在運行時占主導地位，取決于重新索引的文檔和集群資源
參考 更新查詢 API

Required authorization

• Index privileges: read,write

Path parameters

• index String | Array[String] Required
  一個用逗號分隔的數據流、索引和別名列表，用于搜索。它支持通配符（ * ）。要搜索所有數據流或索引，請省略此參數或使用 * 或 _all 。

Query parameters

• allow_no_indices Boolean
  如果是false,當任何通配符表達式、索引別名或_all值僅針對缺失或已經關閉的索引時，，請求返回錯誤。即使請求針對其他開放索引，規則也適用。如果一個索引是以 foo 開頭，但是沒有以 bar 開頭的索引，那么針對 foo*,bar* 請求將會返回錯誤.
• analyzer String 分析器
  用于查詢字符串的分析器，當且僅當指定了 q查詢字符串參數時才可以使用。
• analyze_wildcard Boolean
  如果是 true則分析通配符和前綴查詢。當且僅當指定了 q查詢字符串參數時才可以使用。
• conflicts String
  如果通過查詢刪除的時候遇見版本沖突該怎么辦：abort 還是 proceed
  Supported values include 支持的值包括
  • abort：如果存在沖突，就停止重新索引
  • proceed： 即使純真沖突也繼續重新索引
• default_operator String
  查詢字符串默認運算符：AND 或 OR 。當且僅當指定了 q查詢字符串參數時才可以使用。
• df String 當查詢的字符串中為提供字段前綴時，用作默認字段的字段。當且僅當指定了 q查詢字符串參數時才可以使用。
• expand_wildcards String ｜ Array[String] 通配符模式可以匹配的索引的類型。如果請求可以定位數據流。支持逗號分隔的值，eg open,hidden.支持的值包括：
  • all ： 匹配任何的數據流和索引，包含隱藏的數據流和索引
  • open： 匹配開放的非隱藏的索引和數據流
  • closed；匹配已關閉的非隱藏索引。也匹配任意非隱藏的數據流。數據流無法關閉。
  • hidden：匹配隱藏的數據流和隱藏的索引。必須與 open、close或 both結合使用
  • none: 不接受通配符表達式
• form Number 跳過指定數量的文檔
• ignore_unavailable Boolean：忽略不可用，如果是false,當請求針對缺失或關閉的索引時，返回錯誤。
• lenient Boolean：如果是true,查詢字符串基于格式的查詢失敗（例如，向數字字段提供文本）將被忽略。當且僅當指定了 q查詢字符串參數時才可以使用。
• max_docs Number ：需要處理的最大文檔數。默認所有文檔。如果設置小于或等于scroll_size值，則不會使用滾動來檢索操作的結果。
• preference String：執行操作的節點或分片，默認是隨機的
• q String 一個使用 Lucene 查詢字符串語法的查詢。
• refresh Boolean：
  如果為 true，Elasticsearch會在請求完成后刷新delete by查詢中涉及的所有分片。這個和delete API的refresh參數不同，后者僅刷新收到刪除請求的分片。并且這里不支持 wait_for。
• request_cache Boolean： 如果是true，表示請求中使用請求緩存。默認是索引級別的設置。
• requests_per_second Number：每秒請求數量，請求的限制（以每秒子請求數量計算）
• routing String：用于將操作路由到特定分片的自定義值。
• q String：Lucene 查詢字符串語法中的查詢。
• scroll String：保留搜索上下文以進行滾動的時間段，可以是 -1 或 0
• scroll_size Number：支持該操作的滾動請求的大小。
• search_timeout String：每次搜索請求的顯式超時時間，默認無超時。可以為0或-1
• search_type String: 搜索操作的類型。可以選query_then_fetch 和 dfs_query_then_fetch
  • query_then_fetch:文檔的打分是基于分片內的本地詞頻和文檔頻率來計算的。這種方式通常更快，但準確性較低
  • dfs_query_then_fetch：使用所有分片中的全局詞頻和文檔頻率對文檔進行評分。這種速度較慢，但更準確。
• slices Number｜String 切片數，可以為auto或數字（該任務應該劃分的切片數）
• sort Array[String] ：以逗號分隔的 <field>:<direction>的列表
• stats Array[String]:用于記錄和統計目的的請求的特定的tag
• terminate_after : 每個分片可收集的最大文檔數。如果查詢達到這個限制，Elasticsearch會提前終止查詢。Elasticsearch會在排序之前收集文檔。需要謹慎使用。Elasticsearch會將此參數應用與處理請求的每個分片。如果可能，請讓Elasticsearch自動執行提前終止。如果請求的目標數據流包含跨很多歌數據層的支持索引，請避免使用這個參數。
• timeout String：每個刪除請求等待活動分片的時間，可以為 -1 或 0
• version Boolean:如果是true則返回文檔版本作為匹配的一部分
• wait_for_active_shards Number|String
  繼續操作之前必須等待至少多少個分片副本處于活動狀態。可以設置為all或者任意正整數,最大是索引中分片副本數(number_of_replicas+1)。timeout值控制每個寫入win各位iu放入哪個粉絲不可用分片的可用時間,值可以是 all 或 index_setting.
• wait_for_completion Boolean
  如果是true,請求會被阻塞，直到操作完成。如果是 false,Elasticsearch會執行一些預檢查，啟動請求，并返回一個任務，可以使用該任務取消或獲取其狀態。Elasticsearch會在 .tasks/task/${taskId}中創建此任務的記錄作為文檔。完成任務后，可以刪除這個任務文檔，以便Elasticsearch回收空間。

Body

• max_docs Number： 要更新的最大文檔數
• query Object：定義Elasticsearch查詢DSL對象 參考文檔
• script Object
  • source String | Object 如果是Object
    • aggregations Object 定義作為搜索請求一部分運行的聚合。 參考文檔
    • collapse Object 參考文檔
    • explain Boolean 如果 true ，請求將返回關于分數計算的詳細信息作為命中的一部分。默認值false
    • ext Object Elasticsearch 插件定義的搜索擴展的配置。
    • from Number 起始文檔偏移量，必須是非負數。默認情況下，您無法使用 from 和 size 參數分頁瀏覽超過 · 個命中。要分頁瀏覽更多命中，請使用 search_after 參數。默認值 0 。
    • highlight Object
      • type String 值是 plain ， fvh ，或 unified 。
      • boundary_chars String 包含每個邊界字符的字符串。 默認值為 .,!? \t\n 。
      • boundary_max_scan Number 掃描邊界字符的距離。默認值為 20 。
      • boundary_scanner String 邊界掃描器，值是 chars ， sentence ，或 word 。
      • boundary_scanner_locale String 邊界掃描器語言,控制使用哪種語言環境來搜索句子和單詞邊界。此參數采用語言標簽的形式，例如： "en-US" ， "fr-FR" ， "ja-JP" 。默認值為 Locale.ROOT 。
      • force_source Boolean Deprecated 強制使用源[棄用]
      • fragmenter String 片段化字符串 值為 simple 或 span 。
      • fragment_size Number 片段大小（數字） 高亮片段的字符大小。默認值為 100 。
      • highlight_filter Boolean
      • highlight_query Object 使用DSL查詢 query dsl
      • max_fragment_length Number
      • max_analyzed_offset number 如果設置為非負值，高亮顯示將在定義的最大限制處停止。其余文本不會被處理，因此不會被高亮顯示，也不會返回錯誤。 max_analyzed_offset 查詢設置不會覆蓋 index.highlight.max_analyzed_offset 設置，當 index.highlight.max_analyzed_offset 設置的值低于查詢設置時，index.highlight.max_analyzed_offset 設置將優先。
      • no_match_size Number 如果沒有匹配的片段需要高亮顯示，則希望從字段的開始返回的文本量。默認值為 0 。
      • number_of_fragments Number 要返回的最大片段數。如果片段數設置為 0 ，則不返回任何片段。相反，將高亮顯示并返回整個字段內容。這在您需要高亮顯示標題或地址等短文本但不要求片段化時很有用。如果 number_of_fragments 等于 0 ，則忽略 fragment_size 。
      • options Object
      • order String 值為 score
      • phrase_limit Number 控制文檔中考慮的匹配短語數量。防止 fvh 高亮器分析過多短語并消耗過多內存。在使用 matched_fields 時，每個匹配字段考慮 phrase_limit 個短語。提高限制會增加查詢時間并消耗更多內存。僅由 fvh 高亮器支持。默認值為 256 。
      • post_tags Array[String] 與 pre_tags 結合使用，以定義用于高亮文本的 HTML 標簽。默認情況下，高亮文本被包裹在 和 標簽中。
      • pre_tags Array[String] 與 post_tags 結合使用，以定義用于高亮文本的 HTML 標簽。默認情況下，高亮文本被包裹在 和 標簽中。
      • require_field_match Boolean 默認情況下，僅包含查詢匹配的字段會被高亮。設置為 false 以高亮所有字段。默認值為 true 。
      • tags_schema String 值為 styled 。
      • encoder String 值為 default 或 html 。
      • fields Object | Array[Object] Required
    • track_total_hits Boolean | Number 表示匹配查詢的準確命中數。如果為 true，則以犧牲部分性能為代價返回確切的命中數。如果為 false，則響應不包含匹配查詢的命中總數。默認值為 10,000 個命中。
    • indices_boost Array[Object] 提升指定索引中文檔的 _score 數量。提升值是用于乘以得分的因子。大于 1.0 的提升值會增加得分。在 0 和 1.0 之間的提升值會降低得分。 參考文檔 參考文檔
    • docvalue_fields Array[Object] 一個通配符 ( * ) 字段模式的數組。請求返回匹配這些模式在響應的 hits.fields 屬性中字段名的 doc 值。
      • field String Required 字段路徑或路徑數組。某些 API 支持路徑中的通配符來選擇多個字段。
      • format String 返回值的格式。
      • include_unmapped Boolean 用來控制 是否對未映射字段（unmapped field）也返回聚合結果
    • knn Object|Array[Object] 運行近似 kNN 搜索 參考文檔knn-search 如果是Object
      • field String Object 字段路徑或路徑數組。某些 API 支持路徑中的通配符來選擇多個字段。
      • query_vector Array[Number]
      • query_vector_builder Object
        • text_embedding Object
      • k Number 返回作為頂級命中的最終最近鄰數量
      • num_candidates Number 每個分片考慮的最近鄰候選數量
      • boost Number 應用于 kNN 分數的提升值
      • filter Object|Array[Object] kNN 搜索查詢的過濾器
        如果是Object 是DSL語言 query-dsl
      • similarity Number 向量被視為匹配的最小相似度
      • inner_hits Object
        • name String
        • size Number 返回每個 inner_hits 的最大命中數。默認值為 3 。
        • from Number 內部命中起始文檔偏移量。默認值為 0 。
      • collapse Object
        • docvalue_fields Array[Object]
        • explain Boolean
        • highlight
        • ignore_unmapped Boolean
        • script_fields Object
        • seq_no_primary_term Boolean
        • fields Array[String] 字段路徑或路徑數組。某些 API 支持路徑中的通配符來選擇多個字段。
        • sort
        • _source
        • stored_fields String|Array[String]
        • track_scores Boolean 默認 false
        • version Boolean
      • rescore_vector object
        • oversample Number Required 將指定的過采樣因子應用于近似 kNN 搜索中的 k
    • rank Object
      • rrf Object
        • rank_constant Number 單個查詢中每個結果集的文檔對最終排序結果集有多大影響
        • rank_window_size Number每個查詢中單個結果集的大小
    • min_score Number 匹配文檔的最小 _score 。評分低于 _score 的文檔不會被包含在搜索結果或聚合結果中。
    • post_filter Object DSL語言query-dsl
    • profile Boolean 設置為 true 將返回關于搜索請求中單個組件執行過程的詳細時間信息。注意：這是一個調試工具，會對搜索執行造成顯著的開銷。默認值為 false
    • query Object DSL語言query-dsl
    • rescore Object|Array[Object] 可用于通過重新排序 query 和 post_filter 階段返回的頂部（例如 100 - 500）文檔來提高精確度。
      • window_size Number 窗口大小
      • query Object
      • learning_to_rank Object
    • retriever Object
      • standard Object
        • filter
        • min_score Number 匹配文檔的最低 _score。_score 較低的文檔不包含在頂級文檔中。
        • _name String 檢索器名稱。
        • query Object DSL語言query-dsl
        • search_after Array[Number|String|Boolean|Null] 一個字段值
        • terminate_after Number 每個分片收集的最大文檔數量。
        • sort
        • collapse Object
      • knn Object
        • filter
        • min_score Number 匹配文檔的最小 _score。_score 較低的文檔不會被包含在頂級文檔中。
        • _name String 檢索器名稱。
        • field String Required 用于搜索的向量字段的名稱。
        • query_vector Array[Number]
        • query_vector_builder Object
        • k Number Required 返回作為頂級命中的最近鄰數量。
        • num_candidates Number Required 每個分片需要考慮的最近鄰候選數量。
        • similarity Number 文檔被視為匹配所需的最小相似度。
        • rescore_vector Object
      • rff Object
        • filter
        • min_score 匹配文檔的最小 _score。_score 較低的文檔不會被包含在頂級文檔中。
        • _name String 檢索器名稱。
        • retrievers Array[Object] Required 指定哪些返回的頂級文檔集將應用 RRF 公式的一個子檢索器列表。
        • rank_constant Number 此值決定每個查詢的各個結果集對最終排序結果集的影響程度。
        • rank_window_size Number 此值決定每個查詢的各個結果集的大小。
        • query String
        • fields Array[String]
      • text_similarity_reranker Object
        • filter
        • min_score 匹配文檔的最小 _score。_score 較低的文檔不會被包含在頂級文檔中。
        • _name String 檢索器名稱。
        • retrievers Array[Object] Required
        • rank_window_size Number 此值決定每個查詢的各個結果集的大小。
        • inference_id String 使用推理 API 創建的推理端點的唯一標識符。
        • inference_text String Required 用于相似度比較的文本片段
        • field String Required 用于文本相似度比較的文檔字段。該字段應包含將用于與推理文本進行比較的文本
      • rule Object
        • filter
        • min_score 匹配文檔的最小 _score。_score 較低的文檔不會被包含在頂級文檔中。
        • _name String 檢索器名稱。
        • ruleset_ids
        • match_criteria Object Required 用于確定是否應應用所提供規則集中的規則的匹配條件。
        • retriever Object Required
        • rank_window_size Number 此值決定了單個結果集的大小。
      • rescorer Object
        • filter
        • min_score 匹配文檔的最小 _score。_score 較低的文檔不會被包含在頂級文檔中。
        • _name String 檢索器名稱。
        • retriever Object Required
        • rescore
      • linear Object
        • filter
        • min_score 匹配文檔的最小 _score。_score 較低的文檔不會被包含在頂級文檔中。
        • _name String 檢索器名稱。
        • retrievers Array[Object]
        • rank_window_size Number
        • query String
        • fields Array[String]
        • normalizer string 值是 none ， minmax ，或 l2_norm 。
      • pinned Obejct
        • filter
        • min_score 匹配文檔的最小 _score。_score 較低的文檔不會被包含在頂級文檔中。
        • _name String 檢索器名稱。
        • retrievers Array[Object]
        • ids Array[String]
        • docs Array[Object]
        • rank_window_size Number
    • script_fields Object 為每個命中檢索腳本評估（基于不同字段）。
      • script Object Required
      • ignore_failure Boolean
    • search_after Array[Number|String|Boolean|Null] 一個字段值
    • size Number 返回命中數的數量，不能為負。默認情況下，使用 from 和 size 參數無法分頁瀏覽超過 10,000 個命中。要分頁瀏覽更多命中，請使用 search_after 屬性。默認值為 10 。
    • slice Object
      • field String 字段路徑或路徑數組。某些 API 支持路徑中的通配符來選擇多個字段。
      • id String Required
      • max Number Required
    • sort String|Object|Array[String|Object] 如果是String 字段路徑或路徑數組。某些 API 支持路徑中的通配符來選擇多個字段。如果是Object
      • _score Object
      • _doc Object
      • _geo_distance Object
      • _script Object
    • _source Boolean|Object 定義獲取源的方式。獲取可以完全禁用，或者源可以被過濾。如果是Object
      • exclude_vectors Boolean 如果 true ，返回的源中會排除向量字段。此選項優先于 includes ：即使向量字段與 includes 規則匹配，也會被排除。
      • excludes String|Array[String]
      • includes String|Array[String]
    • fields Array[Object] 一個通配符（ * ）字段模式的數組。請求返回匹配這些模式在 hits.fields 屬性中的字段名稱的值。一個包含格式說明的返回值字段引用
      • field String Required 字段路徑或路徑數組。某些 API 支持路徑中的通配符來選擇多個字段。
      • format String 返回值的格式。
      • include_unmapped Boolean 用來控制 是否對未映射字段（unmapped field）也返回聚合結果
    • suggest Object
      • text String 全局建議文本，避免在多個建議器中使用相同文本時重復
    • terminate_after Number 每個分片最多收集的文檔數量。如果一個查詢達到這個限制，Elasticsearch 會提前終止查詢。Elasticsearch 在排序之前收集文檔。 重要提示：謹慎使用。Elasticsearch 將此屬性應用于處理請求的每個分片。在可能的情況下，讓 Elasticsearch 自動執行早期終止。避免針對跨多個數據層的數據流索引的請求指定此屬性。 如果設置為 0 （默認值），查詢不會提前終止。默認值為 0 。
    • timeout 等待每個分片響應的時間。如果在超時到期之前未收到響應，請求將失敗并返回錯誤。默認情況下無超時設置。
    • track_scores Boolean 如果 true ，即使分數不用于排序，也會計算并返回文檔分數。默認值為 false 。
    • version Boolean 如果 true ，請求將文檔版本作為命中的一部分返回。默認值為 false 。
    • seq_no_primary_term Boolean 如果 true ，請求將每個命中的最后修改的序列號和主術語返回。 參考文檔
    • stored_fields String|Array[String]
    • pit Object
      • id String Required
      • keep_alive String 一個持續時間。單位可以是 nanos 、 micros 、 ms (毫秒)、 s (秒)、 m (分鐘)、 h (小時) 和 d (天)。也接受沒有單位的 “0” 和表示未指定值的 “-1”。
    • runtime_mappings Object
      • fields Object 對于類型 composite
      • fetch_fields Array[Object] 對于類型 lookup
      • format String date 類型運行時字段的自定義格式。
      • input_field String 字段路徑或路徑數組。某些 API 支持路徑中的通配符來選擇多個字段。
      • target_field String 字段路徑或路徑數組。某些 API 支持路徑中的通配符來選擇多個字段。
      • target_index String
      • script Object
      • type String Required 值是 boolean ， composite ， date ， double ， geo_point ， geo_shape ， ip ， keyword ， long ，或 lookup 。
      • stats Array[String] 與搜索關聯的統計分組。每個分組為其關聯的搜索維護一個統計聚合。您可以使用索引統計 API 檢索這些統計信息。
  • id String
  • params string
  • lang String 值是 painless 、 expression 、 mustache 或 java 。
  • options Object
• slice Object
  • field String：字段路徑或路徑數組。某些API支持在路徑中使用通配符來選擇多個字段
  • id String：Required
  • max Number：Required
• conflicts String 值為 abort 或 proceed 。

Responses

200

• batches Number 通過更新查詢檢索到的滾動響應數量。
• failures Array[object]: 如果在過程中出現任何不可恢復的錯誤，就會包含一系列的失敗。如果數組不為空，那么請求由于這些失敗而異常結束。通過查詢刪除是通過批量實現的，任何失敗都會導致整個過程結束，但當前批次的全部失敗都會被收集到該數組，可以使用 conflict選項來方式由于版本沖突而重新索引的結束。
  • cause Object Required：請求失敗的成因和詳細信息，定義了所有錯誤類型的共有屬性，還提供了根據錯誤類型而變化的額外詳細信息。
    • type String Required：錯誤類型
    • reason String ｜ Null
    • stack_trace String ：服務器堆棧跟蹤。僅當請求中包含 error_trace=true參數時才顯示。
    • caused_by Object: 請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
    • root_cause Array｜Object：請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
    • suppressed Array[Object]: 請求失敗的成因和詳細信息。此類定義了所有的錯誤類型共有的屬性。還提供了根據錯誤類型而變化的額外詳細信息。
  • id String Required
  • index String Required
  • status Number Required
• noops Number 由于更新查詢中使用的腳本為 ctx.op 返回了 nooping 值，而被忽略的文檔數量。
• deleted Number 成功刪除的文檔數量。
• requests_per_second Number 在更新查詢期間實際每秒運行的有效請求數量。
• retries Object
  • bulk Number Required 批量操作重試次數。
  • search Number Required 搜索操作重試次數。
• task String
• timed_out Boolean 如果為 true，則在通過查詢更新期間，某些請求超時了。
• took Number 毫秒時間單位=
• total Number 成功處理的文檔數量。
• updated Number 成功更新的文檔數量。
• version_conflicts Number 查詢更新觸發的版本沖突數量。
• throttled String：一個持續時間。單位可以是 nanos、micros、ms、s、m、h和d。也可以使用沒有單位的 0 和 -1 表示沒有指定值。
• throttled_millis Number 毫秒時間單位
• throttled_until String 一個持續時間。 nanos、micros、ms、s、m、h和d。也可以使用沒有單位的 0 和 -1 表示沒有指定值。
• throttled_unit_millis Number: 毫秒時間單位

示例

更新與查詢匹配的文檔

POST my-index-000001/_update_by_query?conflicts=proceed
{"query": { "term": {"user.id": "kimchy"}}
}

通過腳本來更新文檔的 _source。
它會把索引 my-index-000001 中所有 user.id 為 kimchy 的文檔的 count 字段加 1

POST my-index-000001/_update_by_query
{"script": {"source": "ctx._source.count++","lang": "painless"},"query": {"term": {"user.id": "kimchy"}}
}

查詢更新并手動分片（slice）

POST my-index-000001/_update_by_query
{"slice": {"id": 0,"max": 2},"script": {"source": "ctx._source['extra'] = 'test'"}
}

自動分片

POST my-index-000001/_update_by_query?refresh&slices=5
{"script": {"source": "ctx._source['extra'] = 'test'"}
}

Throttle an update by query operation 通過查詢限制更顯操作

格式

POST /_update_by_query/{task_id}/_rethrottle

更改特定 update by query 操作的每秒請求數量。加速查詢的 rethrottle 立即生效，而減速查詢的 rethrottle 則在完成當前批次后才生效，以防止滾動超時。

Path parameters

• task_id String Required

Query parameters

• requests_per_second Number 此請求在子請求每秒的節流限制。要關閉節流，將其設置為 -1 。

Responses

200

• nodes Object Required

Query DSL

Query DSL

什么是 Query DSL

是一種功能齊全的JSON樣式的查詢語言，支持復雜的搜索、過濾和聚合操作。他是Elasticsearch目前最原始最強大的查詢語言。

search

search

映射

Mapping

模版

templates

Aggregations

aggregations

節點設置

node-settings、

分析器

text-analysis

優化加速

search-speed

生產指導

生產指導

其他

mapping-source-field

_source 字段說明

_source 字段包含在索引時傳遞的原始json文檔正文。_source 字段本身不會被索引（因此不可搜索），但他被存儲起來，以便在執行獲取請求（如 get 或 search ）時返回.
如果關心磁盤使用情況，可以考慮下面的選項：

• 使用 synthetic _source,他在檢索時，重建源內容，而不是將其存儲在磁盤上。這樣會減少磁盤使用，但是會降低 Get 和 Search 查詢中對 _source 的訪問速度。
• 完全禁用 _source 字段。這回減少磁盤使用，但會禁用依賴 _source 的功能。

Synthetic _source

雖然很方便，但源字段中磁盤上占用了大量空間。Elasticsearch不是將源文檔按發送時的樣子存儲在磁盤上，而是在檢索時動態重建內容，要啟用此訂閱功能，請將索引設置 index.mapping.source.mode 的 值設置為 synthetic：

PUT idx
{"settings": {"index": {"mapping": {"source": {"mode": "synthetic"}}}}
}

雖然這種動態重建通常比按原樣保存源文檔并在查詢時加載它們要慢，但節省了大量存儲空間，在不需要時，通常不在查詢中加載 _source 字段，可以避免額外的延遲。

Supported fields 支持的字段

Synthetic _source 所有類型的字段都是支持。根據實現細節，不同的字段類型中使用 Synthetic _source 具有不同的屬性。

大多數字段類型使用相同的數據構造合成 _source ,最常見的是 doc_values 和存儲字段。對于這些字段類型， 不需要額外的空間來存儲 _source 字段的值。由于 doc_values 的存儲布局，生成的 _source 字段和原始文檔會發生變化。

對于所有其他字段類型，字段的原始值會“原樣”存儲，就像在非合成（non-synthetic）模式下的 _source 字段一樣。
在這種情況下，不會進行任何修改，_source 中的字段數據與原始文檔中的數據完全一致。
類似地，那些使用了 ignore_malformed（忽略格式錯誤）或 ignore_above（忽略過長值）的字段，其格式錯誤或被忽略的值也必須原樣存儲。
這種方式的缺點是存儲效率比較低，因為為了能重建 _source，需要額外保存一份字段的原始數據，而索引字段時本身還需要保存其他數據（比如 doc_values），導致同一份信息在不同地方重復存儲。

Synthetic _source restrictions 合成 _source 限制

Synthetic _source modifications 合成 _source 修改

當啟用合成 _source 時，檢索到的文檔與原始 JSON 相比會進行一些修改。

Arrays moved to leaf fields 數組已經移動到葉子結點

PUT idx/_doc/1
{"foo": [{"bar": 1},{"bar": 2}]
}

會變成

{"foo": {"bar": [1, 2]}
}

這可能會導致某些數組消失：

PUT idx/_doc/1
{"foo": [{"bar": 1},{"baz": 2}]
}

將會變為：

{"foo": {"bar": 1,"baz": 2}
}

Fields named as they are mapped 字段按其映射命名

按映射中的名稱創建合成源字段。在使用動態映射時，字段名中包含點（ . ）默認被視為多個對象，而字段名中的點在禁用 subobjects 的對象中會被保留。例如：

PUT idx/_doc/1
{"foo.bar.baz": 1
}

會變為

{"foo": {"bar": {"baz": 1}}
}

這會影響在腳本中如何引用源內容。例如，以腳本原始源形式引用腳本將返回 null：

"script": { "source": """  emit(params._source['foo.bar.baz'])  """ }

相反，源引用需要與映射結構保持一致：

"script": { "source": """  emit(params._source['foo']['bar']['baz'])  """ }

或者

"script": { "source": """  emit(params._source.foo.bar.baz)  """ }

以下字段 API 更可取，因為它們不僅對映射結構保持中立，而且如果可用會使用 docvalues，并且僅在需要時才回退到合成源。這減少了源合成，這是一個緩慢且昂貴的操作。

"script": { "source": """  emit(field('foo.bar.baz').get(null))   """ }
"script": { "source": """  emit($('foo.bar.baz', null))   """ }

Alphabetical sorting 字母排序

合成 _source 字段按字母順序排序。JSON RFC 將對象定義為“零個或多個名稱/值對的無序集合”，因此應用程序不應關心，但如果沒有合成 _source ，原始順序將被保留，并且某些應用程序可能會與規范相悖，根據該順序執行某些操作。

Representation of ranges

范圍字段值（例如long_range）始終以包含兩邊的方式表示

Reduced precision of geo_point values 精度降低

geo_point 字段的值以合成 _source 的形式表示，精度降低。

Minimizing source modifications

可以避免對特定對象或字段進行合成源代碼修改，但這需要額外的存儲成本。這通過參數 synthetic_source_keep 進行控制，具有以下選項：

• none: 源代碼與上述原始源代碼不同（默認）。
• arrays: 字段或對象的數組保留原始元素順序和重復元素。對于此類數組，合成源代碼片段不一定能完全匹配原始源代碼，例如數組 [1, 2, [5], [[4, [3]]], 5] 可能以原樣或等效格式（如 [1, 2, 5, 4, 3, 5] ）出現。未來可能會更改確切格式，以減少此選項的存儲開銷。
• all : 單例實例和相應字段或對象的數組源都會被記錄。應用于對象時，所有子對象和子字段的源都會被捕獲。此外，數組的原始源也會被捕獲，并以合成源的形式出現，且無修改。

PUT idx_keep
{"settings": {"index": {"mapping": {"source": {"mode": "synthetic"}}}},"mappings": {"properties": {"path": {"type": "object","synthetic_source_keep": "all"},"ids": {"type": "integer","synthetic_source_keep": "arrays"}}}
}

PUT idx_keep/_doc/1
{"path": {"to": [{ "foo": [3, 2, 1] },{ "foo": [30, 20, 10] }],"bar": "baz"},"ids": [ 200, 100, 300, 100 ]
}

返回原始源，無數組去重和排序：

{"path": {"to": [{ "foo": [3, 2, 1] },{ "foo": [30, 20, 10] }],"bar": "baz"},"ids": [ 200, 100, 300, 100 ]
}

捕獲數組源的選擇可以在索引級別應用，通過將 index.mapping.synthetic_source_keep 設置為 arrays 。這適用于索引中的所有對象和字段，除了那些 synthetic_source_keep 設置為 none 的顯式覆蓋項。在這種情況下，存儲開銷會隨著每個文檔源中數組數量和大小而增長，這是自然的。

Field types that support synthetic source with no storage overhead

以下字段類型使用 doc_values 或存儲字段的數據支持合成源，構建 _source 字段時無需額外的存儲空間。
不進行詳細介紹了

• aggregate_metric_double
• annotated-text
• binary
• boolean
• byte
• date
• date_nanos
• dense_vector
• double
• flattened
• float
• geo_point
• half_float
• histogram
• integer
• ip
• keyword
• long
• rang types
• scaled_float
• short
• text
• version
• wildcard

Disabling the _source field 禁用 _source 字段

盡管它非常方便，但源字段確實會在索引中產生存儲開銷。因此，可以按照以下方式禁用它：

PUT my-index-000001
{"mappings": {"_source": {"enabled": false}}
}

注意： 不要禁用 _source 字段，除非絕對必要。如果你禁用它，以下關鍵功能將不受支持：

• update 、 update_by_query 和 reindex API。
• 在 Kibana Discover 應用中顯示字段數據。
• 動態高亮顯示
• 從其中一個 Elasticsearch 索引重新索引到另一個索引的能力，無論是更改映射或分析，還是將索引升級到新的大版本。
• 通過查看索引時使用的原始文檔來調試查詢或聚合的能力。
• 未來可能具備自動修復索引損壞的能力。

注意 您不能禁用字段 _source ，當索引的 index_mode 設置為 logsdb 或 time_series 時。

如果磁盤空間是問題，最好增加壓縮級別而不是禁用 _source 。

Including / Excluding fields from _source 包含或者排除 _source 字段

從 _source 中移除字段與禁用 _source 類似，都有類似的缺點，尤其是你無法從一個 Elasticsearch 索引重新索引文檔到另一個索引。考慮使用源過濾代替。

includes / excludes 參數（也接受通配符）可以按如下方式使用：

PUT logs
{"mappings": {"_source": {"includes": ["*.count","meta.*"],"excludes": ["meta.description","meta.other.*"]}}
}

PUT logs/_doc/1
{"requests": {"count": 10,"foo": "bar"  (i)},"meta": {"name": "Some metric", "description": "Some metric description",  (i)"other": {"foo": "one",  (i)"baz": "two"   (i)}}
}

GET logs/_search
{"query": {"match": {"meta.other.foo": "one"   (ii)}}
}

(i) 這些字段將從存儲的 _source 字段中移除。
(ii)即使它不在存儲的 _source 中，我們仍然可以在這個字段上搜索。

重新索引

reindex

詞向量

Term vectors

Update a document

Update a document

更新查詢

update_by_query

Collapse search results

Collapse search results

Query and filter context

Query and filter context

kNN search

kNN search

Optimistic concurrency control

Optimistic concurrency control