elasticsearch 9.0.0__py3-none-any.whl → 9.0.2__py3-none-any.whl

elasticsearch/dsl/_sync/_sync_check/search.py

@@ -0,0 +1,230 @@
+#  Licensed to Elasticsearch B.V. under one or more contributor
+#  license agreements. See the NOTICE file distributed with
+#  this work for additional information regarding copyright
+#  ownership. Elasticsearch B.V. licenses this file to you under
+#  the Apache License, Version 2.0 (the "License"); you may
+#  not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+# 	http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing,
+#  software distributed under the License is distributed on an
+#  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#  KIND, either express or implied.  See the License for the
+#  specific language governing permissions and limitations
+#  under the License.
+
+import contextlib
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Dict,
+    Iterator,
+    List,
+    Optional,
+    cast,
+)
+
+from typing_extensions import Self
+
+from elasticsearch.exceptions import ApiError
+from elasticsearch.helpers import scan
+
+from ..connections import get_connection
+from ..response import Response
+from ..search_base import MultiSearchBase, SearchBase
+from ..utils import _R, AttrDict, UsingType
+
+
+class Search(SearchBase[_R]):
+    _using: UsingType
+
+    def __iter__(self) -> Iterator[_R]:
+        """
+        Iterate over the hits.
+        """
+
+        class ResultsIterator(Iterator[_R]):
+            def __init__(self, search: Search[_R]):
+                self.search = search
+                self.iterator: Optional[Iterator[_R]] = None
+
+            def __next__(self) -> _R:
+                if self.iterator is None:
+                    self.iterator = iter(self.search.execute())
+                try:
+                    return next(self.iterator)
+                except StopIteration:
+                    raise StopIteration()
+
+        return ResultsIterator(self)
+
+    def count(self) -> int:
+        """
+        Return the number of hits matching the query and filters. Note that
+        only the actual number is returned.
+        """
+        if hasattr(self, "_response") and self._response.hits.total.relation == "eq":  # type: ignore[attr-defined]
+            return cast(int, self._response.hits.total.value)  # type: ignore[attr-defined]
+
+        es = get_connection(self._using)
+
+        d = self.to_dict(count=True)
+        # TODO: failed shards detection
+        resp = es.count(
+            index=self._index,
+            query=cast(Optional[Dict[str, Any]], d.get("query", None)),
+            **self._params,
+        )
+
+        return cast(int, resp["count"])
+
+    def execute(self, ignore_cache: bool = False) -> Response[_R]:
+        """
+        Execute the search and return an instance of ``Response`` wrapping all
+        the data.
+
+        :arg ignore_cache: if set to ``True``, consecutive calls will hit
+            ES, while cached result will be ignored. Defaults to `False`
+        """
+        if ignore_cache or not hasattr(self, "_response"):
+            es = get_connection(self._using)
+
+            self._response = self._response_class(
+                self,
+                (
+                    es.search(index=self._index, body=self.to_dict(), **self._params)
+                ).body,
+            )
+        return self._response
+
+    def scan(self) -> Iterator[_R]:
+        """
+        Turn the search into a scan search and return a generator that will
+        iterate over all the documents matching the query.
+
+        Use the ``params`` method to specify any additional arguments you wish to
+        pass to the underlying ``scan`` helper from ``elasticsearch-py`` -
+        https://elasticsearch-py.readthedocs.io/en/latest/helpers.html#scan
+
+        The ``iterate()`` method should be preferred, as it provides similar
+        functionality using an Elasticsearch point in time.
+        """
+        es = get_connection(self._using)
+
+        for hit in scan(es, query=self.to_dict(), index=self._index, **self._params):
+            yield self._get_result(cast(AttrDict[Any], hit))
+
+    def delete(self) -> AttrDict[Any]:
+        """
+        ``delete()`` executes the query by delegating to ``delete_by_query()``.
+
+        Use the ``params`` method to specify any additional arguments you wish to
+        pass to the underlying ``delete_by_query`` helper from ``elasticsearch-py`` -
+        https://elasticsearch-py.readthedocs.io/en/latest/api/elasticsearch.html#elasticsearch.Elasticsearch.delete_by_query
+        """
+
+        es = get_connection(self._using)
+        assert self._index is not None
+
+        return AttrDict(
+            cast(
+                Dict[str, Any],
+                es.delete_by_query(
+                    index=self._index, body=self.to_dict(), **self._params
+                ),
+            )
+        )
+
+    @contextlib.contextmanager
+    def point_in_time(self, keep_alive: str = "1m") -> Iterator[Self]:
+        """
+        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: str = "1m") -> Iterator[_R]:
+        """
+        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 = s.search_after()
+
+
+class MultiSearch(MultiSearchBase[_R]):
+    """
+    Combine multiple :class:`~elasticsearch.dsl.Search` objects into a single
+    request.
+    """
+
+    _using: UsingType
+
+    if TYPE_CHECKING:
+
+        def add(self, search: Search[_R]) -> Self: ...  # type: ignore[override]
+
+    def execute(
+        self, ignore_cache: bool = False, raise_on_error: bool = True
+    ) -> List[Response[_R]]:
+        """
+        Execute the multi search request and return a list of search results.
+        """
+        if ignore_cache or not hasattr(self, "_response"):
+            es = get_connection(self._using)
+
+            responses = es.msearch(
+                index=self._index, body=self.to_dict(), **self._params
+            )
+
+            out: List[Response[_R]] = []
+            for s, r in zip(self._searches, responses["responses"]):
+                if r.get("error", False):
+                    if raise_on_error:
+                        raise ApiError("N/A", meta=responses.meta, body=r)
+                    r = None
+                else:
+                    r = Response(s, r)
+                out.append(r)
+
+            self._response = out
+
+        return self._response
+
+
+class EmptySearch(Search[_R]):
+    def count(self) -> int:
+        return 0
+
+    def execute(self, ignore_cache: bool = False) -> Response[_R]:
+        return self._response_class(self, {"hits": {"total": 0, "hits": []}})
+
+    def scan(self) -> Iterator[_R]:
+        return
+        yield  # a bit strange, but this forces an empty generator function
+
+    def delete(self) -> AttrDict[Any]:
+        return AttrDict[Any]({})

