Method: Elasticsearch::API::Actions#update

Defined in:
lib/elasticsearch/api/actions/update.rb

#update(arguments = {}) ⇒ Object

Update a document. Update a document by running a script or passing a partial document. If the Elasticsearch security features are enabled, you must have the ‘index` or `write` index privilege for the target index or index alias. The script can update, delete, or skip modifying the document. The API also supports passing a partial document, which is merged into the existing document. To fully replace an existing document, use the index API. This operation:

  • Gets the document (collocated with the shard) from the index.

  • Runs the specified script.

  • Indexes the result.

The document must still be reindexed, but using this API removes some network roundtrips and reduces chances of version conflicts between the GET and the index operation. The ‘_source` field must be enabled to use this API. In addition to `_source`, you can access the following variables through the `ctx` map: `_index`, `_type`, `_id`, `_version`, `_routing`, and `_now` (the current timestamp). For usage examples such as partial updates, upserts, and scripted updates, see the External documentation.

Parameters:

  • arguments (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    A unique identifier for the document to be updated. (Required)

  • :index (String) —

    The name of the target index. By default, the index is created automatically if it doesn’t exist. (Required)

  • :if_primary_term (Integer) —

    Only perform the operation if the document has this primary term.

  • :if_seq_no (Integer) —

    Only perform the operation if the document has this sequence number.

  • :include_source_on_error (Boolean) —

    True or false if to include the document source in the error message in case of parsing errors. Server default: true.

  • :lang (String) —

    The script language. Server default: painless.

  • :refresh (String) —

    If ‘true’, Elasticsearch refreshes the affected shards to make this operation visible to search. If ‘wait_for’, it waits for a refresh to make this operation visible to search. If ‘false’, it does nothing with refreshes. Server default: false.

  • :require_alias (Boolean) —

    If ‘true`, the destination must be an index alias.

  • :retry_on_conflict (Integer) —

    The number of times the operation should be retried when a conflict occurs. Server default: 0.

  • :routing (String) —

    A custom value used to route operations to a specific shard.

  • :timeout (Time) —

    The period to wait for the following operations: dynamic mapping updates and waiting for active shards. Elasticsearch waits for at least the timeout period before failing. The actual wait time could be longer, particularly when multiple waits occur. Server default: 1m.

  • :wait_for_active_shards (Integer, String) —

    The number of copies of each shard that must be active before proceeding with the operation. Set to ‘all’ or any positive integer up to the total number of shards in the index (‘number_of_replicas`+1). The default value of `1` means it waits for each primary shard to be active. Server default: 1.

  • :_source (Boolean, String, Array<String>) —

    If ‘false`, source retrieval is turned off. You can also specify a comma-separated list of the fields you want to retrieve. Server default: true.

  • :_source_excludes (String, Array<String>) —

    The source fields you want to exclude.

  • :_source_includes (String, Array<String>) —

    The source fields you want to retrieve.

  • :error_trace (Boolean) —

    When set to ‘true` Elasticsearch will include the full stack trace of errors when they occur.

  • :filter_path (String, Array<String>) —

    Comma-separated list of filters in dot notation which reduce the response returned by Elasticsearch.

  • :human (Boolean) —

    When set to ‘true` will return statistics in a format suitable for humans. For example `“exists_time”: “1h”` for humans and `“exists_time_in_millis”: 3600000` for computers. When disabled the human readable values will be omitted. This makes sense for responses being consumed only by machines.

  • :pretty (Boolean) —

    If set to ‘true` the returned JSON will be “pretty-formatted”. Only use this option for debugging only.

  • :headers (Hash) —

    Custom HTTP headers

  • :body (Hash) —

    request body

Raises:

  • (ArgumentError)

See Also:



78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
 
# File 'lib/elasticsearch/api/actions/update.rb', line 78

def update(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'update' }

  defined_params = [:index, :id].each_with_object({}) do |variable, set_variables|
    set_variables[variable] = arguments[variable] if arguments.key?(variable)
  end
  request_opts[:defined_params] = defined_params unless defined_params.empty?

  raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]
  raise ArgumentError, "Required argument 'index' missing" unless arguments[:index]
  raise ArgumentError, "Required argument 'id' missing" unless arguments[:id]

  arguments = arguments.clone
  headers = arguments.delete(:headers) || {}

  body = arguments.delete(:body)

  _id = arguments.delete(:id)

  _index = arguments.delete(:index)

  method = Elasticsearch::API::HTTP_POST
  path   = "#{Utils.listify(_index)}/_update/#{Utils.listify(_id)}"
  params = Utils.process_params(arguments)

  if Array(arguments[:ignore]).include?(404)
    Utils.rescue_from_not_found do
      Elasticsearch::API::Response.new(
        perform_request(method, path, params, body, headers, request_opts)
      )
    end
  else
    Elasticsearch::API::Response.new(
      perform_request(method, path, params, body, headers, request_opts)
    )
  end
end