# ES|QL

class elasticsearch.client.EsqlClient

  To use this client, access `client.esql` from an `Elasticsearch` client. For example:

      from elasticsearch import Elasticsearch

      # Create the client instance
      client = Elasticsearch(...)
      # Use the esql client
      client.esql.<method>(...)

  async_query(*, query=None, allow_partial_results=None, columnar=None, delimiter=None, drop_null_columns=None, error_trace=None, filter=None, filter_path=None, format=None, human=None, include_ccs_metadata=None, include_execution_metadata=None, keep_alive=None, keep_on_completion=None, locale=None, params=None, pretty=None, profile=None, project_routing=None, settings=None, tables=None, time_zone=None, wait_for_completion_timeout=None, body=None)

    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.

    https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-esql-async-query

    Parameters:

      - query (str | ESQLBase | None) – The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results.

      - allow_partial_results (bool | None) – 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.

      - columnar (bool | None) – By default, ES|QL returns results as rows. For example, FROM returns each individual document as one row. For the JSON, YAML, CBOR and smile formats, ES|QL can return the results in a columnar fashion where one row represents all the values of a certain column in the results.

      - delimiter (str | None) – The character to use between values within a CSV row. It is valid only for the CSV format.

      - drop_null_columns (bool | None) – 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.

      - filter (Mapping[str, Any] | None) – Specify a Query DSL query in the filter parameter to filter the set of documents that an ES|QL query runs on.

      - format (str | Literal['arrow', 'cbor', 'csv', 'json', 'smile', 'tsv', 'txt', 'yaml'] | None) – 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.

      - include_ccs_metadata (bool | None) – When set to true and performing a cross-cluster/cross-project query, the response will include an extra _clusters object with information about the clusters that participated in the search along with info such as shards count.

      - include_execution_metadata (bool | None) – When set to true, the response will include an extra _clusters object with information about the clusters that participated in the search along with info such as shards count. This is similar to include_ccs_metadata, but it also returns metadata when the query is not CCS/CPS

      - keep_alive (str | Literal[-1] | ~typing.Literal[0] | None) – The period for which the query and its results are stored in the cluster. The default period is five days. When this period expires, the query and its results are deleted, even if the query is still ongoing. If the keep_on_completion parameter is false, Elasticsearch only stores async queries that do not complete within the period set by the wait_for_completion_timeout parameter, regardless of this value.

      - keep_on_completion (bool | None) – Indicates whether the query and its results are stored in the cluster. If false, the query and its results are stored in the cluster only if the request does not complete during the period set by the wait_for_completion_timeout parameter.

      - locale (str | None) – Returns results (especially dates) formatted per the conventions of the locale.

      - params (Sequence[Mapping[str, Mapping[str, Any] | Sequence[None | bool | float | int | str] | None | bool | float | int | str]] | Sequence[Sequence[None | bool | float | int | str] | None | bool | float | int | str] | None) – To avoid any attempts of hacking or code injection, extract the values in a separate list of parameters. Use question mark placeholders (?) in the query string for each of the parameters.

      - profile (bool | None) – If provided and true the response will include an extra profile object with information on how the query was executed. This information is for human debugging and its format can change at any time but it can give some insight into the performance of each part of the query.

      - project_routing (str | None) – Specifies a subset of projects to target using project metadata tags in a subset of Lucene query syntax. Allowed Lucene queries: the _alias tag and a single value (possibly wildcarded). Examples: _alias:my-project _alias:_origin _alias:pr Supported in serverless only.

      - settings (Mapping[str, Any] | None) – Per-query settings, the request-body equivalent of the in-query SET command. For example, time_zone can be supplied here instead of as a top-level field.

      - tables (Mapping[str, Mapping[str, Mapping[str, Any]]] | None) – Tables to use with the LOOKUP operation. The top level key is the table name and the next level key is the column name.

      - time_zone (str | None) – Sets the default timezone of the query.

      - wait_for_completion_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – The period to wait for the request to finish. By default, the request waits for 1 second for the query results. If the query completes during this period, results are returned Otherwise, a query ID is returned that can later be used to retrieve the results.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

      - body (Dict[str, Any] | None)

    Return type:

      ObjectApiResponse[Any]

  async_query_delete(*, id, error_trace=None, filter_path=None, human=None, pretty=None)

    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

    https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-esql-async-query-delete

    Parameters:

      - id (str) – 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.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  async_query_get(*, id, drop_null_columns=None, error_trace=None, filter_path=None, format=None, human=None, keep_alive=None, pretty=None, wait_for_completion_timeout=None)

    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.

    https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-esql-async-query-get

    Parameters:

      - id (str) – 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.

      - drop_null_columns (bool | None) – 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 (str | Literal['arrow', 'cbor', 'csv', 'json', 'smile', 'tsv', 'txt', 'yaml'] | None) – A short version of the Accept header, for example json or yaml.

      - keep_alive (str | Literal[-1] | ~typing.Literal[0] | None) – 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 (str | Literal[-1] | ~typing.Literal[0] | None) – 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 (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  async_query_stop(*, id, drop_null_columns=None, error_trace=None, filter_path=None, human=None, pretty=None)

    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.

    https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-esql-async-query-stop

    Parameters:

      - id (str) – 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.

      - drop_null_columns (bool | None) – 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 (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  delete_view(*, name, error_trace=None, filter_path=None, human=None, pretty=None)

    Delete an ES|QL view.

    Deletes a stored ES|QL view.

    https://www.elastic.co/docs/api/doc/elasticsearch#TODO

    Parameters:

      - name (str | Sequence[str]) – The view name to remove.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  get_query(*, id, error_trace=None, filter_path=None, human=None, pretty=None)

    Get a specific running ES|QL query information.

    Returns an object extended information about a running ES|QL query.

    https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-esql-get-query

    Parameters:

      - id (str) – The query ID

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  get_view(*, name=None, error_trace=None, filter_path=None, human=None, pretty=None)

    Get an ES|QL view.

    Returns a stored ES|QL view.

    https://www.elastic.co/docs/api/doc/elasticsearch#TODO

    Parameters:

      - name (str | None) – The comma-separated view names to retrieve.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  list_queries(*, error_trace=None, filter_path=None, human=None, pretty=None)

    Get running ES|QL queries information.

    Returns an object containing IDs and other information about the running ES|QL queries.

    https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-esql-list-queries

    Parameters:

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  put_view(*, name, query=None, error_trace=None, filter_path=None, human=None, pretty=None, body=None)

    Create or update an ES|QL view.

    https://www.elastic.co/docs/api/doc/elasticsearch#TODO

    Parameters:

      - name (str) – The view name to create or update.

      - query (str | ESQLBase | None) – The ES|QL query string from which to create a view.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

      - body (Dict[str, Any] | None)

    Return type:

      ObjectApiResponse[Any]

  query(*, query=None, allow_partial_results=None, columnar=None, delimiter=None, drop_null_columns=None, error_trace=None, filter=None, filter_path=None, format=None, human=None, include_ccs_metadata=None, include_execution_metadata=None, locale=None, params=None, pretty=None, profile=None, project_routing=None, settings=None, tables=None, time_zone=None, body=None)

    Run an ES|QL query.

    Get search results for an ES|QL (Elasticsearch query language) query.

    https://www.elastic.co/docs/explore-analyze/query-filter/languages/esql-rest

    Parameters:

      - query (str | ESQLBase | None) – The ES|QL query API accepts an ES|QL query string in the query parameter, runs it, and returns the results.

      - allow_partial_results (bool | None) – 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.

      - columnar (bool | None) – By default, ES|QL returns results as rows. For example, FROM returns each individual document as one row. For the JSON, YAML, CBOR and smile formats, ES|QL can return the results in a columnar fashion where one row represents all the values of a certain column in the results.

      - delimiter (str | None) – The character to use between values within a CSV row. Only valid for the CSV format.

      - drop_null_columns (bool | None) – 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.

      - filter (Mapping[str, Any] | None) – Specify a Query DSL query in the filter parameter to filter the set of documents that an ES|QL query runs on.

      - format (str | Literal['arrow', 'cbor', 'csv', 'json', 'smile', 'tsv', 'txt', 'yaml'] | None) – 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.

      - include_ccs_metadata (bool | None) – When set to true and performing a cross-cluster/cross-project query, the response will include an extra _clusters object with information about the clusters that participated in the search along with info such as shards count.

      - include_execution_metadata (bool | None) – When set to true, the response will include an extra _clusters object with information about the clusters that participated in the search along with info such as shards count. This is similar to include_ccs_metadata, but it also returns metadata when the query is not CCS/CPS

      - locale (str | None) – Returns results (especially dates) formatted per the conventions of the locale.

      - params (Sequence[Mapping[str, Mapping[str, Any] | Sequence[None | bool | float | int | str] | None | bool | float | int | str]] | Sequence[Sequence[None | bool | float | int | str] | None | bool | float | int | str] | None) – To avoid any attempts of hacking or code injection, extract the values in a separate list of parameters. Use question mark placeholders (?) in the query string for each of the parameters.

      - profile (bool | None) – If provided and true the response will include an extra profile object with information on how the query was executed. This information is for human debugging and its format can change at any time but it can give some insight into the performance of each part of the query.

      - project_routing (str | None) – Specifies a subset of projects to target using project metadata tags in a subset of Lucene query syntax. Allowed Lucene queries: the _alias tag and a single value (possibly wildcarded). Examples: _alias:my-project _alias:_origin _alias:pr Supported in serverless only.

      - settings (Mapping[str, Any] | None) – Per-query settings, the request-body equivalent of the in-query SET command. For example, time_zone can be supplied here instead of as a top-level field.

      - tables (Mapping[str, Mapping[str, Mapping[str, Any]]] | None) – Tables to use with the LOOKUP operation. The top level key is the table name and the next level key is the column name.

      - time_zone (str | None) – Sets the default timezone of the query.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

      - body (Dict[str, Any] | None)

    Return type:

      ObjectApiResponse[Any]