Module: Elasticsearch::API::Actions

Defined in:
lib/elasticsearch/api/actions/get.rb,
lib/elasticsearch/api/actions/mlt.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/suggest.rb,
lib/elasticsearch/api/actions/benchmark.rb,
lib/elasticsearch/api/actions/percolate.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/mpercolate.rb,
lib/elasticsearch/api/actions/put_script.rb,
lib/elasticsearch/api/actions/field_stats.rb,
lib/elasticsearch/api/actions/termvectors.rb,
lib/elasticsearch/api/actions/clear_scroll.rb,
lib/elasticsearch/api/actions/get_template.rb,
lib/elasticsearch/api/actions/mtermvectors.rb,
lib/elasticsearch/api/actions/put_template.rb,
lib/elasticsearch/api/actions/delete_script.rb,
lib/elasticsearch/api/actions/search_exists.rb,
lib/elasticsearch/api/actions/search_shards.rb,
lib/elasticsearch/api/actions/abort_benchmark.rb,
lib/elasticsearch/api/actions/count_percolate.rb,
lib/elasticsearch/api/actions/delete_by_query.rb,
lib/elasticsearch/api/actions/delete_template.rb,
lib/elasticsearch/api/actions/list_benchmarks.rb,
lib/elasticsearch/api/actions/search_template.rb,
lib/elasticsearch/api/actions/update_by_query.rb,
lib/elasticsearch/api/actions/render_search_template.rb

Instance Method Summary collapse

Instance Method Details

#abort_benchmark(arguments = {}) ⇒ Object

Abort a running benchmark

Examples:


client.abort_benchmark name: 'my_benchmark'

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :name (String) —

    A benchmark name

See Also:



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

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*' } } }
      ]
    }
  ]
}

Parameters:

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

    a customizable set of options

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:



50
51
52
53
54
55
56
57
58
59
 
# File 'lib/elasticsearch/api/actions/benchmark.rb', line 50

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

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

#bulk(arguments = {}) ⇒ Hash

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 } }
             }}

]

Parameters:

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

    a customizable set of options

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

  • :fields (List) —

    Default comma-separated list of fields to return in the response for updates, can be overridden on each sub-request

  • :_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_exclude (List) —

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

  • :_source_include (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

Returns:

  • (Hash) —

    Deserialized Elasticsearch response

See Also:



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/elasticsearch/api/actions/bulk.rb', line 66

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

  type      = arguments.delete(:type)

  valid_params = [
    :wait_for_active_shards,
    :refresh,
    :routing,
    :timeout,
    :type,
    :fields,
    :_source,
    :_source_exclude,
    :_source_include,
    :pipeline ]

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

  params = Utils.__validate_and_extract_params arguments, valid_params
  body   = arguments[:body]

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

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

#clear_scroll(arguments = {}) ⇒ Object

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

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :scroll_id (List) —

    A comma-separated list of scroll IDs to clear; use ‘_all` clear all scroll search contexts

Raises:

  • (ArgumentError)

See Also:



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

def clear_scroll(arguments={})
  raise ArgumentError, "Required argument 'scroll_id' missing" unless arguments[:scroll_id]

  method = 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'] } } } }

Parameters:

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

    a customizable set of options

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)

  • :allow_no_indices (Boolean) —

    Whether to ignore if a wildcard indices expression resolves into no concrete indices.

  • :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 (String) —

    Specific routing value

  • :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

  • :lowercase_expanded_terms (Boolean) —

    Specify whether query terms should be lowercased

See Also:



47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/elasticsearch/api/actions/count.rb', line 47

def count(arguments={})
  valid_params = [
    :ignore_unavailable,
    :allow_no_indices,
    :expand_wildcards,
    :min_score,
    :preference,
    :routing,
    :q,
    :analyzer,
    :analyze_wildcard,
    :default_operator,
    :df,
    :lenient,
    :lowercase_expanded_terms ]

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

  params = Utils.__validate_and_extract_params arguments, valid_params
  body   = arguments[:body]

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

#count_percolate(arguments = {}) ⇒ Object

Return the number of queries matching a document.

Percolator allows you to register queries and then evaluate a document against them: the number of matching queries is returned in the response.

Examples:

Register query named “alert-1” for the “my-index” index


client.index index: 'my-index',
             type: '.percolator',
             id: 'alert-1',
             body: { query: { query_string: { query: 'foo' } } }

Return the number of matching queries for a custom document


client.count_percolate index: 'my-index', type: 'my-type', body: { doc: { title: "Foo Bar" } }
# => { ..., total: 1}

Return the number of matching queries for an existing document


client.index index: 'my-index', type: 'my-type', id: '123', body: { title: "Foo Bar" }

client.count_percolate index: 'my-index', type: 'my-type', id: '123'
# => { ..., total: 1}

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :index (String) —

    The index of the document being percolated. (Required)

  • :type (String) —

    The type of the document being percolated. (Required)

  • :id (String) —

    Fetch the document specified by index/type/id and use it instead of the passed ‘doc`

  • :body (Hash) —

    The percolator request definition using the percolate DSL

  • :routing (List) —

    A comma-separated list of specific routing values

  • :preference (String) —

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

  • :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)

  • :percolate_index (String) —

    The index to percolate the document into. Defaults to passed ‘index`.

  • :percolate_type (String) —

    The type to percolate document into. Defaults to passed ‘type`.

  • :version (Number) —

    Explicit version number for concurrency control

  • :version_type (String) —

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

