Module: Elasticsearch::API::Actions

Defined in:
lib/elasticsearch/api/actions/get.rb,
lib/elasticsearch/api/actions/bulk.rb,
lib/elasticsearch/api/actions/info.rb,
lib/elasticsearch/api/actions/mget.rb,
lib/elasticsearch/api/actions/ping.rb,
lib/elasticsearch/api/actions/count.rb,
lib/elasticsearch/api/actions/index.rb,
lib/elasticsearch/api/actions/create.rb,
lib/elasticsearch/api/actions/delete.rb,
lib/elasticsearch/api/actions/exists.rb,
lib/elasticsearch/api/actions/scroll.rb,
lib/elasticsearch/api/actions/search.rb,
lib/elasticsearch/api/actions/update.rb,
lib/elasticsearch/api/actions/explain.rb,
lib/elasticsearch/api/actions/msearch.rb,
lib/elasticsearch/api/actions/reindex.rb,
lib/elasticsearch/api/actions/benchmark.rb,
lib/elasticsearch/api/actions/rank_eval.rb,
lib/elasticsearch/api/actions/field_caps.rb,
lib/elasticsearch/api/actions/get_script.rb,
lib/elasticsearch/api/actions/get_source.rb,
lib/elasticsearch/api/actions/put_script.rb,
lib/elasticsearch/api/actions/termvectors.rb,
lib/elasticsearch/api/actions/clear_scroll.rb,
lib/elasticsearch/api/actions/mtermvectors.rb,
lib/elasticsearch/api/actions/delete_script.rb,
lib/elasticsearch/api/actions/exists_source.rb,
lib/elasticsearch/api/actions/search_shards.rb,
lib/elasticsearch/api/actions/abort_benchmark.rb,
lib/elasticsearch/api/actions/delete_by_query.rb,
lib/elasticsearch/api/actions/params_registry.rb,
lib/elasticsearch/api/actions/search_template.rb,
lib/elasticsearch/api/actions/update_by_query.rb,
lib/elasticsearch/api/actions/msearch_template.rb,
lib/elasticsearch/api/actions/reindex_rethrottle.rb,
lib/elasticsearch/api/actions/delete_by_rethrottle.rb,
lib/elasticsearch/api/actions/render_search_template.rb,
lib/elasticsearch/api/actions/scripts_painless_execute.rb,
lib/elasticsearch/api/actions/update_by_query_rethrottle.rb

Defined Under Namespace

Modules: ParamsRegistry

Instance Method Summary collapse

Instance Method Details

#abort_benchmark(arguments = {}) ⇒ Object

Abort a running benchmark

Examples:


client.abort_benchmark name: 'my_benchmark'

Options Hash (arguments):

  • :name (String) —

    A benchmark name

See Also:


19
20
21
22
23
24
25
26
 
# File 'lib/elasticsearch/api/actions/abort_benchmark.rb', line 19

def abort_benchmark(arguments={})
  method = HTTP_POST
  path   = "_bench/abort/#{arguments[:name]}"
  params = {}
  body   = nil

  perform_request(method, path, params, body).body
end

#benchmark(arguments = {}) ⇒ Object

Run a single query, or a set of queries, and return statistics on their performance

Examples:

Return statistics for a single query


client.benchmark body: {
  name: 'my_benchmark',
  competitors: [
    {
      name: 'query_1',
      requests: [
        { query: { match: { _all: 'a*' } } }
      ]
    }
  ]
}

Return statistics for a set of “competing” queries


client.benchmark body: {
  name: 'my_benchmark',
  competitors: [
    {
      name: 'query_a',
      requests: [
        { query: { match: { _all: 'a*' } } }
      ]
    },
    {
      name: 'query_b',
      requests: [
        { query: { match: { _all: 'b*' } } }
      ]
    }
  ]
}

Options Hash (arguments):

  • :index (List) —

    A comma-separated list of index names; use `_all` or empty string to perform the operation on all indices

  • :type (String) —

    The name of the document type

  • :body (Hash) —

    The search definition using the Query DSL

  • :verbose (Boolean) —

    Specify whether to return verbose statistics about each iteration (default: false)

See Also:


54
55
56
57
58
59
60
61
 
# File 'lib/elasticsearch/api/actions/benchmark.rb', line 54

def benchmark(arguments={})
  method = HTTP_PUT
  path   = "_bench"
  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = arguments[:body]

  perform_request(method, path, params, body).body
end

#bulk(arguments = {}) ⇒ Hash

Note:

The body argument is required and cannot be empty.

Perform multiple index, delete or update operations in a single request.

Supports various different formats of the payload: Array of Strings, Header/Data pairs, or the conveniency “combined” format where data is passed along with the header in a single item in a custom `:data` key.

Examples:

Perform three operations in a single request, passing actions and data as an array of hashes


client.bulk body: [
  { index: { _index: 'myindex', _type: 'mytype', _id: 1 } },
  { title: 'foo' },

  { index: { _index: 'myindex', _type: 'mytype', _id: 2 } },
  { title: 'foo' },

  { delete: { _index: 'myindex', _type: 'mytype', _id: 3  } }
]

Perform three operations in a single request, passing data in the `:data` option


client.bulk body: [
  { index:  { _index: 'myindex', _type: 'mytype', _id: 1, data: { title: 'foo' } } },
  { update: { _index: 'myindex', _type: 'mytype', _id: 2, data: { doc: { title: 'foo' } } } },
  { delete: { _index: 'myindex', _type: 'mytype', _id: 3  } }
]

Perform a script-based bulk update, passing scripts in the `:data` option


client.bulk body: [
  { update: { _index: 'myindex', _type: 'mytype', _id: 1,
             data: {
              script: "ctx._source.counter += value",
              lang: 'js',
              params: { value: 1 }, upsert: { counter: 0 } }
            }},
  { update: { _index: 'myindex', _type: 'mytype', _id: 2,
             data: {
              script: "ctx._source.counter += value",
              lang: 'js',
              params: { value: 42 }, upsert: { counter: 0 } }
             }}

]

