Merge branch 'main' into main

Author: miguelgrinberg

Changelog.rst

@@ -3,6 +3,20 @@
 Changelog
 =========
 
+8.14.0 (2024-06-10)
+-------------------
+
+* Added ``text_expansion`` query clause (`#1837 <https://github.com/elastic/elasticsearch-dsl-py/pull/1837>`_)
+* Added ``Response.search_after()`` and ``Search.search_after()`` methods for efficient iteration (`#1829 <https://github.com/elastic/elasticsearch-dsl-py/pull/1829>`_)
+* Added point in time support and the ``iterate()`` method in the ``Search`` class (`#1833 <https://github.com/elastic/elasticsearch-dsl-py/pull/1833>`_)
+* Added support for slicing multiple times in ``Search`` class (`#1771 <https://github.com/elastic/elasticsearch-dsl-py/pull/1771>`_)
+  Added support for regular expressions in ``Completion.suggest()`` (`#1836 <https://github.com/elastic/elasticsearch-dsl-py/pull/1836>`_)
+* Fixed ``suggest()`` method of the ``Completion`` class to format requests correctly. (`#1836 <https://github.com/elastic/elasticsearch-dsl-py/pull/1836>`_)
+* Fixed ``Document.update()`` to accept fields set to ``None`` or empty (`#1820 <https://github.com/elastic/elasticsearch-dsl-py/pull/1820>`_)
+* Started work on type hints (Thanks Caio Fontes for leading this effort!)
+    * Added Type hints to ``function.py`` (`#1827 <https://github.com/elastic/elasticsearch-dsl-py/pull/1827>`_)
+    * Added Type hints to ``query.py`` (`#1821 <https://github.com/elastic/elasticsearch-dsl-py/pull/1821>`_)
+
 8.13.1 (2024-04-30)
 -------------------
 

elasticsearch_dsl/__init__.py

@@ -93,7 +93,7 @@
 from .utils import AttrDict, AttrList, DslBase
 from .wrappers import Range
 