Raises:

  • (ArgumentError)

See Also:



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
 
# File 'lib/elasticsearch/api/actions/count_percolate.rb', line 51

def count_percolate(arguments={})
  raise ArgumentError, "Required argument 'index' missing" unless arguments[:index]
  raise ArgumentError, "Required argument 'type' missing"  unless arguments[:type]
  valid_params = [
    :routing,
    :preference,
    :ignore_unavailable,
    :allow_no_indices,
    :expand_wildcards,
    :percolate_index,
    :percolate_type,
    :version,
    :version_type ]

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

  params = Utils.__validate_and_extract_params arguments, valid_params
  body   = arguments[:body]

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

#create(arguments = {}) ⇒ Object

Create a document.

Enforce the create operation when indexing a document – the operation will return an error when the document already exists.

(The ‘:op_type` argument is ignored.)

Examples:

Create a document


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

Parameters:

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

    a customizable set of options

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)

  • :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:



29
30
31
 
# File 'lib/elasticsearch/api/actions/create.rb', line 29

def create(arguments={})
  index arguments.update :op_type => 'create'
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'

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    The 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)

  • :consistency (String) —

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

  • :parent (String) —

    ID of parent 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

  • :version (Number) —

    Explicit version number for concurrency control

  • :version_type (String) —

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

Raises:

  • (ArgumentError)

See Also:



31
32
33
34
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
 
# File 'lib/elasticsearch/api/actions/delete.rb', line 31

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

  valid_params = [
    :consistency,
    :parent,
    :refresh,
    :replication,
    :routing,
    :timeout,
    :version,
    :version_type ]

  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, valid_params
  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.elasticsearch.org/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 } } }

Parameters:

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

    a customizable set of options

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_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

  • :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 update_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 (Integer) —

    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:



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
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
100
101
102
 
# File 'lib/elasticsearch/api/actions/delete_by_query.rb', line 56

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

  valid_params = [
    :analyzer,
    :analyze_wildcard,
    :default_operator,
    :df,
    :from,
    :ignore_unavailable,
    :allow_no_indices,
    :conflicts,
    :expand_wildcards,
    :lenient,
    :preference,
    :q,
    :routing,
    :scroll,
    :search_type,
    :search_timeout,
    :size,
    :sort,
    :_source,
    :_source_exclude,
    :_source_include,
    :terminate_after,
    :stats,
    :version,
    :request_cache,
    :refresh,
    :timeout,
    :wait_for_active_shards,
    :scroll_size,
    :wait_for_completion,
    :requests_per_second,
    :slices ]

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

  params = Utils.__validate_and_extract_params arguments, valid_params
  body   = arguments[:body]

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

#delete_script(arguments = {}) ⇒ Object

Remove an indexed script from Elasticsearch

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    Script ID (Required)

  • :lang (String) —

    Script language (Required)

  • :version (Number) —

    Explicit version number for concurrency control

  • :version_type (String) —

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

Raises:

  • (ArgumentError)

See Also:



14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
 
# File 'lib/elasticsearch/api/actions/delete_script.rb', line 14

def delete_script(arguments={})
  raise ArgumentError, "Required argument 'id' missing"   unless arguments[:id]
  raise ArgumentError, "Required argument 'lang' missing" unless arguments[:lang]

  valid_params = [
    :version,
    :version_type ]

  method = HTTP_DELETE
  path   = "_scripts/#{arguments.delete(:lang)}/#{arguments[:id]}"
  params = Utils.__validate_and_extract_params arguments, valid_params
  body   = nil

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

#delete_template(arguments = {}) ⇒ Object

Retrieve an indexed template from Elasticsearch

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    Template ID

See Also:



11
12
13
14
15
16
17
18
 
# File 'lib/elasticsearch/api/actions/delete_template.rb', line 11

def delete_template(arguments={})
  method = HTTP_DELETE
  path   = "_search/template/#{arguments[:id]}"
  params = {}
  body   = nil

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

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

Raises:

  • (ArgumentError)

See Also:



29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/elasticsearch/api/actions/exists.rb', line 29

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

  valid_params = [
    :stored_fields,
    :parent,
    :preference,
    :realtime,
    :refresh,
    :routing,
    :_source,
    :_source_exclude,
    :_source_include,
    :version,
    :version_type ]

  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, valid_params
  body   = nil

  Utils.__rescue_from_not_found do
    perform_request(method, path, params, body).status == 200 ? true : false
  end
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' } } }

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    The document ID (Required)

  • :index (String) —

    The name of the index (Required)

  • :type (String) —

    The type of the document (Required)

  • :body (Hash) —

    The query definition using the Query DSL (Required)

  • :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)

  • :fields (List) —

    A comma-separated list of 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

  • :lowercase_expanded_terms (Boolean) —

    Specify whether query terms should be lowercased

  • :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 (String) —

    The URL-encoded query definition (instead of using the 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

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
78
79
80
81
 
# File 'lib/elasticsearch/api/actions/explain.rb', line 46

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

  valid_params = [
    :analyze_wildcard,
    :analyzer,
    :default_operator,
    :df,
    :fields,
    :lenient,
    :lowercase_expanded_terms,
    :parent,
    :preference,
    :q,
    :routing,
    :source,
    :_source,
    :_source_include,
    :_source_exclude,
    :stored_fields ]

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

  params = Utils.__validate_and_extract_params arguments, valid_params
  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}} ...

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :index (List) —

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

  • :body (Hash) —

    Field json objects containing an array of field names

  • :fields (List) —

    A comma-separated list of field names (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:



20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/elasticsearch/api/actions/field_caps.rb', line 20

def field_caps(arguments={})
  raise ArgumentError, "Required argument 'fields' missing" unless arguments[:fields]

  valid_params = [
    :fields,
    :ignore_unavailable,
    :allow_no_indices,
    :expand_wildcards ]

  method = HTTP_GET
  path   = Utils.__pathify Utils.__listify(arguments[:index]), '_field_caps'
  params = Utils.__validate_and_extract_params arguments, valid_params
  body   = arguments[:body]

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

#field_stats(arguments = {}) ⇒ Object

Returns statistical information about a field without executing a search.

Parameters:

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

    a customizable set of options

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 fields for to get field statistics for (min value, max value, and more)

  • :level (String) —

    Defines if field stats should be returned on a per index level or on a cluster wide level (options: indices, cluster)

  • :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)

See Also:



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

def field_stats(arguments={})
  valid_params = [
    :fields,
    :level,
    :ignore_unavailable,
    :allow_no_indices,
    :expand_wildcards ]
  method = 'GET'
  path   = Utils.__pathify Utils.__escape(arguments[:index]), "_field_stats"
  params = Utils.__validate_and_extract_params arguments, valid_params
  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'

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    The 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; use ‘_all` to fetch the first document matching the ID across all types) (Required)

  • :fields (List) —

    A comma-separated list of 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

  • :version (Number) —

    Explicit version number for concurrency control

  • :version_type (String) —

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

  • :_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

  • :_source_transform (Boolean) —

    Retransform the source before returning it

  • :stored_fields (List) —

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

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
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# 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] ||= UNDERSCORE_ALL

  valid_params = [
    :fields,
    :parent,
    :preference,
    :realtime,
    :refresh,
    :routing,
    :version,
    :version_type,
    :_source,
    :_source_include,
    :_source_exclude,
    :_source_transform,
    :stored_fields ]

  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, valid_params
  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

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    Script ID (Required)

  • :lang (String) —

    Script language (Required)