elasticsearch/dsl/_sync/_sync_check/update_by_query.py

@@ -0,0 +1,45 @@
+#  Licensed to Elasticsearch B.V. under one or more contributor
+#  license agreements. See the NOTICE file distributed with
+#  this work for additional information regarding copyright
+#  ownership. Elasticsearch B.V. licenses this file to you under
+#  the Apache License, Version 2.0 (the "License"); you may
+#  not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+# 	http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing,
+#  software distributed under the License is distributed on an
+#  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+#  KIND, either express or implied.  See the License for the
+#  specific language governing permissions and limitations
+#  under the License.
+
+from typing import TYPE_CHECKING
+
+from ..connections import get_connection
+from ..update_by_query_base import UpdateByQueryBase
+from ..utils import _R, UsingType
+
+if TYPE_CHECKING:
+    from ..response import UpdateByQueryResponse
+
+
+class UpdateByQuery(UpdateByQueryBase[_R]):
+    _using: UsingType
+
+    def execute(self) -> "UpdateByQueryResponse[_R]":
+        """
+        Execute the search and return an instance of ``Response`` wrapping all
+        the data.
+        """
+        es = get_connection(self._using)
+        assert self._index is not None
+
+        self._response = self._response_class(
+            self,
+            (
+                es.update_by_query(index=self._index, **self.to_dict(), **self._params)
+            ).body,
+        )
+        return self._response

elasticsearch/dsl/_sync/document.py

@@ -92,7 +92,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":

elasticsearch/dsl/field.py

@@ -1290,7 +1290,7 @@ class Date(Field):
         if isinstance(data, datetime):
             if self._default_timezone and data.tzinfo is None:
                 data = data.replace(tzinfo=self._default_timezone)
-            return data
+            return cast(datetime, data)
         if isinstance(data, date):
             return data
         if isinstance(data, int):
@@ -3689,6 +3689,11 @@ class SemanticText(Field):
         by using the Update mapping API. Use the Create inference API to
         create the endpoint. If not specified, the inference endpoint
         defined by inference_id will be used at both index and query time.
