Module: Elasticsearch::API::Esql::Actions

Defined in:
lib/elasticsearch/api/actions/esql/query.rb,
lib/elasticsearch/api/actions/esql/get_query.rb,
lib/elasticsearch/api/actions/esql/async_query.rb,
lib/elasticsearch/api/actions/esql/list_queries.rb,
lib/elasticsearch/api/actions/esql/async_query_get.rb,
lib/elasticsearch/api/actions/esql/async_query_stop.rb,
lib/elasticsearch/api/actions/esql/async_query_delete.rb

Instance Method Summary collapse

Instance Method Details

#async_query(arguments = {}) ⇒ Object

Run an async ES|QL query. Asynchronously run an ES|QL (Elasticsearch query language) query, monitor its progress, and retrieve results when they become available. The API accepts the same parameters and request body as the synchronous query API, along with additional async related properties.

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :allow_partial_results (Boolean) —

    If ‘true`, partial results will be returned if there are shard failures, but the query can continue to execute on other clusters and shards. If `false`, the query will fail if there are any failures.To override the default behavior, you can set the `esql.query.allow_partial_results` cluster setting to `false`. Server default: true.

  • :delimiter (String) —

    The character to use between values within a CSV row. It is valid only for the CSV format.

  • :drop_null_columns (Boolean) —

    Indicates whether columns that are entirely ‘null` will be removed from the `columns` and `values` portion of the results. If `true`, the response will include an extra section under the name `all_columns` which has the name of all the columns.

  • :format (String) —

    A short version of the Accept header, e.g. json, yaml.‘csv`, `tsv`, and `txt` formats will return results in a tabular format, excluding other metadata fields from the response.For async requests, nothing will be returned if the async query doesn’t finish within the timeout. The query ID and running status are available in the ‘X-Elasticsearch-Async-Id` and `X-Elasticsearch-Async-Is-Running` HTTP headers of the response, respectively.

  • :error_trace (Boolean) —

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

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

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

  • :human (Boolean) —

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

  • :pretty (Boolean) —

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

  • :headers (Hash) —

    Custom HTTP headers

  • :body (Hash) —

    request body

Raises:

  • (ArgumentError)

See Also:



53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/elasticsearch/api/actions/esql/async_query.rb', line 53

def async_query(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'esql.async_query' }

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

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

  body = arguments.delete(:body)

  method = Elasticsearch::API::HTTP_POST
  path   = '_query/async'
  params = Utils.process_params(arguments)

  Elasticsearch::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#async_query_delete(arguments = {}) ⇒ Object

Delete an async ES|QL query. If the query is still running, it is cancelled. Otherwise, the stored results are deleted. If the Elasticsearch security features are enabled, only the following users can use this API to delete a query:

  • The authenticated user that submitted the original query request

  • Users with the ‘cancel_task` cluster privilege

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    The unique identifier of the query. A query ID is provided in the ES|QL async query API response for a query that does not complete in the designated time. A query ID is also provided when the request was submitted with the ‘keep_on_completion` parameter set to `true`. (Required)

  • :error_trace (Boolean) —

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

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

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

  • :human (Boolean) —

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

  • :pretty (Boolean) —

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

  • :headers (Hash) —

    Custom HTTP headers

Raises:

  • (ArgumentError)

See Also:



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

def async_query_delete(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'esql.async_query_delete' }

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

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

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

  body = nil

  _id = arguments.delete(:id)

  method = Elasticsearch::API::HTTP_DELETE
  path   = "_query/async/#{Utils.listify(_id)}"
  params = Utils.process_params(arguments)

  Elasticsearch::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#async_query_get(arguments = {}) ⇒ Object

Get async ES|QL query results. Get the current status and available results or stored results for an ES|QL asynchronous query. If the Elasticsearch security features are enabled, only the user who first submitted the ES|QL query can retrieve the results using this API.

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    The unique identifier of the query. A query ID is provided in the ES|QL async query API response for a query that does not complete in the designated time. A query ID is also provided when the request was submitted with the ‘keep_on_completion` parameter set to `true`. (Required)

  • :drop_null_columns (Boolean) —

    Indicates whether columns that are entirely ‘null` will be removed from the `columns` and `values` portion of the results. If `true`, the response will include an extra section under the name `all_columns` which has the name of all the columns.

  • :format (String) —

    A short version of the Accept header, for example ‘json` or `yaml`.

  • :keep_alive (Time) —

    The period for which the query and its results are stored in the cluster. When this period expires, the query and its results are deleted, even if the query is still ongoing.

  • :wait_for_completion_timeout (Time) —

    The period to wait for the request to finish. By default, the request waits for complete query results. If the request completes during the period specified in this parameter, complete query results are returned. Otherwise, the response returns an ‘is_running` value of `true` and no results.

  • :error_trace (Boolean) —

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

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

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

  • :human (Boolean) —

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

  • :pretty (Boolean) —

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

  • :headers (Hash) —

    Custom HTTP headers

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