Options Hash (arguments):

  • :index (String) —

    Default index for items which don't provide one

  • :type (String) —

    Default document type for items which don't provide one

  • :body (Hash) —

    The operation definition and data (action-data pairs), separated by newlines (Required)

  • :wait_for_active_shards (String) —

    Sets the number of shard copies that must be active before proceeding with the bulk operation. Defaults to 1, meaning the primary shard only. Set to `all` for all shard copies, otherwise set to any non-negative value less than or equal to the total number of copies for the shard (number of replicas + 1)

  • :refresh (String) —

    If `true` then refresh the effected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` (the default) then do nothing with refreshes. (options: true, false, wait_for)

  • :routing (String) —

    Specific routing value

  • :timeout (Time) —

    Explicit operation timeout

  • :type (String) —

    Default document type for items which don't provide one

  • :_source (List) —

    True or false to return the _source field or not, or default list of fields to return, can be overridden on each sub-request

  • :_source_excludes (List) —

    Default list of fields to exclude from the returned _source field, can be overridden on each sub-request

  • :_source_includes (List) —

    Default list of fields to extract and return from the _source field, can be overridden on each sub-request

  • :pipeline (String) —

    The pipeline id to preprocess incoming documents with

See Also:


71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/elasticsearch/api/actions/bulk.rb', line 71

def bulk(arguments={})
  arguments = arguments.clone

  type      = arguments.delete(:type)

  method = HTTP_POST
  path   = Utils.__pathify Utils.__escape(arguments[:index]), Utils.__escape(type), '_bulk'

  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = arguments[:body]

  if body.is_a? Array
    payload = Utils.__bulkify(body)
  else
    payload = body
  end

  perform_request(method, path, params, payload, {"Content-Type" => "application/x-ndjson"}).body
end

#clear_scroll(arguments = {}) ⇒ Object

Abort a particular scroll search and clear all the resources associated with it.

Options Hash (arguments):

  • :scroll_id (List) —

    A comma-separated list of scroll IDs to clear

  • :body (Hash) —

    A comma-separated list of scroll IDs to clear if none was specified via the scroll_id parameter

See Also:


16
17
18
19
20
21
22
23
 
# File 'lib/elasticsearch/api/actions/clear_scroll.rb', line 16

def clear_scroll(arguments={})
  method = Elasticsearch::API::HTTP_DELETE
  path   = Utils.__pathify '_search/scroll', Utils.__listify(arguments.delete(:scroll_id))
  params = {}
  body   = arguments[:body]

  perform_request(method, path, params, body).body
end

#count(arguments = {}) ⇒ Object

Get the number of documents for the cluster, index, type, or a query.

Examples:

Get the number of all documents in the cluster


client.count

Get the number of documents in a specified index


client.count index: 'myindex'

Get the number of documents matching a specific query


index: 'my_index', body: { filtered: { filter: { terms: { foo: ['bar'] } } } }

Options Hash (arguments):

  • :index (List) —

    A comma-separated list of indices to restrict the results

  • :type (List) —

    A comma-separated list of types to restrict the results

  • :body (Hash) —

    A query to restrict the results specified with the Query DSL (optional)

  • :ignore_unavailable (Boolean) —

    Whether specified concrete indices should be ignored when unavailable (missing or closed)

  • :ignore_throttled (Boolean) —

    Whether specified concrete, expanded or aliased indices should be ignored when throttled

  • :allow_no_indices (Boolean) —

    Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified)

  • :expand_wildcards (String) —

    Whether to expand wildcard expression to concrete indices that are open, closed or both. (options: open, closed, none, all)

  • :min_score (Number) —

    Include only documents with a specific `_score` value in the result

  • :preference (String) —

    Specify the node or shard the operation should be performed on (default: random)

  • :routing (List) —

    A comma-separated list of specific routing values

  • :q (String) —

    Query in the Lucene query string syntax

  • :analyzer (String) —

    The analyzer to use for the query string

  • :analyze_wildcard (Boolean) —

    Specify whether wildcard and prefix queries should be analyzed (default: false)

  • :default_operator (String) —

    The default operator for query string query (AND or OR) (options: AND, OR)

  • :df (String) —

    The field to use as default where no field prefix is given in the query string

  • :lenient (Boolean) —

    Specify whether format-based query failures (such as providing text to a numeric field) should be ignored

  • :terminate_after (Number) —

    The maximum count for each shard, upon reaching which the query execution will terminate early

See Also:


44
45
46
47
48
49
50
51
52
 
# File 'lib/elasticsearch/api/actions/count.rb', line 44

def count(arguments={})
  method = HTTP_GET
  path   = Utils.__pathify( Utils.__listify(arguments[:index]), Utils.__listify(arguments[:type]), '_count' )

  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = arguments[:body]

  perform_request(method, path, params, body).body
end

#create(arguments = {}) ⇒ Object

Create a new document.

The API will create new document, if it doesn't exist yet – in that case, it will return a `409` error (`version_conflict_engine_exception`).

You can leave out the `:id` parameter for the ID to be generated automatically

Examples:

Create a document with an ID


client.create index: 'myindex',
             type: 'doc',
             id: '1',
             body: {
              title: 'Test 1'
            }

Create a document with an auto-generated ID


client.create index: 'myindex',
             type: 'doc',
             body: {
              title: 'Test 1'
            }

Options Hash (arguments):

  • :id (String) —

    Document ID (optional, will be auto-generated if missing)

  • :index (String) —

    The name of the index (Required)

  • :type (String) —

    The type of the document (Required)

  • :body (Hash) —

    The document

  • :consistency (String) —

    Explicit write consistency setting for the operation (options: one, quorum, all)

  • :include_type_name (Boolean) —

    Whether a type should be expected in the body of the mappings.

  • :op_type (String) —

    Explicit operation type (options: index, create)

  • :parent (String) —

    ID of the parent document

  • :percolate (String) —

    Percolator queries to execute while indexing the document

  • :refresh (Boolean) —

    Refresh the index after performing the operation

  • :replication (String) —

    Specific replication type (options: sync, async)

  • :routing (String) —

    Specific routing value

  • :timeout (Time) —

    Explicit operation timeout

  • :timestamp (Time) —

    Explicit timestamp for the document

  • :ttl (Duration) —

    Expiration time for the document

  • :version (Number) —

    Explicit version number for concurrency control

  • :version_type (String) —

    Specific version type (options: internal, external, external_gte, force)

See Also:


37
38
39
40
41
42
43
 
# File 'lib/elasticsearch/api/actions/create.rb', line 37

def create(arguments={})
  if arguments[:id]
    index arguments.update :op_type => 'create'
  else
    index arguments
  end
end

#delete(arguments = {}) ⇒ Object

Delete a single document.

Examples:

Delete a document


client.delete index: 'myindex', type: 'mytype', id: '1'

Delete a document with specific routing


client.delete index: 'myindex', type: 'mytype', id: '1', routing: 'abc123'

Options Hash (arguments):

  • :id (String) —

    The document ID (Required)

  • :index (String) —

    The name of the index (Required)

  • :type (String) —

    The type of the document

  • :wait_for_active_shards (String) —

    Sets the number of shard copies that must be active before proceeding with the delete operation. Defaults to 1, meaning the primary shard only. Set to `all` for all shard copies, otherwise set to any non-negative value less than or equal to the total number of copies for the shard (number of replicas + 1)

  • :parent (String) —

    ID of parent document

  • :refresh (String) —

    If `true` then refresh the effected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` (the default) then do nothing with refreshes. (options: true, false, wait_for)

  • :routing (String) —

    Specific routing value

  • :timeout (Time) —

    Explicit operation timeout

  • :if_seq_no (Number) —

    only perform the delete operation if the last operation that has changed the document has the specified sequence number

  • :if_primary_term (Number) —

    only perform the delete operation if the last operation that has changed the document has the specified primary term

  • :version (Number) —

    Explicit version number for concurrency control

  • :version_type (String) —

    Specific version type (options: internal, external, external_gte, force)

Raises:

  • (ArgumentError)

See Also:


34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/elasticsearch/api/actions/delete.rb', line 34

def delete(arguments={})
  raise ArgumentError, "Required argument 'index' missing" unless arguments[:index]
  raise ArgumentError, "Required argument 'id' missing"    unless arguments[:id]
  arguments[:type] ||= DEFAULT_DOC

  method = HTTP_DELETE
  path   = Utils.__pathify Utils.__escape(arguments[:index]),
                           Utils.__escape(arguments[:type]),
                           Utils.__escape(arguments[:id])

  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = nil

  if Array(arguments[:ignore]).include?(404)
    Utils.__rescue_from_not_found { perform_request(method, path, params, body).body }
  else
    perform_request(method, path, params, body).body
  end
end

#delete_by_query(arguments = {}) ⇒ Object

Delete documents which match specified query.

Provide the query either as a “query string” query in the `:q` argument, or using the Elasticsearch's [Query DSL](www.elastic.co/guide/reference/query-dsl/) in the `:body` argument.

Examples:

Deleting documents with a simple query


client.delete_by_query index: 'myindex', q: 'title:test'

Deleting documents using the Query DSL


client.delete_by_query index: 'myindex', body: { query: { term: { published: false } } }

Options Hash (arguments):

  • :index (List) —

    A comma-separated list of index names to search; use `_all` or empty string to perform the operation on all indices (Required)

  • :type (List) —

    A comma-separated list of document types to search; leave empty to perform the operation on all types

  • :body (Hash) —

    The search definition using the Query DSL (Required)

  • :analyzer (String) —

    The analyzer to use for the query string

  • :analyze_wildcard (Boolean) —

    Specify whether wildcard and prefix queries should be analyzed (default: false)

  • :default_operator (String) —

    The default operator for query string query (AND or OR) (options: AND, OR)

  • :df (String) —

    The field to use as default where no field prefix is given in the query string

  • :from (Number) —

    Starting offset (default: 0)

  • :ignore_unavailable (Boolean) —

    Whether specified concrete indices should be ignored when unavailable (missing or closed)

  • :allow_no_indices (Boolean) —

    Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified)

  • :conflicts (String) —

    What to do when the delete by query hits version conflicts? (options: abort, proceed)

  • :expand_wildcards (String) —

    Whether to expand wildcard expression to concrete indices that are open, closed or both. (options: open, closed, none, all)

  • :lenient (Boolean) —

    Specify whether format-based query failures (such as providing text to a numeric field) should be ignored

  • :preference (String) —

    Specify the node or shard the operation should be performed on (default: random)

  • :q (String) —

    Query in the Lucene query string syntax

  • :routing (List) —

    A comma-separated list of specific routing values

  • :scroll (Time) —

    Specify how long a consistent view of the index should be maintained for scrolled search

  • :search_type (String) —

    Search operation type (options: query_then_fetch, dfs_query_then_fetch)

  • :search_timeout (Time) —

    Explicit timeout for each search request. Defaults to no timeout.

  • :size (Number) —

    Number of hits to return (default: 10)

  • :sort (List) —

    A comma-separated list of <field>:<direction> pairs

  • :_source (List) —

    True or false to return the _source field or not, or a list of fields to return

  • :_source_excludes (List) —

    A list of fields to exclude from the returned _source field

  • :_source_includes (List) —

    A list of fields to extract and return from the _source field

  • :terminate_after (Number) —

    The maximum number of documents to collect for each shard, upon reaching which the query execution will terminate early.

  • :stats (List) —

    Specific 'tag' of the request for logging and statistical purposes

  • :version (Boolean) —

    Specify whether to return document version as part of a hit

  • :request_cache (Boolean) —

    Specify if request cache should be used for this request or not, defaults to index level setting

  • :refresh (Boolean) —

    Should the effected indexes be refreshed?

  • :timeout (Time) —

    Time each individual bulk request should wait for shards that are unavailable.

  • :wait_for_active_shards (String) —

    Sets the number of shard copies that must be active before proceeding with the delete by query operation. Defaults to 1, meaning the primary shard only. Set to `all` for all shard copies, otherwise set to any non-negative value less than or equal to the total number of copies for the shard (number of replicas + 1)

  • :scroll_size (Number) —

    Size on the scroll request powering the delete by query

  • :wait_for_completion (Boolean) —

    Should the request should block until the delete by query is complete.

  • :requests_per_second (Number) —

    The throttle for this request in sub-requests per second. -1 means no throttle.

  • :slices (Number) —

    The number of slices this task should be divided into. Defaults to 1 meaning the task isn't sliced into subtasks.

Raises:

  • (ArgumentError)

See Also:


60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/elasticsearch/api/actions/delete_by_query.rb', line 60

def delete_by_query(arguments={})
  raise ArgumentError, "Required argument 'index' missing" unless arguments[:index]
  method = HTTP_POST
  path   = Utils.__pathify Utils.__listify(arguments[:index]),
                           Utils.__listify(arguments[:type]),
                           '/_delete_by_query'

  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = arguments[:body]

  perform_request(method, path, params, body).body
end

#delete_by_query_rethrottle(arguments = {}) ⇒ Object

The value of requests_per_second can be changed on a running delete by query using the _rethrottle API

Options Hash (arguments):

  • :task_id (String) —

    The task id to rethrottle (Required)

  • :requests_per_second (Number) —

    The throttle to set on this request in floating sub-requests per second. -1 means set no throttle.

Raises:

  • (ArgumentError)

See Also:


16
17
18
19
20
21
22
23
24
 
# File 'lib/elasticsearch/api/actions/delete_by_rethrottle.rb', line 16

