type NewUpdateByQuery func(indexstring) *UpdateByQuery

funcNewUpdateByQueryFunc¶

func NewUpdateByQueryFunc(tpelastictransport.Interface)NewUpdateByQuery

NewUpdateByQueryFunc returns a new instance of UpdateByQuery with the provided transport.Used in the index of the library this allows to retrieve every apis in once place.

type Request struct {// Conflicts The preferred behavior when update by query hits version conflicts: `abort`// or `proceed`.Conflicts *conflicts.Conflicts `json:"conflicts,omitempty"`// MaxDocs The maximum number of documents to update.MaxDocs *int64 `json:"max_docs,omitempty"`// Query The documents to update using the Query DSL.Query *types.Query `json:"query,omitempty"`// Script The script to run to update the document source or metadata when updating.Script *types.Script `json:"script,omitempty"`// Slice Slice the request manually using the provided slice ID and total number of// slices.Slice *types.SlicedScroll `json:"slice,omitempty"`}

funcNewRequest¶added inv8.5.0

func NewRequest() *Request

NewRequest returns a Request

func (*Request)FromJSON¶added inv8.5.0

func (r *Request) FromJSON(datastring) (*Request,error)

FromJSON allows to load an arbitrary json into the request structure

type Response struct {// Batches The number of scroll responses pulled back by the update by query.Batches *int64 `json:"batches,omitempty"`// Deleted The number of documents that were successfully deleted.Deleted *int64 `json:"deleted,omitempty"`// Failures Array of failures if there were any unrecoverable errors during the process.// If this is non-empty then the request ended because of those failures.// Update by query is implemented using batches.// Any failure causes the entire process to end, but all failures in the current// batch are collected into the array.// You can use the `conflicts` option to prevent reindex from ending when// version conflicts occur.Failures []types.BulkIndexByScrollFailure `json:"failures,omitempty"`// Noops The number of documents that were ignored because the script used for the// update by query returned a noop value for `ctx.op`.Noops *int64 `json:"noops,omitempty"`// RequestsPerSecond The number of requests per second effectively run during the update by query.RequestsPerSecond *float32 `json:"requests_per_second,omitempty"`// Retries The number of retries attempted by update by query.// `bulk` is the number of bulk actions retried.// `search` is the number of search actions retried.Retries   *types.Retries `json:"retries,omitempty"`Tasktypes.TaskId   `json:"task,omitempty"`Throttledtypes.Duration `json:"throttled,omitempty"`// ThrottledMillis The number of milliseconds the request slept to conform to// `requests_per_second`.ThrottledMillis *int64         `json:"throttled_millis,omitempty"`ThrottledUntiltypes.Duration `json:"throttled_until,omitempty"`// ThrottledUntilMillis This field should always be equal to zero in an _update_by_query response.// It only has meaning when using the task API, where it indicates the next time// (in milliseconds since epoch) a throttled request will be run again in order// to conform to `requests_per_second`.ThrottledUntilMillis *int64 `json:"throttled_until_millis,omitempty"`// TimedOut If true, some requests timed out during the update by query.TimedOut *bool `json:"timed_out,omitempty"`// Took The number of milliseconds from start to end of the whole operation.Took *int64 `json:"took,omitempty"`// Total The number of documents that were successfully processed.Total *int64 `json:"total,omitempty"`// Updated The number of documents that were successfully updated.Updated *int64 `json:"updated,omitempty"`// VersionConflicts The number of version conflicts that the update by query hit.VersionConflicts *int64 `json:"version_conflicts,omitempty"`}

funcNewResponse¶added inv8.7.0

func NewResponse() *Response

NewResponse returns a Response

type UpdateByQuery struct {// contains filtered or unexported fields}

funcNew¶

func New(tpelastictransport.Interface) *UpdateByQuery

Update documents.Updates documents that match the specified query.If no query is specified, performs an update on every document in the datastream or index without modifying the source, which is useful for picking upmapping changes.

If the Elasticsearch security features are enabled, you must have thefollowing index privileges for the target data stream, index, or alias:

* `read`* `index` or `write`

You can specify the query criteria in the request URI or the request bodyusing the same syntax as the search API.

When you submit an update by query request, Elasticsearch gets a snapshot ofthe data stream or index when it begins processing the request and updatesmatching documents using internal versioning.When the versions match, the document is updated and the version number isincremented.If a document changes between the time that the snapshot is taken and theupdate operation is processed, it results in a version conflict and theoperation fails.You can opt to count version conflicts instead of halting and returning bysetting `conflicts` to `proceed`.Note that if you opt to count version conflicts, the operation could attemptto update more documents from the source than `max_docs` until it hassuccessfully updated `max_docs` documents or it has gone through everydocument in the source query.

NOTE: Documents with a version equal to 0 cannot be updated using update byquery because internal versioning does not support 0 as a valid versionnumber.

While processing an update by query request, Elasticsearch performs multiplesearch requests sequentially to find all of the matching documents.A bulk update request is performed for each batch of matching documents.Any query or update failures cause the update by query request to fail andthe failures are shown in the response.Any update requests that completed successfully still stick, they are notrolled back.

**Throttling update requests**

To control the rate at which update by query issues batches of updateoperations, you can set `requests_per_second` to any positive decimal number.This pads each batch with a wait time to throttle the rate.Set `requests_per_second` to `-1` to turn off throttling.

Throttling uses a wait time between batches so that the internal scrollrequests can be given a timeout that takes the request padding into account.The padding time is the difference between the batch size divided by the`requests_per_second` and the time spent writing.By default the batch size is 1000, so if `requests_per_second` is set to`500`:

```target_time = 1000 / 500 per second = 2 secondswait_time = target_time - write_time = 2 seconds - .5 seconds = 1.5 seconds```

Since the batch is issued as a single _bulk request, large batch sizes causeElasticsearch to create many requests and wait before starting the next set.This is "bursty" instead of "smooth".

**Slicing**

Update by query supports sliced scroll to parallelize the update process.This can improve efficiency and provide a convenient way to break the requestdown into smaller parts.

Setting `slices` to `auto` chooses a reasonable number for most data streamsand indices.This setting will use one slice per shard, up to a certain limit.If there are multiple source data streams or indices, it will choose thenumber of slices based on the index or backing index with the smallest numberof shards.

Adding `slices` to `_update_by_query` just automates the manual process ofcreating sub-requests, which means it has some quirks:

* You can see these requests in the tasks APIs. These sub-requests are"child" tasks of the task for the request with slices.* Fetching the status of the task for the request with `slices` only containsthe status of completed slices.* These sub-requests are individually addressable for things likecancellation and rethrottling.* Rethrottling the request with `slices` will rethrottle the unfinishedsub-request proportionally.* Canceling the request with slices will cancel each sub-request.* Due to the nature of slices each sub-request won't get a perfectly evenportion of the documents. All documents will be addressed, but some slicesmay be larger than others. Expect larger slices to have a more evendistribution.* Parameters like `requests_per_second` and `max_docs` on a request withslices are distributed proportionally to each sub-request. Combine that withthe point above about distribution being uneven and you should conclude thatusing `max_docs` with `slices` might not result in exactly `max_docs`documents being updated.* Each sub-request gets a slightly different snapshot of the source datastream or index though these are all taken at approximately the same time.

If you're slicing manually or otherwise tuning automatic slicing, keep inmind that:

* Query performance is most efficient when the number of slices is equal tothe number of shards in the index or backing index. If that number is large(for example, 500), choose a lower number as too many slices hurtsperformance. Setting slices higher than the number of shards generally doesnot improve efficiency and adds overhead.* Update performance scales linearly across available resources with thenumber of slices.

Whether query or update performance dominates the runtime depends on thedocuments being reindexed and cluster resources.

**Update the document source**

Update by query supports scripts to update the document source.As with the update API, you can set `ctx.op` to change the operation that isperformed.

Set `ctx.op = "noop"` if your script decides that it doesn't have to make anychanges.The update by query operation skips updating the document and increments the`noop` counter.

Set `ctx.op = "delete"` if your script decides that the document should bedeleted.The update by query operation deletes the document and increments the`deleted` counter.

Update by query supports only `index`, `noop`, and `delete`.Setting `ctx.op` to anything else is an error.Setting any other field in `ctx` is an error.This API enables you to only modify the source of matching documents; youcannot move them.

https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-update-by-query.html

func (*UpdateByQuery)AllowNoIndices¶

func (r *UpdateByQuery) AllowNoIndices(allownoindicesbool) *UpdateByQuery

AllowNoIndices If `false`, the request returns an error if any wildcard expression, indexalias, or `_all` value targets only missing or closed indices.This behavior applies even if the request targets other open indices.For example, a request targeting `foo*,bar*` returns an error if an indexstarts with `foo` but no index starts with `bar`.API name: allow_no_indices

func (*UpdateByQuery)AnalyzeWildcard¶

func (r *UpdateByQuery) AnalyzeWildcard(analyzewildcardbool) *UpdateByQuery

AnalyzeWildcard If `true`, wildcard and prefix queries are analyzed.This parameter can be used only when the `q` query string parameter isspecified.API name: analyze_wildcard

func (*UpdateByQuery)Analyzer¶

func (r *UpdateByQuery) Analyzer(analyzerstring) *UpdateByQuery

Analyzer The analyzer to use for the query string.This parameter can be used only when the `q` query string parameter isspecified.API name: analyzer

func (*UpdateByQuery)Conflicts¶

func (r *UpdateByQuery) Conflicts(conflictsconflicts.Conflicts) *UpdateByQuery

Conflicts The preferred behavior when update by query hits version conflicts: `abort`or `proceed`.API name: conflicts

func (*UpdateByQuery)DefaultOperator¶

func (r *UpdateByQuery) DefaultOperator(defaultoperatoroperator.Operator) *UpdateByQuery

DefaultOperator The default operator for query string query: `AND` or `OR`.This parameter can be used only when the `q` query string parameter isspecified.API name: default_operator

func (*UpdateByQuery)Df¶

func (r *UpdateByQuery) Df(dfstring) *UpdateByQuery

Df The field to use as default where no field prefix is given in the querystring.This parameter can be used only when the `q` query string parameter isspecified.API name: df

func (UpdateByQuery)Do¶

func (rUpdateByQuery) Do(providedCtxcontext.Context) (*Response,error)

Do runs the request through the transport, handle the response and returns a updatebyquery.Response

func (*UpdateByQuery)ErrorTrace¶added inv8.14.0

func (r *UpdateByQuery) ErrorTrace(errortracebool) *UpdateByQuery

ErrorTrace When set to `true` Elasticsearch will include the full stack trace of errorswhen they occur.API name: error_trace

func (*UpdateByQuery)ExpandWildcards¶

func (r *UpdateByQuery) ExpandWildcards(expandwildcards ...expandwildcard.ExpandWildcard) *UpdateByQuery

ExpandWildcards The type of index that wildcard patterns can match.If the request can target data streams, this argument determines whetherwildcard expressions match hidden data streams.It supports comma-separated values, such as `open,hidden`.API name: expand_wildcards

func (*UpdateByQuery)FilterPath¶added inv8.14.0

func (r *UpdateByQuery) FilterPath(filterpaths ...string) *UpdateByQuery

FilterPath Comma-separated list of filters in dot notation which reduce the responsereturned by Elasticsearch.API name: filter_path

func (*UpdateByQuery)From¶

func (r *UpdateByQuery) From(fromstring) *UpdateByQuery

From Skips the specified number of documents.API name: from

func (*UpdateByQuery)Header¶

func (r *UpdateByQuery) Header(key, valuestring) *UpdateByQuery

Header set a key, value pair in the UpdateByQuery headers map.

func (*UpdateByQuery)HttpRequest¶

func (r *UpdateByQuery) HttpRequest(ctxcontext.Context) (*http.Request,error)

HttpRequest returns the http.Request object built from thegiven parameters.

func (*UpdateByQuery)Human¶added inv8.14.0

func (r *UpdateByQuery) Human(humanbool) *UpdateByQuery

Human When set to `true` will return statistics in a format suitable for humans.For example `"exists_time": "1h"` for humans and`"eixsts_time_in_millis": 3600000` for computers. When disabled the humanreadable values will be omitted. This makes sense for responses beingconsumedonly by machines.API name: human

func (*UpdateByQuery)IgnoreUnavailable¶

func (r *UpdateByQuery) IgnoreUnavailable(ignoreunavailablebool) *UpdateByQuery

IgnoreUnavailable If `false`, the request returns an error if it targets a missing or closedindex.API name: ignore_unavailable

func (*UpdateByQuery)Lenient¶

func (r *UpdateByQuery) Lenient(lenientbool) *UpdateByQuery

Lenient If `true`, format-based query failures (such as providing text to a numericfield) in the query string will be ignored.This parameter can be used only when the `q` query string parameter isspecified.API name: lenient

func (*UpdateByQuery)MaxDocs¶

func (r *UpdateByQuery) MaxDocs(maxdocsint64) *UpdateByQuery

MaxDocs The maximum number of documents to update.API name: max_docs

func (UpdateByQuery)Perform¶added inv8.7.0

func (rUpdateByQuery) Perform(providedCtxcontext.Context) (*http.Response,error)

Perform runs the http.Request through the provided transport and returns an http.Response.

func (*UpdateByQuery)Pipeline¶

func (r *UpdateByQuery) Pipeline(pipelinestring) *UpdateByQuery

Pipeline The ID of the pipeline to use to preprocess incoming documents.If the index has a default ingest pipeline specified, then setting the valueto `_none` disables the default ingest pipeline for this request.If a final pipeline is configured it will always run, regardless of the valueof this parameter.API name: pipeline

func (*UpdateByQuery)Preference¶

func (r *UpdateByQuery) Preference(preferencestring) *UpdateByQuery

Preference The node or shard the operation should be performed on.It is random by default.API name: preference

func (*UpdateByQuery)Pretty¶added inv8.14.0

func (r *UpdateByQuery) Pretty(prettybool) *UpdateByQuery

Pretty If set to `true` the returned JSON will be "pretty-formatted". Only usethis option for debugging only.API name: pretty

func (*UpdateByQuery)Q¶added inv8.16.0

func (r *UpdateByQuery) Q(qstring) *UpdateByQuery

Q A query in the Lucene query string syntax.API name: q

func (*UpdateByQuery)Query¶added inv8.9.0

func (r *UpdateByQuery) Query(query *types.Query) *UpdateByQuery

Query The documents to update using the Query DSL.API name: query

func (*UpdateByQuery)Raw¶

func (r *UpdateByQuery) Raw(rawio.Reader) *UpdateByQuery

Raw takes a json payload as input which is then passed to the http.RequestIf specified Raw takes precedence on Request method.

func (*UpdateByQuery)Refresh¶

func (r *UpdateByQuery) Refresh(refreshbool) *UpdateByQuery

Refresh If `true`, Elasticsearch refreshes affected shards to make the operationvisible to search after the request completes.This is different than the update API's `refresh` parameter, which causesjust the shard that received the request to be refreshed.API name: refresh

func (*UpdateByQuery)Request¶

func (r *UpdateByQuery) Request(req *Request) *UpdateByQuery

Request allows to set the request property with the appropriate payload.

func (*UpdateByQuery)RequestCache¶

func (r *UpdateByQuery) RequestCache(requestcachebool) *UpdateByQuery

RequestCache If `true`, the request cache is used for this request.It defaults to the index-level setting.API name: request_cache

func (*UpdateByQuery)RequestsPerSecond¶

func (r *UpdateByQuery) RequestsPerSecond(requestspersecondstring) *UpdateByQuery

RequestsPerSecond The throttle for this request in sub-requests per second.API name: requests_per_second

func (*UpdateByQuery)Routing¶

func (r *UpdateByQuery) Routing(routingstring) *UpdateByQuery

Routing A custom value used to route operations to a specific shard.API name: routing

func (*UpdateByQuery)Script¶added inv8.9.0

func (r *UpdateByQuery) Script(script *types.Script) *UpdateByQuery

Script The script to run to update the document source or metadata when updating.API name: script

func (*UpdateByQuery)Scroll¶

func (r *UpdateByQuery) Scroll(durationstring) *UpdateByQuery

Scroll The period to retain the search context for scrolling.API name: scroll

func (*UpdateByQuery)ScrollSize¶

func (r *UpdateByQuery) ScrollSize(scrollsizestring) *UpdateByQuery

ScrollSize The size of the scroll request that powers the operation.API name: scroll_size

func (*UpdateByQuery)SearchTimeout¶

func (r *UpdateByQuery) SearchTimeout(durationstring) *UpdateByQuery

SearchTimeout An explicit timeout for each search request.By default, there is no timeout.API name: search_timeout

func (*UpdateByQuery)SearchType¶

func (r *UpdateByQuery) SearchType(searchtypesearchtype.SearchType) *UpdateByQuery

SearchType The type of the search operation. Available options include`query_then_fetch` and `dfs_query_then_fetch`.API name: search_type

func (*UpdateByQuery)Slice¶added inv8.9.0

func (r *UpdateByQuery) Slice(slice *types.SlicedScroll) *UpdateByQuery

Slice Slice the request manually using the provided slice ID and total number ofslices.API name: slice

func (*UpdateByQuery)Slices¶

func (r *UpdateByQuery) Slices(slicesstring) *UpdateByQuery

Slices The number of slices this task should be divided into.API name: slices

func (*UpdateByQuery)Sort¶

func (r *UpdateByQuery) Sort(sorts ...string) *UpdateByQuery

Sort A comma-separated list of <field>:<direction> pairs.API name: sort

func (*UpdateByQuery)Stats¶

func (r *UpdateByQuery) Stats(stats ...string) *UpdateByQuery

Stats The specific `tag` of the request for logging and statistical purposes.API name: stats

func (*UpdateByQuery)TerminateAfter¶

func (r *UpdateByQuery) TerminateAfter(terminateafterstring) *UpdateByQuery

TerminateAfter The maximum number of documents to collect for each shard.If a query reaches this limit, Elasticsearch terminates the query early.Elasticsearch collects documents before sorting.

IMPORTANT: Use with caution.Elasticsearch applies this parameter to each shard handling the request.When possible, let Elasticsearch perform early termination automatically.Avoid specifying this parameter for requests that target data streams withbacking indices across multiple data tiers.API name: terminate_after

func (*UpdateByQuery)Timeout¶

func (r *UpdateByQuery) Timeout(durationstring) *UpdateByQuery

Timeout The period each update request waits for the following operations: dynamicmapping updates, waiting for active shards.By default, it is one minute.This guarantees Elasticsearch waits for at least the timeout before failing.The actual wait time could be longer, particularly when multiple waits occur.API name: timeout

func (*UpdateByQuery)Version¶

func (r *UpdateByQuery) Version(versionbool) *UpdateByQuery

Version If `true`, returns the document version as part of a hit.API name: version

func (*UpdateByQuery)VersionType¶

func (r *UpdateByQuery) VersionType(versiontypebool) *UpdateByQuery

VersionType Should the document increment the version number (internal) on hit or not(reindex)API name: version_type

func (*UpdateByQuery)WaitForActiveShards¶

func (r *UpdateByQuery) WaitForActiveShards(waitforactiveshardsstring) *UpdateByQuery

WaitForActiveShards The number of shard copies that must be active before proceeding with theoperation.Set to `all` or any positive integer up to the total number of shards in theindex (`number_of_replicas+1`).The `timeout` parameter controls how long each write request waits forunavailable shards to become available.Both work exactly the way they work in the bulk API.API name: wait_for_active_shards

func (*UpdateByQuery)WaitForCompletion¶

func (r *UpdateByQuery) WaitForCompletion(waitforcompletionbool) *UpdateByQuery

WaitForCompletion If `true`, the request blocks until the operation is complete.If `false`, Elasticsearch performs some preflight checks, launches therequest, and returns a task ID that you can use to cancel or get the statusof the task.Elasticsearch creates a record of this task as a document at`.tasks/task/${taskId}`.API name: wait_for_completion