Raises:

  • (ArgumentError)

See Also:



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

def get_script(arguments={})
  raise ArgumentError, "Required argument 'id' missing"   unless arguments[:id]
  raise ArgumentError, "Required argument 'lang' missing" unless arguments[:lang]
  method = HTTP_GET
  path   = "_scripts/#{arguments[:lang]}/#{arguments[:id]}"
  params = {}
  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'

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    The 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; use ‘_all` to fetch the first document matching the ID across all types) (Required)

  • :fields (List) —

    A comma-separated list of 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 (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

Raises:

  • (ArgumentError)

See Also:

Since:

  • 0.90.1



34
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
61
62
63
64
 
# File 'lib/elasticsearch/api/actions/get_source.rb', line 34

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

  valid_params = [
    :fields,
    :parent,
    :preference,
    :realtime,
    :refresh,
    :routing,
    :_source,
    :_source_include,
    :_source_exclude ]

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

  params = Utils.__validate_and_extract_params arguments, valid_params
  body   = nil

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

  Utils.__rescue_from_not_found do
    perform_request(method, path, params, body).body
  end
end

#get_template(arguments = {}) ⇒ Object

Retrieve an indexed script from Elasticsearch

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    Template ID (Required)

  • :body (Hash) —

    The document

Raises:

  • (ArgumentError)

See Also:



12
13
14
15
16
17
18
19
20
21
22
23
24
 
# File 'lib/elasticsearch/api/actions/get_template.rb', line 12

def get_template(arguments={})
  raise ArgumentError, "Required argument 'id' missing" unless arguments[:id]
  method = HTTP_GET
  path   = "_search/template/#{arguments[:id]}"
  params = {}
  body   = arguments[:body]

  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

#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: { mytype: { _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] ...

Parameters:

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

    a customizable set of options

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)

  • :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:



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
100
101
 
# File 'lib/elasticsearch/api/actions/index.rb', line 73

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

  valid_params = [
    :consistency,
    :op_type,
    :parent,
    :percolate,
    :pipeline,
    :refresh,
    :replication,
    :routing,
    :timeout,
    :timestamp,
    :ttl,
    :version,
    :version_type ]

  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, valid_params
  body   = arguments[:body]

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

#info(arguments = {}) ⇒ Object

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

See Also:



9
10
11
12
13
14
15
16
 
# File 'lib/elasticsearch/api/actions/info.rb', line 9

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

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

#list_benchmarks(arguments = {}) ⇒ Object

Return a list of running benchmarks

Examples:


client.list_benchmarks

Parameters:

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

    a customizable set of options

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

See Also:



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

def list_benchmarks(arguments={})
  method = HTTP_GET
  path   = "_bench"
  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']

Parameters:

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

    a customizable set of options

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)

  • :fields (List) —

    A comma-separated list of 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 (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

Raises:

  • (ArgumentError)

See Also:



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
 
# File 'lib/elasticsearch/api/actions/mget.rb', line 47

def mget(arguments={})
  raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]

  valid_params = [
    :fields,
    :parent,
    :preference,
    :realtime,
    :refresh,
    :routing,
    :_source,
    :_source_include,
    :_source_exclude,
    :stored_fields ]

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

  params = Utils.__validate_and_extract_params arguments, valid_params
  body   = arguments[:body]

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

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

#mlt(arguments = {}) ⇒ Object

Return documents similar to the specified one.

Performs a ‘more_like_this` query with the specified document as the input.