def delete_by_query_rethrottle(arguments={})
  raise ArgumentError, "Required argument 'task_id' missing" unless arguments[:task_id]
  method = Elasticsearch::API::HTTP_POST
  path   = "_delete_by_query/#{arguments[:task_id]}/_rethrottle"
  params = Elasticsearch::API::Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = nil

  perform_request(method, path, params, body).body
end

#delete_script(arguments = {}) ⇒ Object

Remove an indexed script from Elasticsearch

Options Hash (arguments):

  • :id (String) —

    Script ID (Required)

  • :timeout (Time) —

    Explicit operation timeout

  • :master_timeout (Time) —

    Specify timeout for connection to master

Raises:

  • (ArgumentError)

See Also:


17
18
19
20
21
22
23
24
25
 
# File 'lib/elasticsearch/api/actions/delete_script.rb', line 17

def delete_script(arguments={})
  raise ArgumentError, "Required argument 'id' missing"   unless arguments[:id]
  method = HTTP_DELETE
  path   = "_scripts/#{arguments.has_key?(:lang) ? "#{arguments.delete(:lang)}/" : ''}#{arguments[:id]}"
  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = nil

  perform_request(method, path, params, body).body
end

#exists(arguments = {}) ⇒ Object Also known as: exists?

Raises:

  • (ArgumentError)

See Also:


33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/elasticsearch/api/actions/exists.rb', line 33

def exists(arguments={})
  raise ArgumentError, "Required argument 'id' missing"    unless arguments[:id]
  raise ArgumentError, "Required argument 'index' missing" unless arguments[:index]
  arguments[:type] ||= UNDERSCORE_ALL
  method = HTTP_HEAD
  path   = Utils.__pathify Utils.__escape(arguments[:index]),
                           Utils.__escape(arguments[:type]),
                           Utils.__escape(arguments[:id])

  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = nil

  Utils.__rescue_from_not_found do
    perform_request(method, path, params, body).status == 200 ? true : false
  end
end

#exists_source(arguments = {}) ⇒ Object

The get API allows to get a typed JSON document from the index based on its id.

Options Hash (arguments):

  • :id (String) —

    The document ID (Required)

  • :index (String) —

    The name of the index (Required)

  • :type (String) —

    The type of the document; use `_all` to fetch the first document matching the ID across all types (Required)

  • :parent (String) —

    The ID of the parent document

  • :preference (String) —

    Specify the node or shard the operation should be performed on (default: random)

  • :realtime (Boolean) —

    Specify whether to perform the operation in realtime or search mode

  • :refresh (Boolean) —

    Refresh the shard containing the document before performing the operation

  • :routing (String) —

    Specific routing value

  • :_source (List) —

    True or false to return the _source field or not, or a list of fields to return

  • :_source_excludes (List) —

    A list of fields to exclude from the returned _source field

  • :_source_includes (List) —

    A list of fields to extract and return from the _source field

  • :version (Number) —

    Explicit version number for concurrency control

  • :version_type (String) —

    Specific version type (options: internal, external, external_gte, force)

Raises:

  • (ArgumentError)

See Also:


27
28
29
30
31
32
33
34
35
36
37
 
# File 'lib/elasticsearch/api/actions/exists_source.rb', line 27

def exists_source(arguments={})
  raise ArgumentError, "Required argument 'id' missing" unless arguments[:id]
  raise ArgumentError, "Required argument 'index' missing" unless arguments[:index]
  raise ArgumentError, "Required argument 'type' missing" unless arguments[:type]
  method = Elasticsearch::API::HTTP_HEAD
  path   = "#{arguments[:index]}/#{arguments[:type]}/#{arguments[:id]}/_source"
  params = Elasticsearch::API::Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = nil

  perform_request(method, path, params, body).body
end

#explain(arguments = {}) ⇒ Object

Return information if and how well a document matches a query.

The returned information contains a `_score` and its explanation, if the document matches the query.

Examples:

Passing the query in the Lucene query syntax as the `:q` URL parameter


client.explain index: 'myindex', type: 'mytype', id: '1', q: 'test'

Passing the query in the Query DSL as the request `:body`


client.explain index: 'myindex', type: 'mytype', id: '1',
               body: { query: { match: { title: 'test' } } }

Options Hash (arguments):

  • :id (String) —

    The document ID (Required)

  • :index (String) —

    The name of the index (Required)

  • :type (String) —

    The type of the document

  • :body (Hash) —

    The query definition using the Query DSL

  • :analyze_wildcard (Boolean) —

    Specify whether wildcards and prefix queries in the query string query should be analyzed (default: false)

  • :analyzer (String) —

    The analyzer for the query string query

  • :default_operator (String) —

    The default operator for query string query (AND or OR) (options: AND, OR)

  • :df (String) —

    The default field for query string query (default: _all)

  • :stored_fields (List) —

    A comma-separated list of stored fields to return in the response

  • :lenient (Boolean) —

    Specify whether format-based query failures (such as providing text to a numeric field) should be ignored

  • :parent (String) —

    The ID of the parent document

  • :preference (String) —

    Specify the node or shard the operation should be performed on (default: random)

  • :q (String) —

    Query in the Lucene query string syntax

  • :routing (String) —

    Specific routing value

  • :_source (List) —

    True or false to return the _source field or not, or a list of fields to return

  • :_source_excludes (List) —

    A list of fields to exclude from the returned _source field

  • :_source_includes (List) —

    A list of fields to extract and return from the _source field

Raises:

  • (ArgumentError)

See Also:


42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/elasticsearch/api/actions/explain.rb', line 42

def explain(arguments={})
  raise ArgumentError, "Required argument 'index' missing" unless arguments[:index]
  raise ArgumentError, "Required argument 'id' missing"    unless arguments[:id]
  method = HTTP_GET

  if arguments[:type]
    path   = Utils.__pathify Utils.__escape(arguments[:index]),
                             Utils.__escape(arguments[:type]),
                             Utils.__escape(arguments[:id]),
                             '_explain'
  else
    path   = Utils.__pathify Utils.__escape(arguments[:index]),
                             '_explain',
                             Utils.__escape(arguments[:id])
  end

  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = arguments[:body]

  params[:fields] = Utils.__listify(params[:fields]) if params[:fields]

  perform_request(method, path, params, body).body
end

#field_caps(arguments = {}) ⇒ Object

Return the capabilities of fields among multiple indices

Examples:

client.field_caps fields: '*'
# => { "fields" => "t"=>{"text"=>{"type"=>"text", "searchable"=>true, "aggregatable"=>false}} ...

Options Hash (arguments):

  • :index (List) —

    A comma-separated list of index names; use `_all` or empty string to perform the operation on all indices

  • :fields (List) —

    A comma-separated list of field names

  • :ignore_unavailable (Boolean) —

    Whether specified concrete indices should be ignored when unavailable (missing or closed)

  • :allow_no_indices (Boolean) —

    Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified)

  • :expand_wildcards (String) —

    Whether to expand wildcard expression to concrete indices that are open, closed or both. (options: open, closed, none, all)

Raises:

  • (ArgumentError)

See Also:


23
24
25
26
27
28
29
30
31
 
# File 'lib/elasticsearch/api/actions/field_caps.rb', line 23

def field_caps(arguments={})
  raise ArgumentError, "Required argument 'fields' missing" unless arguments[:fields]
  method = HTTP_GET
  path   = Utils.__pathify Utils.__listify(arguments[:index]), '_field_caps'
  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = arguments[:body]

  perform_request(method, path, params, body).body
end

#get(arguments = {}) ⇒ Object

Return a specified document.

The response contains full document, as stored in Elasticsearch, incl. `_source`, `_version`, etc.

Examples:

Get a document


client.get index: 'myindex', type: 'mytype', id: '1'

Options Hash (arguments):

  • :id (String) —

    The document ID (Required)

  • :index (String) —

    The name of the index (Required)

  • :type (String) —

    The type of the document (use `_all` to fetch the first document matching the ID across all types)

  • :stored_fields (List) —

    A comma-separated list of stored fields to return in the response

  • :parent (String) —

    The ID of the parent document

  • :preference (String) —

    Specify the node or shard the operation should be performed on (default: random)

  • :realtime (Boolean) —

    Specify whether to perform the operation in realtime or search mode

  • :refresh (Boolean) —

    Refresh the shard containing the document before performing the operation

  • :routing (String) —

    Specific routing value

  • :_source (List) —

    True or false to return the _source field or not, or a list of fields to return

  • :_source_excludes (List) —

    A list of fields to exclude from the returned _source field

  • :_source_includes (List) —

    A list of fields to extract and return from the _source field

  • :_source_exclude (List) —

    A list of fields to exclude from the returned _source field

  • :_source_include (List) —

    A list of fields to extract and return from the _source field

  • :version (Number) —

    Explicit version number for concurrency control

  • :version_type (String) —

    Specific version type (options: internal, external, external_gte, force)

Raises:

  • (ArgumentError)

See Also:


36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/elasticsearch/api/actions/get.rb', line 36

def get(arguments={})
  raise ArgumentError, "Required argument 'index' missing" unless arguments[:index]
  raise ArgumentError, "Required argument 'id' missing"    unless arguments[:id]
  arguments[:type] ||= DEFAULT_DOC

  method = HTTP_GET
  path   = Utils.__pathify Utils.__escape(arguments[:index]),
                           Utils.__escape(arguments[:type]),
                           Utils.__escape(arguments[:id])

  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = nil

  params[:fields] = Utils.__listify(params[:fields]) if params[:fields]

  if Array(arguments[:ignore]).include?(404)
    Utils.__rescue_from_not_found { perform_request(method, path, params, body).body }
  else
    perform_request(method, path, params, body).body
  end
end

#get_script(arguments = {}) ⇒ Object

Retrieve an indexed script from Elasticsearch

