elasticsearch 9.1.1__py3-none-any.whl → 9.2.0__py3-none-any.whl

elasticsearch/compat.py

@@ -18,8 +18,10 @@
 import inspect
 import os
 import sys
+from contextlib import contextmanager
 from pathlib import Path
-from typing import Tuple, Type, Union
+from threading import Thread
+from typing import Any, Callable, Iterator, Tuple, Type, Union
 
 string_types: Tuple[Type[str], Type[bytes]] = (str, bytes)
 
@@ -76,9 +78,36 @@ def warn_stacklevel() -> int:
     return 0
 
 
+@contextmanager
+def safe_thread(
+    target: Callable[..., Any], *args: Any, **kwargs: Any
+) -> Iterator[Thread]:
+    """Run a thread within a context manager block.
+
+    The thread is automatically joined when the block ends. If the thread raised
+    an exception, it is raised in the caller's context.
+    """
+    captured_exception = None
+
+    def run() -> None:
+        try:
+            target(*args, **kwargs)
+        except BaseException as exc:
+            nonlocal captured_exception
+            captured_exception = exc
+
+    thread = Thread(target=run)
+    thread.start()
+    yield thread
+    thread.join()
+    if captured_exception:
+        raise captured_exception
+
+
 __all__ = [
     "string_types",
     "to_str",
     "to_bytes",
     "warn_stacklevel",
+    "safe_thread",
 ]

elasticsearch/dsl/__init__.py