Examples:

Search for similar documents using the ‘title` property of document `myindex/mytype/1`


# First, let's setup a synonym-aware analyzer ("quick" <=> "fast")
client.indices.create index: 'myindex', body: {
  settings: {
    analysis: {
      filter: {
        synonyms: {
          type: 'synonym',
          synonyms: [ "quick,fast" ]
        }
      },
      analyzer: {
        title_synonym: {
          type: 'custom',
          tokenizer: 'whitespace',
          filter: ['lowercase', 'stop', 'snowball', 'synonyms']
        }
      }
    }
  },
  mappings: {
    mytype: {
      properties: {
        title: {
          type: 'string',
          analyzer: 'title_synonym'
        }
      }
    }
  }
}

# Index three documents
client.index index: 'myindex', type: 'mytype', id: 1, body: { title: 'Quick Brown Fox'   }
client.index index: 'myindex', type: 'mytype', id: 2, body: { title: 'Slow Black Dog'    }
client.index index: 'myindex', type: 'mytype', id: 3, body: { title: 'Fast White Rabbit' }
client.indices.refresh index: 'myindex'

client.mlt index: 'myindex', type: 'mytype', id: 1, mlt_fields: 'title', min_doc_freq: 1, min_term_freq: 1
# => { ... {"title"=>"Fast White Rabbit"}}]}}

Parameters:

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

    a customizable set of options

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)

  • :body (Hash) —

    A specific search request definition

  • :boost_terms (Number) —

    The boost factor

  • :max_doc_freq (Number) —

    The word occurrence frequency as count: words with higher occurrence in the corpus will be ignored

  • :max_query_terms (Number) —

    The maximum query terms to be included in the generated query

  • :max_word_len (Number) —

    The minimum length of the word: longer words will be ignored

  • :min_doc_freq (Number) —

    The word occurrence frequency as count: words with lower occurrence in the corpus will be ignored

  • :min_term_freq (Number) —

    The term frequency as percent: terms with lower occurence in the source document will be ignored

  • :min_word_len (Number) —

    The minimum length of the word: shorter words will be ignored

  • :mlt_fields (List) —

    Specific fields to perform the query against

  • :percent_terms_to_match (Number) —

    How many terms have to match in order to consider the document a match (default: 0.3)

  • :routing (String) —

    Specific routing value

  • :search_from (Number) —

    The offset from which to return results

  • :search_indices (List) —

    A comma-separated list of indices to perform the query against (default: the index containing the document)

  • :search_query_hint (String) —

    The search query hint

  • :search_scroll (String) —

    A scroll search request definition

  • :search_size (Number) —

    The number of documents to return (default: 10)

  • :search_source (String) —

    A specific search request definition (instead of using the request body)

  • :search_type (String) —

    Specific search type (eg. ‘dfs_then_fetch`, `count`, etc)

  • :search_types (List) —

    A comma-separated list of types to perform the query against (default: the same type as the document)

  • :stop_words (List) —

    A list of stop words to be ignored