Options Hash (arguments):

  • :id (String) —

    Script ID (Required)

  • :lang (String) —

    Script language

Raises:

  • (ArgumentError)

See Also:


16
17
18
19
20
21
22
23
24
 
# File 'lib/elasticsearch/api/actions/get_script.rb', line 16

def get_script(arguments={})
  raise ArgumentError, "Required argument 'id' missing"   unless arguments[:id]
  method = Elasticsearch::API::HTTP_GET
  path   = "_scripts/#{arguments[:id]}"
  params = Elasticsearch::API::Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = nil

  perform_request(method, path, params, body).body
end

#get_source(arguments = {}) ⇒ Object

Return a specified document's `_source`.

The response contains just the original document, as passed to Elasticsearch during indexing.

Examples:

Get a document `_source`


client.get_source index: 'myindex', type: 'mytype', id: '1'

Options Hash (arguments):

  • :id (String) —

    The document ID (Required)

  • :index (String) —

    The name of the index (Required)

  • :type (String) —

    The type of the document; deprecated and optional starting with 7.0

  • :parent (String) —

    The ID of the parent document

  • :preference (String) —

    Specify the node or shard the operation should be performed on (default: random)

  • :realtime (Boolean) —

    Specify whether to perform the operation in realtime or search mode

  • :refresh (Boolean) —

    Refresh the shard containing the document before performing the operation

  • :routing (String) —

    Specific routing value

  • :_source (List) —

    True or false to return the _source field or not, or a list of fields to return

  • :_source_excludes (List) —

    A list of fields to exclude from the returned _source field

  • :_source_includes (List) —

    A list of fields to extract and return from the _source field

  • :version (Number) —

    Explicit version number for concurrency control

  • :version_type (String) —

    Specific version type (options: internal, external, external_gte, force)

Raises:

  • (ArgumentError)

See Also:

Since:

  • 0.90.1


35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/elasticsearch/api/actions/get_source.rb', line 35

def get_source(arguments={})
  raise ArgumentError, "Required argument 'index' missing" unless arguments[:index]
  raise ArgumentError, "Required argument 'id' missing"    unless arguments[:id]
  arguments[:type] ||= DEFAULT_DOC

  method = HTTP_GET

  if arguments[:type]
    path   = Utils.__pathify Utils.__escape(arguments[:index]),
                             Utils.__escape(arguments[:type]),
                             Utils.__escape(arguments[:id]),
                             '_source'
  else
    path   = Utils.__pathify Utils.__escape(arguments[:index]),
                             '_source',
                             Utils.__escape(arguments[:id])
  end


  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = nil

  params[:fields] = Utils.__listify(params[:fields]) if params[:fields]

  perform_request(method, path, params, body).body
end

#index(arguments = {}) ⇒ Object

Create or update a document.

The `index` API will either create a new document, or update an existing one, when a document `:id` is passed. When creating a document, an ID will be auto-generated, when it's not passed as an argument.

You can specifically enforce the create operation by setting the `op_type` argument to `create`, or by using the #create method.

Optimistic concurrency control is performed, when the `version` argument is specified. By default, no version checks are performed.

By default, the document will be available for #get immediately, for #search only after an index refresh operation has been performed (either automatically or manually).

Examples:

Create or update a document `myindex/mytype/1`


client.index index: 'myindex',
             type: 'mytype',
             id: '1',
             body: {
              title: 'Test 1',
              tags: ['y', 'z'],
              published: true,
              published_at: Time.now.utc.iso8601,
              counter: 1
            }

Refresh the index after the operation (useful e.g. in integration tests)


client.index index: 'myindex', type: 'mytype', id: '1', body: { title: 'TEST' }, refresh: true
client.search index: 'myindex', q: 'title:test'

Create a document with a specific expiration time (TTL)


# Decrease the default housekeeping interval first:
client.cluster.put_settings body: { transient: { 'indices.ttl.interval' => '1s' } }

# Enable the `_ttl` property for all types within the index
client.indices.create index: 'myindex', body: { mappings: { properties: { _ttl: { enabled: true } }  } }

client.index index: 'myindex', type: 'mytype', id: '1', body: { title: 'TEST' }, ttl: '5s'

sleep 3 and client.get index: 'myindex', type: 'mytype', id: '1'
# => {"_index"=>"myindex" ... "_source"=>{"title"=>"TEST"}}

sleep 3 and client.get index: 'myindex', type: 'mytype', id: '1'
# => Elasticsearch::Transport::Transport::Errors::NotFound: [404] ...

Options Hash (arguments):

  • :id (String) —

    Document ID (optional, will be auto-generated if missing)

  • :index (String) —

    The name of the index (Required)

  • :type (String) —

    The type of the document (Required)

  • :body (Hash) —

    The document

  • :consistency (String) —

    Explicit write consistency setting for the operation (options: one, quorum, all)

  • :include_type_name (Boolean) —

    Whether a type should be expected in the body of the mappings.

  • :op_type (String) —

    Explicit operation type (options: index, create)

  • :parent (String) —

    ID of the parent document

  • :percolate (String) —

    Percolator queries to execute while indexing the document

  • :refresh (Boolean) —

    Refresh the index after performing the operation

  • :replication (String) —

    Specific replication type (options: sync, async)

  • :routing (String) —

    Specific routing value

  • :timeout (Time) —

    Explicit operation timeout

  • :timestamp (Time) —

    Explicit timestamp for the document

  • :ttl (Duration) —

    Expiration time for the document

  • :version (Number) —

    Explicit version number for concurrency control

  • :version_type (String) —

    Specific version type (options: internal, external, external_gte, force)

Raises:

  • (ArgumentError)

See Also:


78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/elasticsearch/api/actions/index.rb', line 78

def index(arguments={})
  raise ArgumentError, "Required argument 'index' missing" unless arguments[:index]
  arguments[:type] ||= DEFAULT_DOC
  method = arguments[:id] ? HTTP_PUT : HTTP_POST
  path   = Utils.__pathify Utils.__escape(arguments[:index]),
                           Utils.__escape(arguments[:type]),
                           Utils.__escape(arguments[:id])

  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = arguments[:body]
  perform_request(method, path, params, body).body
end

#info(arguments = {}) ⇒ Object

Return simple information about the cluster (name, version).

See Also:


13
14
15
16
17
18
19
20
 
# File 'lib/elasticsearch/api/actions/info.rb', line 13

def info(arguments={})
  method = HTTP_GET
  path   = ""
  params = {}
  body   = nil

  perform_request(method, path, params, body).body
end

#mget(arguments = {}) ⇒ Object

Return multiple documents from one or more indices in a single request.

Pass the request definition in the `:body` argument, either as an Array of `docs` specifications, or `ids`, when the `:index` and document `:type` are specified.

Examples:

Get multiple documents fully specified in the `docs` definition


client.mget body: {
  docs: [
    { _index: 'myindex', _type: 'mytype', _id: '1' },
    { _index: 'myindex', _type: 'mytype', _id: '2' },
    { _index: 'myindex', _type: 'mytype', _id: '3' }
  ]
}

Get multiple documents specified by `ids` while passing `:index` and `:type`


client.mget index: 'myindex', type: 'mytype', body: { ids: ['1', '2', '3'] }

Get only specific fields from documents


client.mget index: 'myindex', type: 'mytype', body: { ids: ['1', '2', '3'] }, fields: ['title']

Options Hash (arguments):

  • :index (String) —

    The name of the index

  • :type (String) —

    The type of the document

  • :body (Hash) —

    Document identifiers; can be either `docs` (containing full document information) or `ids` (when index and type is provided in the URL. (Required)

  • :stored_fields (List) —

    A comma-separated list of stored fields to return in the response

  • :preference (String) —

    Specify the node or shard the operation should be performed on (default: random)

  • :realtime (Boolean) —

    Specify whether to perform the operation in realtime or search mode

  • :refresh (Boolean) —

    Refresh the shard containing the document before performing the operation

  • :routing (String) —

    Specific routing value

  • :_source (List) —

    True or false to return the _source field or not, or a list of fields to return

  • :_source_excludes (List) —

    A list of fields to exclude from the returned _source field

  • :_source_includes (List) —

    A list of fields to extract and return from the _source field

Raises:

  • (ArgumentError)

See Also:


46
47
48
49
50
51
52
53
54
55
56
57
58
59
 
# File 'lib/elasticsearch/api/actions/mget.rb', line 46

def mget(arguments={})
  raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]
  method = HTTP_GET
  path   = Utils.__pathify Utils.__escape(arguments[:index]),
                           Utils.__escape(arguments[:type]),
                           '_mget'

  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = arguments[:body]

  params[:fields] = Utils.__listify(params[:fields]) if params[:fields]

  perform_request(method, path, params, body).body
end

#msearch(arguments = {}) ⇒ Object

Perform multiple search operations in a single request.

Pass the search definitions in the `:body` argument

Examples:

Perform multiple different searches as `:search`


client.msearch \
  body: [
    { search: { query: { match_all: {} } } },
    { index: 'myindex', type: 'mytype', search: { query: { query_string: { query: '"Test 1"' } } } },
    { search_type: 'count', search: { aggregations: { published: { terms: { field: 'published' } } } } }
  ]

Perform multiple different searches as an array of meta/data pairs


client.msearch \
  body: [
    { query: { match_all: {} } },
    { index: 'myindex', type: 'mytype' },
    { query: { query_string: { query: '"Test 1"' } } },
    { search_type: 'query_then_fetch' },
    { aggregations: { published: { terms: { field: 'published' } } } }
  ]