+    :arg chunking_settings: Settings for chunking text into smaller
+        passages. If specified, these will override the chunking settings
+        sent in the inference endpoint associated with inference_id. If
+        chunking settings are updated, they will not be applied to
+        existing documents until they are reindexed.
     """
 
     name = "semantic_text"
@@ -3699,6 +3704,9 @@ class SemanticText(Field):
         meta: Union[Mapping[str, str], "DefaultType"] = DEFAULT,
         inference_id: Union[str, "DefaultType"] = DEFAULT,
         search_inference_id: Union[str, "DefaultType"] = DEFAULT,
+        chunking_settings: Union[
+            "types.ChunkingSettings", Dict[str, Any], "DefaultType"
+        ] = DEFAULT,
         **kwargs: Any,
     ):
         if meta is not DEFAULT:
@@ -3707,6 +3715,8 @@ class SemanticText(Field):
             kwargs["inference_id"] = inference_id
         if search_inference_id is not DEFAULT:
             kwargs["search_inference_id"] = search_inference_id
+        if chunking_settings is not DEFAULT:
+            kwargs["chunking_settings"] = chunking_settings
         super().__init__(*args, **kwargs)
 
 

elasticsearch/dsl/query.py

@@ -1084,7 +1084,7 @@ class Knn(Query):
     :arg similarity: The minimum similarity for a vector to be considered
         a match
     :arg rescore_vector: Apply oversampling and rescoring to quantized
-        vectors *
+        vectors
     :arg boost: Floating point number used to decrease or increase the
         relevance scores of the query. Boost values are relative to the
         default value of 1.0. A boost value between 0 and 1.0 decreases
@@ -1382,7 +1382,49 @@ class MoreLikeThis(Query):
         min_term_freq: Union[int, "DefaultType"] = DEFAULT,
         min_word_length: Union[int, "DefaultType"] = DEFAULT,
         routing: Union[str, "DefaultType"] = DEFAULT,
-        stop_words: Union[str, Sequence[str], "DefaultType"] = DEFAULT,
+        stop_words: Union[
+            Literal[
+                "_arabic_",
+                "_armenian_",
+                "_basque_",
+                "_bengali_",
+                "_brazilian_",
+                "_bulgarian_",
+                "_catalan_",
+                "_cjk_",
+                "_czech_",
+                "_danish_",
+                "_dutch_",
+                "_english_",
+                "_estonian_",
+                "_finnish_",
+                "_french_",
+                "_galician_",
+                "_german_",
+                "_greek_",
+                "_hindi_",
+                "_hungarian_",
+                "_indonesian_",
+                "_irish_",
+                "_italian_",
+                "_latvian_",
+                "_lithuanian_",
+                "_norwegian_",
+                "_persian_",
+                "_portuguese_",
+                "_romanian_",
+                "_russian_",
+                "_serbian_",
+                "_sorani_",
+                "_spanish_",
+                "_swedish_",
+                "_thai_",
+                "_turkish_",
+                "_none_",
+            ],
+            Sequence[str],
+            "DefaultType",
+        ] = DEFAULT,
         unlike: Union[
             Union[str, "types.LikeDocument"],
             Sequence[Union[str, "types.LikeDocument"]],

elasticsearch/dsl/types.py

@@ -142,6 +142,48 @@ class ChiSquareHeuristic(AttrDict[Any]):
         super().__init__(kwargs)
 
 
+class ChunkingSettings(AttrDict[Any]):
+    """
+    :arg strategy: (required) The chunking strategy: `sentence` or `word`.
+        Defaults to `sentence` if omitted.
+    :arg max_chunk_size: (required) The maximum size of a chunk in words.
+        This value cannot be higher than `300` or lower than `20` (for
+        `sentence` strategy) or `10` (for `word` strategy). Defaults to
+        `250` if omitted.
+    :arg overlap: The number of overlapping words for chunks. It is
+        applicable only to a `word` chunking strategy. This value cannot
+        be higher than half the `max_chunk_size` value. Defaults to `100`
+        if omitted.
+    :arg sentence_overlap: The number of overlapping sentences for chunks.
+        It is applicable only for a `sentence` chunking strategy. It can
+        be either `1` or `0`. Defaults to `1` if omitted.
+    """
+
+    strategy: Union[str, DefaultType]
+    max_chunk_size: Union[int, DefaultType]
+    overlap: Union[int, DefaultType]
+    sentence_overlap: Union[int, DefaultType]
+
+    def __init__(
+        self,
+        *,
+        strategy: Union[str, DefaultType] = DEFAULT,
+        max_chunk_size: Union[int, DefaultType] = DEFAULT,
+        overlap: Union[int, DefaultType] = DEFAULT,
+        sentence_overlap: Union[int, DefaultType] = DEFAULT,
+        **kwargs: Any,
+    ):
+        if strategy is not DEFAULT:
+            kwargs["strategy"] = strategy
+        if max_chunk_size is not DEFAULT:
+            kwargs["max_chunk_size"] = max_chunk_size
+        if overlap is not DEFAULT:
+            kwargs["overlap"] = overlap
+        if sentence_overlap is not DEFAULT:
+            kwargs["sentence_overlap"] = sentence_overlap
+        super().__init__(kwargs)
+
+
 class ClassificationInferenceOptions(AttrDict[Any]):
     """
     :arg num_top_classes: Specifies the number of top class predictions to