Raises:

  • (ArgumentError)

See Also:



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
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/elasticsearch/api/actions/mlt.rb', line 84

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

  valid_params = [
    :boost_terms,
    :max_doc_freq,
    :max_query_terms,
    :max_word_len,
    :min_doc_freq,
    :min_term_freq,
    :min_word_len,
    :mlt_fields,
    :percent_terms_to_match,
    :routing,
    :search_from,
    :search_indices,
    :search_query_hint,
    :search_scroll,
    :search_size,
    :search_source,
    :search_type,
    :search_types,
    :stop_words ]

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

  params = Utils.__validate_and_extract_params arguments, valid_params

  [:mlt_fields, :search_indices, :search_types, :stop_words].each do |name|
    params[name] = Utils.__listify(params[name]) if params[name]
  end

  body   = arguments[:body]

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

#mpercolate(arguments = {}) ⇒ Object

Perform multiple percolate operations in a single request, similar to the #msearch API

Pass the percolate definitions as header-body pairs in the ‘:body` argument, as an Array of Hashes.

Examples:

Perform two different percolations in a single request


client.mpercolate \
    body: [
      { percolate: { index: "my-index", type: "my-type" } },
      { doc: { message: "foo bar" } },
      { percolate: { index: "my-other-index", type: "my-other-type", id: "1" } },
      { }
    ]

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :index (String) —

    The index of the document being count percolated to use as default

  • :type (String) —

    The type of the document being percolated to use as default.

  • The (Array<Hash>) —

    percolate request definitions (header & body pairs) (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)

Raises:

  • (ArgumentError)

See Also:



32
33
34
35
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/mpercolate.rb', line 32

def mpercolate(arguments={})
  raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]
  valid_params = [
    :ignore_unavailable,
    :allow_no_indices,
    :expand_wildcards,
    :percolate_format ]

  method = HTTP_GET
  path   = "_mpercolate"

  params = Utils.__validate_and_extract_params arguments, valid_params
  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).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: 'count' },
    { aggregations: { published: { terms: { field: 'published' } } } }
  ]

Parameters:

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

    a customizable set of options

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

Raises:

  • (ArgumentError)

See Also:



38
39
40
41
42
43
44
45
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
 
# File 'lib/elasticsearch/api/actions/msearch.rb', line 38

def msearch(arguments={})
  raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]

   valid_params = [
    :search_type,
    :max_concurrent_searches,
    :typed_keys ]

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

  params = Utils.__validate_and_extract_params arguments, valid_params
  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).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] }

Parameters:

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

    a customizable set of options

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)

  • :ids (List) —

    A comma-separated list of documents ids (alternative to ‘:body`)

  • :term_statistics (Boolean) —

    Whether total term frequency and document frequency should be returned.

  • :field_statistics (Boolean) —

    Whether 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) —

    Whether term offsets should be returned

  • :positions (Boolean) —

    Whether term positions should be returned

  • :payloads (Boolean) —

    Whether term payloads should be returned

  • :preference (String) —

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

  • :realtime (String) —

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

  • :routing (String) —

    Specific routing value

  • :parent (String) —

    Parent ID of documents

See Also:



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/elasticsearch/api/actions/mtermvectors.rb', line 37

def mtermvectors(arguments={})
  valid_params = [
    :ids,
    :term_statistics,
    :field_statistics,
    :fields,
    :offsets,
    :positions,
    :payloads,
    :preference,
    :realtime,
    :routing,
    :parent ]

  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, valid_params

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

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

#percolate(arguments = {}) ⇒ Object

Return names of queries matching a document.

Percolator allows you to register queries and then evaluate a document against them: the IDs of matching queries are returned in the response.

Examples:

Register queries named “alert-1” and “alert-2” for the “my-index” index


client.index index: 'my-index',
             type: '.percolator',
             id: 'alert-1',
             body: { query: { query_string: { query: 'foo' } } }

client.index index: 'my-index',
             type: '.percolator',
             id: 'alert-2',
             body: { query: { query_string: { query: 'bar' } } }