Options Hash (arguments):

  • :index (List) —

    A comma-separated list of index names to use as default

  • :type (List) —

    A comma-separated list of document types to use as default

  • :body (Hash) —

    The request definitions (metadata-search request definition pairs), separated by newlines (Required)

  • :search_type (String) —

    Search operation type (options: query_then_fetch, query_and_fetch, dfs_query_then_fetch, dfs_query_and_fetch)

  • :max_concurrent_searches (Number) —

    Controls the maximum number of concurrent searches the multi search api will execute

  • :typed_keys (Boolean) —

    Specify whether aggregation and suggester names should be prefixed by their respective types in the response

  • :pre_filter_shard_size (Number) —

    A threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on it's rewrite method ie. if date filters are mandatory to match but the shard bounds and the query are disjoint.

  • :max_concurrent_shard_requests (Number) —

    The number of concurrent shard requests each sub search executes concurrently. This value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests

  • :rest_total_hits_as_int (Boolean) —

    Indicates whether hits.total should be rendered as an integer or an object in the rest search response

  • :ccs_minimize_roundtrips (Boolean) —

    Indicates whether network round-trips should be minimized as part of cross-cluster search requests execution

Raises:

  • (ArgumentError)

See Also:


46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/elasticsearch/api/actions/msearch.rb', line 46

def msearch(arguments={})
  raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]
  method = HTTP_GET
  path   = Utils.__pathify( Utils.__listify(arguments[:index]), Utils.__listify(arguments[:type]), '_msearch' )

  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = arguments[:body]

  case
  when body.is_a?(Array) && body.any? { |d| d.has_key? :search }
    payload = body.
      inject([]) do |sum, item|
        meta = item
        data = meta.delete(:search)

        sum << meta
        sum << data
        sum
      end.
      map { |item| Elasticsearch::API.serializer.dump(item) }
    payload << "" unless payload.empty?
    payload = payload.join("\n")
  when body.is_a?(Array)
    payload = body.map { |d| d.is_a?(String) ? d : Elasticsearch::API.serializer.dump(d) }
    payload << "" unless payload.empty?
    payload = payload.join("\n")
  else
    payload = body
  end

  perform_request(method, path, params, payload, {"Content-Type" => "application/x-ndjson"}).body
end

#msearch_template(arguments = {}) ⇒ Object

Execute several search requests using templates (inline, indexed or stored in a file)

Examples:

Search with an inline script


client.msearch_template body: [
  { index: 'test' },
  { inline: { query: { match: { title: '{{q}}' } } }, params: { q: 'foo'} }
]

Options Hash (arguments):

  • :index (List) —

    A comma-separated list of index names to use as default

  • :type (List) —

    A comma-separated list of document types to use as default

  • :body (Hash) —

    The request definitions (metadata-search request definition pairs), separated by newlines (Required)

  • :search_type (String) —

    Search operation type (options: query_then_fetch, query_and_fetch, dfs_query_then_fetch, dfs_query_and_fetch)

  • :typed_keys (Boolean) —

    Specify whether aggregation and suggester names should be prefixed by their respective types in the response

  • :max_concurrent_searches (Number) —

    Controls the maximum number of concurrent searches the multi search api will execute

  • :rest_total_hits_as_int (Boolean) —

    Indicates whether hits.total should be rendered as an integer or an object in the rest search response

  • :ccs_minimize_roundtrips (Boolean) —

    Indicates whether network round-trips should be minimized as part of cross-cluster search requests execution

Raises:

  • (ArgumentError)

See Also:


29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/elasticsearch/api/actions/msearch_template.rb', line 29

def msearch_template(arguments={})
  raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]
  method = HTTP_GET
  path   = Utils.__pathify Utils.__listify(arguments[:index]),
                           Utils.__listify(arguments[:type]),
                           '_msearch/template'
  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = arguments[:body]

  case
    when body.is_a?(Array)
      payload = body.map { |d| d.is_a?(String) ? d : Elasticsearch::API.serializer.dump(d) }
      payload << "" unless payload.empty?
      payload = payload.join("\n")
    else
      payload = body
  end

  perform_request(method, path, params, payload, {"Content-Type" => "application/x-ndjson"}).body
end

#mtermvectors(arguments = {}) ⇒ Object

Returns information and statistics about terms in the fields of multiple documents in a single request/response. The semantics are similar to the #mget API.

Examples:

Return information about multiple documents in a specific index


subject.mtermvectors index: 'my-index', type: 'my-type', body: { ids: [1, 2, 3] }

Options Hash (arguments):

  • :index (String) —

    The index in which the document resides.

  • :type (String) —

    The type of the document.

  • :body (Hash) —

    Define ids, documents, parameters or a list of parameters per document here. You must at least provide a list of document ids. See documentation.

  • :ids (List) —

    A comma-separated list of documents ids. You must define ids as parameter or set “ids” or “docs” in the request body

  • :term_statistics (Boolean) —

    Specifies if total term frequency and document frequency should be returned. Applies to all returned documents unless otherwise specified in body “params” or “docs”.

  • :field_statistics (Boolean) —

    Specifies if document count, sum of document frequencies and sum of total term frequencies should be returned. Applies to all returned documents unless otherwise specified in body “params” or “docs”.

  • :fields (List) —

    A comma-separated list of fields to return. Applies to all returned documents unless otherwise specified in body “params” or “docs”.

  • :offsets (Boolean) —

    Specifies if term offsets should be returned. Applies to all returned documents unless otherwise specified in body “params” or “docs”.

  • :positions (Boolean) —

    Specifies if term positions should be returned. Applies to all returned documents unless otherwise specified in body “params” or “docs”.

  • :payloads (Boolean) —

    Specifies if term payloads should be returned. Applies to all returned documents unless otherwise specified in body “params” or “docs”.

  • :preference (String) —

    Specify the node or shard the operation should be performed on (default: random) .Applies to all returned documents unless otherwise specified in body “params” or “docs”.

  • :routing (String) —

    Specific routing value. Applies to all returned documents unless otherwise specified in body “params” or “docs”.

  • :parent (String) —

    Parent id of documents. Applies to all returned documents unless otherwise specified in body “params” or “docs”.

  • :realtime (Boolean) —

    Specifies if requests are real-time as opposed to near-real-time (default: true).

  • :version (Number) —

    Explicit version number for concurrency control

  • :version_type (String) —

    Specific version type (options: internal, external, external_gte, force)

See Also:


38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
 
# File 'lib/elasticsearch/api/actions/mtermvectors.rb', line 38

def mtermvectors(arguments={})
  ids = arguments.delete(:ids)

  method = HTTP_GET
  path   = Utils.__pathify Utils.__escape(arguments[:index]),
                           Utils.__escape(arguments[:type]),
                           '_mtermvectors'

  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)

  if ids
    body = { :ids => ids }
  else
    body = arguments[:body]
  end

  perform_request(method, path, params, body).body
end

#ping(arguments = {}) ⇒ Object

Returns true if the cluster returns a successful HTTP response, false otherwise.

Examples:


client.ping

See Also:


17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/elasticsearch/api/actions/ping.rb', line 17

def ping(arguments={})
  method = HTTP_HEAD
  path   = ""
  params = {}
  body   = nil

  begin
    perform_request(method, path, params, body).status == 200 ? true : false
  rescue Exception => e
    if e.class.to_s =~ /NotFound|ConnectionFailed/ || e.message =~ /Not\s*Found|404|ConnectionFailed/i
      false
    else
      raise e
    end
  end
end

#put_script(arguments = {}) ⇒ Object

Store a script in an internal index (`.scripts`), to be able to reference them in search definitions (with dynamic scripting disabled)

Examples:

Storing an Mvel script in Elasticsearch and using it in function score


client.put_script id: 'my_score', body: { script: { lang: 'groovy', source: 'log(_score * factor)' } }

client.search body: {
  query: {
    function_score: {
      query: { match: { title: 'foo' } },
      functions: [ { script_score: { script_id: 'my_score', params: { factor: 3 } } } ]
    }
  }
}

Options Hash (arguments):

  • :id (String) —

    Script ID (Required)

  • :context (String) —

    Script context

  • :body (Hash) —

    The document (Required)

  • :timeout (Time) —

    Explicit operation timeout

  • :master_timeout (Time) —

    Specify timeout for connection to master

  • :context (String) —

    Context name to compile script against

Raises:

  • (ArgumentError)

See Also:


34
35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/elasticsearch/api/actions/put_script.rb', line 34

def put_script(arguments={})
  raise ArgumentError, "Required argument 'id' missing"   unless arguments[:id]
  raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]
  method = HTTP_PUT
  path   = "_scripts/#{arguments.has_key?(:lang) ? "#{arguments.delete(:lang)}/" : ''}#{arguments[:id]}"

  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)

  body   = arguments[:body]

  perform_request(method, path, params, body).body
end

#rank_eval(arguments = {}) ⇒ Object

The ranking evaluation API allows to evaluate the quality of ranked search results over a set of typical search queries.

Given this set of queries and a list of manually rated documents, the _rank_eval endpoint calculates and
returns typical information retrieval metrics like mean reciprocal rank, precision or discounted cumulative gain.

Options Hash (arguments):

  • :index (List) —

    A comma-separated list of index names to search; use `_all` or empty string to perform the operation on all indices

  • :body (Hash) —

    The ranking evaluation search definition, including search requests, document ratings and ranking metric definition. (Required)

  • :ignore_unavailable (Boolean) —

    Whether specified concrete indices should be ignored when unavailable (missing or closed)

  • :allow_no_indices (Boolean) —

    Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified)

  • :expand_wildcards (String) —

    Whether to expand wildcard expression to concrete indices that are open, closed or both. (options: open, closed, none, all)

Raises:

  • (ArgumentError)

See Also:


21
22
23
24
25
26
27
28
29
 
# File 'lib/elasticsearch/api/actions/rank_eval.rb', line 21

