elasticsearch 8.18.1__py3-none-any.whl → 8.19.1__py3-none-any.whl

elasticsearch/_sync/client/sql.py

@@ -44,7 +44,7 @@ class SqlClient(NamespacedClient):
           <p>Clear an SQL search cursor.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/clear-sql-cursor-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/clear-sql-cursor-api.html>`_
 
         :param cursor: Cursor to clear.
         """
@@ -99,7 +99,7 @@ class SqlClient(NamespacedClient):
           </ul>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/delete-async-sql-search-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/delete-async-sql-search-api.html>`_
 
         :param id: The identifier for the search.
         """
@@ -150,7 +150,7 @@ class SqlClient(NamespacedClient):
           <p>If the Elasticsearch security features are enabled, only the user who first submitted the SQL search can retrieve the search using this API.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/get-async-sql-search-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/get-async-sql-search-api.html>`_
 
         :param id: The identifier for the search.
         :param delimiter: The separator for CSV results. The API supports this parameter
@@ -212,7 +212,7 @@ class SqlClient(NamespacedClient):
           Get the current status of an async SQL search or a stored synchronous SQL search.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/get-async-sql-search-status-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/get-async-sql-search-status-api.html>`_
 
         :param id: The identifier for the search.
         """
@@ -283,7 +283,7 @@ class SqlClient(NamespacedClient):
         keep_alive: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
         keep_on_completion: t.Optional[bool] = None,
         page_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
-        params: t.Optional[t.Mapping[str, t.Any]] = None,
+        params: t.Optional[t.Sequence[t.Any]] = None,
         pretty: t.Optional[bool] = None,
         query: t.Optional[str] = None,
         request_timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
@@ -301,7 +301,7 @@ class SqlClient(NamespacedClient):
           Run an SQL request.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/sql-search-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/sql-search-api.html>`_
 
         :param allow_partial_search_results: If `true`, the response has partial results
             when there are shard request timeouts or shard failures. If `false`, the
@@ -427,7 +427,7 @@ class SqlClient(NamespacedClient):
           It accepts the same request body parameters as the SQL search API, excluding <code>cursor</code>.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/sql-translate-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/sql-translate-api.html>`_
 
         :param query: The SQL query to run.
         :param fetch_size: The maximum number of rows (or entries) to return in one response.

elasticsearch/_sync/client/ssl.py