Evaluate a custom document (passed as ‘:doc`) against the queries


client.percolate index: 'my-index', type: 'my-type', body: { doc: { title: "Foo" } }
# => {..., matches: [ {_index: 'my-index', _id: 'alert-1'} ]}

client.percolate index: 'my-index', type: 'my-type', body: { doc: { title: "Foo Bar" } }
# => {..., matches: [ {_index: 'my-index', _id: 'alert-2'}, {_index: 'my-index', _id: 'alert-1'} ] }

Evaluate an existing document against the queries


client.index index: 'my-index', type: 'my-type', id: 123, body: { title: "Foo Bar" }

client.percolate index: 'my-index', type: 'my-type', id: '123'
# => { ..., matches: [ {_index: 'my-index', _id: 'alert-2'}, { _index: 'my-index', _id: 'alert-1'} ] }

Register a query with custom ‘priority` property


client.index index: 'my-index',
             type: '.percolator',
             id: 'alert-high-1',
             body: { query: { query_string: { query: 'foo' } },
                     priority: 'high' }

Evaluate a document against “high priority” percolator queries


client.percolate index: 'my-index', type: 'my-type', body: {
    doc:    { title: "Foo" },
    filter: { term: { priority: 'high' } }
  }
# => {..., matches: [ {_index: 'my-index', _id: 'alert-high-1'} ]}

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :index (String) —

    The index of the document being percolated. (Required)

  • :type (String) —

    The type of the document being percolated. (Required)

  • :id (String) —

    Fetch the document specified by index/type/id and use it instead of the passed ‘doc`

  • :body (Hash) —

    The percolator request definition using the percolate DSL

  • :routing (List) —

    A comma-separated list of specific routing values

  • :preference (String) —

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

  • :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)

  • :percolate_index (String) —

    The index to percolate the document into. Defaults to passed ‘index`.

  • :percolate_format (String) —

    Return an array of matching query IDs instead of objects. (options: ids)

  • :percolate_type (String) —

    The type to percolate document into. Defaults to passed ‘type`.

  • :version (Number) —

    Explicit version number for concurrency control

  • :version_type (String) —

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

Raises:

  • (ArgumentError)

See Also:



77
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
 
# File 'lib/elasticsearch/api/actions/percolate.rb', line 77

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

  valid_params = [
    :routing,
    :preference,
    :ignore_unavailable,
    :allow_no_indices,
    :expand_wildcards,
    :percolate_index,
    :percolate_type,
    :percolate_format,
    :version,
    :version_type ]

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

  params = Utils.__validate_and_extract_params arguments, valid_params
  body   = arguments[:body]

  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:



13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
 
# File 'lib/elasticsearch/api/actions/ping.rb', line 13

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 lang: 'groovy', id: 'my_score', body: { script: 'log(_score * factor)' }

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

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    Script ID (Required)

  • :lang (String) —

    Script language (Required)

  • :body (Hash) —

    A JSON document containing the script (Required)

  • :version (Number) —

    Explicit version number for concurrency control

  • :version_type (String) —

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

  • :op_type (String) —

    Explicit operation type (options: index, create)

Raises:

  • (ArgumentError)

See Also:



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

def put_script(arguments={})
  raise ArgumentError, "Required argument 'id' missing"   unless arguments[:id]
  raise ArgumentError, "Required argument 'lang' missing" unless arguments[:lang]
  raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]

  valid_params = [
    :op_type,
    :version,
    :version_type ]

  method = HTTP_PUT
  path   = "_scripts/#{arguments.delete(:lang)}/#{arguments[:id]}"

  params = Utils.__validate_and_extract_params arguments, valid_params

  body   = arguments[:body]

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

#put_template(arguments = {}) ⇒ Object

Store a template for the search definition in Elasticsearch, to be later used with the ‘search_template` method

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    Template ID (Required)

  • :body (Hash) —

    The document (Required)

Raises:

  • (ArgumentError)

See Also:



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

def put_template(arguments={})
  raise ArgumentError, "Required argument 'id' missing"   unless arguments[:id]
  raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]
  method = HTTP_PUT
  path   = "_search/template/#{arguments[:id]}"
  params = {}
  body   = arguments[:body]

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

#reindex(arguments = {}) ⇒ Object

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :requests_per_second (Float) —

    The throttling for this request in sub-requests per second. 0 means set no throttling (default)

Raises:

  • (ArgumentError)

See Also:



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/elasticsearch/api/actions/reindex.rb', line 52

def reindex(arguments={})
  raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]
  valid_params = [
    :refresh,
    :timeout,
    :consistency,
    :wait_for_completion,
    :requests_per_second ]
  method = 'POST'
  path   = "_reindex"
  params = Utils.__validate_and_extract_params arguments, valid_params
  body   = arguments[:body]

  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

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    The id of the stored search template

  • :body (Hash) —

    The search definition template and its params