def rank_eval(arguments={})
  raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]
  method = Elasticsearch::API::HTTP_GET
  path   = "_rank_eval"
  params = Elasticsearch::API::Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = arguments[:body]

  perform_request(method, path, params, body).body
end

#reindex(arguments = {}) ⇒ Object

Copy documents from one index to another, potentially changing its settings, mappings and the documents itself.

Examples:

Copy documents into a different index


client.reindex body: { source: { index: 'test1' }, dest: { index: 'test2' } }

Limit the copied documents with a query


client.reindex body: {
  source: {
    index: 'test1',
    query: { terms: { category: ['one', 'two'] }  }
  },
  dest: {
    index: 'test2'
  }
}

Remove a field from reindexed documents


client.reindex body: {
  source: {
    index: 'test1'
  },
  dest: {
    index: 'test3'
  },
  script: {
    inline: 'ctx._source.remove("category")'
  }
}

Options Hash (arguments):

  • :body (Hash) —

    The search definition using the Query DSL and the prototype for the index request. (Required)

  • :refresh (Boolean) —

    Should the effected indexes be refreshed?

  • :timeout (Time) —

    Time each individual bulk request should wait for shards that are unavailable.

  • :wait_for_active_shards (String) —

    Sets the number of shard copies that must be active before proceeding with the reindex operation. Defaults to 1, meaning the primary shard only. Set to `all` for all shard copies, otherwise set to any non-negative value less than or equal to the total number of copies for the shard (number of replicas + 1)

  • :wait_for_completion (Boolean) —

    Should the request should block until the reindex is complete.

  • :requests_per_second (Number) —

    The throttle to set on this request in sub-requests per second. -1 means no throttle.

  • :scroll (Time) —

    Control how long to keep the search context alive

  • :slices (Number) —

    The number of slices this task should be divided into. Defaults to 1 meaning the task isn't sliced into subtasks.

Raises:

  • (ArgumentError)

See Also:


53
54
55
56
57
58
59
60
61
 
# File 'lib/elasticsearch/api/actions/reindex.rb', line 53

def reindex(arguments={})
  raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]
  method = 'POST'
  path   = "_reindex"
  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = arguments[:body]

  perform_request(method, path, params, body).body
end

#reindex_rethrottle(arguments = {}) ⇒ Object

The value of requests_per_second can be changed on a running reindex using the _rethrottle

Options Hash (arguments):

  • :task_id (String) —

    The task id to rethrottle (Required)

  • :requests_per_second (Number) —

    The throttle to set on this request in floating sub-requests per second. -1 means set no throttle.

Raises:

  • (ArgumentError)

See Also:


16
17
18
19
20
21
22
23
24
 
# File 'lib/elasticsearch/api/actions/reindex_rethrottle.rb', line 16

def reindex_rethrottle(arguments={})
  raise ArgumentError, "Required argument 'task_id' missing" unless arguments[:task_id]
  method = Elasticsearch::API::HTTP_POST
  path   = "_reindex/#{arguments[:task_id]}/_rethrottle"
  params = Elasticsearch::API::Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = nil

  perform_request(method, path, params, body).body
end

#render_search_template(arguments = {}) ⇒ Object

Pre-render search requests before they are executed and fill existing templates with template parameters

Options Hash (arguments):

  • :id (String) —

    The id of the stored search template

  • :body (Hash) —

    The search definition template and its params

See Also:


16
17
18
19
20
21
22
23
 
# File 'lib/elasticsearch/api/actions/render_search_template.rb', line 16

def render_search_template(arguments={})
  method = 'GET'
  path   = "_render/template"
  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = arguments[:body]

  perform_request(method, path, params, body).body
end

#scripts_painless_execute(arguments = {}) ⇒ Object

The Painless execute API allows an arbitrary script to be executed and a result to be returned.

Options Hash (arguments):

  • :body (Hash) —

    The script to execute

See Also:


15
16
17
18
19
20
21
22
 
# File 'lib/elasticsearch/api/actions/scripts_painless_execute.rb', line 15

def scripts_painless_execute(arguments={})
  method = Elasticsearch::API::HTTP_GET
  path   = "_scripts/painless/_execute"
  params = {}
  body   = arguments[:body]

  perform_request(method, path, params, body).body
end

#scroll(arguments = {}) ⇒ Object

Efficiently iterate over a large result set.

When using `from` and `size` to return a large result sets, performance drops as you “paginate” in the set, and you can't guarantee the consistency when the index is being updated at the same time.

The “Scroll” API uses a “point in time” snapshot of the index state, which was created via a “Search” API request specifying the `scroll` parameter.

Examples:

A basic example


result = client.search index: 'scrollindex',
                       scroll: '5m',
                       body: { query: { match: { title: 'test' } }, sort: '_id' }

result = client.scroll body: { scroll_id: result['_scroll_id'], scroll: '5m' }

Call the `scroll` API until all the documents are returned


# Index 1,000 documents
client.indices.delete index: 'test'
1_000.times do |i| client.index index: 'test', type: 'test', id: i+1, body: {title: "Test #{i+1}"} end
client.indices.refresh index: 'test'

# Open the "view" of the index by passing the `scroll` parameter
# Sorting by `_doc` makes the operations faster
r = client.search index: 'test', scroll: '1m', body: {sort: ['_doc']}

# Display the initial results
puts "--- BATCH 0 -------------------------------------------------"
puts r['hits']['hits'].map { |d| d['_source']['title'] }.inspect

# Call the `scroll` API until empty results are returned
while r = client.scroll(body: { scroll_id: r['_scroll_id'] }, scroll: '5m') and not r['hits']['hits'].empty? do
  puts "--- BATCH #{defined?($i) ? $i += 1 : $i = 1} -------------------------------------------------"
  puts r['hits']['hits'].map { |d| d['_source']['title'] }.inspect
  puts
end

Options Hash (arguments):

  • :scroll_id (String) —

    The scroll ID

  • :body (Hash) —

    The scroll ID if not passed by URL or query parameter.

  • :scroll (Time) —

    Specify how long a consistent view of the index should be maintained for scrolled search

  • :scroll_id (String) —

    The scroll ID for scrolled search

  • :rest_total_hits_as_int (Boolean) —

    Indicates whether hits.total should be rendered as an integer or an object in the rest search response

See Also:


56
57
58
59
60
61
62
63
 
# File 'lib/elasticsearch/api/actions/scroll.rb', line 56

def scroll(arguments={})
  method = HTTP_GET
  path   = "_search/scroll"
  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = arguments[:body]

  perform_request(method, path, params, body).body
end

#search(arguments = {}) ⇒ Hash

Return documents matching a query, as well as aggregations (facets), highlighted snippets, suggestions, etc.

The search API is used to query one or more indices either using simple [query string queries](www.elastic.co/guide/reference/api/search/uri-request/) as the `:q` argument , or by passing the [full request definition](www.elastic.co/guide/reference/api/search/request-body/) in the [Query DSL](www.elastic.co/guide/reference/query-dsl/) as the `:body` argument.

Examples:

Search with a simple query string query


client.search index: 'myindex', q: 'title:test'

Passing a full request definition in the Elasticsearch's Query DSL as a `Hash`


client.search index: 'myindex',
              body: {
                query: { match: { title: 'test' } },
                aggregations: { tags: { terms: { field: 'tags' } } }
              }

Paginating results: return 10 documents, beginning from the 10th


client.search index: 'myindex',
              body: {
                query: { match: { title: 'test' } },
                from: 10,
                size: 10
              }

Passing the search definition as a `String`, built with a JSON builder


require 'jbuilder'

json = Jbuilder.encode do |json|
  json.query do
    json.match do
      json.title do
        json.query    'test 1'
        json.operator 'and'
      end
    end
  end
end

client.search index: 'myindex', body: json

Wrapping the result in [`Hashie::Mash`](github.com/intridea/hashie) for easier access


response = client.search index: 'myindex',
                         body: {
                           query:  { match: { title: 'test' } },
                           aggregations: { tags:  { terms: { field: 'tags' } } }
                         }

response = Hashie::Mash.new response

response.hits.hits.first._source.title

response.aggregations.tags.terms.to_a.map { |f| "#{f.term} [#{f.count}]" }.join(', ')