-VERSION = (8, 13, 1)
+VERSION = (8, 14, 0)
 __version__ = VERSION
 __versionstr__ = ".".join(map(str, VERSION))
 __all__ = [

elasticsearch_dsl/_async/search.py

@@ -15,6 +15,8 @@
 #  specific language governing permissions and limitations
 #  under the License.
 
+import contextlib
+
 from elasticsearch.exceptions import ApiError
 from elasticsearch.helpers import async_scan
 
@@ -92,6 +94,8 @@ async def scan(self):
         pass to the underlying ``scan`` helper from ``elasticsearch-py`` -
         https://elasticsearch-py.readthedocs.io/en/master/helpers.html#elasticsearch.helpers.scan
 
+        The ``iterate()`` method should be preferred, as it provides similar
+        functionality using an Elasticsearch point in time.
         """
         es = get_connection(self._using)
 
@@ -113,6 +117,45 @@ async def delete(self):
             )
         )
 
+    @contextlib.asynccontextmanager
+    async def point_in_time(self, keep_alive="1m"):
+        """
+        Open a point in time (pit) that can be used across several searches.
+
+        This method implements a context manager that returns a search object
+        configured to operate within the created pit.
+
+        :arg keep_alive: the time to live for the point in time, renewed with each search request
+        """
+        es = get_connection(self._using)
+
+        pit = await es.open_point_in_time(
+            index=self._index or "*", keep_alive=keep_alive
+        )
+        search = self.index().extra(pit={"id": pit["id"], "keep_alive": keep_alive})
+        if not search._sort:
+            search = search.sort("_shard_doc")
+        yield search
+        await es.close_point_in_time(id=pit["id"])
+
+    async def iterate(self, keep_alive="1m"):
+        """
+        Return a generator that iterates over all the documents matching the query.
+
+        This method uses a point in time to provide consistent results even when
+        the index is changing. It should be preferred over ``scan()``.
+
+        :arg keep_alive: the time to live for the point in time, renewed with each new search request
+        """
+        async with self.point_in_time(keep_alive=keep_alive) as s:
+            while True:
+                r = await s.execute()
+                for hit in r:
+                    yield hit
+                if len(r.hits) == 0:
+                    break
+                s = r.search_after()
+
 
 class AsyncMultiSearch(MultiSearchBase):
     """

elasticsearch_dsl/_sync/search.py

@@ -15,6 +15,8 @@
 #  specific language governing permissions and limitations
 #  under the License.
 
+import contextlib
+
 from elasticsearch.exceptions import ApiError
 from elasticsearch.helpers import scan
 
@@ -88,6 +90,8 @@ def scan(self):
         pass to the underlying ``scan`` helper from ``elasticsearch-py`` -
         https://elasticsearch-py.readthedocs.io/en/master/helpers.html#elasticsearch.helpers.scan
 
+        The ``iterate()`` method should be preferred, as it provides similar
+        functionality using an Elasticsearch point in time.
         """
         es = get_connection(self._using)
 
@@ -105,6 +109,43 @@ def delete(self):
             es.delete_by_query(index=self._index, body=self.to_dict(), **self._params)
         )
 
+    @contextlib.contextmanager
+    def point_in_time(self, keep_alive="1m"):
+        """
+        Open a point in time (pit) that can be used across several searches.
+
+        This method implements a context manager that returns a search object
+        configured to operate within the created pit.
+
+        :arg keep_alive: the time to live for the point in time, renewed with each search request
+        """
+        es = get_connection(self._using)
+
+        pit = es.open_point_in_time(index=self._index or "*", keep_alive=keep_alive)
+        search = self.index().extra(pit={"id": pit["id"], "keep_alive": keep_alive})
+        if not search._sort:
+            search = search.sort("_shard_doc")
+        yield search
+        es.close_point_in_time(id=pit["id"])
+
+    def iterate(self, keep_alive="1m"):
+        """
+        Return a generator that iterates over all the documents matching the query.
+
+        This method uses a point in time to provide consistent results even when
+        the index is changing. It should be preferred over ``scan()``.
+
+        :arg keep_alive: the time to live for the point in time, renewed with each new search request
+        """
+        with self.point_in_time(keep_alive=keep_alive) as s:
+            while True:
+                r = s.execute()
+                for hit in r:
+                    yield hit
+                if len(r.hits) == 0:
+                    break
+                s = r.search_after()
+
 
 class MultiSearch(MultiSearchBase):
     """

elasticsearch_dsl/query.py

@@ -551,6 +551,10 @@ class TermsSet(Query):
     name = "terms_set"
 
 
+class TextExpansion(Query):
+    name = "text_expansion"
+
+
 class Wildcard(Query):
     name = "wildcard"
 

elasticsearch_dsl/search_base.py

@@ -743,7 +743,7 @@ def highlight(self, *fields, **kwargs):
             s._highlight[f] = kwargs
         return s
 
-    def suggest(self, name, text, **kwargs):
+    def suggest(self, name, text=None, regex=None, **kwargs):
         """
         Add a suggestions request to the search.
 
@@ -754,9 +754,27 @@ def suggest(self, name, text, **kwargs):
 
             s = Search()
             s = s.suggest('suggestion-1', 'Elasticsearch', term={'field': 'body'})
+
+        # regex query for Completion Suggester
+            s = Search()
+            s = s.suggest('suggestion-1', regex='py[thon|py]', completion={'field': 'body'})
         """
+        if text is None and regex is None:
+            raise ValueError('You have to pass "text" or "regex" argument.')
+        if text and regex:
+            raise ValueError('You can only pass either "text" or "regex" argument.')
+        if regex and "completion" not in kwargs:
+            raise ValueError(
+                '"regex" argument must be passed with "completion" keyword argument.'
+            )
+
         s = self._clone()
-        s._suggest[name] = {"text": text}
+        if regex:
+            s._suggest[name] = {"regex": regex}
+        elif "completion" in kwargs:
+            s._suggest[name] = {"prefix": text}
+        else:
+            s._suggest[name] = {"text": text}
         s._suggest[name].update(kwargs)
         return s