# SQL

class elasticsearch.client.SqlClient

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

      from elasticsearch import Elasticsearch

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

  clear_cursor(*, cursor=None, error_trace=None, filter_path=None, human=None, pretty=None, body=None)

    Clear an SQL search cursor.

    https://www.elastic.co/guide/en/elasticsearch/reference/8.17/clear-sql-cursor-api.html

    Parameters:

      - cursor (str | None) – Cursor to clear.

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

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

    Delete an async SQL search. Delete an async SQL search or a stored synchronous SQL search. If the search is still running, the API cancels it.

    If the Elasticsearch security features are enabled, only the following users can use this API to delete a search:

    - Users with the `cancel_task` cluster privilege.
    - The user who first submitted the search.

    https://www.elastic.co/guide/en/elasticsearch/reference/8.17/delete-async-sql-search-api.html

    Parameters:

      - id (str) – The identifier for the search.

      - error_trace (bool | None)

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

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  get_async(*, id, delimiter=None, error_trace=None, filter_path=None, format=None, human=None, keep_alive=None, pretty=None, wait_for_completion_timeout=None)

    Get async SQL search results. Get the current status and available results for an async SQL search or stored synchronous SQL search.

    If the Elasticsearch security features are enabled, only the user who first submitted the SQL search can retrieve the search using this API.

    https://www.elastic.co/guide/en/elasticsearch/reference/8.17/get-async-sql-search-api.html

    Parameters:

      - id (str) – The identifier for the search.

      - delimiter (str | None) – The separator for CSV results. The API supports this parameter only for CSV responses.

      - format (str | None) – The format for the response. You must specify a format using this parameter or the Accept HTTP header. If you specify both, the API uses this parameter.

      - keep_alive (str | Literal[-1] | ~typing.Literal[0] | None) – The retention period for the search and its results. It defaults to the keep_alive period for the original SQL search.

      - wait_for_completion_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – The period to wait for complete results. It defaults to no timeout, meaning the request waits for complete search results.

      - error_trace (bool | None)

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

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

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

    Get the async SQL search status. Get the current status of an async SQL search or a stored synchronous SQL search.

    https://www.elastic.co/guide/en/elasticsearch/reference/8.17/get-async-sql-search-status-api.html

    Parameters:

      - id (str) – The identifier for the search.

      - error_trace (bool | None)

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

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  query(*, allow_partial_search_results=None, catalog=None, columnar=None, cursor=None, error_trace=None, fetch_size=None, field_multi_value_leniency=None, filter=None, filter_path=None, format=None, human=None, index_using_frozen=None, keep_alive=None, keep_on_completion=None, page_timeout=None, params=None, pretty=None, query=None, request_timeout=None, runtime_mappings=None, time_zone=None, wait_for_completion_timeout=None, body=None)

    Get SQL search results. Run an SQL request.

    https://www.elastic.co/guide/en/elasticsearch/reference/8.17/sql-search-api.html

    Parameters:

      - allow_partial_search_results (bool | None) – If true, the response has partial results when there are shard request timeouts or shard failures. If false, the API returns an error with no partial results.

      - catalog (str | None) – The default catalog (cluster) for queries. If unspecified, the queries execute on the data in the local cluster only.

      - columnar (bool | None) – If true, the results are in a columnar fashion: one row represents all the values of a certain column from the current page of results. The API supports this parameter only for CBOR, JSON, SMILE, and YAML responses.

      - cursor (str | None) – The cursor used to retrieve a set of paginated results. If you specify a cursor, the API only uses the columnar and time_zone request body parameters. It ignores other request body parameters.

      - fetch_size (int | None) – The maximum number of rows (or entries) to return in one response.

      - field_multi_value_leniency (bool | None) – If false, the API returns an exception when encountering multiple values for a field. If true, the API is lenient and returns the first value from the array with no guarantee of consistent results.

      - filter (Mapping[str, Any] | None) – The Elasticsearch query DSL for additional filtering.

      - format (str | Literal['cbor', 'csv', 'json', 'smile', 'tsv', 'txt', 'yaml'] | None) – The format for the response. You can also specify a format using the Accept HTTP header. If you specify both this parameter and the Accept HTTP header, this parameter takes precedence.

      - index_using_frozen (bool | None) – If true, the search can run on frozen indices.

      - keep_alive (str | Literal[-1] | ~typing.Literal[0] | None) – The retention period for an async or saved synchronous search.

      - keep_on_completion (bool | None) – If true, Elasticsearch stores synchronous searches if you also specify the wait_for_completion_timeout parameter. If false, Elasticsearch only stores async searches that don’t finish before the wait_for_completion_timeout.

      - page_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – The minimum retention period for the scroll cursor. After this time period, a pagination request might fail because the scroll cursor is no longer available. Subsequent scroll requests prolong the lifetime of the scroll cursor by the duration of page_timeout in the scroll request.

      - params (Mapping[str, Any] | None) – The values for parameters in the query.

      - query (str | None) – The SQL query to run.

      - request_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – The timeout before the request fails.

      - runtime_mappings (Mapping[str, Mapping[str, Any]] | None) – One or more runtime fields for the search request. These fields take precedence over mapped fields with the same name.

      - time_zone (str | None) – The ISO-8601 time zone ID for the search.

      - wait_for_completion_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – The period to wait for complete results. It defaults to no timeout, meaning the request waits for complete search results. If the search doesn’t finish within this period, the search becomes async. To save a synchronous search, you must specify this parameter and the keep_on_completion parameter.

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

  translate(*, query=None, error_trace=None, fetch_size=None, filter=None, filter_path=None, human=None, pretty=None, time_zone=None, body=None)

    Translate SQL into Elasticsearch queries. Translate an SQL search into a search API request containing Query DSL. It accepts the same request body parameters as the SQL search API, excluding `cursor`.

    https://www.elastic.co/guide/en/elasticsearch/reference/8.17/sql-translate-api.html

    Parameters:

      - query (str | None) – The SQL query to run.

      - fetch_size (int | None) – The maximum number of rows (or entries) to return in one response.

      - filter (Mapping[str, Any] | None) – The Elasticsearch query DSL for additional filtering.

      - time_zone (str | None) – The ISO-8601 time zone ID for the search.

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