Options Hash (arguments):

  • :index (List) —

    A comma-separated list of index names to search; use `_all` or empty string to perform the operation on all indices

  • :type (List) —

    A comma-separated list of document types to search; leave empty to perform the operation on all types

  • :body (Hash) —

    The search definition using the Query DSL

  • :analyzer (String) —

    The analyzer to use for the query string

  • :analyze_wildcard (Boolean) —

    Specify whether wildcard and prefix queries should be analyzed (default: false)

  • :default_operator (String) —

    The default operator for query string query (AND or OR) (options: AND, OR)

  • :df (String) —

    The field to use as default where no field prefix is given in the query string

  • :explain (Boolean) —

    Specify whether to return detailed information about score computation as part of a hit

  • :fields (List) —

    A comma-separated list of fields to return as part of a hit

  • :fielddata_fields (List) —

    A comma-separated list of fields to return as the field data representation of a field for each hit

  • :docvalue_fields (List) —

    A comma-separated list of fields to return as the docvalue representation of a field for each hit

  • :stored_fields (List) —

    A comma-separated list of stored fields to return as part of a hit

  • :from (Number) —

    Starting offset (default: 0)

  • :include_type_name (Boolean) —

    Whether a type should be expected in the body of the mappings.

  • :ignore_indices (String) —

    When performed on multiple indices, allows to ignore `missing` ones (options: none, missing)

  • :lenient (Boolean) —

    Specify whether format-based query failures (such as providing text to a numeric field) should be ignored

  • :lowercase_expanded_terms (Boolean) —

    Specify whether query terms should be lowercased

  • :preference (String) —

    Specify the node or shard the operation should be performed on (default: random)

  • :q (String) —

    Query in the Lucene query string syntax

  • :request_cache (Boolean) —

    Specify if request cache should be used for this request (defaults to index level setting)

  • :routing (List) —

    A comma-separated list of specific routing values

  • :scroll (Duration) —

    Specify how long a consistent view of the index should be maintained for scrolled search

  • :search_type (String) —

    Search operation type (options: query_then_fetch, query_and_fetch, dfs_query_then_fetch, dfs_query_and_fetch, count, scan)

  • :size (Number) —

    Number of hits to return (default: 10)

  • :sort (List) —

    A comma-separated list of <field>:<direction> pairs

  • :source (String) —

    The URL-encoded request definition using the Query DSL (instead of using request body)

  • :_source (String) —

    Specify whether the _source field should be returned, or a list of fields to return

  • :_source_exclude (String) —

    A list of fields to exclude from the returned _source field

  • :_source_include (String) —

    A list of fields to extract and return from the _source field

  • :stored_fields (List) —

    A comma-separated list of stored fields to return in the response

  • :stats (List) —

    Specific 'tag' of the request for logging and statistical purposes

  • :suggest_field (String) —

    Specify which field to use for suggestions

  • :suggest_mode (String) —

    Specify suggest mode (options: missing, popular, always)

  • :suggest_size (Number) —

    How many suggestions to return in response

  • :suggest_text (Text) —

    The source text for which the suggestions should be returned

  • :terminate_after (Number) —

    The maximum number of documents to collect for each shard

  • :timeout (Time) —

    Explicit operation timeout

  • :typed_keys (Boolean) —

    Specify whether aggregation and suggester names should be prefixed by their respective types in the response

  • :version (Boolean) —

    Specify whether to return document version as part of a hit

  • :batched_reduce_size (Number) —

    The number of shard results that should be reduced at once on the coordinating node. This value should be used as a protection mechanism to reduce the memory overhead per search request if the potential number of shards in the request can be large.

  • :max_concurrent_shard_requests (Number) —

    The number of concurrent shard requests this search executes concurrently. This value should be used to limit the impact of the search on the cluster in order to limit the number of concurrent shard requests. The default grows with the number of nodes in the cluster but is at most 256.

  • :pre_filter_shard_size (Number) —

    A threshold that enforces a pre-filter roundtrip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on it's rewrite method ie. if date filters are mandatory to match but the shard bounds and the query are disjoint. (Default: 128)

See Also:


132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/elasticsearch/api/actions/search.rb', line 132

def search(arguments={})
  arguments[:index] = UNDERSCORE_ALL if ! arguments[:index] && arguments[:type]
  method = HTTP_GET
  path   = Utils.__pathify( Utils.__listify(arguments[:index]), Utils.__listify(arguments[:type]), UNDERSCORE_SEARCH )

  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)

  body   = arguments[:body]

  params[:fields] = Utils.__listify(params[:fields], :escape => false) if params[:fields]
  params[:fielddata_fields] = Utils.__listify(params[:fielddata_fields], :escape => false) if params[:fielddata_fields]

  # FIX: Unescape the `filter_path` parameter due to __listify default behavior. Investigate.
  params[:filter_path] =  defined?(EscapeUtils) ? EscapeUtils.unescape_url(params[:filter_path]) : CGI.unescape(params[:filter_path]) if params[:filter_path]

  perform_request(method, path, params, body).body
end

#search_shards(arguments = {}) ⇒ Object

Returns the names of indices and shards on which a search request would be executed

