Method: Elasticsearch::API::Actions#explain

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

#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