@@ -329,6 +371,9 @@ class DenseVectorIndexOptions(AttrDict[Any]):
     :arg m: The number of neighbors each node will be connected to in the
         HNSW graph.  Only applicable to `hnsw`, `int8_hnsw`, `bbq_hnsw`,
         and `int4_hnsw` index types. Defaults to `16` if omitted.
+    :arg rescore_vector: The rescore vector options. This is only
+        applicable to `bbq_hnsw`, `int4_hnsw`, `int8_hnsw`, `bbq_flat`,
+        `int4_flat`, and `int8_flat` index types.
     """
 
     type: Union[
@@ -347,6 +392,9 @@ class DenseVectorIndexOptions(AttrDict[Any]):
     confidence_interval: Union[float, DefaultType]
     ef_construction: Union[int, DefaultType]
     m: Union[int, DefaultType]
+    rescore_vector: Union[
+        "DenseVectorIndexOptionsRescoreVector", Dict[str, Any], DefaultType
+    ]
 
     def __init__(
         self,
@@ -367,6 +415,9 @@ class DenseVectorIndexOptions(AttrDict[Any]):
         confidence_interval: Union[float, DefaultType] = DEFAULT,
         ef_construction: Union[int, DefaultType] = DEFAULT,
         m: Union[int, DefaultType] = DEFAULT,
+        rescore_vector: Union[
+            "DenseVectorIndexOptionsRescoreVector", Dict[str, Any], DefaultType
+        ] = DEFAULT,
         **kwargs: Any,
     ):
         if type is not DEFAULT:
@@ -377,6 +428,29 @@ class DenseVectorIndexOptions(AttrDict[Any]):
             kwargs["ef_construction"] = ef_construction
         if m is not DEFAULT:
             kwargs["m"] = m
+        if rescore_vector is not DEFAULT:
+            kwargs["rescore_vector"] = rescore_vector
+        super().__init__(kwargs)
+
+
+class DenseVectorIndexOptionsRescoreVector(AttrDict[Any]):
+    """
+    :arg oversample: (required) The oversampling factor to use when
+        searching for the nearest neighbor. This is only applicable to the
+        quantized formats: `bbq_*`, `int4_*`, and `int8_*`. When provided,
+        `oversample * k` vectors will be gathered and then their scores
+        will be re-computed with the original vectors.  valid values are
+        between `1.0` and `10.0` (inclusive), or `0` exactly to disable
+        oversampling.
+    """
+
+    oversample: Union[float, DefaultType]
+
+    def __init__(
+        self, *, oversample: Union[float, DefaultType] = DEFAULT, **kwargs: Any
+    ):
+        if oversample is not DEFAULT:
+            kwargs["oversample"] = oversample
         super().__init__(kwargs)
 
 
@@ -1561,11 +1635,7 @@ class InnerHits(AttrDict[Any]):
         DefaultType,
     ]
     seq_no_primary_term: Union[bool, DefaultType]
-    fields: Union[
-        Union[str, InstrumentedField],
-        Sequence[Union[str, InstrumentedField]],
-        DefaultType,
-    ]
+    fields: Union[Sequence[Union[str, InstrumentedField]], DefaultType]
     sort: Union[
         Union[Union[str, InstrumentedField], "SortOptions"],
         Sequence[Union[Union[str, InstrumentedField], "SortOptions"]],
@@ -1600,11 +1670,7 @@ class InnerHits(AttrDict[Any]):
             DefaultType,
         ] = DEFAULT,
         seq_no_primary_term: Union[bool, DefaultType] = DEFAULT,
-        fields: Union[
-            Union[str, InstrumentedField],
-            Sequence[Union[str, InstrumentedField]],
-            DefaultType,
-        ] = DEFAULT,
+        fields: Union[Sequence[Union[str, InstrumentedField]], DefaultType] = DEFAULT,
         sort: Union[
             Union[Union[str, InstrumentedField], "SortOptions"],
             Sequence[Union[Union[str, InstrumentedField], "SortOptions"]],

elasticsearch/exceptions.py

@@ -61,6 +61,7 @@ class ApiError(_ApiError):
             if self.body and isinstance(self.body, dict) and "error" in self.body:
                 if isinstance(self.body["error"], dict):
                     root_cause = self.body["error"]["root_cause"][0]
+                    caused_by = self.body["error"].get("caused_by", {})
                     cause = ", ".join(
                         filter(
                             None,
@@ -68,6 +69,7 @@ class ApiError(_ApiError):
                                 repr(root_cause["reason"]),
                                 root_cause.get("resource.id"),
                                 root_cause.get("resource.type"),
+                                caused_by.get("reason"),
                             ],
                         )
                     )

{elasticsearch-9.0.0.dist-info → elasticsearch-9.0.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: elasticsearch
-Version: 9.0.0
+Version: 9.0.2
 Summary: Python client for Elasticsearch
 Project-URL: Documentation, https://elasticsearch-py.readthedocs.io/
 Project-URL: Homepage, https://github.com/elastic/elasticsearch-py
@@ -142,24 +142,23 @@ of the getting started documentation.
 
 ## Compatibility
 
-Language clients are forward compatible; meaning that the clients support
-communicating with greater or equal minor versions of Elasticsearch without
-breaking. It does not mean that the clients automatically support new features
-of newer Elasticsearch versions; it is only possible after a release of a new
-client version. For example, a 8.12 client version won't automatically support
-the new features of the 8.13 version of Elasticsearch, the 8.13 client version
-is required for that. Elasticsearch language clients are only backwards
-compatible with default distributions and without guarantees made.
+Language clients are _forward compatible:_ each client version works with equivalent and later minor versions of Elasticsearch without breaking.
 
-| Elasticsearch Version | Elasticsearch-Python Branch | Supported |
-| --------------------- | ------------------------ | --------- |
-| main                  | main                     |           |
-| 8.x                   | 8.x                      | 8.x       |
-| 7.x                   | 7.x                      | 7.17      |
+Compatibility does not imply full feature parity. New Elasticsearch features are supported only in equivalent client versions. For example, an 8.12 client fully supports Elasticsearch 8.12 features and works with 8.13 without breaking; however, it does not support new Elasticsearch 8.13 features. An 8.13 client fully supports Elasticsearch 8.13 features.
 
+| Elasticsearch version | elasticsearch-py branch |
+| --- | --- |
+| main | main |
+| 9.x | 9.x |
+| 9.x | 8.x |
+| 8.x | 8.x |
 
-If you have a need to have multiple versions installed at the same time older
-versions are also released as ``elasticsearch7`` and ``elasticsearch8``.
+Elasticsearch language clients are also _backward compatible_ across minor versions — with default distributions and without guarantees.
+
+> [!TIP]
+> To upgrade to a new major version, first upgrade Elasticsearch, then upgrade the Python Elasticsearch client.
+
+If you need to work with multiple client versions, note that older versions are also released as `elasticsearch7` and `elasticsearch8`.
 
 
 ## Documentation