Options Hash (arguments):

  • :index (String) —

    The name of the index

  • :type (String) —

    The type of the document

  • :preference (String) —

    Specify the node or shard the operation should be performed on (default: random)

  • :routing (String) —

    Specific routing value

  • :local (Boolean) —

    Return local information, do not retrieve the state from master node (default: false)

  • :ignore_unavailable (Boolean) —

    Whether specified concrete indices should be ignored when unavailable (missing or closed)

  • :allow_no_indices (Boolean) —

    Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` or when no indices have been specified)

  • :expand_wildcards (String) —

    Whether to expand wildcard expression to concrete indices that are open, closed or both. (options: open, closed)

See Also:


28
29
30
31
32
33
34
35
 
# File 'lib/elasticsearch/api/actions/search_shards.rb', line 28

def search_shards(arguments={})
  method = HTTP_GET
  path   = Utils.__pathify( Utils.__listify(arguments[:index]), Utils.__listify(arguments[:type]), '_search_shards' )
  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = nil

  perform_request(method, path, params, body).body
end

#search_template(arguments = {}) ⇒ Object

Configure the search definition witha template in Mustache and parameters

Examples:

Insert the start and end values for the `range` query


client.search_template index: 'myindex',
                       body: {
                         template: {
                           query: {
                             range: {
                               date: { gte: "{{start}}", lte: "{{end}}" }
                             }
                           }
                         },
                         params: { start: "2014-02-01", end: "2014-03-01" }
                       }

Options Hash (arguments):

  • :index (List) —

    A comma-separated list of index names to search; use `_all` or empty string to perform the operation on all indices

  • :type (List) —

    A comma-separated list of document types to search; leave empty to perform the operation on all types

  • :body (Hash) —

    The search definition template and its params (Required)

  • :ignore_unavailable (Boolean) —

    Whether specified concrete indices should be ignored when unavailable (missing or closed)

  • :ignore_throttled (Boolean) —

    Whether specified concrete, expanded or aliased indices should be ignored when throttled

  • :allow_no_indices (Boolean) —

    Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified)

  • :expand_wildcards (String) —

    Whether to expand wildcard expression to concrete indices that are open, closed or both. (options: open, closed, none, all)

  • :preference (String) —

    Specify the node or shard the operation should be performed on (default: random)

  • :routing (List) —

    A comma-separated list of specific routing values

  • :scroll (Time) —

    Specify how long a consistent view of the index should be maintained for scrolled search

  • :search_type (String) —

    Search operation type (options: query_then_fetch, query_and_fetch, dfs_query_then_fetch, dfs_query_and_fetch)

  • :explain (Boolean) —

    Specify whether to return detailed information about score computation as part of a hit

  • :profile (Boolean) —

    Specify whether to profile the query execution

  • :typed_keys (Boolean) —

    Specify whether aggregation and suggester names should be prefixed by their respective types in the response

  • :rest_total_hits_as_int (Boolean) —

    Indicates whether hits.total should be rendered as an integer or an object in the rest search response

  • :ccs_minimize_roundtrips (Boolean) —

    Indicates whether network round-trips should be minimized as part of cross-cluster search requests execution

See Also:


44
45
46
47
48
49
50
51
 
# File 'lib/elasticsearch/api/actions/search_template.rb', line 44

def search_template(arguments={})
  method = HTTP_GET
  path   = Utils.__pathify( Utils.__listify(arguments[:index]), Utils.__listify(arguments[:type]), '_search/template' )
  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = arguments[:body]

  perform_request(method, path, params, body).body
end

#termvector(arguments = {}) ⇒ Object

Deprecated.

Use the plural version, #termvectors


84
85
86
 
# File 'lib/elasticsearch/api/actions/termvectors.rb', line 84

def termvector(arguments={})
  termvectors(arguments.merge :endpoint => '_termvector')
end

#termvectors(arguments = {}) ⇒ Object

Return information and statistics about terms in the fields of a particular document

Examples:

Get statistics for an indexed document


client.indices.create index: 'my_index',
                      body: {
                        mappings: {
                          properties: {
                            text: {
                              type: 'string',
                              term_vector: 'with_positions_offsets_payloads'
                            }
                          }
                        }
                      }

client.index index: 'my_index', type: 'my_type', id: '1', body: { text: 'Foo Bar Fox' }

client.termvectors index: 'my_index', type: 'my_type', id: '1'
# => { ..., "term_vectors" => { "text" => { "field_statistics" => { ... }, "terms" => { "bar" => ... } } }

Get statistics for an arbitrary document


client.termvector index: 'my_index', type: 'my_type',
                  body: {
                    doc: {
                      text: 'Foo Bar Fox'
                    }
                  }
# => { ..., "term_vectors" => { "text" => { "field_statistics" => { ... }, "terms" => { "bar" => ... } } }

Options Hash (arguments):

  • :index (String) —

    The index in which the document resides. (Required)

  • :type (String) —

    The type of the document.

  • :id (String) —

    The id of the document, when not specified a doc param should be supplied.

  • :body (Hash) —

    Define parameters and or supply a document to get termvectors for. See documentation.

  • :term_statistics (Boolean) —

    Specifies if total term frequency and document frequency should be returned.

  • :field_statistics (Boolean) —

    Specifies if document count, sum of document frequencies and sum of total term frequencies should be returned.

  • :fields (List) —

    A comma-separated list of fields to return.

  • :offsets (Boolean) —

    Specifies if term offsets should be returned.

  • :positions (Boolean) —

    Specifies if term positions should be returned.

  • :payloads (Boolean) —

    Specifies if term payloads should be returned.

  • :preference (String) —

    Specify the node or shard the operation should be performed on (default: random).

  • :routing (String) —

    Specific routing value.

  • :parent (String) —

    Parent id of documents.

  • :realtime (Boolean) —

    Specifies if request is real-time as opposed to near-real-time (default: true).

  • :version (Number) —

    Explicit version number for concurrency control

  • :version_type (String) —

    Specific version type (options: internal, external, external_gte, force)

Raises:

  • (ArgumentError)

See Also:


60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/elasticsearch/api/actions/termvectors.rb', line 60

def termvectors(arguments={})
  raise ArgumentError, "Required argument 'index' missing" unless arguments[:index]
  method = HTTP_GET
  endpoint = arguments.delete(:endpoint) || '_termvectors'

  if arguments[:type]
    path   = Utils.__pathify Utils.__escape(arguments[:index]),
                                            arguments[:type],
                                            arguments[:id],
                                            endpoint
  else
    path   = Utils.__pathify Utils.__escape(arguments[:index]),
                                            endpoint,
                                            arguments[:id]
  end

  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = arguments[:body]

  perform_request(method, path, params, body).body
end

#update(arguments = {}) ⇒ Object

Update a document without sending the whole document in the request (“partial update”).

Send either a partial document (`doc` ) which will be deeply merged into an existing document, or a `script`, which will update the document content, in the `:body` argument.

The partial update operation allows you to limit the amount of data you send over the wire and reduces the chance of failed updates due to conflict.

Specify the `:version` and `:retry_on_conflict` arguments to balance convenience and consistency.

Examples:

Update document title using partial `doc`-ument


client.update index: 'myindex', type: 'mytype', id: '1',
              body: { doc: { title: 'Updated' } }

Add a tag to document `tags` property using a `script`


client.update index: 'myindex', type: 'mytype', id: '1',
               body: { script: { source: 'ctx._source.tags.add(params.tag)', params: { tag: 'x' } } }

Increment a document counter by 1 or initialize it, when the document does not exist


client.update index: 'myindex', type: 'mytype', id: '666',
              body: { script: 'ctx._source.counter += 1', upsert: { counter: 1 } }

Delete a document if it's tagged “to-delete”


client.update index: 'myindex', type: 'mytype', id: '1',
              body: { script: 'ctx._source.tags.contains(params.tag) ? ctx.op = "delete" : ctx.op = "none"',
                      params: { tag: 'to-delete' } }

Options Hash (arguments):

  • :id (String) —

    Document ID (Required)

  • :ignore (Number, List) —

    The list of HTTP errors to ignore; only `404` supported at the moment

  • :index (String) —

    The name of the index (Required)

  • :type (String) —

    The type of the document (Required)

  • :body (Hash) —

    The request definition using either `script` or partial `doc` (Required)

  • :consistency (String) —

    Explicit write consistency setting for the operation (options: one, quorum, all)

  • :fields (List) —

    A comma-separated list of fields to return in the response

  • :include_type_name (Boolean) —

    Whether a type should be expected in the body of the mappings.

  • :lang (String) —

    The script language (default: mvel)

  • :parent (String) —

    ID of the parent document

  • :percolate (String) —

    Perform percolation during the operation; use specific registered query name, attribute, or wildcard

  • :refresh (Boolean) —

    Refresh the index after performing the operation

  • :replication (String) —

    Specific replication type (options: sync, async)

  • :retry_on_conflict (Number) —

    Specify how many times should the operation be retried when a conflict occurs (default: 0)

  • :routing (String) —

    Specific routing value

  • :script (String) —

    The URL-encoded script definition (instead of using request body)

  • :_source (String) —

    Specify whether the _source field should be returned, or a list of fields to return

  • :_source_exclude (String) —

    A list of fields to exclude from the returned _source field

  • :_source_include (String) —

    A list of fields to extract and return from the _source field

  • :timeout (Time) —

    Explicit operation timeout

  • :timestamp (Time) —

    Explicit timestamp for the document

  • :ttl (Duration) —

    Expiration time for the document

  • :version (Number) —

    Explicit version number for concurrency control

  • :version_type (Number) —

    Explicit version number for concurrency control

Raises:

  • (ArgumentError)

See Also:

Since:

  • 0.20


73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/elasticsearch/api/actions/update.rb', line 73

def update(arguments={})
  raise ArgumentError, "Required argument 'index' missing" unless arguments[:index]
  raise ArgumentError, "Required argument 'id' missing"    unless arguments[:id]
  arguments[:type] ||= DEFAULT_DOC
  method = HTTP_POST

  if arguments[:type]
    path   = Utils.__pathify Utils.__escape(arguments[:index]),
                             Utils.__escape(arguments[:type]),
                             Utils.__escape(arguments[:id]),
                             '_update'
  else
    path   = Utils.__pathify Utils.__escape(arguments[:index]),
                             '_update',
                             Utils.__escape(arguments[:id])
  end

  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = arguments[:body]
  params[:fields] = Utils.__listify(params[:fields]) if params[:fields]

  if Array(arguments[:ignore]).include?(404)
    Utils.__rescue_from_not_found { perform_request(method, path, params, body).body }
  else
    perform_request(method, path, params, body).body
  end
end

#update_by_query(arguments = {}) ⇒ Object

Process every document matching a query, potentially updating it

Examples:

Update all documents in the index, eg. to pick up new mappings


client.update_by_query index: 'articles'

Update a property of documents matching a query in the index


client.update_by_query index: 'article',
                       body: {
                         script: { inline: 'ctx._source.views += 1' },
                         query: { match: { title: 'foo' } }
                       }

Options Hash (arguments):

  • :index (List) —

    A comma-separated list of index names to search; use `_all` or empty string to perform the operation on all indices (Required)

  • :type (List) —

    A comma-separated list of document types to search; leave empty to perform the operation on all types

  • :body (Hash) —

    The search definition using the Query DSL

  • :analyzer (String) —

    The analyzer to use for the query string

  • :analyze_wildcard (Boolean) —

    Specify whether wildcard and prefix queries should be analyzed (default: false)

  • :default_operator (String) —

    The default operator for query string query (AND or OR) (options: AND, OR)

  • :df (String) —

    The field to use as default where no field prefix is given in the query string

  • :from (Number) —

    Starting offset (default: 0)

  • :ignore_unavailable (Boolean) —

    Whether specified concrete indices should be ignored when unavailable (missing or closed)

  • :allow_no_indices (Boolean) —

    Whether to ignore if a wildcard indices expression resolves into no concrete indices. (This includes `_all` string or when no indices have been specified)

  • :conflicts (String) —

    What to do when the update by query hits version conflicts? (options: abort, proceed)

  • :expand_wildcards (String) —

    Whether to expand wildcard expression to concrete indices that are open, closed or both. (options: open, closed, none, all)

  • :lenient (Boolean) —

    Specify whether format-based query failures (such as providing text to a numeric field) should be ignored

  • :pipeline (String) —

    Ingest pipeline to set on index requests made by this action. (default: none)

  • :preference (String) —

    Specify the node or shard the operation should be performed on (default: random)

  • :q (String) —

    Query in the Lucene query string syntax

  • :routing (List) —

    A comma-separated list of specific routing values

  • :scroll (Time) —

    Specify how long a consistent view of the index should be maintained for scrolled search

  • :search_type (String) —

    Search operation type (options: query_then_fetch, dfs_query_then_fetch)

  • :search_timeout (Time) —

    Explicit timeout for each search request. Defaults to no timeout.

  • :size (Number) —

    Number of hits to return (default: 10)

  • :sort (List) —

    A comma-separated list of <field>:<direction> pairs

  • :_source (List) —

    True or false to return the _source field or not, or a list of fields to return

  • :_source_excludes (List) —

    A list of fields to exclude from the returned _source field

  • :_source_includes (List) —

    A list of fields to extract and return from the _source field

  • :terminate_after (Number) —

    The maximum number of documents to collect for each shard, upon reaching which the query execution will terminate early.

  • :stats (List) —

    Specific 'tag' of the request for logging and statistical purposes

  • :version (Boolean) —

    Specify whether to return document version as part of a hit

  • :version_type (Boolean) —

    Should the document increment the version number (internal) on hit or not (reindex)

  • :request_cache (Boolean) —

    Specify if request cache should be used for this request or not, defaults to index level setting

  • :refresh (Boolean) —

    Should the effected indexes be refreshed?

  • :timeout (Time) —

    Time each individual bulk request should wait for shards that are unavailable.

  • :wait_for_active_shards (String) —

    Sets the number of shard copies that must be active before proceeding with the update by query operation. Defaults to 1, meaning the primary shard only. Set to `all` for all shard copies, otherwise set to any non-negative value less than or equal to the total number of copies for the shard (number of replicas + 1)

  • :scroll_size (Number) —

    Size on the scroll request powering the update by query

  • :wait_for_completion (Boolean) —

    Should the request should block until the update by query operation is complete.

  • :requests_per_second (Number) —

    The throttle to set on this request in sub-requests per second. -1 means no throttle.

  • :slices (Number) —

    The number of slices this task should be divided into. Defaults to 1 meaning the task isn't sliced into subtasks.

Raises:

  • (ArgumentError)

See Also:


63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/elasticsearch/api/actions/update_by_query.rb', line 63

def update_by_query(arguments={})
  raise ArgumentError, "Required argument 'index' missing" unless arguments[:index]
  method = HTTP_POST

  path   = Utils.__pathify Utils.__listify(arguments[:index]),
                           Utils.__listify(arguments[:type]),
                           '/_update_by_query'

  params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)

  body   = arguments[:body]

  perform_request(method, path, params, body).body
end

#update_by_query_rethrottle(arguments = {}) ⇒ Object

The value of requests_per_second can be changed on a running update by query using the _rethrottle API

Options Hash (arguments):

  • :task_id (String) —

    The task id to rethrottle (Required)

  • :requests_per_second (Number) —

    The throttle to set on this request in floating sub-requests per second. -1 means set no throttle.

Raises:

  • (ArgumentError)

See Also:


16
17
18
19
20
21
22
23
24
 
# File 'lib/elasticsearch/api/actions/update_by_query_rethrottle.rb', line 16

def update_by_query_rethrottle(arguments={})
  raise ArgumentError, "Required argument 'task_id' missing" unless arguments[:task_id]
  method = Elasticsearch::API::HTTP_POST
  path   = "_update_by_query/#{arguments[:task_id]}/_rethrottle"
  params = Elasticsearch::API::Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
  body   = nil

  perform_request(method, path, params, body).body
end