@@ -38,23 +38,30 @@ from .faceted_search import (
     TermsFacet,
 )
 from .field import (
+    AggregateMetricDouble,
+    Alias,
     Binary,
     Boolean,
     Byte,
     Completion,
     ConstantKeyword,
+    CountedKeyword,
     CustomField,
     Date,
+    DateNanos,
     DateRange,
     DenseVector,
     Double,
     DoubleRange,
     Field,
+    Flattened,
     Float,
     FloatRange,
     GeoPoint,
     GeoShape,
     HalfFloat,
+    Histogram,
+    IcuCollationKeyword,
     Integer,
     IntegerRange,
     Ip,
@@ -63,21 +70,28 @@ from .field import (
     Keyword,
     Long,
     LongRange,
+    MatchOnlyText,
     Murmur3,
     Nested,
     Object,
+    Passthrough,
     Percolator,
     Point,
     RangeField,
     RankFeature,
     RankFeatures,
+    RankVectors,
     ScaledFloat,
     SearchAsYouType,
+    SemanticText,
     Shape,
     Short,
     SparseVector,
     Text,
     TokenCount,
+    UnsignedLong,
+    Version,
+    Wildcard,
     construct_field,
 )
 from .function import SF
@@ -108,6 +122,8 @@ __all__ = [
     "A",
     "Agg",
     "AggResponse",
+    "AggregateMetricDouble",
+    "Alias",
     "AsyncComposableIndexTemplate",
     "AsyncDocument",
     "AsyncEmptySearch",
@@ -126,9 +142,11 @@ __all__ = [
     "Completion",
     "ComposableIndexTemplate",
     "ConstantKeyword",
+    "CountedKeyword",
     "CustomField",
     "Date",
     "DateHistogramFacet",
+    "DateNanos",
     "DateRange",
     "DenseVector",
     "Document",
@@ -142,12 +160,15 @@ __all__ = [
     "FacetedResponse",
     "FacetedSearch",
     "Field",
+    "Flattened",
     "Float",
     "FloatRange",
     "GeoPoint",
     "GeoShape",
     "HalfFloat",
+    "Histogram",
     "HistogramFacet",
+    "IcuCollationKeyword",
     "IllegalOperation",
     "Index",
     "IndexTemplate",
@@ -162,12 +183,14 @@ __all__ = [
     "LongRange",
     "M",
     "Mapping",
+    "MatchOnlyText",
     "MetaField",
     "MultiSearch",
     "Murmur3",
     "Nested",
     "NestedFacet",
     "Object",
+    "Passthrough",
     "Percolator",
     "Point",
     "Q",
@@ -177,11 +200,13 @@ __all__ = [
     "RangeField",
     "RankFeature",
     "RankFeatures",
+    "RankVectors",
     "Response",
     "SF",
     "ScaledFloat",
     "Search",
     "SearchAsYouType",
+    "SemanticText",
     "Shape",
     "Short",
     "SparseVector",
@@ -189,9 +214,12 @@ __all__ = [
     "Text",
     "TokenCount",
     "UnknownDslObject",
+    "UnsignedLong",
     "UpdateByQuery",
     "UpdateByQueryResponse",
     "ValidationException",
+    "Version",
+    "Wildcard",
     "analyzer",
     "async_connections",
     "char_filter",

elasticsearch/dsl/_async/document.py

@@ -126,9 +126,10 @@ class AsyncDocument(DocumentBase, metaclass=AsyncIndexMeta):
         Create an :class:`~elasticsearch.dsl.Search` instance that will search
         over this ``Document``.
         """
-        return AsyncSearch(
+        s = AsyncSearch[Self](
             using=cls._get_using(using), index=cls._default_index(index), doc_type=[cls]
         )
+        return s.source(exclude_vectors=False)
 
     @classmethod
     async def get(

elasticsearch/dsl/_sync/document.py

@@ -120,9 +120,10 @@ class Document(DocumentBase, metaclass=IndexMeta):
         Create an :class:`~elasticsearch.dsl.Search` instance that will search
         over this ``Document``.
         """
-        return Search(
+        s = Search[Self](
             using=cls._get_using(using), index=cls._default_index(index), doc_type=[cls]
         )
+        return s.source(exclude_vectors=False)
 
     @classmethod
     def get(

elasticsearch/dsl/aggs.py

@@ -653,6 +653,54 @@ class Cardinality(Agg[_R]):
         )
 
 
+class CartesianBounds(Agg[_R]):
+    """
+    A metric aggregation that computes the spatial bounding box containing
+    all values for a Point or Shape field.
+
+    :arg field: The field on which to run the aggregation.
+    :arg missing: The value to apply to documents that do not have a
+        value. By default, documents without a value are ignored.
+    :arg script:
+    """
+
+    name = "cartesian_bounds"
+
+    def __init__(
+        self,
+        *,
+        field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT,
+        missing: Union[str, int, float, bool, "DefaultType"] = DEFAULT,
+        script: Union["types.Script", Dict[str, Any], "DefaultType"] = DEFAULT,
+        **kwargs: Any,
+    ):
+        super().__init__(field=field, missing=missing, script=script, **kwargs)
+
+
+class CartesianCentroid(Agg[_R]):
+    """
+    A metric aggregation that computes the weighted centroid from all
+    coordinate values for point and shape fields.
+
+    :arg field: The field on which to run the aggregation.
+    :arg missing: The value to apply to documents that do not have a
+        value. By default, documents without a value are ignored.
+    :arg script:
+    """
+
+    name = "cartesian_centroid"
+
+    def __init__(
+        self,
+        *,
+        field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT,
+        missing: Union[str, int, float, bool, "DefaultType"] = DEFAULT,
+        script: Union["types.Script", Dict[str, Any], "DefaultType"] = DEFAULT,
+        **kwargs: Any,
+    ):
+        super().__init__(field=field, missing=missing, script=script, **kwargs)
+
+
 class CategorizeText(Bucket[_R]):
     """
     A multi-bucket aggregation that groups semi-structured text into
@@ -735,6 +783,43 @@ class CategorizeText(Bucket[_R]):
         )
 
 
+class ChangePoint(Pipeline[_R]):
+    """
+    A sibling pipeline that detects, spikes, dips, and change points in a
+    metric. Given a distribution of values provided by the sibling multi-
+    bucket aggregation, this aggregation indicates the bucket of any spike
+    or dip and/or the bucket at which the largest change in the
+    distribution of values, if they are statistically significant. There
+    must be at least 22 bucketed values. Fewer than 1,000 is preferred.
+
+    :arg format: `DecimalFormat` pattern for the output value. If
+        specified, the formatted value is returned in the aggregation’s
+        `value_as_string` property.
+    :arg gap_policy: Policy to apply when gaps are found in the data.
+        Defaults to `skip` if omitted.
+    :arg buckets_path: Path to the buckets that contain one set of values
+        to correlate.
+    """
+
+    name = "change_point"
+
+    def __init__(
+        self,
+        *,
+        format: Union[str, "DefaultType"] = DEFAULT,
+        gap_policy: Union[
+            Literal["skip", "insert_zeros", "keep_values"], "DefaultType"
+        ] = DEFAULT,
+        buckets_path: Union[
+            str, Sequence[str], Mapping[str, str], "DefaultType"
+        ] = DEFAULT,
+        **kwargs: Any,
+    ):
+        super().__init__(
+            format=format, gap_policy=gap_policy, buckets_path=buckets_path, **kwargs
+        )
+
+
 class Children(Bucket[_R]):
     """
     A single bucket aggregation that selects child documents that have the
@@ -2980,6 +3065,14 @@ class SignificantTerms(Bucket[_R]):
         the foreground sample with a term divided by the number of
         documents in the background with the term.
     :arg script_heuristic: Customized score, implemented via a script.
+    :arg p_value: Significant terms heuristic that calculates the p-value
+        between the term existing in foreground and background sets.  The
+        p-value is the probability of obtaining test results at least as
+        extreme as the results actually observed, under the assumption
+        that the null hypothesis is correct. The p-value is calculated
+        assuming that the foreground set and the background set are
+        independent https://en.wikipedia.org/wiki/Bernoulli_trial, with
+        the null hypothesis that the probabilities are the same.
     :arg shard_min_doc_count: Regulates the certainty a shard has if the
         term should actually be added to the candidate list or not with
         respect to the `min_doc_count`. Terms will only be considered if
@@ -3033,6 +3126,9 @@ class SignificantTerms(Bucket[_R]):
         script_heuristic: Union[
             "types.ScriptedHeuristic", Dict[str, Any], "DefaultType"
         ] = DEFAULT,
+        p_value: Union[
+            "types.PValueHeuristic", Dict[str, Any], "DefaultType"
+        ] = DEFAULT,
         shard_min_doc_count: Union[int, "DefaultType"] = DEFAULT,
         shard_size: Union[int, "DefaultType"] = DEFAULT,
         size: Union[int, "DefaultType"] = DEFAULT,
@@ -3051,6 +3147,7 @@ class SignificantTerms(Bucket[_R]):
             mutual_information=mutual_information,
             percentage=percentage,
             script_heuristic=script_heuristic,
+            p_value=p_value,
             shard_min_doc_count=shard_min_doc_count,
             shard_size=shard_size,
             size=size,

elasticsearch/dsl/document_base.py

@@ -34,6 +34,13 @@ from typing import (
     overload,
 )
 
+from typing_extensions import _AnnotatedAlias
+
+try:
+    import annotationlib
+except ImportError:
+    annotationlib = None
+
 try:
     from types import UnionType
 except ImportError:
@@ -332,6 +339,16 @@ class DocumentOptions:
         #     # ignore attributes
         #     field10: ClassVar[string] = "a regular class variable"
         annotations = attrs.get("__annotations__", {})
+        if not annotations and annotationlib:
+            # Python 3.14+ uses annotationlib
+            annotate = annotationlib.get_annotate_from_class_namespace(attrs)
+            if annotate:
+                annotations = (
+                    annotationlib.call_annotate_function(
+                        annotate, format=annotationlib.Format.VALUE
+                    )
+                    or {}
+                )
         fields = {n for n in attrs if isinstance(attrs[n], Field)}
         fields.update(annotations.keys())
         field_defaults = {}
@@ -343,6 +360,10 @@ class DocumentOptions:
                 # the field has a type annotation, so next we try to figure out
                 # what field type we can use
                 type_ = annotations[name]
+                type_metadata = []
+                if isinstance(type_, _AnnotatedAlias):
+                    type_metadata = type_.__metadata__
+                    type_ = type_.__origin__
                 skip = False
                 required = True
                 multi = False
@@ -389,6 +410,12 @@ class DocumentOptions:
                     # use best field type for the type hint provided
                     field, field_kwargs = self.type_annotation_map[type_]  # type: ignore[assignment]
 
+                # if this field does not have a right-hand value, we look in the metadata
+                # of the annotation to see if we find it there
+                for md in type_metadata:
+                    if isinstance(md, (_FieldMetadataDict, Field)):
+                        attrs[name] = md
+
                 if field:
                     field_kwargs = {
                         "multi": multi,
@@ -401,17 +428,20 @@ class DocumentOptions:
                 # this field has a right-side value, which can be field
                 # instance on its own or wrapped with mapped_field()
                 attr_value = attrs[name]
-                if isinstance(attr_value, dict):
+                if isinstance(attr_value, _FieldMetadataDict):
                     # the mapped_field() wrapper function was used so we need
                     # to look for the field instance and also record any
                     # dataclass-style defaults
+                    if attr_value.get("exclude"):
+                        # skip this field
+                        continue
                     attr_value = attrs[name].get("_field")
                     default_value = attrs[name].get("default") or attrs[name].get(
                         "default_factory"
                     )
                     if default_value:
                         field_defaults[name] = default_value
-                if attr_value:
+                if isinstance(attr_value, Field):
                     value = attr_value
                     if required is not None:
                         value._required = required
@@ -490,12 +520,19 @@ class Mapped(Generic[_FieldType]):
 M = Mapped
 
 
+class _FieldMetadataDict(dict[str, Any]):
+    """This class is used to identify metadata returned by the `mapped_field()` function."""
+
+    pass
+
+
 def mapped_field(
     field: Optional[Field] = None,
     *,
     init: bool = True,
     default: Any = None,
     default_factory: Optional[Callable[[], Any]] = None,
+    exclude: bool = False,
     **kwargs: Any,
 ) -> Any:
     """Construct a field using dataclass behaviors
@@ -505,22 +542,25 @@ def mapped_field(
     options.
 
     :param field: The instance of ``Field`` to use for this field. If not provided,
-    an instance that is appropriate for the type given to the field is used.
+        an instance that is appropriate for the type given to the field is used.
     :param init: a value of ``True`` adds this field to the constructor, and a
-    value of ``False`` omits it from it. The default is ``True``.
+        value of ``False`` omits it from it. The default is ``True``.
     :param default: a default value to use for this field when one is not provided
-    explicitly.
+        explicitly.
     :param default_factory: a callable that returns a default value for the field,
-    when one isn't provided explicitly. Only one of ``factory`` and
-    ``default_factory`` can be used.
+        when one isn't provided explicitly. Only one of ``factory`` and
+        ``default_factory`` can be used.
+    :param exclude: Set to ``True`` to exclude this field from the Elasticsearch
+        index.
     """
-    return {
-        "_field": field,
-        "init": init,
-        "default": default,
-        "default_factory": default_factory,
+    return _FieldMetadataDict(
+        _field=field,
+        init=init,
+        default=default,
+        default_factory=default_factory,
+        exclude=exclude,
         **kwargs,
-    }
+    )
 
 
 @dataclass_transform(field_specifiers=(mapped_field,))

elasticsearch/dsl/field.py

@@ -572,7 +572,11 @@ class Object(Field):
         if isinstance(data, collections.abc.Mapping):
             return data
 
-        return data.to_dict(skip_empty=skip_empty)
+        try:
+            return data.to_dict(skip_empty=skip_empty)
+        except TypeError:
+            # this would only happen if an AttrDict was given instead of an InnerDoc
+            return data.to_dict()
 
     def clean(self, data: Any) -> Any:
         data = super().clean(data)
@@ -3862,14 +3866,21 @@ 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 index_options: Settings for index_options that override any
+        defaults used by semantic_text, for example specific quantization
+        settings.
     :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.
+    :arg fields:
     """
 
     name = "semantic_text"
+    _param_defs = {
+        "fields": {"type": "field", "hash": True},
+    }
 
     def __init__(
         self,
@@ -3877,9 +3888,13 @@ class SemanticText(Field):
         meta: Union[Mapping[str, str], "DefaultType"] = DEFAULT,
         inference_id: Union[str, "DefaultType"] = DEFAULT,
         search_inference_id: Union[str, "DefaultType"] = DEFAULT,
+        index_options: Union[
+            "types.SemanticTextIndexOptions", Dict[str, Any], "DefaultType"
+        ] = DEFAULT,
         chunking_settings: Union[
-            "types.ChunkingSettings", Dict[str, Any], "DefaultType"
+            "types.ChunkingSettings", None, Dict[str, Any], "DefaultType"
         ] = DEFAULT,
+        fields: Union[Mapping[str, Field], "DefaultType"] = DEFAULT,
         **kwargs: Any,
     ):
         if meta is not DEFAULT:
@@ -3888,8 +3903,12 @@ class SemanticText(Field):
             kwargs["inference_id"] = inference_id
         if search_inference_id is not DEFAULT:
             kwargs["search_inference_id"] = search_inference_id
+        if index_options is not DEFAULT:
+            kwargs["index_options"] = index_options
         if chunking_settings is not DEFAULT:
             kwargs["chunking_settings"] = chunking_settings
+        if fields is not DEFAULT:
+            kwargs["fields"] = fields
         super().__init__(*args, **kwargs)
 
 

elasticsearch/dsl/pydantic.py

@@ -0,0 +1,152 @@
+#  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 Any, ClassVar, Dict, List, Optional, Tuple, Type
+
+from pydantic import BaseModel, Field, PrivateAttr
+from typing_extensions import Annotated, Self, dataclass_transform
+
+from elasticsearch import dsl
+
+
+class ESMeta(BaseModel):
+    """Metadata items associated with Elasticsearch documents."""
+
+    id: str = ""
+    index: str = ""
+    primary_term: int = 0
+    seq_no: int = 0
+    version: int = 0
+    score: float = 0
+
+
+class _BaseModel(BaseModel):
+    meta: Annotated[ESMeta, dsl.mapped_field(exclude=True)] = Field(
+        default=ESMeta(),
+        init=False,
+    )
+
+
+class _BaseESModelMetaclass(type(BaseModel)):  # type: ignore[misc]
+    """Generic metaclass methods for BaseEsModel and AsyncBaseESModel."""
+
+    @staticmethod
+    def process_annotations(
+        metacls: Type["_BaseESModelMetaclass"], annotations: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Process Pydantic typing annotations and adapt them so that they can
+        be used to create the Elasticsearch document.
+        """
+        updated_annotations = {}
+        for var, ann in annotations.items():
+            if isinstance(ann, type(BaseModel)):
+                # an inner Pydantic model is transformed into an Object field
+                updated_annotations[var] = metacls.make_dsl_class(
+                    metacls, dsl.InnerDoc, ann
+                )
+            elif (
+                hasattr(ann, "__origin__")
+                and ann.__origin__ in [list, List]
+                and isinstance(ann.__args__[0], type(BaseModel))
+            ):
+                # an inner list of Pydantic models is transformed into a Nested field
+                updated_annotations[var] = List[  # type: ignore[assignment,misc]
+                    metacls.make_dsl_class(metacls, dsl.InnerDoc, ann.__args__[0])
+                ]
+            else:
+                updated_annotations[var] = ann
+        return updated_annotations
+
+    @staticmethod
+    def make_dsl_class(
+        metacls: Type["_BaseESModelMetaclass"],
+        dsl_class: type,
+        pydantic_model: type,
+        pydantic_attrs: Optional[Dict[str, Any]] = None,
+    ) -> type:
+        """Create a DSL document class dynamically, using the structure of a
+        Pydantic model."""
+        dsl_attrs = {
+            attr: value
+            for attr, value in dsl_class.__dict__.items()
+            if not attr.startswith("__")
+        }
+        pydantic_attrs = {
+            **(pydantic_attrs or {}),
+            "__annotations__": metacls.process_annotations(
+                metacls, pydantic_model.__annotations__
+            ),
+        }
+        return type(dsl_class)(
+            f"_ES{pydantic_model.__name__}",
+            (dsl_class,),
+            {
+                **pydantic_attrs,
+                **dsl_attrs,
+                "__qualname__": f"_ES{pydantic_model.__name__}",
+            },
+        )
+
+
+class BaseESModelMetaclass(_BaseESModelMetaclass):
+    """Metaclass for the BaseESModel class."""
+
+    def __new__(cls, name: str, bases: Tuple[type, ...], attrs: Dict[str, Any]) -> Any:
+        model = super().__new__(cls, name, bases, attrs)
+        model._doc = cls.make_dsl_class(cls, dsl.Document, model, attrs)
+        return model
+
+
+class AsyncBaseESModelMetaclass(_BaseESModelMetaclass):
+    """Metaclass for the AsyncBaseESModel class."""
+
+    def __new__(cls, name: str, bases: Tuple[type, ...], attrs: Dict[str, Any]) -> Any:
+        model = super().__new__(cls, name, bases, attrs)
+        model._doc = cls.make_dsl_class(cls, dsl.AsyncDocument, model, attrs)
+        return model
+
+
+@dataclass_transform(kw_only_default=True, field_specifiers=(Field, PrivateAttr))
+class BaseESModel(_BaseModel, metaclass=BaseESModelMetaclass):
+    _doc: ClassVar[Type[dsl.Document]]
+
+    def to_doc(self) -> dsl.Document:
+        """Convert this model to an Elasticsearch document."""
+        data = self.model_dump()
+        meta = {f"_{k}": v for k, v in data.pop("meta", {}).items() if v}
+        return self._doc(**meta, **data)
+
+    @classmethod
+    def from_doc(cls, dsl_obj: dsl.Document) -> Self:
+        """Create a model from the given Elasticsearch document."""
+        return cls(meta=ESMeta(**dsl_obj.meta.to_dict()), **dsl_obj.to_dict())
+
+
+@dataclass_transform(kw_only_default=True, field_specifiers=(Field, PrivateAttr))
+class AsyncBaseESModel(_BaseModel, metaclass=AsyncBaseESModelMetaclass):
+    _doc: ClassVar[Type[dsl.AsyncDocument]]
+
+    def to_doc(self) -> dsl.AsyncDocument:
+        """Convert this model to an Elasticsearch document."""
+        data = self.model_dump()
+        meta = {f"_{k}": v for k, v in data.pop("meta", {}).items() if v}
+        return self._doc(**meta, **data)
+
+    @classmethod
+    def from_doc(cls, dsl_obj: dsl.AsyncDocument) -> Self:
+        """Create a model from the given Elasticsearch document."""
+        return cls(meta=ESMeta(**dsl_obj.meta.to_dict()), **dsl_obj.to_dict())