See Also:



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

def render_search_template(arguments={})
  valid_params = [
    :id
  ]
  method = 'GET'
  path   = "_render/template"
  params = Utils.__validate_and_extract_params arguments, valid_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 scroll: '5m', scroll_id: result['_scroll_id']

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}"} 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(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

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :scroll_id (String) —

    The scroll ID

  • :body (Hash) —

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

  • :scroll (Duration) —

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

See Also:



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

def scroll(arguments={})
  method = HTTP_GET
  path   = "_search/scroll"
  valid_params = [
    :scroll,
    :scroll_id ]

  params = Utils.__validate_and_extract_params arguments, valid_params
  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.elasticsearch.org/guide/reference/api/search/uri-request/) as the ‘:q` argument , or by passing the [full request definition](www.elasticsearch.org/guide/reference/api/search/request-body/) in the [Query DSL](www.elasticsearch.org/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(', ')

Parameters:

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

    a customizable set of options

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)

  • :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.

Returns:

  • (Hash)

See Also:



125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
 
# File 'lib/elasticsearch/api/actions/search.rb', line 125

def search(arguments={})
  arguments[:index] = UNDERSCORE_ALL if ! arguments[:index] && arguments[:type]

  valid_params = [
    :analyzer,
    :analyze_wildcard,
    :default_operator,
    :df,
    :explain,
    :fielddata_fields,
    :docvalue_fields,
    :stored_fields,
    :fields,
    :from,
    :ignore_indices,
    :ignore_unavailable,
    :allow_no_indices,
    :expand_wildcards,
    :lenient,
    :lowercase_expanded_terms,
    :preference,
    :q,
    :query_cache,
    :request_cache,
    :routing,
    :scroll,
    :search_type,
    :size,
    :sort,
    :source,
    :_source,
    :_source_include,
    :_source_exclude,
    :stored_fields,
    :stats,
    :suggest_field,
    :suggest_mode,
    :suggest_size,
    :suggest_text,
    :terminate_after,
    :timeout,
    :typed_keys,
    :version,
    :batched_reduce_size ]

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

  params = Utils.__validate_and_extract_params arguments, valid_params

  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_exists(arguments = {}) ⇒ Object

Return whether documents exists for a particular query

Parameters:

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

    a customizable set of options

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)

  • :allow_no_indices (Boolean) —

    Whether to ignore if a wildcard indices expression resolves into no concrete indices.

  • :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 (String) —

    Specific routing value

  • :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

  • :lowercase_expanded_terms (Boolean) —

    Specify whether query terms should be lowercased

See Also:



35
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/search_exists.rb', line 35

def search_exists(arguments={})
  valid_params = [
    :ignore_unavailable,
    :allow_no_indices,
    :expand_wildcards,
    :min_score,
    :preference,
    :routing,
    :q,
    :analyzer,
    :analyze_wildcard,
    :default_operator,
    :df,
    :lenient,
    :lowercase_expanded_terms ]
  method = 'POST'
  path   = "_search/exists"
  params = Utils.__validate_and_extract_params arguments, valid_params
  body   = arguments[:body]

  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

Parameters:

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

    a customizable set of options

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:



24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
 
# File 'lib/elasticsearch/api/actions/search_shards.rb', line 24

def search_shards(arguments={})
  valid_params = [
    :preference,
    :routing,
    :local,
    :ignore_unavailable,
    :allow_no_indices,
    :expand_wildcards ]
  method = HTTP_GET
  path   = Utils.__pathify( Utils.__listify(arguments[:index]), Utils.__listify(arguments[:type]), '_search_shards' )
  params = Utils.__validate_and_extract_params arguments, valid_params
  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" }
                       }

Parameters:

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

    a customizable set of options

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

  • :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)

  • :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 (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)

See Also:



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

def search_template(arguments={})
  valid_params = [
    :ignore_unavailable,
    :allow_no_indices,
    :expand_wildcards,
    :preference,
    :routing,
    :scroll,
    :search_type ]
  method = HTTP_GET
  path   = Utils.__pathify( Utils.__listify(arguments[:index]), Utils.__listify(arguments[:type]), '_search/template' )
  params = Utils.__validate_and_extract_params arguments, valid_params
  body   = arguments[:body]

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

#suggest(arguments = {}) ⇒ Object

Return query terms suggestions based on provided text and configuration.

Pass the request definition in the ‘:body` argument.

Examples:

Return query terms suggestions (“auto-correction”)


client.suggest index: 'myindex',
               body: { my_suggest: { text: 'tset', term: { field: 'title' } } }