def async_query_get(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'esql.async_query_get' }

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

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

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

  body = nil

  _id = arguments.delete(:id)

  method = Elasticsearch::API::HTTP_GET
  path   = "_query/async/#{Utils.listify(_id)}"
  params = Utils.process_params(arguments)

  Elasticsearch::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#async_query_stop(arguments = {}) ⇒ Object

Stop async ES|QL query. This API interrupts the query execution and returns the results so far. If the Elasticsearch security features are enabled, only the user who first submitted the ES|QL query can stop it.

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    The unique identifier of the query. A query ID is provided in the ES|QL async query API response for a query that does not complete in the designated time. A query ID is also provided when the request was submitted with the ‘keep_on_completion` parameter set to `true`. (Required)

  • :drop_null_columns (Boolean) —

    Indicates whether columns that are entirely ‘null` will be removed from the `columns` and `values` portion of the results. If `true`, the response will include an extra section under the name `all_columns` which has the name of all the columns.

  • :error_trace (Boolean) —

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

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

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

  • :human (Boolean) —

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

  • :pretty (Boolean) —

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

  • :headers (Hash) —

    Custom HTTP headers

Raises:

  • (ArgumentError)

See Also:



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/esql/async_query_stop.rb', line 49

def async_query_stop(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'esql.async_query_stop' }

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

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

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

  body = nil

  _id = arguments.delete(:id)

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

  Elasticsearch::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#get_query(arguments = {}) ⇒ Object

Get a specific running ES|QL query information. Returns an object extended information about a running ES|QL query. This functionality is Experimental and may be changed or removed completely in a future release. Elastic will take a best effort approach to fix any issues, but experimental features are not subject to the support SLA of official GA features.

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :id (String) —

    The query ID (Required)

  • :error_trace (Boolean) —

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

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

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

  • :human (Boolean) —

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

  • :pretty (Boolean) —

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

  • :headers (Hash) —

    Custom HTTP headers

Raises:

  • (ArgumentError)

See Also:

  • [TODO]


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

def get_query(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'esql.get_query' }

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

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

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

  body = nil

  _id = arguments.delete(:id)

  method = Elasticsearch::API::HTTP_GET
  path   = "_query/queries/#{Utils.listify(_id)}"
  params = Utils.process_params(arguments)

  Elasticsearch::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#list_queries(arguments = {}) ⇒ Object

Get running ES|QL queries information. Returns an object containing IDs and other information about the running ES|QL queries. This functionality is Experimental and may be changed or removed completely in a future release. Elastic will take a best effort approach to fix any issues, but experimental features are not subject to the support SLA of official GA features.

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :error_trace (Boolean) —

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

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

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

  • :human (Boolean) —

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

  • :pretty (Boolean) —

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

  • :headers (Hash) —

    Custom HTTP headers

See Also:

  • [TODO]


47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/elasticsearch/api/actions/esql/list_queries.rb', line 47

def list_queries(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'esql.list_queries' }

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

  body = nil

  method = Elasticsearch::API::HTTP_GET
  path   = '_query/queries'
  params = Utils.process_params(arguments)

  Elasticsearch::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end

#query(arguments = {}) ⇒ Object

Run an ES|QL query. Get search results for an ES|QL (Elasticsearch query language) query. This functionality is subject to potential breaking changes within a minor version, meaning that your referencing code may break when this library is upgraded.

Parameters:

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

    a customizable set of options

Options Hash (arguments):

  • :format (String) —

    A short version of the Accept header, e.g. json, yaml.‘csv`, `tsv`, and `txt` formats will return results in a tabular format, excluding other metadata fields from the response.

  • :delimiter (String) —

    The character to use between values within a CSV row. Only valid for the CSV format.

  • :drop_null_columns (Boolean) —

    Should columns that are entirely ‘null` be removed from the `columns` and `values` portion of the results? Defaults to `false`. If `true` then the response will include an extra section under the name `all_columns` which has the name of all columns.

  • :allow_partial_results (Boolean) —

    If ‘true`, partial results will be returned if there are shard failures, but the query can continue to execute on other clusters and shards. If `false`, the query will fail if there are any failures.To override the default behavior, you can set the `esql.query.allow_partial_results` cluster setting to `false`. Server default: true.

  • :error_trace (Boolean) —

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

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

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

  • :human (Boolean) —

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

  • :pretty (Boolean) —

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

  • :headers (Hash) —

    Custom HTTP headers

  • :body (Hash) —

    request body

Raises:

  • (ArgumentError)

See Also:



53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/elasticsearch/api/actions/esql/query.rb', line 53

def query(arguments = {})
  request_opts = { endpoint: arguments[:endpoint] || 'esql.query' }

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

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

  body = arguments.delete(:body)

  method = Elasticsearch::API::HTTP_POST
  path   = '_query'
  params = Utils.process_params(arguments)

  Elasticsearch::API::Response.new(
    perform_request(method, path, params, body, headers, request_opts)
  )
end