@@ -52,7 +52,7 @@ class SslClient(NamespacedClient):
           <p>If Elasticsearch is configured to use a keystore or truststore, the API output includes all certificates in that store, even though some of the certificates might not be in active use within the cluster.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/security-api-ssl.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/security-api-ssl.html>`_
         """
         __path_parts: t.Dict[str, str] = {}
         __path = "/_ssl/certificates"

elasticsearch/_sync/client/synonyms.py

@@ -53,7 +53,7 @@ class SynonymsClient(NamespacedClient):
           When the synonyms set is not used in analyzers, you will be able to delete it.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/delete-synonyms-set.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/delete-synonyms-set.html>`_
 
         :param id: The synonyms set identifier to delete.
         """
@@ -98,7 +98,7 @@ class SynonymsClient(NamespacedClient):
           Delete a synonym rule from a synonym set.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/delete-synonym-rule.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/delete-synonym-rule.html>`_
 
         :param set_id: The ID of the synonym set to update.
         :param rule_id: The ID of the synonym rule to delete.
@@ -151,7 +151,7 @@ class SynonymsClient(NamespacedClient):
           <p>Get a synonym set.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/get-synonyms-set.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/get-synonyms-set.html>`_
 
         :param id: The synonyms set identifier to retrieve.
         :param from_: The starting offset for query rules to retrieve.
@@ -202,7 +202,7 @@ class SynonymsClient(NamespacedClient):
           Get a synonym rule from a synonym set.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/get-synonym-rule.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/get-synonym-rule.html>`_
 
         :param set_id: The ID of the synonym set to retrieve the synonym rule from.
         :param rule_id: The ID of the synonym rule to retrieve.
@@ -255,7 +255,7 @@ class SynonymsClient(NamespacedClient):
           Get a summary of all defined synonym sets.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/get-synonyms-set.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/get-synonyms-set.html>`_
 
         :param from_: The starting offset for synonyms sets to retrieve.
         :param size: The maximum number of synonyms sets to retrieve.
@@ -311,7 +311,7 @@ class SynonymsClient(NamespacedClient):
           This is equivalent to invoking the reload search analyzers API for all indices that use the synonyms set.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/put-synonyms-set.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/put-synonyms-set.html>`_
 
         :param id: The ID of the synonyms set to be created or updated.
         :param synonyms_set: The synonym rules definitions for the synonyms set.
@@ -370,7 +370,7 @@ class SynonymsClient(NamespacedClient):
           <p>When you update a synonym rule, all analyzers using the synonyms set will be reloaded automatically to reflect the new rule.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/put-synonym-rule.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/put-synonym-rule.html>`_
 
         :param set_id: The ID of the synonym set.
         :param rule_id: The ID of the synonym rule to be updated or created.

elasticsearch/_sync/client/tasks.py

@@ -60,7 +60,7 @@ class TasksClient(NamespacedClient):
           You can also use the node hot threads API to obtain detailed information about the work the system is doing instead of completing the cancelled task.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/tasks.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/tasks.html>`_
 
         :param task_id: The task identifier.
         :param actions: A comma-separated list or wildcard expression of actions that
@@ -128,7 +128,7 @@ class TasksClient(NamespacedClient):
           <p>If the task identifier is not found, a 404 response code indicates that there are no resources that match the request.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/tasks.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/tasks.html>`_
 
         :param task_id: The task identifier.
         :param timeout: The period to wait for a response. If no response is received
@@ -238,7 +238,7 @@ class TasksClient(NamespacedClient):
           The <code>X-Opaque-Id</code> in the children <code>headers</code> is the child task of the task that was initiated by the REST request.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/tasks.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/tasks.html>`_
 
         :param actions: A comma-separated list or wildcard expression of actions used
             to limit the request. For example, you can use `cluser:*` to retrieve all

elasticsearch/_sync/client/text_structure.py

@@ -72,7 +72,7 @@ class TextStructureClient(NamespacedClient):
           It helps determine why the returned structure was chosen.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/find-field-structure.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/find-field-structure.html>`_
 
         :param field: The field that should be analyzed.
         :param index: The name of the index that contains the analyzed field.
@@ -259,7 +259,7 @@ class TextStructureClient(NamespacedClient):
           It helps determine why the returned structure was chosen.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/find-message-structure.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/find-message-structure.html>`_
 
         :param messages: The list of messages you want to analyze.
         :param column_names: If the format is `delimited`, you can specify the column
@@ -433,7 +433,7 @@ class TextStructureClient(NamespacedClient):
           However, you can optionally override some of the decisions about the text structure by specifying one or more query parameters.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/find-structure.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/find-structure.html>`_
 
         :param text_files:
         :param charset: The text's character set. It must be a character set that is
@@ -620,7 +620,7 @@ class TextStructureClient(NamespacedClient):
           The API indicates whether the lines match the pattern together with the offsets and lengths of the matched substrings.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/test-grok-pattern.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/test-grok-pattern.html>`_
 
         :param grok_pattern: The Grok pattern to run on the text.
         :param text: The lines of text to run the Grok pattern on.

elasticsearch/_sync/client/transform.py

@@ -44,7 +44,7 @@ class TransformClient(NamespacedClient):
           <p>Delete a transform.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/delete-transform.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/delete-transform.html>`_
 
         :param transform_id: Identifier for the transform.
         :param delete_dest_index: If this value is true, the destination index is deleted
@@ -108,7 +108,7 @@ class TransformClient(NamespacedClient):
           Get configuration information for transforms.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/get-transform.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/get-transform.html>`_
 
         :param transform_id: Identifier for the transform. It can be a transform identifier
             or a wildcard expression. You can get information for all transforms by using
@@ -181,7 +181,7 @@ class TransformClient(NamespacedClient):
           <p>Get usage information for transforms.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/get-transform-stats.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/get-transform-stats.html>`_
 
         :param transform_id: Identifier for the transform. It can be a transform identifier
             or a wildcard expression. You can get information for all transforms by using
@@ -269,7 +269,7 @@ class TransformClient(NamespacedClient):
           types of the source index and the transform aggregations.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/preview-transform.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/preview-transform.html>`_
 
         :param transform_id: Identifier for the transform to preview. If you specify
             this path parameter, you cannot provide transform configuration details in
@@ -406,7 +406,7 @@ class TransformClient(NamespacedClient):
           give users any privileges on <code>.data-frame-internal*</code> indices.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/put-transform.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/put-transform.html>`_
 
         :param transform_id: Identifier for the transform. This identifier can contain
             lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores.
@@ -512,7 +512,7 @@ class TransformClient(NamespacedClient):
           If the destination index was created by the transform, it is deleted.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/reset-transform.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/reset-transform.html>`_
 
         :param transform_id: Identifier for the transform. This identifier can contain
             lowercase alphanumeric characters (a-z and 0-9), hyphens, and underscores.
@@ -572,7 +572,7 @@ class TransformClient(NamespacedClient):
           is called again in the meantime.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/schedule-now-transform.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/schedule-now-transform.html>`_
 
         :param transform_id: Identifier for the transform.
         :param timeout: Controls the time to wait for the scheduling to take place
@@ -602,6 +602,66 @@ class TransformClient(NamespacedClient):
             path_parts=__path_parts,
         )
 
+    @_rewrite_parameters()
+    def set_upgrade_mode(
+        self,
+        *,
+        enabled: t.Optional[bool] = None,
+        error_trace: t.Optional[bool] = None,
+        filter_path: t.Optional[t.Union[str, t.Sequence[str]]] = None,
+        human: t.Optional[bool] = None,
+        pretty: t.Optional[bool] = None,
+        timeout: t.Optional[t.Union[str, t.Literal[-1], t.Literal[0]]] = None,
+    ) -> ObjectApiResponse[t.Any]:
+        """
+        .. raw:: html
+
+          <p>Set upgrade_mode for transform indices.
+          Sets a cluster wide upgrade_mode setting that prepares transform
+          indices for an upgrade.
+          When upgrading your cluster, in some circumstances you must restart your
+          nodes and reindex your transform indices. In those circumstances,
+          there must be no transforms running. You can close the transforms,
+          do the upgrade, then open all the transforms again. Alternatively,
+          you can use this API to temporarily halt tasks associated with the transforms
+          and prevent new transforms from opening. You can also use this API
+          during upgrades that do not require you to reindex your transform
+          indices, though stopping transforms is not a requirement in that case.
+          You can see the current value for the upgrade_mode setting by using the get
+          transform info API.</p>
+
+
+        `<https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-transform-set-upgrade-mode>`_
+
+        :param enabled: When `true`, it enables `upgrade_mode` which temporarily halts
+            all transform tasks and prohibits new transform tasks from starting.
+        :param timeout: The time to wait for the request to be completed.
+        """
+        __path_parts: t.Dict[str, str] = {}
+        __path = "/_transform/set_upgrade_mode"
+        __query: t.Dict[str, t.Any] = {}
+        if enabled is not None:
+            __query["enabled"] = enabled
+        if error_trace is not None:
+            __query["error_trace"] = error_trace
+        if filter_path is not None:
+            __query["filter_path"] = filter_path
+        if human is not None:
+            __query["human"] = human
+        if pretty is not None:
+            __query["pretty"] = pretty
+        if timeout is not None:
+            __query["timeout"] = timeout
+        __headers = {"accept": "application/json"}
+        return self.perform_request(  # type: ignore[return-value]
+            "POST",
+            __path,
+            params=__query,
+            headers=__headers,
+            endpoint_id="transform.set_upgrade_mode",
+            path_parts=__path_parts,
+        )
+
     @_rewrite_parameters(
         parameter_aliases={"from": "from_"},
     )
@@ -635,7 +695,7 @@ class TransformClient(NamespacedClient):
           destination indices, the transform fails when it attempts unauthorized operations.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/start-transform.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/start-transform.html>`_
 
         :param transform_id: Identifier for the transform.
         :param from_: Restricts the set of transformed entities to those changed after
@@ -693,7 +753,7 @@ class TransformClient(NamespacedClient):
           Stops one or more transforms.</p>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/stop-transform.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/stop-transform.html>`_
 
         :param transform_id: Identifier for the transform. To stop multiple transforms,
             use a comma-separated list or a wildcard expression. To stop all transforms,

elasticsearch/_sync/client/xpack.py

@@ -54,7 +54,7 @@ class XPackClient(NamespacedClient):
           </ul>
 
 
-        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.18/info-api.html>`_
+        `<https://www.elastic.co/guide/en/elasticsearch/reference/8.19/info-api.html>`_
 
         :param accept_enterprise: If this param is used it must be set to true
         :param categories: A comma-separated list of the information categories to include

elasticsearch/_version.py

@@ -15,4 +15,4 @@
 #  specific language governing permissions and limitations
 #  under the License.
 
-__versionstr__ = "8.18.1"
+__versionstr__ = "8.19.1"

elasticsearch/compat.py

@@ -16,12 +16,15 @@
 #  under the License.
 
 import inspect
+import os
 import sys
 from pathlib import Path
 from typing import Tuple, Type, Union
 
 string_types: Tuple[Type[str], Type[bytes]] = (str, bytes)
 
+DISABLE_WARN_STACKLEVEL_ENV_VAR = "DISABLE_WARN_STACKLEVEL"
+
 
 def to_str(x: Union[str, bytes], encoding: str = "ascii") -> str:
     if not isinstance(x, str):
@@ -37,6 +40,8 @@ def to_bytes(x: Union[str, bytes], encoding: str = "ascii") -> bytes:
 
 def warn_stacklevel() -> int:
     """Dynamically determine warning stacklevel for warnings based on the call stack"""
+    if os.environ.get(DISABLE_WARN_STACKLEVEL_ENV_VAR) in ["1", "true", "True"]:
+        return 0
     try:
         # Grab the root module from the current module '__name__'
         module_name = __name__.partition(".")[0]

elasticsearch/dsl/__init__.py

@@ -19,7 +19,7 @@ from . import async_connections, connections
 from .aggs import A, Agg
 from .analysis import analyzer, char_filter, normalizer, token_filter, tokenizer
 from .document import AsyncDocument, Document
-from .document_base import InnerDoc, M, MetaField, mapped_field
+from .document_base import E, InnerDoc, M, MetaField, mapped_field
 from .exceptions import (
     ElasticsearchDslException,
     IllegalOperation,
@@ -135,6 +135,7 @@ __all__ = [
     "Double",
     "DoubleRange",
     "DslBase",
+    "E",
     "ElasticsearchDslException",
     "EmptySearch",
     "Facet",

elasticsearch/dsl/_async/document.py

@@ -20,6 +20,7 @@ from typing import (
     TYPE_CHECKING,
     Any,
     AsyncIterable,
+    AsyncIterator,
     Dict,
     List,
     Optional,
@@ -42,6 +43,7 @@ from .search import AsyncSearch
 
 if TYPE_CHECKING:
     from elasticsearch import AsyncElasticsearch
+    from elasticsearch.esql.esql import ESQLBase
 
 
 class AsyncIndexMeta(DocumentMeta):
@@ -96,7 +98,7 @@ class AsyncDocument(DocumentBase, metaclass=AsyncIndexMeta):
 
     @classmethod
     def _get_using(cls, using: Optional[AsyncUsingType] = None) -> AsyncUsingType:
-        return cast(AsyncUsingType, using or cls._index._using)
+        return using or cls._index._using
 
     @classmethod
     def _get_connection(
@@ -520,3 +522,85 @@ class AsyncDocument(DocumentBase, metaclass=AsyncIndexMeta):
                 return action
 
         return await async_bulk(es, Generate(actions), **kwargs)
+
+    @classmethod
+    async def esql_execute(
+        cls,
+        query: "ESQLBase",
+        return_additional: bool = False,
+        ignore_missing_fields: bool = False,
+        using: Optional[AsyncUsingType] = None,
+        **kwargs: Any,
+    ) -> AsyncIterator[Union[Self, Tuple[Self, Dict[str, Any]]]]:
+        """
+        Execute the given ES|QL query and return an iterator of 2-element tuples,
+        where the first element is an instance of this ``Document`` and the
+        second a dictionary with any remaining columns requested in the query.
+
+        :arg query: an ES|QL query object created with the ``esql_from()`` method.
+        :arg return_additional: if ``False`` (the default), this method returns
+            document objects. If set to ``True``, the method returns tuples with
+            a document in the first element and a dictionary with any additional
+            columns returned by the query in the second element.
+        :arg ignore_missing_fields: if ``False`` (the default), all the fields of
+            the document must be present in the query, or else an exception is
+            raised. Set to ``True`` to allow missing fields, which will result in
+            partially initialized document objects.
+        :arg using: connection alias to use, defaults to ``'default'``
+        :arg kwargs: additional options for the ``client.esql.query()`` function.
+        """
+        es = cls._get_connection(using)
+        response = await es.esql.query(query=str(query), **kwargs)
+        query_columns = [col["name"] for col in response.body.get("columns", [])]
+
+        # Here we get the list of columns defined in the document, which are the
+        # columns that we will take from each result to assemble the document
+        # object.
+        # When `for_esql=False` is passed below by default, the list will include
+        # nested fields, which ES|QL does not return, causing an error. When passing
+        # `ignore_missing_fields=True` the list will be generated with
+        # `for_esql=True`, so the error will not occur, but the documents will
+        # not have any Nested objects in them.
+        doc_fields = set(cls._get_field_names(for_esql=ignore_missing_fields))
+        if not ignore_missing_fields and not doc_fields.issubset(set(query_columns)):
+            raise ValueError(
+                f"Not all fields of {cls.__name__} were returned by the query. "
+                "Make sure your document does not use Nested fields, which are "
+                "currently not supported in ES|QL. To force the query to be "
+                "evaluated in spite of the missing fields, pass set the "
+                "ignore_missing_fields=True option in the esql_execute() call."
+            )
+        non_doc_fields: set[str] = set(query_columns) - doc_fields - {"_id"}
+        index_id = query_columns.index("_id")
+
+        results = response.body.get("values", [])
+        for column_values in results:
+            # create a dictionary with all the document fields, expanding the
+            # dot notation returned by ES|QL into the recursive dictionaries
+            # used by Document.from_dict()
+            doc_dict: Dict[str, Any] = {}
+            for col, val in zip(query_columns, column_values):
+                if col in doc_fields:
+                    cols = col.split(".")
+                    d = doc_dict
+                    for c in cols[:-1]:
+                        if c not in d:
+                            d[c] = {}
+                        d = d[c]
+                    d[cols[-1]] = val
+
+            # create the document instance
+            obj = cls(meta={"_id": column_values[index_id]})
+            obj._from_dict(doc_dict)
+
+            if return_additional:
+                # build a dict with any other values included in the response
+                other = {
+                    col: val
+                    for col, val in zip(query_columns, column_values)
+                    if col in non_doc_fields
+                }
+
+                yield obj, other
+            else:
+                yield obj

elasticsearch/dsl/_sync/document.py

@@ -21,6 +21,7 @@ from typing import (
     Any,
     Dict,
     Iterable,
+    Iterator,
     List,
     Optional,
     Tuple,
@@ -42,6 +43,7 @@ from .search import Search
 
 if TYPE_CHECKING:
     from elasticsearch import Elasticsearch
+    from elasticsearch.esql.esql import ESQLBase
 
 
 class IndexMeta(DocumentMeta):
@@ -92,7 +94,7 @@ class Document(DocumentBase, metaclass=IndexMeta):
 
     @classmethod
     def _get_using(cls, using: Optional[UsingType] = None) -> UsingType:
-        return cast(UsingType, using or cls._index._using)
+        return using or cls._index._using
 
     @classmethod
     def _get_connection(cls, using: Optional[UsingType] = None) -> "Elasticsearch":
@@ -512,3 +514,85 @@ class Document(DocumentBase, metaclass=IndexMeta):
                 return action
 
         return bulk(es, Generate(actions), **kwargs)
+
+    @classmethod
+    def esql_execute(
+        cls,
+        query: "ESQLBase",
+        return_additional: bool = False,
+        ignore_missing_fields: bool = False,
+        using: Optional[UsingType] = None,
+        **kwargs: Any,
+    ) -> Iterator[Union[Self, Tuple[Self, Dict[str, Any]]]]:
+        """
+        Execute the given ES|QL query and return an iterator of 2-element tuples,
+        where the first element is an instance of this ``Document`` and the
+        second a dictionary with any remaining columns requested in the query.
+
+        :arg query: an ES|QL query object created with the ``esql_from()`` method.
+        :arg return_additional: if ``False`` (the default), this method returns
+            document objects. If set to ``True``, the method returns tuples with
+            a document in the first element and a dictionary with any additional
+            columns returned by the query in the second element.
+        :arg ignore_missing_fields: if ``False`` (the default), all the fields of
+            the document must be present in the query, or else an exception is
+            raised. Set to ``True`` to allow missing fields, which will result in
+            partially initialized document objects.
+        :arg using: connection alias to use, defaults to ``'default'``
+        :arg kwargs: additional options for the ``client.esql.query()`` function.
+        """
+        es = cls._get_connection(using)
+        response = es.esql.query(query=str(query), **kwargs)
+        query_columns = [col["name"] for col in response.body.get("columns", [])]
+
+        # Here we get the list of columns defined in the document, which are the
+        # columns that we will take from each result to assemble the document
+        # object.
+        # When `for_esql=False` is passed below by default, the list will include
+        # nested fields, which ES|QL does not return, causing an error. When passing
+        # `ignore_missing_fields=True` the list will be generated with
+        # `for_esql=True`, so the error will not occur, but the documents will
+        # not have any Nested objects in them.
+        doc_fields = set(cls._get_field_names(for_esql=ignore_missing_fields))
+        if not ignore_missing_fields and not doc_fields.issubset(set(query_columns)):
+            raise ValueError(
+                f"Not all fields of {cls.__name__} were returned by the query. "
+                "Make sure your document does not use Nested fields, which are "
+                "currently not supported in ES|QL. To force the query to be "
+                "evaluated in spite of the missing fields, pass set the "
+                "ignore_missing_fields=True option in the esql_execute() call."
+            )
+        non_doc_fields: set[str] = set(query_columns) - doc_fields - {"_id"}
+        index_id = query_columns.index("_id")
+
+        results = response.body.get("values", [])
+        for column_values in results:
+            # create a dictionary with all the document fields, expanding the
+            # dot notation returned by ES|QL into the recursive dictionaries
+            # used by Document.from_dict()
+            doc_dict: Dict[str, Any] = {}
+            for col, val in zip(query_columns, column_values):
+                if col in doc_fields:
+                    cols = col.split(".")
+                    d = doc_dict
+                    for c in cols[:-1]:
+                        if c not in d:
+                            d[c] = {}
+                        d = d[c]
+                    d[cols[-1]] = val
+
+            # create the document instance
+            obj = cls(meta={"_id": column_values[index_id]})
+            obj._from_dict(doc_dict)
+
+            if return_additional:
+                # build a dict with any other values included in the response
+                other = {
+                    col: val
+                    for col, val in zip(query_columns, column_values)
+                    if col in non_doc_fields
+                }
+
+                yield obj, other
+            else:
+                yield obj