# => { ... "my_suggest"=>[ {"text"=>"tset", ... "options"=>[{"text"=>"test", "score"=>0.75, "freq"=>5}] }]}

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :index (List) —

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

  • :body (Hash) —

    The request definition

  • :ignore_indices (String) —

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

  • :preference (String) —

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

  • :routing (String) —

    Specific routing value

  • :source (String) —

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

See Also:

Since:

  • 0.90



29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/elasticsearch/api/actions/suggest.rb', line 29

def suggest(arguments={})
  valid_params = [
    :ignore_indices,
    :preference,
    :routing,
    :source ]

  method = HTTP_POST
  path   = Utils.__pathify( Utils.__listify(arguments[:index]), '_suggest' )

  params = Utils.__validate_and_extract_params arguments, valid_params
  body   = arguments[:body]

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

#termvector(arguments = {}) ⇒ Object

Deprecated.

Use the plural version, #termvectors



92
93
94
 
# File 'lib/elasticsearch/api/actions/termvectors.rb', line 92

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: {
                          my_type: {
                            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" => ... } } }

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :index (String) —

    The name of the index (Required)

  • :type (String) —

    The type of the document (Required)

  • :id (String) —

    The document ID

  • :body (Hash) —

    The request definition

  • :term_statistics (Boolean) —

    Whether total term frequency and document frequency should be returned

  • :field_statistics (Boolean) —

    Whether 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) —

    Whether term offsets should be returned

  • :positions (Boolean) —

    Whether term positions should be returned

  • :payloads (Boolean) —

    Whether term payloads should be returned

  • :preference (String) —

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

  • :realtime (String) —

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

  • :routing (String) —

    Specific routing value

  • :parent (String) —

    Parent ID of the documents

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
81
82
83
84
85
86
87
88
 
# File 'lib/elasticsearch/api/actions/termvectors.rb', line 60

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

  valid_params = [
    :term_statistics,
    :field_statistics,
    :fields,
    :offsets,
    :positions,
    :payloads,
    :preference,
    :realtime,
    :routing,
    :parent ]

  method = HTTP_GET
  endpoint = arguments.delete(:endpoint) || '_termvectors'

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

  params = Utils.__validate_and_extract_params arguments, valid_params
  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: 'ctx._source.tags += 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(tag) ? ctx.op = "delete" : ctx.op = "none"',
                      params: { tag: 'to-delete' } }

Parameters:

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

    a customizable set of options

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

  • :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



68
69
70
71
72
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
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/elasticsearch/api/actions/update.rb', line 68

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

  valid_params = [
    :consistency,
    :fields,
    :lang,
    :parent,
    :percolate,
    :refresh,
    :replication,
    :retry_on_conflict,
    :routing,
    :script,
    :_source,
    :_source_include,
    :_source_exclude,
    :timeout,
    :timestamp,
    :ttl,
    :version,
    :version_type ]

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

  params = Utils.__validate_and_extract_params arguments, valid_params
  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' } }
                       }

Parameters:

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

    a customizable set of options

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

  • :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

  • :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 reindex 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

  • :lowercase_expanded_terms (Boolean) —

    Specify whether query terms should be lowercased

  • :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 (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, 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_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

  • :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

  • :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

  • :timeout (Time) —

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

  • :track_scores (Boolean) —

    Whether to calculate and return scores even if they are not used for sorting

  • :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?

  • :consistency (String) —

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

  • :scroll_size (Integer) —

    Size on the scroll request powering the update_by_query

  • :wait_for_completion (Boolean) —

    Should the request should block until the reindex is complete.

  • :requests_per_second (Float) —

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

Raises:

  • (ArgumentError)

See Also:



67
68
69
70
71
72
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
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
 
# File 'lib/elasticsearch/api/actions/update_by_query.rb', line 67

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

  valid_params = [
    :analyzer,
    :analyze_wildcard,
    :default_operator,
    :df,
    :explain,
    :fields,
    :fielddata_fields,
    :from,
    :ignore_unavailable,
    :allow_no_indices,
    :conflicts,
    :expand_wildcards,
    :lenient,
    :lowercase_expanded_terms,
    :pipeline,
    :preference,
    :q,
    :routing,
    :scroll,
    :search_type,
    :search_timeout,
    :size,
    :sort,
    :_source,
    :_source_exclude,
    :_source_include,
    :terminate_after,
    :stats,
    :suggest_field,
    :suggest_mode,
    :suggest_size,
    :suggest_text,
    :timeout,
    :track_scores,
    :version,
    :version_type,
    :request_cache,
    :refresh,
    :consistency,
    :scroll_size,
    :wait_for_completion,
    :requests_per_second ]

  method = HTTP_POST

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

  params = Utils.__validate_and_extract_params arguments, valid_params

  body   = arguments[:body]

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