diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 72edf7d8..241b3bdf 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -13,4 +13,5 @@ python: - develop sphinx: + configuration: docs/conf.py fail_on_warning: true diff --git a/README b/README index 234a3a83..f11a8b61 100644 --- a/README +++ b/README @@ -1,6 +1,13 @@ Elasticsearch DSL ================= +> [!NOTE] +> As of release 9.0, Elasticsearch DSL is part of the official Elasticsearch +> client for Python, so a separate install is not needed. To migrate, just +> replace `elasticsearch_dsl` with `elasticsearch.dsl` in all imports. +> +> The following instructions apply to versions 8 and older. + Elasticsearch DSL is a high-level library whose aim is to help with writing and running queries against Elasticsearch. It is built on top of the official low-level client (`elasticsearch-py `_). diff --git a/elasticsearch_dsl/__init__.py b/elasticsearch_dsl/__init__.py index a91e8442..7ad98948 100644 --- a/elasticsearch_dsl/__init__.py +++ b/elasticsearch_dsl/__init__.py @@ -15,192 +15,14 @@ # specific language governing permissions and limitations # under the License. -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 .exceptions import ( - ElasticsearchDslException, - IllegalOperation, - UnknownDslObject, - ValidationException, -) -from .faceted_search import ( - AsyncFacetedSearch, - DateHistogramFacet, - Facet, - FacetedResponse, - FacetedSearch, - HistogramFacet, - NestedFacet, - RangeFacet, - TermsFacet, -) -from .field import ( - Binary, - Boolean, - Byte, - Completion, - ConstantKeyword, - CustomField, - Date, - DateRange, - DenseVector, - Double, - DoubleRange, - Field, - Float, - FloatRange, - GeoPoint, - GeoShape, - HalfFloat, - Integer, - IntegerRange, - Ip, - IpRange, - Join, - Keyword, - Long, - LongRange, - Murmur3, - Nested, - Object, - Percolator, - Point, - RangeField, - RankFeature, - RankFeatures, - ScaledFloat, - SearchAsYouType, - Shape, - Short, - SparseVector, - Text, - TokenCount, - construct_field, -) -from .function import SF -from .index import ( - AsyncComposableIndexTemplate, - AsyncIndex, - AsyncIndexTemplate, - ComposableIndexTemplate, - Index, - IndexTemplate, -) -from .mapping import AsyncMapping, Mapping -from .query import Q, Query -from .response import AggResponse, Response, UpdateByQueryResponse -from .search import ( - AsyncEmptySearch, - AsyncMultiSearch, - AsyncSearch, - EmptySearch, - MultiSearch, - Search, -) -from .update_by_query import AsyncUpdateByQuery, UpdateByQuery -from .utils import AttrDict, AttrList, DslBase -from .wrappers import Range +import sys -VERSION = (8, 17, 1) -__version__ = VERSION -__versionstr__ = ".".join(map(str, VERSION)) -__all__ = [ - "A", - "Agg", - "AggResponse", - "AsyncComposableIndexTemplate", - "AsyncDocument", - "AsyncEmptySearch", - "AsyncFacetedSearch", - "AsyncIndex", - "AsyncIndexTemplate", - "AsyncMapping", - "AsyncMultiSearch", - "AsyncSearch", - "AsyncUpdateByQuery", - "AttrDict", - "AttrList", - "Binary", - "Boolean", - "Byte", - "Completion", - "ComposableIndexTemplate", - "ConstantKeyword", - "CustomField", - "Date", - "DateHistogramFacet", - "DateRange", - "DenseVector", - "Document", - "Double", - "DoubleRange", - "DslBase", - "ElasticsearchDslException", - "EmptySearch", - "Facet", - "FacetedResponse", - "FacetedSearch", - "Field", - "Float", - "FloatRange", - "GeoPoint", - "GeoShape", - "HalfFloat", - "HistogramFacet", - "IllegalOperation", - "Index", - "IndexTemplate", - "InnerDoc", - "Integer", - "IntegerRange", - "Ip", - "IpRange", - "Join", - "Keyword", - "Long", - "LongRange", - "M", - "Mapping", - "MetaField", - "MultiSearch", - "Murmur3", - "Nested", - "NestedFacet", - "Object", - "Percolator", - "Point", - "Q", - "Query", - "Range", - "RangeFacet", - "RangeField", - "RankFeature", - "RankFeatures", - "Response", - "SF", - "ScaledFloat", - "Search", - "SearchAsYouType", - "Shape", - "Short", - "SparseVector", - "TermsFacet", - "Text", - "TokenCount", - "UnknownDslObject", - "UpdateByQuery", - "UpdateByQueryResponse", - "ValidationException", - "analyzer", - "async_connections", - "char_filter", - "connections", - "construct_field", - "mapped_field", - "normalizer", - "token_filter", - "tokenizer", -] +from elasticsearch import __version__, dsl # noqa: F401 + +modules = [mod for mod in sys.modules.keys() if mod.startswith("elasticsearch.dsl")] +for mod in modules: + sys.modules[mod.replace("elasticsearch.dsl", "elasticsearch_dsl")] = sys.modules[ + mod + ] +sys.modules["elasticsearch_dsl"].VERSION = __version__ +sys.modules["elasticsearch_dsl"].__versionstr__ = ".".join(map(str, __version__)) diff --git a/elasticsearch_dsl/_async/__init__.py b/elasticsearch_dsl/_async/__init__.py deleted file mode 100644 index 2a87d183..00000000 --- a/elasticsearch_dsl/_async/__init__.py +++ /dev/null @@ -1,16 +0,0 @@ -# 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. diff --git a/elasticsearch_dsl/_async/document.py b/elasticsearch_dsl/_async/document.py deleted file mode 100644 index 1ff68a79..00000000 --- a/elasticsearch_dsl/_async/document.py +++ /dev/null @@ -1,521 +0,0 @@ -# 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 collections.abc -from typing import ( - TYPE_CHECKING, - Any, - AsyncIterable, - Dict, - List, - Optional, - Tuple, - Union, - cast, -) - -from elasticsearch.exceptions import NotFoundError, RequestError -from elasticsearch.helpers import async_bulk -from typing_extensions import Self, dataclass_transform - -from .._async.index import AsyncIndex -from ..async_connections import get_connection -from ..document_base import DocumentBase, DocumentMeta, mapped_field -from ..exceptions import IllegalOperation -from ..utils import DOC_META_FIELDS, META_FIELDS, AsyncUsingType, merge -from .search import AsyncSearch - -if TYPE_CHECKING: - from elasticsearch import AsyncElasticsearch - - -class AsyncIndexMeta(DocumentMeta): - _index: AsyncIndex - - # global flag to guard us from associating an Index with the base Document - # class, only user defined subclasses should have an _index attr - _document_initialized = False - - def __new__( - cls, name: str, bases: Tuple[type, ...], attrs: Dict[str, Any] - ) -> "AsyncIndexMeta": - new_cls = super().__new__(cls, name, bases, attrs) - if cls._document_initialized: - index_opts = attrs.pop("Index", None) - index = cls.construct_index(index_opts, bases) - new_cls._index = index - index.document(new_cls) - cls._document_initialized = True - return cast(AsyncIndexMeta, new_cls) - - @classmethod - def construct_index( - cls, opts: Dict[str, Any], bases: Tuple[type, ...] - ) -> AsyncIndex: - if opts is None: - for b in bases: - if hasattr(b, "_index"): - return b._index - - # Set None as Index name so it will set _all while making the query - return AsyncIndex(name=None) - - i = AsyncIndex( - getattr(opts, "name", "*"), using=getattr(opts, "using", "default") - ) - i.settings(**getattr(opts, "settings", {})) - i.aliases(**getattr(opts, "aliases", {})) - for a in getattr(opts, "analyzers", ()): - i.analyzer(a) - return i - - -@dataclass_transform(field_specifiers=(mapped_field,)) -class AsyncDocument(DocumentBase, metaclass=AsyncIndexMeta): - """ - Model-like class for persisting documents in elasticsearch. - """ - - if TYPE_CHECKING: - _index: AsyncIndex - - @classmethod - def _get_using(cls, using: Optional[AsyncUsingType] = None) -> AsyncUsingType: - return cast(AsyncUsingType, using or cls._index._using) - - @classmethod - def _get_connection( - cls, using: Optional[AsyncUsingType] = None - ) -> "AsyncElasticsearch": - return get_connection(cls._get_using(using)) - - @classmethod - async def init( - cls, index: Optional[str] = None, using: Optional[AsyncUsingType] = None - ) -> None: - """ - Create the index and populate the mappings in elasticsearch. - """ - i = cls._index - if index: - i = i.clone(name=index) - await i.save(using=using) - - @classmethod - def search( - cls, using: Optional[AsyncUsingType] = None, index: Optional[str] = None - ) -> AsyncSearch[Self]: - """ - Create an :class:`~elasticsearch_dsl.Search` instance that will search - over this ``Document``. - """ - return AsyncSearch( - using=cls._get_using(using), index=cls._default_index(index), doc_type=[cls] - ) - - @classmethod - async def get( - cls, - id: str, - using: Optional[AsyncUsingType] = None, - index: Optional[str] = None, - **kwargs: Any, - ) -> Optional[Self]: - """ - Retrieve a single document from elasticsearch using its ``id``. - - :arg id: ``id`` of the document to be retrieved - :arg index: elasticsearch index to use, if the ``Document`` is - associated with an index this can be omitted. - :arg using: connection alias to use, defaults to ``'default'`` - - Any additional keyword arguments will be passed to - ``Elasticsearch.get`` unchanged. - """ - es = cls._get_connection(using) - doc = await es.get(index=cls._default_index(index), id=id, **kwargs) - if not doc.get("found", False): - return None - return cls.from_es(doc) - - @classmethod - async def exists( - cls, - id: str, - using: Optional[AsyncUsingType] = None, - index: Optional[str] = None, - **kwargs: Any, - ) -> bool: - """ - check if exists a single document from elasticsearch using its ``id``. - - :arg id: ``id`` of the document to check if exists - :arg index: elasticsearch index to use, if the ``Document`` is - associated with an index this can be omitted. - :arg using: connection alias to use, defaults to ``'default'`` - - Any additional keyword arguments will be passed to - ``Elasticsearch.exists`` unchanged. - """ - es = cls._get_connection(using) - return bool(await es.exists(index=cls._default_index(index), id=id, **kwargs)) - - @classmethod - async def mget( - cls, - docs: List[Dict[str, Any]], - using: Optional[AsyncUsingType] = None, - index: Optional[str] = None, - raise_on_error: bool = True, - missing: str = "none", - **kwargs: Any, - ) -> List[Optional[Self]]: - r""" - Retrieve multiple document by their ``id``\s. Returns a list of instances - in the same order as requested. - - :arg docs: list of ``id``\s of the documents to be retrieved or a list - of document specifications as per - https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-multi-get.html - :arg index: elasticsearch index to use, if the ``Document`` is - associated with an index this can be omitted. - :arg using: connection alias to use, defaults to ``'default'`` - :arg missing: what to do when one of the documents requested is not - found. Valid options are ``'none'`` (use ``None``), ``'raise'`` (raise - ``NotFoundError``) or ``'skip'`` (ignore the missing document). - - Any additional keyword arguments will be passed to - ``Elasticsearch.mget`` unchanged. - """ - if missing not in ("raise", "skip", "none"): - raise ValueError("'missing' must be 'raise', 'skip', or 'none'.") - es = cls._get_connection(using) - body = { - "docs": [ - doc if isinstance(doc, collections.abc.Mapping) else {"_id": doc} - for doc in docs - ] - } - results = await es.mget(index=cls._default_index(index), body=body, **kwargs) - - objs: List[Optional[Self]] = [] - error_docs: List[Self] = [] - missing_docs: List[Self] = [] - for doc in results["docs"]: - if doc.get("found"): - if error_docs or missing_docs: - # We're going to raise an exception anyway, so avoid an - # expensive call to cls.from_es(). - continue - - objs.append(cls.from_es(doc)) - - elif doc.get("error"): - if raise_on_error: - error_docs.append(doc) - if missing == "none": - objs.append(None) - - # The doc didn't cause an error, but the doc also wasn't found. - elif missing == "raise": - missing_docs.append(doc) - elif missing == "none": - objs.append(None) - - if error_docs: - error_ids = [doc["_id"] for doc in error_docs] - message = "Required routing not provided for documents %s." - message %= ", ".join(error_ids) - raise RequestError(400, message, error_docs) # type: ignore - if missing_docs: - missing_ids = [doc["_id"] for doc in missing_docs] - message = f"Documents {', '.join(missing_ids)} not found." - raise NotFoundError(404, message, {"docs": missing_docs}) # type: ignore - return objs - - async def delete( - self, - using: Optional[AsyncUsingType] = None, - index: Optional[str] = None, - **kwargs: Any, - ) -> None: - """ - Delete the instance in elasticsearch. - - :arg index: elasticsearch index to use, if the ``Document`` is - associated with an index this can be omitted. - :arg using: connection alias to use, defaults to ``'default'`` - - Any additional keyword arguments will be passed to - ``Elasticsearch.delete`` unchanged. - """ - es = self._get_connection(using) - # extract routing etc from meta - doc_meta = {k: self.meta[k] for k in DOC_META_FIELDS if k in self.meta} - - # Optimistic concurrency control - if "seq_no" in self.meta and "primary_term" in self.meta: - doc_meta["if_seq_no"] = self.meta["seq_no"] - doc_meta["if_primary_term"] = self.meta["primary_term"] - - doc_meta.update(kwargs) - i = self._get_index(index) - assert i is not None - - await es.delete(index=i, **doc_meta) - - async def update( - self, - using: Optional[AsyncUsingType] = None, - index: Optional[str] = None, - detect_noop: bool = True, - doc_as_upsert: bool = False, - refresh: bool = False, - retry_on_conflict: Optional[int] = None, - script: Optional[Union[str, Dict[str, Any]]] = None, - script_id: Optional[str] = None, - scripted_upsert: bool = False, - upsert: Optional[Dict[str, Any]] = None, - return_doc_meta: bool = False, - **fields: Any, - ) -> Any: - """ - Partial update of the document, specify fields you wish to update and - both the instance and the document in elasticsearch will be updated:: - - doc = MyDocument(title='Document Title!') - doc.save() - doc.update(title='New Document Title!') - - :arg index: elasticsearch index to use, if the ``Document`` is - associated with an index this can be omitted. - :arg using: connection alias to use, defaults to ``'default'`` - :arg detect_noop: Set to ``False`` to disable noop detection. - :arg refresh: Control when the changes made by this request are visible - to search. Set to ``True`` for immediate effect. - :arg retry_on_conflict: In between the get and indexing phases of the - update, it is possible that another process might have already - updated the same document. By default, the update will fail with a - version conflict exception. The retry_on_conflict parameter - controls how many times to retry the update before finally throwing - an exception. - :arg doc_as_upsert: Instead of sending a partial doc plus an upsert - doc, setting doc_as_upsert to true will use the contents of doc as - the upsert value - :arg script: the source code of the script as a string, or a dictionary - with script attributes to update. - :arg return_doc_meta: set to ``True`` to return all metadata from the - index API call instead of only the operation result - - :return: operation result noop/updated - """ - body: Dict[str, Any] = { - "doc_as_upsert": doc_as_upsert, - "detect_noop": detect_noop, - } - - # scripted update - if script or script_id: - if upsert is not None: - body["upsert"] = upsert - - if script: - if isinstance(script, str): - script = {"source": script} - else: - script = {"id": script_id} - - if "params" not in script: - script["params"] = fields - else: - script["params"].update(fields) - - body["script"] = script - body["scripted_upsert"] = scripted_upsert - - # partial document update - else: - if not fields: - raise IllegalOperation( - "You cannot call update() without updating individual fields or a script. " - "If you wish to update the entire object use save()." - ) - - # update given fields locally - merge(self, fields) - - # prepare data for ES - values = self.to_dict(skip_empty=False) - - # if fields were given: partial update - body["doc"] = {k: values.get(k) for k in fields.keys()} - - # extract routing etc from meta - doc_meta = {k: self.meta[k] for k in DOC_META_FIELDS if k in self.meta} - - if retry_on_conflict is not None: - doc_meta["retry_on_conflict"] = retry_on_conflict - - # Optimistic concurrency control - if ( - retry_on_conflict in (None, 0) - and "seq_no" in self.meta - and "primary_term" in self.meta - ): - doc_meta["if_seq_no"] = self.meta["seq_no"] - doc_meta["if_primary_term"] = self.meta["primary_term"] - - i = self._get_index(index) - assert i is not None - - meta = await self._get_connection(using).update( - index=i, body=body, refresh=refresh, **doc_meta - ) - - # update meta information from ES - for k in META_FIELDS: - if "_" + k in meta: - setattr(self.meta, k, meta["_" + k]) - - return meta if return_doc_meta else meta["result"] - - async def save( - self, - using: Optional[AsyncUsingType] = None, - index: Optional[str] = None, - validate: bool = True, - skip_empty: bool = True, - return_doc_meta: bool = False, - **kwargs: Any, - ) -> Any: - """ - Save the document into elasticsearch. If the document doesn't exist it - is created, it is overwritten otherwise. Returns ``True`` if this - operations resulted in new document being created. - - :arg index: elasticsearch index to use, if the ``Document`` is - associated with an index this can be omitted. - :arg using: connection alias to use, defaults to ``'default'`` - :arg validate: set to ``False`` to skip validating the document - :arg skip_empty: if set to ``False`` will cause empty values (``None``, - ``[]``, ``{}``) to be left on the document. Those values will be - stripped out otherwise as they make no difference in elasticsearch. - :arg return_doc_meta: set to ``True`` to return all metadata from the - update API call instead of only the operation result - - Any additional keyword arguments will be passed to - ``Elasticsearch.index`` unchanged. - - :return: operation result created/updated - """ - if validate: - self.full_clean() - - es = self._get_connection(using) - # extract routing etc from meta - doc_meta = {k: self.meta[k] for k in DOC_META_FIELDS if k in self.meta} - - # Optimistic concurrency control - if "seq_no" in self.meta and "primary_term" in self.meta: - doc_meta["if_seq_no"] = self.meta["seq_no"] - doc_meta["if_primary_term"] = self.meta["primary_term"] - - doc_meta.update(kwargs) - i = self._get_index(index) - assert i is not None - - meta = await es.index( - index=i, - body=self.to_dict(skip_empty=skip_empty), - **doc_meta, - ) - # update meta information from ES - for k in META_FIELDS: - if "_" + k in meta: - setattr(self.meta, k, meta["_" + k]) - - return meta if return_doc_meta else meta["result"] - - @classmethod - async def bulk( - cls, - actions: AsyncIterable[Union[Self, Dict[str, Any]]], - using: Optional[AsyncUsingType] = None, - index: Optional[str] = None, - validate: bool = True, - skip_empty: bool = True, - **kwargs: Any, - ) -> Tuple[int, Union[int, List[Any]]]: - """ - Allows to perform multiple indexing operations in a single request. - - :arg actions: a generator that returns document instances to be indexed, - bulk operation dictionaries. - :arg using: connection alias to use, defaults to ``'default'`` - :arg index: Elasticsearch index to use, if the ``Document`` is - associated with an index this can be omitted. - :arg validate: set to ``False`` to skip validating the documents - :arg skip_empty: if set to ``False`` will cause empty values (``None``, - ``[]``, ``{}``) to be left on the document. Those values will be - stripped out otherwise as they make no difference in Elasticsearch. - - Any additional keyword arguments will be passed to - ``Elasticsearch.bulk`` unchanged. - - :return: bulk operation results - """ - es = cls._get_connection(using) - - i = cls._default_index(index) - assert i is not None - - class Generate: - def __init__( - self, - doc_iterator: AsyncIterable[Union[AsyncDocument, Dict[str, Any]]], - ): - self.doc_iterator = doc_iterator.__aiter__() - - def __aiter__(self) -> Self: - return self - - async def __anext__(self) -> Dict[str, Any]: - doc: Optional[Union[AsyncDocument, Dict[str, Any]]] = ( - await self.doc_iterator.__anext__() - ) - - if isinstance(doc, dict): - action = doc - doc = None - if "_source" in action and isinstance( - action["_source"], AsyncDocument - ): - doc = action["_source"] - if validate: # pragma: no cover - doc.full_clean() - action["_source"] = doc.to_dict( - include_meta=False, skip_empty=skip_empty - ) - elif doc is not None: - if validate: # pragma: no cover - doc.full_clean() - action = doc.to_dict(include_meta=True, skip_empty=skip_empty) - if "_index" not in action: - action["_index"] = i - return action - - return await async_bulk(es, Generate(actions), **kwargs) diff --git a/elasticsearch_dsl/_async/faceted_search.py b/elasticsearch_dsl/_async/faceted_search.py deleted file mode 100644 index ee80f0c2..00000000 --- a/elasticsearch_dsl/_async/faceted_search.py +++ /dev/null @@ -1,51 +0,0 @@ -# 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 elasticsearch_dsl.faceted_search_base import FacetedResponse, FacetedSearchBase - -from ..utils import _R -from .search import AsyncSearch - -if TYPE_CHECKING: - from ..response import Response - - -class AsyncFacetedSearch(FacetedSearchBase[_R]): - _s: AsyncSearch[_R] - - async def count(self) -> int: - return await self._s.count() - - def search(self) -> AsyncSearch[_R]: - """ - Returns the base Search object to which the facets are added. - - You can customize the query by overriding this method and returning a - modified search object. - """ - s = AsyncSearch[_R](doc_type=self.doc_types, index=self.index, using=self.using) - return s.response_class(FacetedResponse) - - async def execute(self) -> "Response[_R]": - """ - Execute the search and return the response. - """ - r = await self._s.execute() - r._faceted_search = self - return r diff --git a/elasticsearch_dsl/_async/index.py b/elasticsearch_dsl/_async/index.py deleted file mode 100644 index 22da1b14..00000000 --- a/elasticsearch_dsl/_async/index.py +++ /dev/null @@ -1,638 +0,0 @@ -# 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, Any, Dict, Optional - -from typing_extensions import Self - -from ..async_connections import get_connection -from ..exceptions import IllegalOperation -from ..index_base import IndexBase -from ..utils import AsyncUsingType -from .mapping import AsyncMapping -from .search import AsyncSearch -from .update_by_query import AsyncUpdateByQuery - -if TYPE_CHECKING: - from elastic_transport import ObjectApiResponse - from elasticsearch import AsyncElasticsearch - - -class AsyncIndexTemplate: - def __init__( - self, - name: str, - template: str, - index: Optional["AsyncIndex"] = None, - order: Optional[int] = None, - **kwargs: Any, - ): - if index is None: - self._index = AsyncIndex(template, **kwargs) - else: - if kwargs: - raise ValueError( - "You cannot specify options for Index when" - " passing an Index instance." - ) - self._index = index.clone() - self._index._name = template - self._template_name = name - self.order = order - - def __getattr__(self, attr_name: str) -> Any: - return getattr(self._index, attr_name) - - def to_dict(self) -> Dict[str, Any]: - d = self._index.to_dict() - d["index_patterns"] = [self._index._name] - if self.order is not None: - d["order"] = self.order - return d - - async def save( - self, using: Optional[AsyncUsingType] = None - ) -> "ObjectApiResponse[Any]": - es = get_connection(using or self._index._using) - return await es.indices.put_template( - name=self._template_name, body=self.to_dict() - ) - - -class AsyncComposableIndexTemplate: - def __init__( - self, - name: str, - template: str, - index: Optional["AsyncIndex"] = None, - priority: Optional[int] = None, - **kwargs: Any, - ): - if index is None: - self._index = AsyncIndex(template, **kwargs) - else: - if kwargs: - raise ValueError( - "You cannot specify options for Index when" - " passing an Index instance." - ) - self._index = index.clone() - self._index._name = template - self._template_name = name - self.priority = priority - - def __getattr__(self, attr_name: str) -> Any: - return getattr(self._index, attr_name) - - def to_dict(self) -> Dict[str, Any]: - d: Dict[str, Any] = {"template": self._index.to_dict()} - d["index_patterns"] = [self._index._name] - if self.priority is not None: - d["priority"] = self.priority - return d - - async def save( - self, using: Optional[AsyncUsingType] = None - ) -> "ObjectApiResponse[Any]": - es = get_connection(using or self._index._using) - return await es.indices.put_index_template( - name=self._template_name, **self.to_dict() - ) - - -class AsyncIndex(IndexBase): - _using: AsyncUsingType - - if TYPE_CHECKING: - - def get_or_create_mapping(self) -> AsyncMapping: ... - - def __init__(self, name: str, using: AsyncUsingType = "default"): - """ - :arg name: name of the index - :arg using: connection alias to use, defaults to ``'default'`` - """ - super().__init__(name, AsyncMapping, using=using) - - def _get_connection( - self, using: Optional[AsyncUsingType] = None - ) -> "AsyncElasticsearch": - if self._name is None: - raise ValueError("You cannot perform API calls on the default index.") - return get_connection(using or self._using) - - connection = property(_get_connection) - - def as_template( - self, - template_name: str, - pattern: Optional[str] = None, - order: Optional[int] = None, - ) -> AsyncIndexTemplate: - return AsyncIndexTemplate( - template_name, pattern or self._name, index=self, order=order - ) - - def as_composable_template( - self, - template_name: str, - pattern: Optional[str] = None, - priority: Optional[int] = None, - ) -> AsyncComposableIndexTemplate: - return AsyncComposableIndexTemplate( - template_name, pattern or self._name, index=self, priority=priority - ) - - async def load_mappings(self, using: Optional[AsyncUsingType] = None) -> None: - await self.get_or_create_mapping().update_from_es( - self._name, using=using or self._using - ) - - def clone( - self, name: Optional[str] = None, using: Optional[AsyncUsingType] = None - ) -> Self: - """ - Create a copy of the instance with another name or connection alias. - Useful for creating multiple indices with shared configuration:: - - i = Index('base-index') - i.settings(number_of_shards=1) - i.create() - - i2 = i.clone('other-index') - i2.create() - - :arg name: name of the index - :arg using: connection alias to use, defaults to ``'default'`` - """ - i = self.__class__(name or self._name, using=using or self._using) - i._settings = self._settings.copy() - i._aliases = self._aliases.copy() - i._analysis = self._analysis.copy() - i._doc_types = self._doc_types[:] - if self._mapping is not None: - i._mapping = self._mapping._clone() - return i - - def search(self, using: Optional[AsyncUsingType] = None) -> AsyncSearch: - """ - Return a :class:`~elasticsearch_dsl.Search` object searching over the - index (or all the indices belonging to this template) and its - ``Document``\\s. - """ - return AsyncSearch( - using=using or self._using, index=self._name, doc_type=self._doc_types - ) - - def updateByQuery( - self, using: Optional[AsyncUsingType] = None - ) -> AsyncUpdateByQuery: - """ - Return a :class:`~elasticsearch_dsl.UpdateByQuery` object searching over the index - (or all the indices belonging to this template) and updating Documents that match - the search criteria. - - For more information, see here: - https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-update-by-query.html - """ - return AsyncUpdateByQuery( - using=using or self._using, - index=self._name, - ) - - async def create( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Creates the index in elasticsearch. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.create`` unchanged. - """ - return await self._get_connection(using).indices.create( - index=self._name, body=self.to_dict(), **kwargs - ) - - async def is_closed(self, using: Optional[AsyncUsingType] = None) -> bool: - state = await self._get_connection(using).cluster.state( - index=self._name, metric="metadata" - ) - return bool(state["metadata"]["indices"][self._name]["state"] == "close") - - async def save( - self, using: Optional[AsyncUsingType] = None - ) -> "Optional[ObjectApiResponse[Any]]": - """ - Sync the index definition with elasticsearch, creating the index if it - doesn't exist and updating its settings and mappings if it does. - - Note some settings and mapping changes cannot be done on an open - index (or at all on an existing index) and for those this method will - fail with the underlying exception. - """ - if not await self.exists(using=using): - return await self.create(using=using) - - body = self.to_dict() - settings = body.pop("settings", {}) - analysis = settings.pop("analysis", None) - current_settings = (await self.get_settings(using=using))[self._name][ - "settings" - ]["index"] - if analysis: - if await self.is_closed(using=using): - # closed index, update away - settings["analysis"] = analysis - else: - # compare analysis definition, if all analysis objects are - # already defined as requested, skip analysis update and - # proceed, otherwise raise IllegalOperation - existing_analysis = current_settings.get("analysis", {}) - if any( - existing_analysis.get(section, {}).get(k, None) - != analysis[section][k] - for section in analysis - for k in analysis[section] - ): - raise IllegalOperation( - "You cannot update analysis configuration on an open index, " - "you need to close index %s first." % self._name - ) - - # try and update the settings - if settings: - settings = settings.copy() - for k, v in list(settings.items()): - if k in current_settings and current_settings[k] == str(v): - del settings[k] - - if settings: - await self.put_settings(using=using, body=settings) - - # update the mappings, any conflict in the mappings will result in an - # exception - mappings = body.pop("mappings", {}) - if mappings: - return await self.put_mapping(using=using, body=mappings) - - return None - - async def analyze( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Perform the analysis process on a text and return the tokens breakdown - of the text. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.analyze`` unchanged. - """ - return await self._get_connection(using).indices.analyze( - index=self._name, **kwargs - ) - - async def refresh( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Performs a refresh operation on the index. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.refresh`` unchanged. - """ - return await self._get_connection(using).indices.refresh( - index=self._name, **kwargs - ) - - async def flush( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Performs a flush operation on the index. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.flush`` unchanged. - """ - return await self._get_connection(using).indices.flush( - index=self._name, **kwargs - ) - - async def get( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - The get index API allows to retrieve information about the index. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.get`` unchanged. - """ - return await self._get_connection(using).indices.get(index=self._name, **kwargs) - - async def open( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Opens the index in elasticsearch. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.open`` unchanged. - """ - return await self._get_connection(using).indices.open( - index=self._name, **kwargs - ) - - async def close( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Closes the index in elasticsearch. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.close`` unchanged. - """ - return await self._get_connection(using).indices.close( - index=self._name, **kwargs - ) - - async def delete( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Deletes the index in elasticsearch. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.delete`` unchanged. - """ - return await self._get_connection(using).indices.delete( - index=self._name, **kwargs - ) - - async def exists( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> bool: - """ - Returns ``True`` if the index already exists in elasticsearch. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.exists`` unchanged. - """ - return bool( - await self._get_connection(using).indices.exists(index=self._name, **kwargs) - ) - - async def put_mapping( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Register specific mapping definition for a specific type. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.put_mapping`` unchanged. - """ - return await self._get_connection(using).indices.put_mapping( - index=self._name, **kwargs - ) - - async def get_mapping( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Retrieve specific mapping definition for a specific type. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.get_mapping`` unchanged. - """ - return await self._get_connection(using).indices.get_mapping( - index=self._name, **kwargs - ) - - async def get_field_mapping( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Retrieve mapping definition of a specific field. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.get_field_mapping`` unchanged. - """ - return await self._get_connection(using).indices.get_field_mapping( - index=self._name, **kwargs - ) - - async def put_alias( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Create an alias for the index. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.put_alias`` unchanged. - """ - return await self._get_connection(using).indices.put_alias( - index=self._name, **kwargs - ) - - async def exists_alias( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> bool: - """ - Return a boolean indicating whether given alias exists for this index. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.exists_alias`` unchanged. - """ - return bool( - await self._get_connection(using).indices.exists_alias( - index=self._name, **kwargs - ) - ) - - async def get_alias( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Retrieve a specified alias. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.get_alias`` unchanged. - """ - return await self._get_connection(using).indices.get_alias( - index=self._name, **kwargs - ) - - async def delete_alias( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Delete specific alias. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.delete_alias`` unchanged. - """ - return await self._get_connection(using).indices.delete_alias( - index=self._name, **kwargs - ) - - async def get_settings( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Retrieve settings for the index. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.get_settings`` unchanged. - """ - return await self._get_connection(using).indices.get_settings( - index=self._name, **kwargs - ) - - async def put_settings( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Change specific index level settings in real time. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.put_settings`` unchanged. - """ - return await self._get_connection(using).indices.put_settings( - index=self._name, **kwargs - ) - - async def stats( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Retrieve statistics on different operations happening on the index. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.stats`` unchanged. - """ - return await self._get_connection(using).indices.stats( - index=self._name, **kwargs - ) - - async def segments( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Provide low level segments information that a Lucene index (shard - level) is built with. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.segments`` unchanged. - """ - return await self._get_connection(using).indices.segments( - index=self._name, **kwargs - ) - - async def validate_query( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Validate a potentially expensive query without executing it. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.validate_query`` unchanged. - """ - return await self._get_connection(using).indices.validate_query( - index=self._name, **kwargs - ) - - async def clear_cache( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Clear all caches or specific cached associated with the index. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.clear_cache`` unchanged. - """ - return await self._get_connection(using).indices.clear_cache( - index=self._name, **kwargs - ) - - async def recovery( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - The indices recovery API provides insight into on-going shard - recoveries for the index. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.recovery`` unchanged. - """ - return await self._get_connection(using).indices.recovery( - index=self._name, **kwargs - ) - - async def shard_stores( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Provides store information for shard copies of the index. Store - information reports on which nodes shard copies exist, the shard copy - version, indicating how recent they are, and any exceptions encountered - while opening the shard index or from earlier engine failure. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.shard_stores`` unchanged. - """ - return await self._get_connection(using).indices.shard_stores( - index=self._name, **kwargs - ) - - async def forcemerge( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - The force merge API allows to force merging of the index through an - API. The merge relates to the number of segments a Lucene index holds - within each shard. The force merge operation allows to reduce the - number of segments by merging them. - - This call will block until the merge is complete. If the http - connection is lost, the request will continue in the background, and - any new requests will block until the previous force merge is complete. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.forcemerge`` unchanged. - """ - return await self._get_connection(using).indices.forcemerge( - index=self._name, **kwargs - ) - - async def shrink( - self, using: Optional[AsyncUsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - The shrink index API allows you to shrink an existing index into a new - index with fewer primary shards. The number of primary shards in the - target index must be a factor of the shards in the source index. For - example an index with 8 primary shards can be shrunk into 4, 2 or 1 - primary shards or an index with 15 primary shards can be shrunk into 5, - 3 or 1. If the number of shards in the index is a prime number it can - only be shrunk into a single primary shard. Before shrinking, a - (primary or replica) copy of every shard in the index must be present - on the same node. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.shrink`` unchanged. - """ - return await self._get_connection(using).indices.shrink( - index=self._name, **kwargs - ) diff --git a/elasticsearch_dsl/_async/mapping.py b/elasticsearch_dsl/_async/mapping.py deleted file mode 100644 index 7ef9c6da..00000000 --- a/elasticsearch_dsl/_async/mapping.py +++ /dev/null @@ -1,49 +0,0 @@ -# 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 List, Optional, Union - -from typing_extensions import Self - -from ..async_connections import get_connection -from ..mapping_base import MappingBase -from ..utils import AsyncUsingType - - -class AsyncMapping(MappingBase): - @classmethod - async def from_es( - cls, index: Optional[Union[str, List[str]]], using: AsyncUsingType = "default" - ) -> Self: - m = cls() - await m.update_from_es(index, using) - return m - - async def update_from_es( - self, index: Optional[Union[str, List[str]]], using: AsyncUsingType = "default" - ) -> None: - es = get_connection(using) - raw = await es.indices.get_mapping(index=index) - _, raw = raw.popitem() - self._update_from_dict(raw["mappings"]) - - async def save(self, index: str, using: AsyncUsingType = "default") -> None: - from .index import AsyncIndex - - i = AsyncIndex(index, using=using) - i.mapping(self) - await i.save() diff --git a/elasticsearch_dsl/_async/search.py b/elasticsearch_dsl/_async/search.py deleted file mode 100644 index 94fbe289..00000000 --- a/elasticsearch_dsl/_async/search.py +++ /dev/null @@ -1,232 +0,0 @@ -# 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, - AsyncIterator, - Dict, - Iterator, - List, - Optional, - cast, -) - -from elasticsearch.exceptions import ApiError -from elasticsearch.helpers import async_scan -from typing_extensions import Self - -from ..async_connections import get_connection -from ..response import Response -from ..search_base import MultiSearchBase, SearchBase -from ..utils import _R, AsyncUsingType, AttrDict - - -class AsyncSearch(SearchBase[_R]): - _using: AsyncUsingType - - def __aiter__(self) -> AsyncIterator[_R]: - """ - Iterate over the hits. - """ - - class ResultsIterator(AsyncIterator[_R]): - def __init__(self, search: AsyncSearch[_R]): - self.search = search - self.iterator: Optional[Iterator[_R]] = None - - async def __anext__(self) -> _R: - if self.iterator is None: - self.iterator = iter(await self.search.execute()) - try: - return next(self.iterator) - except StopIteration: - raise StopAsyncIteration() - - return ResultsIterator(self) - - async 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 = await es.count( - index=self._index, - query=cast(Optional[Dict[str, Any]], d.get("query", None)), - **self._params, - ) - - return cast(int, resp["count"]) - - async 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, - ( - await es.search( - index=self._index, body=self.to_dict(), **self._params - ) - ).body, - ) - return self._response - - async def scan(self) -> AsyncIterator[_R]: - """ - Turn the search into a scan search and return a generator that will - iterate over all the documents matching the query. - - Use ``params`` method to specify any additional arguments you with to - 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) - - async for hit in async_scan( - es, query=self.to_dict(), index=self._index, **self._params - ): - yield self._get_result(cast(AttrDict[Any], hit)) - - async def delete(self) -> AttrDict[Any]: - """ - delete() executes the query by delegating to delete_by_query() - """ - - es = get_connection(self._using) - assert self._index is not None - - return AttrDict( - cast( - Dict[str, Any], - await es.delete_by_query( - index=self._index, body=self.to_dict(), **self._params - ), - ) - ) - - @contextlib.asynccontextmanager - async def point_in_time(self, keep_alive: str = "1m") -> AsyncIterator[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 = 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: str = "1m") -> AsyncIterator[_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 - """ - 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 = s.search_after() - - -class AsyncMultiSearch(MultiSearchBase[_R]): - """ - Combine multiple :class:`~elasticsearch_dsl.Search` objects into a single - request. - """ - - _using: AsyncUsingType - - if TYPE_CHECKING: - - def add(self, search: AsyncSearch[_R]) -> Self: ... # type: ignore[override] - - async 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 = await 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 AsyncEmptySearch(AsyncSearch[_R]): - async def count(self) -> int: - return 0 - - async def execute(self, ignore_cache: bool = False) -> Response[_R]: - return self._response_class(self, {"hits": {"total": 0, "hits": []}}) - - async def scan(self) -> AsyncIterator[_R]: - return - yield # a bit strange, but this forces an empty generator function - - async def delete(self) -> AttrDict[Any]: - return AttrDict[Any]({}) diff --git a/elasticsearch_dsl/_async/update_by_query.py b/elasticsearch_dsl/_async/update_by_query.py deleted file mode 100644 index bff3aa94..00000000 --- a/elasticsearch_dsl/_async/update_by_query.py +++ /dev/null @@ -1,47 +0,0 @@ -# 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 ..async_connections import get_connection -from ..update_by_query_base import UpdateByQueryBase -from ..utils import _R, AsyncUsingType - -if TYPE_CHECKING: - from ..response import UpdateByQueryResponse - - -class AsyncUpdateByQuery(UpdateByQueryBase[_R]): - _using: AsyncUsingType - - async 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, - ( - await es.update_by_query( - index=self._index, **self.to_dict(), **self._params - ) - ).body, - ) - return self._response diff --git a/elasticsearch_dsl/_sync/__init__.py b/elasticsearch_dsl/_sync/__init__.py deleted file mode 100644 index 2a87d183..00000000 --- a/elasticsearch_dsl/_sync/__init__.py +++ /dev/null @@ -1,16 +0,0 @@ -# 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. diff --git a/elasticsearch_dsl/_sync/document.py b/elasticsearch_dsl/_sync/document.py deleted file mode 100644 index abcda3a3..00000000 --- a/elasticsearch_dsl/_sync/document.py +++ /dev/null @@ -1,513 +0,0 @@ -# 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 collections.abc -from typing import ( - TYPE_CHECKING, - Any, - Dict, - Iterable, - List, - Optional, - Tuple, - Union, - cast, -) - -from elasticsearch.exceptions import NotFoundError, RequestError -from elasticsearch.helpers import bulk -from typing_extensions import Self, dataclass_transform - -from .._sync.index import Index -from ..connections import get_connection -from ..document_base import DocumentBase, DocumentMeta, mapped_field -from ..exceptions import IllegalOperation -from ..utils import DOC_META_FIELDS, META_FIELDS, UsingType, merge -from .search import Search - -if TYPE_CHECKING: - from elasticsearch import Elasticsearch - - -class IndexMeta(DocumentMeta): - _index: Index - - # global flag to guard us from associating an Index with the base Document - # class, only user defined subclasses should have an _index attr - _document_initialized = False - - def __new__( - cls, name: str, bases: Tuple[type, ...], attrs: Dict[str, Any] - ) -> "IndexMeta": - new_cls = super().__new__(cls, name, bases, attrs) - if cls._document_initialized: - index_opts = attrs.pop("Index", None) - index = cls.construct_index(index_opts, bases) - new_cls._index = index - index.document(new_cls) - cls._document_initialized = True - return cast(IndexMeta, new_cls) - - @classmethod - def construct_index(cls, opts: Dict[str, Any], bases: Tuple[type, ...]) -> Index: - if opts is None: - for b in bases: - if hasattr(b, "_index"): - return b._index - - # Set None as Index name so it will set _all while making the query - return Index(name=None) - - i = Index(getattr(opts, "name", "*"), using=getattr(opts, "using", "default")) - i.settings(**getattr(opts, "settings", {})) - i.aliases(**getattr(opts, "aliases", {})) - for a in getattr(opts, "analyzers", ()): - i.analyzer(a) - return i - - -@dataclass_transform(field_specifiers=(mapped_field,)) -class Document(DocumentBase, metaclass=IndexMeta): - """ - Model-like class for persisting documents in elasticsearch. - """ - - if TYPE_CHECKING: - _index: Index - - @classmethod - def _get_using(cls, using: Optional[UsingType] = None) -> UsingType: - return cast(UsingType, using or cls._index._using) - - @classmethod - def _get_connection(cls, using: Optional[UsingType] = None) -> "Elasticsearch": - return get_connection(cls._get_using(using)) - - @classmethod - def init( - cls, index: Optional[str] = None, using: Optional[UsingType] = None - ) -> None: - """ - Create the index and populate the mappings in elasticsearch. - """ - i = cls._index - if index: - i = i.clone(name=index) - i.save(using=using) - - @classmethod - def search( - cls, using: Optional[UsingType] = None, index: Optional[str] = None - ) -> Search[Self]: - """ - Create an :class:`~elasticsearch_dsl.Search` instance that will search - over this ``Document``. - """ - return Search( - using=cls._get_using(using), index=cls._default_index(index), doc_type=[cls] - ) - - @classmethod - def get( - cls, - id: str, - using: Optional[UsingType] = None, - index: Optional[str] = None, - **kwargs: Any, - ) -> Optional[Self]: - """ - Retrieve a single document from elasticsearch using its ``id``. - - :arg id: ``id`` of the document to be retrieved - :arg index: elasticsearch index to use, if the ``Document`` is - associated with an index this can be omitted. - :arg using: connection alias to use, defaults to ``'default'`` - - Any additional keyword arguments will be passed to - ``Elasticsearch.get`` unchanged. - """ - es = cls._get_connection(using) - doc = es.get(index=cls._default_index(index), id=id, **kwargs) - if not doc.get("found", False): - return None - return cls.from_es(doc) - - @classmethod - def exists( - cls, - id: str, - using: Optional[UsingType] = None, - index: Optional[str] = None, - **kwargs: Any, - ) -> bool: - """ - check if exists a single document from elasticsearch using its ``id``. - - :arg id: ``id`` of the document to check if exists - :arg index: elasticsearch index to use, if the ``Document`` is - associated with an index this can be omitted. - :arg using: connection alias to use, defaults to ``'default'`` - - Any additional keyword arguments will be passed to - ``Elasticsearch.exists`` unchanged. - """ - es = cls._get_connection(using) - return bool(es.exists(index=cls._default_index(index), id=id, **kwargs)) - - @classmethod - def mget( - cls, - docs: List[Dict[str, Any]], - using: Optional[UsingType] = None, - index: Optional[str] = None, - raise_on_error: bool = True, - missing: str = "none", - **kwargs: Any, - ) -> List[Optional[Self]]: - r""" - Retrieve multiple document by their ``id``\s. Returns a list of instances - in the same order as requested. - - :arg docs: list of ``id``\s of the documents to be retrieved or a list - of document specifications as per - https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-multi-get.html - :arg index: elasticsearch index to use, if the ``Document`` is - associated with an index this can be omitted. - :arg using: connection alias to use, defaults to ``'default'`` - :arg missing: what to do when one of the documents requested is not - found. Valid options are ``'none'`` (use ``None``), ``'raise'`` (raise - ``NotFoundError``) or ``'skip'`` (ignore the missing document). - - Any additional keyword arguments will be passed to - ``Elasticsearch.mget`` unchanged. - """ - if missing not in ("raise", "skip", "none"): - raise ValueError("'missing' must be 'raise', 'skip', or 'none'.") - es = cls._get_connection(using) - body = { - "docs": [ - doc if isinstance(doc, collections.abc.Mapping) else {"_id": doc} - for doc in docs - ] - } - results = es.mget(index=cls._default_index(index), body=body, **kwargs) - - objs: List[Optional[Self]] = [] - error_docs: List[Self] = [] - missing_docs: List[Self] = [] - for doc in results["docs"]: - if doc.get("found"): - if error_docs or missing_docs: - # We're going to raise an exception anyway, so avoid an - # expensive call to cls.from_es(). - continue - - objs.append(cls.from_es(doc)) - - elif doc.get("error"): - if raise_on_error: - error_docs.append(doc) - if missing == "none": - objs.append(None) - - # The doc didn't cause an error, but the doc also wasn't found. - elif missing == "raise": - missing_docs.append(doc) - elif missing == "none": - objs.append(None) - - if error_docs: - error_ids = [doc["_id"] for doc in error_docs] - message = "Required routing not provided for documents %s." - message %= ", ".join(error_ids) - raise RequestError(400, message, error_docs) # type: ignore - if missing_docs: - missing_ids = [doc["_id"] for doc in missing_docs] - message = f"Documents {', '.join(missing_ids)} not found." - raise NotFoundError(404, message, {"docs": missing_docs}) # type: ignore - return objs - - def delete( - self, - using: Optional[UsingType] = None, - index: Optional[str] = None, - **kwargs: Any, - ) -> None: - """ - Delete the instance in elasticsearch. - - :arg index: elasticsearch index to use, if the ``Document`` is - associated with an index this can be omitted. - :arg using: connection alias to use, defaults to ``'default'`` - - Any additional keyword arguments will be passed to - ``Elasticsearch.delete`` unchanged. - """ - es = self._get_connection(using) - # extract routing etc from meta - doc_meta = {k: self.meta[k] for k in DOC_META_FIELDS if k in self.meta} - - # Optimistic concurrency control - if "seq_no" in self.meta and "primary_term" in self.meta: - doc_meta["if_seq_no"] = self.meta["seq_no"] - doc_meta["if_primary_term"] = self.meta["primary_term"] - - doc_meta.update(kwargs) - i = self._get_index(index) - assert i is not None - - es.delete(index=i, **doc_meta) - - def update( - self, - using: Optional[UsingType] = None, - index: Optional[str] = None, - detect_noop: bool = True, - doc_as_upsert: bool = False, - refresh: bool = False, - retry_on_conflict: Optional[int] = None, - script: Optional[Union[str, Dict[str, Any]]] = None, - script_id: Optional[str] = None, - scripted_upsert: bool = False, - upsert: Optional[Dict[str, Any]] = None, - return_doc_meta: bool = False, - **fields: Any, - ) -> Any: - """ - Partial update of the document, specify fields you wish to update and - both the instance and the document in elasticsearch will be updated:: - - doc = MyDocument(title='Document Title!') - doc.save() - doc.update(title='New Document Title!') - - :arg index: elasticsearch index to use, if the ``Document`` is - associated with an index this can be omitted. - :arg using: connection alias to use, defaults to ``'default'`` - :arg detect_noop: Set to ``False`` to disable noop detection. - :arg refresh: Control when the changes made by this request are visible - to search. Set to ``True`` for immediate effect. - :arg retry_on_conflict: In between the get and indexing phases of the - update, it is possible that another process might have already - updated the same document. By default, the update will fail with a - version conflict exception. The retry_on_conflict parameter - controls how many times to retry the update before finally throwing - an exception. - :arg doc_as_upsert: Instead of sending a partial doc plus an upsert - doc, setting doc_as_upsert to true will use the contents of doc as - the upsert value - :arg script: the source code of the script as a string, or a dictionary - with script attributes to update. - :arg return_doc_meta: set to ``True`` to return all metadata from the - index API call instead of only the operation result - - :return: operation result noop/updated - """ - body: Dict[str, Any] = { - "doc_as_upsert": doc_as_upsert, - "detect_noop": detect_noop, - } - - # scripted update - if script or script_id: - if upsert is not None: - body["upsert"] = upsert - - if script: - if isinstance(script, str): - script = {"source": script} - else: - script = {"id": script_id} - - if "params" not in script: - script["params"] = fields - else: - script["params"].update(fields) - - body["script"] = script - body["scripted_upsert"] = scripted_upsert - - # partial document update - else: - if not fields: - raise IllegalOperation( - "You cannot call update() without updating individual fields or a script. " - "If you wish to update the entire object use save()." - ) - - # update given fields locally - merge(self, fields) - - # prepare data for ES - values = self.to_dict(skip_empty=False) - - # if fields were given: partial update - body["doc"] = {k: values.get(k) for k in fields.keys()} - - # extract routing etc from meta - doc_meta = {k: self.meta[k] for k in DOC_META_FIELDS if k in self.meta} - - if retry_on_conflict is not None: - doc_meta["retry_on_conflict"] = retry_on_conflict - - # Optimistic concurrency control - if ( - retry_on_conflict in (None, 0) - and "seq_no" in self.meta - and "primary_term" in self.meta - ): - doc_meta["if_seq_no"] = self.meta["seq_no"] - doc_meta["if_primary_term"] = self.meta["primary_term"] - - i = self._get_index(index) - assert i is not None - - meta = self._get_connection(using).update( - index=i, body=body, refresh=refresh, **doc_meta - ) - - # update meta information from ES - for k in META_FIELDS: - if "_" + k in meta: - setattr(self.meta, k, meta["_" + k]) - - return meta if return_doc_meta else meta["result"] - - def save( - self, - using: Optional[UsingType] = None, - index: Optional[str] = None, - validate: bool = True, - skip_empty: bool = True, - return_doc_meta: bool = False, - **kwargs: Any, - ) -> Any: - """ - Save the document into elasticsearch. If the document doesn't exist it - is created, it is overwritten otherwise. Returns ``True`` if this - operations resulted in new document being created. - - :arg index: elasticsearch index to use, if the ``Document`` is - associated with an index this can be omitted. - :arg using: connection alias to use, defaults to ``'default'`` - :arg validate: set to ``False`` to skip validating the document - :arg skip_empty: if set to ``False`` will cause empty values (``None``, - ``[]``, ``{}``) to be left on the document. Those values will be - stripped out otherwise as they make no difference in elasticsearch. - :arg return_doc_meta: set to ``True`` to return all metadata from the - update API call instead of only the operation result - - Any additional keyword arguments will be passed to - ``Elasticsearch.index`` unchanged. - - :return: operation result created/updated - """ - if validate: - self.full_clean() - - es = self._get_connection(using) - # extract routing etc from meta - doc_meta = {k: self.meta[k] for k in DOC_META_FIELDS if k in self.meta} - - # Optimistic concurrency control - if "seq_no" in self.meta and "primary_term" in self.meta: - doc_meta["if_seq_no"] = self.meta["seq_no"] - doc_meta["if_primary_term"] = self.meta["primary_term"] - - doc_meta.update(kwargs) - i = self._get_index(index) - assert i is not None - - meta = es.index( - index=i, - body=self.to_dict(skip_empty=skip_empty), - **doc_meta, - ) - # update meta information from ES - for k in META_FIELDS: - if "_" + k in meta: - setattr(self.meta, k, meta["_" + k]) - - return meta if return_doc_meta else meta["result"] - - @classmethod - def bulk( - cls, - actions: Iterable[Union[Self, Dict[str, Any]]], - using: Optional[UsingType] = None, - index: Optional[str] = None, - validate: bool = True, - skip_empty: bool = True, - **kwargs: Any, - ) -> Tuple[int, Union[int, List[Any]]]: - """ - Allows to perform multiple indexing operations in a single request. - - :arg actions: a generator that returns document instances to be indexed, - bulk operation dictionaries. - :arg using: connection alias to use, defaults to ``'default'`` - :arg index: Elasticsearch index to use, if the ``Document`` is - associated with an index this can be omitted. - :arg validate: set to ``False`` to skip validating the documents - :arg skip_empty: if set to ``False`` will cause empty values (``None``, - ``[]``, ``{}``) to be left on the document. Those values will be - stripped out otherwise as they make no difference in Elasticsearch. - - Any additional keyword arguments will be passed to - ``Elasticsearch.bulk`` unchanged. - - :return: bulk operation results - """ - es = cls._get_connection(using) - - i = cls._default_index(index) - assert i is not None - - class Generate: - def __init__( - self, - doc_iterator: Iterable[Union[Document, Dict[str, Any]]], - ): - self.doc_iterator = doc_iterator.__iter__() - - def __iter__(self) -> Self: - return self - - def __next__(self) -> Dict[str, Any]: - doc: Optional[Union[Document, Dict[str, Any]]] = ( - self.doc_iterator.__next__() - ) - - if isinstance(doc, dict): - action = doc - doc = None - if "_source" in action and isinstance(action["_source"], Document): - doc = action["_source"] - if validate: # pragma: no cover - doc.full_clean() - action["_source"] = doc.to_dict( - include_meta=False, skip_empty=skip_empty - ) - elif doc is not None: - if validate: # pragma: no cover - doc.full_clean() - action = doc.to_dict(include_meta=True, skip_empty=skip_empty) - if "_index" not in action: - action["_index"] = i - return action - - return bulk(es, Generate(actions), **kwargs) diff --git a/elasticsearch_dsl/_sync/faceted_search.py b/elasticsearch_dsl/_sync/faceted_search.py deleted file mode 100644 index de720550..00000000 --- a/elasticsearch_dsl/_sync/faceted_search.py +++ /dev/null @@ -1,51 +0,0 @@ -# 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 elasticsearch_dsl.faceted_search_base import FacetedResponse, FacetedSearchBase - -from ..utils import _R -from .search import Search - -if TYPE_CHECKING: - from ..response import Response - - -class FacetedSearch(FacetedSearchBase[_R]): - _s: Search[_R] - - def count(self) -> int: - return self._s.count() - - def search(self) -> Search[_R]: - """ - Returns the base Search object to which the facets are added. - - You can customize the query by overriding this method and returning a - modified search object. - """ - s = Search[_R](doc_type=self.doc_types, index=self.index, using=self.using) - return s.response_class(FacetedResponse) - - def execute(self) -> "Response[_R]": - """ - Execute the search and return the response. - """ - r = self._s.execute() - r._faceted_search = self - return r diff --git a/elasticsearch_dsl/_sync/index.py b/elasticsearch_dsl/_sync/index.py deleted file mode 100644 index 3b562a67..00000000 --- a/elasticsearch_dsl/_sync/index.py +++ /dev/null @@ -1,596 +0,0 @@ -# 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, Any, Dict, Optional - -from typing_extensions import Self - -from ..connections import get_connection -from ..exceptions import IllegalOperation -from ..index_base import IndexBase -from ..utils import UsingType -from .mapping import Mapping -from .search import Search -from .update_by_query import UpdateByQuery - -if TYPE_CHECKING: - from elastic_transport import ObjectApiResponse - from elasticsearch import Elasticsearch - - -class IndexTemplate: - def __init__( - self, - name: str, - template: str, - index: Optional["Index"] = None, - order: Optional[int] = None, - **kwargs: Any, - ): - if index is None: - self._index = Index(template, **kwargs) - else: - if kwargs: - raise ValueError( - "You cannot specify options for Index when" - " passing an Index instance." - ) - self._index = index.clone() - self._index._name = template - self._template_name = name - self.order = order - - def __getattr__(self, attr_name: str) -> Any: - return getattr(self._index, attr_name) - - def to_dict(self) -> Dict[str, Any]: - d = self._index.to_dict() - d["index_patterns"] = [self._index._name] - if self.order is not None: - d["order"] = self.order - return d - - def save(self, using: Optional[UsingType] = None) -> "ObjectApiResponse[Any]": - es = get_connection(using or self._index._using) - return es.indices.put_template(name=self._template_name, body=self.to_dict()) - - -class ComposableIndexTemplate: - def __init__( - self, - name: str, - template: str, - index: Optional["Index"] = None, - priority: Optional[int] = None, - **kwargs: Any, - ): - if index is None: - self._index = Index(template, **kwargs) - else: - if kwargs: - raise ValueError( - "You cannot specify options for Index when" - " passing an Index instance." - ) - self._index = index.clone() - self._index._name = template - self._template_name = name - self.priority = priority - - def __getattr__(self, attr_name: str) -> Any: - return getattr(self._index, attr_name) - - def to_dict(self) -> Dict[str, Any]: - d: Dict[str, Any] = {"template": self._index.to_dict()} - d["index_patterns"] = [self._index._name] - if self.priority is not None: - d["priority"] = self.priority - return d - - def save(self, using: Optional[UsingType] = None) -> "ObjectApiResponse[Any]": - es = get_connection(using or self._index._using) - return es.indices.put_index_template(name=self._template_name, **self.to_dict()) - - -class Index(IndexBase): - _using: UsingType - - if TYPE_CHECKING: - - def get_or_create_mapping(self) -> Mapping: ... - - def __init__(self, name: str, using: UsingType = "default"): - """ - :arg name: name of the index - :arg using: connection alias to use, defaults to ``'default'`` - """ - super().__init__(name, Mapping, using=using) - - def _get_connection(self, using: Optional[UsingType] = None) -> "Elasticsearch": - if self._name is None: - raise ValueError("You cannot perform API calls on the default index.") - return get_connection(using or self._using) - - connection = property(_get_connection) - - def as_template( - self, - template_name: str, - pattern: Optional[str] = None, - order: Optional[int] = None, - ) -> IndexTemplate: - return IndexTemplate( - template_name, pattern or self._name, index=self, order=order - ) - - def as_composable_template( - self, - template_name: str, - pattern: Optional[str] = None, - priority: Optional[int] = None, - ) -> ComposableIndexTemplate: - return ComposableIndexTemplate( - template_name, pattern or self._name, index=self, priority=priority - ) - - def load_mappings(self, using: Optional[UsingType] = None) -> None: - self.get_or_create_mapping().update_from_es( - self._name, using=using or self._using - ) - - def clone( - self, name: Optional[str] = None, using: Optional[UsingType] = None - ) -> Self: - """ - Create a copy of the instance with another name or connection alias. - Useful for creating multiple indices with shared configuration:: - - i = Index('base-index') - i.settings(number_of_shards=1) - i.create() - - i2 = i.clone('other-index') - i2.create() - - :arg name: name of the index - :arg using: connection alias to use, defaults to ``'default'`` - """ - i = self.__class__(name or self._name, using=using or self._using) - i._settings = self._settings.copy() - i._aliases = self._aliases.copy() - i._analysis = self._analysis.copy() - i._doc_types = self._doc_types[:] - if self._mapping is not None: - i._mapping = self._mapping._clone() - return i - - def search(self, using: Optional[UsingType] = None) -> Search: - """ - Return a :class:`~elasticsearch_dsl.Search` object searching over the - index (or all the indices belonging to this template) and its - ``Document``\\s. - """ - return Search( - using=using or self._using, index=self._name, doc_type=self._doc_types - ) - - def updateByQuery(self, using: Optional[UsingType] = None) -> UpdateByQuery: - """ - Return a :class:`~elasticsearch_dsl.UpdateByQuery` object searching over the index - (or all the indices belonging to this template) and updating Documents that match - the search criteria. - - For more information, see here: - https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-update-by-query.html - """ - return UpdateByQuery( - using=using or self._using, - index=self._name, - ) - - def create( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Creates the index in elasticsearch. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.create`` unchanged. - """ - return self._get_connection(using).indices.create( - index=self._name, body=self.to_dict(), **kwargs - ) - - def is_closed(self, using: Optional[UsingType] = None) -> bool: - state = self._get_connection(using).cluster.state( - index=self._name, metric="metadata" - ) - return bool(state["metadata"]["indices"][self._name]["state"] == "close") - - def save( - self, using: Optional[UsingType] = None - ) -> "Optional[ObjectApiResponse[Any]]": - """ - Sync the index definition with elasticsearch, creating the index if it - doesn't exist and updating its settings and mappings if it does. - - Note some settings and mapping changes cannot be done on an open - index (or at all on an existing index) and for those this method will - fail with the underlying exception. - """ - if not self.exists(using=using): - return self.create(using=using) - - body = self.to_dict() - settings = body.pop("settings", {}) - analysis = settings.pop("analysis", None) - current_settings = (self.get_settings(using=using))[self._name]["settings"][ - "index" - ] - if analysis: - if self.is_closed(using=using): - # closed index, update away - settings["analysis"] = analysis - else: - # compare analysis definition, if all analysis objects are - # already defined as requested, skip analysis update and - # proceed, otherwise raise IllegalOperation - existing_analysis = current_settings.get("analysis", {}) - if any( - existing_analysis.get(section, {}).get(k, None) - != analysis[section][k] - for section in analysis - for k in analysis[section] - ): - raise IllegalOperation( - "You cannot update analysis configuration on an open index, " - "you need to close index %s first." % self._name - ) - - # try and update the settings - if settings: - settings = settings.copy() - for k, v in list(settings.items()): - if k in current_settings and current_settings[k] == str(v): - del settings[k] - - if settings: - self.put_settings(using=using, body=settings) - - # update the mappings, any conflict in the mappings will result in an - # exception - mappings = body.pop("mappings", {}) - if mappings: - return self.put_mapping(using=using, body=mappings) - - return None - - def analyze( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Perform the analysis process on a text and return the tokens breakdown - of the text. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.analyze`` unchanged. - """ - return self._get_connection(using).indices.analyze(index=self._name, **kwargs) - - def refresh( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Performs a refresh operation on the index. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.refresh`` unchanged. - """ - return self._get_connection(using).indices.refresh(index=self._name, **kwargs) - - def flush( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Performs a flush operation on the index. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.flush`` unchanged. - """ - return self._get_connection(using).indices.flush(index=self._name, **kwargs) - - def get( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - The get index API allows to retrieve information about the index. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.get`` unchanged. - """ - return self._get_connection(using).indices.get(index=self._name, **kwargs) - - def open( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Opens the index in elasticsearch. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.open`` unchanged. - """ - return self._get_connection(using).indices.open(index=self._name, **kwargs) - - def close( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Closes the index in elasticsearch. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.close`` unchanged. - """ - return self._get_connection(using).indices.close(index=self._name, **kwargs) - - def delete( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Deletes the index in elasticsearch. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.delete`` unchanged. - """ - return self._get_connection(using).indices.delete(index=self._name, **kwargs) - - def exists(self, using: Optional[UsingType] = None, **kwargs: Any) -> bool: - """ - Returns ``True`` if the index already exists in elasticsearch. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.exists`` unchanged. - """ - return bool( - self._get_connection(using).indices.exists(index=self._name, **kwargs) - ) - - def put_mapping( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Register specific mapping definition for a specific type. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.put_mapping`` unchanged. - """ - return self._get_connection(using).indices.put_mapping( - index=self._name, **kwargs - ) - - def get_mapping( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Retrieve specific mapping definition for a specific type. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.get_mapping`` unchanged. - """ - return self._get_connection(using).indices.get_mapping( - index=self._name, **kwargs - ) - - def get_field_mapping( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Retrieve mapping definition of a specific field. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.get_field_mapping`` unchanged. - """ - return self._get_connection(using).indices.get_field_mapping( - index=self._name, **kwargs - ) - - def put_alias( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Create an alias for the index. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.put_alias`` unchanged. - """ - return self._get_connection(using).indices.put_alias(index=self._name, **kwargs) - - def exists_alias(self, using: Optional[UsingType] = None, **kwargs: Any) -> bool: - """ - Return a boolean indicating whether given alias exists for this index. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.exists_alias`` unchanged. - """ - return bool( - self._get_connection(using).indices.exists_alias(index=self._name, **kwargs) - ) - - def get_alias( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Retrieve a specified alias. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.get_alias`` unchanged. - """ - return self._get_connection(using).indices.get_alias(index=self._name, **kwargs) - - def delete_alias( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Delete specific alias. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.delete_alias`` unchanged. - """ - return self._get_connection(using).indices.delete_alias( - index=self._name, **kwargs - ) - - def get_settings( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Retrieve settings for the index. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.get_settings`` unchanged. - """ - return self._get_connection(using).indices.get_settings( - index=self._name, **kwargs - ) - - def put_settings( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Change specific index level settings in real time. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.put_settings`` unchanged. - """ - return self._get_connection(using).indices.put_settings( - index=self._name, **kwargs - ) - - def stats( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Retrieve statistics on different operations happening on the index. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.stats`` unchanged. - """ - return self._get_connection(using).indices.stats(index=self._name, **kwargs) - - def segments( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Provide low level segments information that a Lucene index (shard - level) is built with. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.segments`` unchanged. - """ - return self._get_connection(using).indices.segments(index=self._name, **kwargs) - - def validate_query( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Validate a potentially expensive query without executing it. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.validate_query`` unchanged. - """ - return self._get_connection(using).indices.validate_query( - index=self._name, **kwargs - ) - - def clear_cache( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Clear all caches or specific cached associated with the index. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.clear_cache`` unchanged. - """ - return self._get_connection(using).indices.clear_cache( - index=self._name, **kwargs - ) - - def recovery( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - The indices recovery API provides insight into on-going shard - recoveries for the index. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.recovery`` unchanged. - """ - return self._get_connection(using).indices.recovery(index=self._name, **kwargs) - - def shard_stores( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - Provides store information for shard copies of the index. Store - information reports on which nodes shard copies exist, the shard copy - version, indicating how recent they are, and any exceptions encountered - while opening the shard index or from earlier engine failure. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.shard_stores`` unchanged. - """ - return self._get_connection(using).indices.shard_stores( - index=self._name, **kwargs - ) - - def forcemerge( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - The force merge API allows to force merging of the index through an - API. The merge relates to the number of segments a Lucene index holds - within each shard. The force merge operation allows to reduce the - number of segments by merging them. - - This call will block until the merge is complete. If the http - connection is lost, the request will continue in the background, and - any new requests will block until the previous force merge is complete. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.forcemerge`` unchanged. - """ - return self._get_connection(using).indices.forcemerge( - index=self._name, **kwargs - ) - - def shrink( - self, using: Optional[UsingType] = None, **kwargs: Any - ) -> "ObjectApiResponse[Any]": - """ - The shrink index API allows you to shrink an existing index into a new - index with fewer primary shards. The number of primary shards in the - target index must be a factor of the shards in the source index. For - example an index with 8 primary shards can be shrunk into 4, 2 or 1 - primary shards or an index with 15 primary shards can be shrunk into 5, - 3 or 1. If the number of shards in the index is a prime number it can - only be shrunk into a single primary shard. Before shrinking, a - (primary or replica) copy of every shard in the index must be present - on the same node. - - Any additional keyword arguments will be passed to - ``Elasticsearch.indices.shrink`` unchanged. - """ - return self._get_connection(using).indices.shrink(index=self._name, **kwargs) diff --git a/elasticsearch_dsl/_sync/mapping.py b/elasticsearch_dsl/_sync/mapping.py deleted file mode 100644 index 4ee0f282..00000000 --- a/elasticsearch_dsl/_sync/mapping.py +++ /dev/null @@ -1,49 +0,0 @@ -# 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 List, Optional, Union - -from typing_extensions import Self - -from ..connections import get_connection -from ..mapping_base import MappingBase -from ..utils import UsingType - - -class Mapping(MappingBase): - @classmethod - def from_es( - cls, index: Optional[Union[str, List[str]]], using: UsingType = "default" - ) -> Self: - m = cls() - m.update_from_es(index, using) - return m - - def update_from_es( - self, index: Optional[Union[str, List[str]]], using: UsingType = "default" - ) -> None: - es = get_connection(using) - raw = es.indices.get_mapping(index=index) - _, raw = raw.popitem() - self._update_from_dict(raw["mappings"]) - - def save(self, index: str, using: UsingType = "default") -> None: - from .index import Index - - i = Index(index, using=using) - i.mapping(self) - i.save() diff --git a/elasticsearch_dsl/_sync/search.py b/elasticsearch_dsl/_sync/search.py deleted file mode 100644 index f3906f59..00000000 --- a/elasticsearch_dsl/_sync/search.py +++ /dev/null @@ -1,217 +0,0 @@ -# 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 elasticsearch.exceptions import ApiError -from elasticsearch.helpers import scan -from typing_extensions import Self - -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 ``params`` method to specify any additional arguments you with to - 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) - - 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() - """ - - 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]({}) diff --git a/elasticsearch_dsl/_sync/update_by_query.py b/elasticsearch_dsl/_sync/update_by_query.py deleted file mode 100644 index 0caecc02..00000000 --- a/elasticsearch_dsl/_sync/update_by_query.py +++ /dev/null @@ -1,45 +0,0 @@ -# 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 diff --git a/elasticsearch_dsl/aggs.py b/elasticsearch_dsl/aggs.py deleted file mode 100644 index 2f79c308..00000000 --- a/elasticsearch_dsl/aggs.py +++ /dev/null @@ -1,3731 +0,0 @@ -# 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 collections.abc -from copy import deepcopy -from typing import ( - TYPE_CHECKING, - Any, - ClassVar, - Dict, - Generic, - Iterable, - Literal, - Mapping, - MutableMapping, - Optional, - Sequence, - Union, - cast, -) - -from elastic_transport.client_utils import DEFAULT - -from .query import Query -from .response.aggs import AggResponse, BucketData, FieldBucketData, TopHitsData -from .utils import _R, AttrDict, DslBase - -if TYPE_CHECKING: - from elastic_transport.client_utils import DefaultType - - from elasticsearch_dsl import types - - from .document_base import InstrumentedField - from .search_base import SearchBase - - -def A( - name_or_agg: Union[MutableMapping[str, Any], "Agg[_R]", str], - filter: Optional[Union[str, "Query"]] = None, - **params: Any, -) -> "Agg[_R]": - if filter is not None: - if name_or_agg != "filter": - raise ValueError( - "Aggregation %r doesn't accept positional argument 'filter'." - % name_or_agg - ) - params["filter"] = filter - - # {"terms": {"field": "tags"}, "aggs": {...}} - if isinstance(name_or_agg, collections.abc.MutableMapping): - if params: - raise ValueError("A() cannot accept parameters when passing in a dict.") - # copy to avoid modifying in-place - agg = deepcopy(name_or_agg) - # pop out nested aggs - aggs = agg.pop("aggs", None) - # pop out meta data - meta = agg.pop("meta", None) - # should be {"terms": {"field": "tags"}} - if len(agg) != 1: - raise ValueError( - 'A() can only accept dict with an aggregation ({"terms": {...}}). ' - "Instead it got (%r)" % name_or_agg - ) - agg_type, params = agg.popitem() - if aggs: - params = params.copy() - params["aggs"] = aggs - if meta: - params = params.copy() - params["meta"] = meta - return Agg[_R].get_dsl_class(agg_type)(_expand__to_dot=False, **params) - - # Terms(...) just return the nested agg - elif isinstance(name_or_agg, Agg): - if params: - raise ValueError( - "A() cannot accept parameters when passing in an Agg object." - ) - return name_or_agg - - # "terms", field="tags" - return Agg[_R].get_dsl_class(name_or_agg)(**params) - - -class Agg(DslBase, Generic[_R]): - _type_name = "agg" - _type_shortcut = staticmethod(A) - name = "" - - def __contains__(self, key: str) -> bool: - return False - - def to_dict(self) -> Dict[str, Any]: - d = super().to_dict() - if isinstance(d[self.name], dict): - n = cast(Dict[str, Any], d[self.name]) - if "meta" in n: - d["meta"] = n.pop("meta") - return d - - def result(self, search: "SearchBase[_R]", data: Dict[str, Any]) -> AttrDict[Any]: - return AggResponse[_R](self, search, data) - - -class AggBase(Generic[_R]): - aggs: Dict[str, Agg[_R]] - _base: Agg[_R] - _params: Dict[str, Any] - _param_defs: ClassVar[Dict[str, Any]] = { - "aggs": {"type": "agg", "hash": True}, - } - - def __contains__(self, key: str) -> bool: - return key in self._params.get("aggs", {}) - - def __getitem__(self, agg_name: str) -> Agg[_R]: - agg = cast( - Agg[_R], self._params.setdefault("aggs", {})[agg_name] - ) # propagate KeyError - - # make sure we're not mutating a shared state - whenever accessing a - # bucket, return a shallow copy of it to be safe - if isinstance(agg, Bucket): - agg = A(agg.name, **agg._params) - # be sure to store the copy so any modifications to it will affect us - self._params["aggs"][agg_name] = agg - - return agg - - def __setitem__(self, agg_name: str, agg: Agg[_R]) -> None: - self.aggs[agg_name] = A(agg) - - def __iter__(self) -> Iterable[str]: - return iter(self.aggs) - - def _agg( - self, - bucket: bool, - name: str, - agg_type: Union[Dict[str, Any], Agg[_R], str], - *args: Any, - **params: Any, - ) -> Agg[_R]: - agg = self[name] = A(agg_type, *args, **params) - - # For chaining - when creating new buckets return them... - if bucket: - return agg - # otherwise return self._base so we can keep chaining - else: - return self._base - - def metric( - self, - name: str, - agg_type: Union[Dict[str, Any], Agg[_R], str], - *args: Any, - **params: Any, - ) -> Agg[_R]: - return self._agg(False, name, agg_type, *args, **params) - - def bucket( - self, - name: str, - agg_type: Union[Dict[str, Any], Agg[_R], str], - *args: Any, - **params: Any, - ) -> "Bucket[_R]": - return cast("Bucket[_R]", self._agg(True, name, agg_type, *args, **params)) - - def pipeline( - self, - name: str, - agg_type: Union[Dict[str, Any], Agg[_R], str], - *args: Any, - **params: Any, - ) -> "Pipeline[_R]": - return cast("Pipeline[_R]", self._agg(False, name, agg_type, *args, **params)) - - def result(self, search: "SearchBase[_R]", data: Any) -> AttrDict[Any]: - return BucketData(self, search, data) # type: ignore - - -class Bucket(AggBase[_R], Agg[_R]): - def __init__(self, **params: Any): - super().__init__(**params) - # remember self for chaining - self._base = self - - def to_dict(self) -> Dict[str, Any]: - d = super(AggBase, self).to_dict() - if isinstance(d[self.name], dict): - n = cast(AttrDict[Any], d[self.name]) - if "aggs" in n: - d["aggs"] = n.pop("aggs") - return d - - -class Pipeline(Agg[_R]): - pass - - -class AdjacencyMatrix(Bucket[_R]): - """ - A bucket aggregation returning a form of adjacency matrix. The request - provides a collection of named filter expressions, similar to the - `filters` aggregation. Each bucket in the response represents a non- - empty cell in the matrix of intersecting filters. - - :arg filters: Filters used to create buckets. At least one filter is - required. - :arg separator: Separator used to concatenate filter names. Defaults - to &. - """ - - name = "adjacency_matrix" - _param_defs = { - "filters": {"type": "query", "hash": True}, - } - - def __init__( - self, - *, - filters: Union[Mapping[str, Query], "DefaultType"] = DEFAULT, - separator: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(filters=filters, separator=separator, **kwargs) - - -class AutoDateHistogram(Bucket[_R]): - """ - A multi-bucket aggregation similar to the date histogram, except - instead of providing an interval to use as the width of each bucket, a - target number of buckets is provided. - - :arg buckets: The target number of buckets. Defaults to `10` if - omitted. - :arg field: The field on which to run the aggregation. - :arg format: The date format used to format `key_as_string` in the - response. If no `format` is specified, the first date format - specified in the field mapping is used. - :arg minimum_interval: The minimum rounding interval. This can make - the collection process more efficient, as the aggregation will not - attempt to round at any interval lower than `minimum_interval`. - :arg missing: The value to apply to documents that do not have a - value. By default, documents without a value are ignored. - :arg offset: Time zone specified as a ISO 8601 UTC offset. - :arg params: - :arg script: - :arg time_zone: Time zone ID. - """ - - name = "auto_date_histogram" - - def __init__( - self, - *, - buckets: Union[int, "DefaultType"] = DEFAULT, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - format: Union[str, "DefaultType"] = DEFAULT, - minimum_interval: Union[ - Literal["second", "minute", "hour", "day", "month", "year"], "DefaultType" - ] = DEFAULT, - missing: Any = DEFAULT, - offset: Union[str, "DefaultType"] = DEFAULT, - params: Union[Mapping[str, Any], "DefaultType"] = DEFAULT, - script: Union["types.Script", Dict[str, Any], "DefaultType"] = DEFAULT, - time_zone: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - buckets=buckets, - field=field, - format=format, - minimum_interval=minimum_interval, - missing=missing, - offset=offset, - params=params, - script=script, - time_zone=time_zone, - **kwargs, - ) - - def result(self, search: "SearchBase[_R]", data: Any) -> AttrDict[Any]: - return FieldBucketData(self, search, data) - - -class Avg(Agg[_R]): - """ - A single-value metrics aggregation that computes the average of - numeric values that are extracted from the aggregated documents. - - :arg format: - :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 = "avg" - - def __init__( - self, - *, - format: Union[str, "DefaultType"] = DEFAULT, - 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__( - format=format, field=field, missing=missing, script=script, **kwargs - ) - - -class AvgBucket(Pipeline[_R]): - """ - A sibling pipeline aggregation which calculates the mean value of a - specified metric in a sibling aggregation. The specified metric must - be numeric and the sibling aggregation must be a multi-bucket - aggregation. - - :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 = "avg_bucket" - - 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 Boxplot(Agg[_R]): - """ - A metrics aggregation that computes a box plot of numeric values - extracted from the aggregated documents. - - :arg compression: Limits the maximum number of nodes used by the - underlying TDigest algorithm to `20 * compression`, enabling - control of memory usage and approximation error. - :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 = "boxplot" - - def __init__( - self, - *, - compression: Union[float, "DefaultType"] = DEFAULT, - 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__( - compression=compression, - field=field, - missing=missing, - script=script, - **kwargs, - ) - - -class BucketScript(Pipeline[_R]): - """ - A parent pipeline aggregation which runs a script which can perform - per bucket computations on metrics in the parent multi-bucket - aggregation. - - :arg script: The script to run for this aggregation. - :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 = "bucket_script" - - def __init__( - self, - *, - script: Union["types.Script", Dict[str, Any], "DefaultType"] = DEFAULT, - 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__( - script=script, - format=format, - gap_policy=gap_policy, - buckets_path=buckets_path, - **kwargs, - ) - - -class BucketSelector(Pipeline[_R]): - """ - A parent pipeline aggregation which runs a script to determine whether - the current bucket will be retained in the parent multi-bucket - aggregation. - - :arg script: The script to run for this aggregation. - :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 = "bucket_selector" - - def __init__( - self, - *, - script: Union["types.Script", Dict[str, Any], "DefaultType"] = DEFAULT, - 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__( - script=script, - format=format, - gap_policy=gap_policy, - buckets_path=buckets_path, - **kwargs, - ) - - -class BucketSort(Bucket[_R]): - """ - A parent pipeline aggregation which sorts the buckets of its parent - multi-bucket aggregation. - - :arg from: Buckets in positions prior to `from` will be truncated. - :arg gap_policy: The policy to apply when gaps are found in the data. - Defaults to `skip` if omitted. - :arg size: The number of buckets to return. Defaults to all buckets of - the parent aggregation. - :arg sort: The list of fields to sort on. - """ - - name = "bucket_sort" - - def __init__( - self, - *, - from_: Union[int, "DefaultType"] = DEFAULT, - gap_policy: Union[ - Literal["skip", "insert_zeros", "keep_values"], "DefaultType" - ] = DEFAULT, - size: Union[int, "DefaultType"] = DEFAULT, - sort: Union[ - Union[Union[str, "InstrumentedField"], "types.SortOptions"], - Sequence[Union[Union[str, "InstrumentedField"], "types.SortOptions"]], - Dict[str, Any], - "DefaultType", - ] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - from_=from_, gap_policy=gap_policy, size=size, sort=sort, **kwargs - ) - - -class BucketCountKsTest(Pipeline[_R]): - """ - A sibling pipeline aggregation which runs a two sample - Kolmogorov–Smirnov test ("K-S test") against a provided distribution - and the distribution implied by the documents counts in the configured - sibling aggregation. - - :arg alternative: A list of string values indicating which K-S test - alternative to calculate. The valid values are: "greater", "less", - "two_sided". This parameter is key for determining the K-S - statistic used when calculating the K-S test. Default value is all - possible alternative hypotheses. - :arg fractions: A list of doubles indicating the distribution of the - samples with which to compare to the `buckets_path` results. In - typical usage this is the overall proportion of documents in each - bucket, which is compared with the actual document proportions in - each bucket from the sibling aggregation counts. The default is to - assume that overall documents are uniformly distributed on these - buckets, which they would be if one used equal percentiles of a - metric to define the bucket end points. - :arg sampling_method: Indicates the sampling methodology when - calculating the K-S test. Note, this is sampling of the returned - values. This determines the cumulative distribution function (CDF) - points used comparing the two samples. Default is `upper_tail`, - which emphasizes the upper end of the CDF points. Valid options - are: `upper_tail`, `uniform`, and `lower_tail`. - :arg buckets_path: Path to the buckets that contain one set of values - to correlate. - """ - - name = "bucket_count_ks_test" - - def __init__( - self, - *, - alternative: Union[Sequence[str], "DefaultType"] = DEFAULT, - fractions: Union[Sequence[float], "DefaultType"] = DEFAULT, - sampling_method: Union[str, "DefaultType"] = DEFAULT, - buckets_path: Union[ - str, Sequence[str], Mapping[str, str], "DefaultType" - ] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - alternative=alternative, - fractions=fractions, - sampling_method=sampling_method, - buckets_path=buckets_path, - **kwargs, - ) - - -class BucketCorrelation(Pipeline[_R]): - """ - A sibling pipeline aggregation which runs a correlation function on - the configured sibling multi-bucket aggregation. - - :arg function: (required) The correlation function to execute. - :arg buckets_path: Path to the buckets that contain one set of values - to correlate. - """ - - name = "bucket_correlation" - - def __init__( - self, - *, - function: Union[ - "types.BucketCorrelationFunction", Dict[str, Any], "DefaultType" - ] = DEFAULT, - buckets_path: Union[ - str, Sequence[str], Mapping[str, str], "DefaultType" - ] = DEFAULT, - **kwargs: Any, - ): - super().__init__(function=function, buckets_path=buckets_path, **kwargs) - - -class Cardinality(Agg[_R]): - """ - A single-value metrics aggregation that calculates an approximate - count of distinct values. - - :arg precision_threshold: A unique count below which counts are - expected to be close to accurate. This allows to trade memory for - accuracy. Defaults to `3000` if omitted. - :arg rehash: - :arg execution_hint: Mechanism by which cardinality aggregations is - run. - :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 = "cardinality" - - def __init__( - self, - *, - precision_threshold: Union[int, "DefaultType"] = DEFAULT, - rehash: Union[bool, "DefaultType"] = DEFAULT, - execution_hint: Union[ - Literal[ - "global_ordinals", - "segment_ordinals", - "direct", - "save_memory_heuristic", - "save_time_heuristic", - ], - "DefaultType", - ] = DEFAULT, - 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__( - precision_threshold=precision_threshold, - rehash=rehash, - execution_hint=execution_hint, - field=field, - missing=missing, - script=script, - **kwargs, - ) - - -class CategorizeText(Bucket[_R]): - """ - A multi-bucket aggregation that groups semi-structured text into - buckets. - - :arg field: (required) The semi-structured text field to categorize. - :arg max_unique_tokens: The maximum number of unique tokens at any - position up to max_matched_tokens. Must be larger than 1. Smaller - values use less memory and create fewer categories. Larger values - will use more memory and create narrower categories. Max allowed - value is 100. Defaults to `50` if omitted. - :arg max_matched_tokens: The maximum number of token positions to - match on before attempting to merge categories. Larger values will - use more memory and create narrower categories. Max allowed value - is 100. Defaults to `5` if omitted. - :arg similarity_threshold: The minimum percentage of tokens that must - match for text to be added to the category bucket. Must be between - 1 and 100. The larger the value the narrower the categories. - Larger values will increase memory usage and create narrower - categories. Defaults to `50` if omitted. - :arg categorization_filters: This property expects an array of regular - expressions. The expressions are used to filter out matching - sequences from the categorization field values. You can use this - functionality to fine tune the categorization by excluding - sequences from consideration when categories are defined. For - example, you can exclude SQL statements that appear in your log - files. This property cannot be used at the same time as - categorization_analyzer. If you only want to define simple regular - expression filters that are applied prior to tokenization, setting - this property is the easiest method. If you also want to customize - the tokenizer or post-tokenization filtering, use the - categorization_analyzer property instead and include the filters - as pattern_replace character filters. - :arg categorization_analyzer: The categorization analyzer specifies - how the text is analyzed and tokenized before being categorized. - The syntax is very similar to that used to define the analyzer in - the [Analyze endpoint](https://www.elastic.co/guide/en/elasticsear - ch/reference/8.0/indices-analyze.html). This property cannot be - used at the same time as categorization_filters. - :arg shard_size: The number of categorization buckets to return from - each shard before merging all the results. - :arg size: The number of buckets to return. Defaults to `10` if - omitted. - :arg min_doc_count: The minimum number of documents in a bucket to be - returned to the results. - :arg shard_min_doc_count: The minimum number of documents in a bucket - to be returned from the shard before merging. - """ - - name = "categorize_text" - - def __init__( - self, - *, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - max_unique_tokens: Union[int, "DefaultType"] = DEFAULT, - max_matched_tokens: Union[int, "DefaultType"] = DEFAULT, - similarity_threshold: Union[int, "DefaultType"] = DEFAULT, - categorization_filters: Union[Sequence[str], "DefaultType"] = DEFAULT, - categorization_analyzer: Union[ - str, "types.CustomCategorizeTextAnalyzer", Dict[str, Any], "DefaultType" - ] = DEFAULT, - shard_size: Union[int, "DefaultType"] = DEFAULT, - size: Union[int, "DefaultType"] = DEFAULT, - min_doc_count: Union[int, "DefaultType"] = DEFAULT, - shard_min_doc_count: Union[int, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - field=field, - max_unique_tokens=max_unique_tokens, - max_matched_tokens=max_matched_tokens, - similarity_threshold=similarity_threshold, - categorization_filters=categorization_filters, - categorization_analyzer=categorization_analyzer, - shard_size=shard_size, - size=size, - min_doc_count=min_doc_count, - shard_min_doc_count=shard_min_doc_count, - **kwargs, - ) - - -class Children(Bucket[_R]): - """ - A single bucket aggregation that selects child documents that have the - specified type, as defined in a `join` field. - - :arg type: The child type that should be selected. - """ - - name = "children" - - def __init__(self, type: Union[str, "DefaultType"] = DEFAULT, **kwargs: Any): - super().__init__(type=type, **kwargs) - - -class Composite(Bucket[_R]): - """ - A multi-bucket aggregation that creates composite buckets from - different sources. Unlike the other multi-bucket aggregations, you can - use the `composite` aggregation to paginate *all* buckets from a - multi-level aggregation efficiently. - - :arg after: When paginating, use the `after_key` value returned in the - previous response to retrieve the next page. - :arg size: The number of composite buckets that should be returned. - Defaults to `10` if omitted. - :arg sources: The value sources used to build composite buckets. Keys - are returned in the order of the `sources` definition. - """ - - name = "composite" - - def __init__( - self, - *, - after: Union[ - Mapping[ - Union[str, "InstrumentedField"], Union[int, float, str, bool, None, Any] - ], - "DefaultType", - ] = DEFAULT, - size: Union[int, "DefaultType"] = DEFAULT, - sources: Union[Sequence[Mapping[str, Agg[_R]]], "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(after=after, size=size, sources=sources, **kwargs) - - -class CumulativeCardinality(Pipeline[_R]): - """ - A parent pipeline aggregation which calculates the cumulative - cardinality in a parent `histogram` or `date_histogram` aggregation. - - :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 = "cumulative_cardinality" - - 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 CumulativeSum(Pipeline[_R]): - """ - A parent pipeline aggregation which calculates the cumulative sum of a - specified metric in a parent `histogram` or `date_histogram` - aggregation. - - :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 = "cumulative_sum" - - 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 DateHistogram(Bucket[_R]): - """ - A multi-bucket values source based aggregation that can be applied on - date values or date range values extracted from the documents. It - dynamically builds fixed size (interval) buckets over the values. - - :arg calendar_interval: Calendar-aware interval. Can be specified - using the unit name, such as `month`, or as a single unit - quantity, such as `1M`. - :arg extended_bounds: Enables extending the bounds of the histogram - beyond the data itself. - :arg hard_bounds: Limits the histogram to specified bounds. - :arg field: The date field whose values are use to build a histogram. - :arg fixed_interval: Fixed intervals: a fixed number of SI units and - never deviate, regardless of where they fall on the calendar. - :arg format: The date format used to format `key_as_string` in the - response. If no `format` is specified, the first date format - specified in the field mapping is used. - :arg interval: - :arg min_doc_count: Only returns buckets that have `min_doc_count` - number of documents. By default, all buckets between the first - bucket that matches documents and the last one are returned. - :arg missing: The value to apply to documents that do not have a - value. By default, documents without a value are ignored. - :arg offset: Changes the start value of each bucket by the specified - positive (`+`) or negative offset (`-`) duration. - :arg order: The sort order of the returned buckets. - :arg params: - :arg script: - :arg time_zone: Time zone used for bucketing and rounding. Defaults to - Coordinated Universal Time (UTC). - :arg keyed: Set to `true` to associate a unique string key with each - bucket and return the ranges as a hash rather than an array. - """ - - name = "date_histogram" - - def __init__( - self, - *, - calendar_interval: Union[ - Literal[ - "second", "minute", "hour", "day", "week", "month", "quarter", "year" - ], - "DefaultType", - ] = DEFAULT, - extended_bounds: Union[ - "types.ExtendedBounds", Dict[str, Any], "DefaultType" - ] = DEFAULT, - hard_bounds: Union[ - "types.ExtendedBounds", Dict[str, Any], "DefaultType" - ] = DEFAULT, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - fixed_interval: Any = DEFAULT, - format: Union[str, "DefaultType"] = DEFAULT, - interval: Any = DEFAULT, - min_doc_count: Union[int, "DefaultType"] = DEFAULT, - missing: Any = DEFAULT, - offset: Any = DEFAULT, - order: Union[ - Mapping[Union[str, "InstrumentedField"], Literal["asc", "desc"]], - Sequence[Mapping[Union[str, "InstrumentedField"], Literal["asc", "desc"]]], - "DefaultType", - ] = DEFAULT, - params: Union[Mapping[str, Any], "DefaultType"] = DEFAULT, - script: Union["types.Script", Dict[str, Any], "DefaultType"] = DEFAULT, - time_zone: Union[str, "DefaultType"] = DEFAULT, - keyed: Union[bool, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - calendar_interval=calendar_interval, - extended_bounds=extended_bounds, - hard_bounds=hard_bounds, - field=field, - fixed_interval=fixed_interval, - format=format, - interval=interval, - min_doc_count=min_doc_count, - missing=missing, - offset=offset, - order=order, - params=params, - script=script, - time_zone=time_zone, - keyed=keyed, - **kwargs, - ) - - def result(self, search: "SearchBase[_R]", data: Any) -> AttrDict[Any]: - return FieldBucketData(self, search, data) - - -class DateRange(Bucket[_R]): - """ - A multi-bucket value source based aggregation that enables the user to - define a set of date ranges - each representing a bucket. - - :arg field: The date field whose values are use to build ranges. - :arg format: The date format used to format `from` and `to` in the - response. - :arg missing: The value to apply to documents that do not have a - value. By default, documents without a value are ignored. - :arg ranges: Array of date ranges. - :arg time_zone: Time zone used to convert dates from another time zone - to UTC. - :arg keyed: Set to `true` to associate a unique string key with each - bucket and returns the ranges as a hash rather than an array. - """ - - name = "date_range" - - def __init__( - self, - *, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - format: Union[str, "DefaultType"] = DEFAULT, - missing: Union[str, int, float, bool, "DefaultType"] = DEFAULT, - ranges: Union[ - Sequence["types.DateRangeExpression"], - Sequence[Dict[str, Any]], - "DefaultType", - ] = DEFAULT, - time_zone: Union[str, "DefaultType"] = DEFAULT, - keyed: Union[bool, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - field=field, - format=format, - missing=missing, - ranges=ranges, - time_zone=time_zone, - keyed=keyed, - **kwargs, - ) - - -class Derivative(Pipeline[_R]): - """ - A parent pipeline aggregation which calculates the derivative of a - specified metric in a parent `histogram` or `date_histogram` - aggregation. - - :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 = "derivative" - - 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 DiversifiedSampler(Bucket[_R]): - """ - A filtering aggregation used to limit any sub aggregations' processing - to a sample of the top-scoring documents. Similar to the `sampler` - aggregation, but adds the ability to limit the number of matches that - share a common value. - - :arg execution_hint: The type of value used for de-duplication. - Defaults to `global_ordinals` if omitted. - :arg max_docs_per_value: Limits how many documents are permitted per - choice of de-duplicating value. Defaults to `1` if omitted. - :arg script: - :arg shard_size: Limits how many top-scoring documents are collected - in the sample processed on each shard. Defaults to `100` if - omitted. - :arg field: The field used to provide values used for de-duplication. - """ - - name = "diversified_sampler" - - def __init__( - self, - *, - execution_hint: Union[ - Literal["map", "global_ordinals", "bytes_hash"], "DefaultType" - ] = DEFAULT, - max_docs_per_value: Union[int, "DefaultType"] = DEFAULT, - script: Union["types.Script", Dict[str, Any], "DefaultType"] = DEFAULT, - shard_size: Union[int, "DefaultType"] = DEFAULT, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - execution_hint=execution_hint, - max_docs_per_value=max_docs_per_value, - script=script, - shard_size=shard_size, - field=field, - **kwargs, - ) - - -class ExtendedStats(Agg[_R]): - """ - A multi-value metrics aggregation that computes stats over numeric - values extracted from the aggregated documents. - - :arg sigma: The number of standard deviations above/below the mean to - display. - :arg format: - :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 = "extended_stats" - - def __init__( - self, - *, - sigma: Union[float, "DefaultType"] = DEFAULT, - format: Union[str, "DefaultType"] = DEFAULT, - 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__( - sigma=sigma, - format=format, - field=field, - missing=missing, - script=script, - **kwargs, - ) - - -class ExtendedStatsBucket(Pipeline[_R]): - """ - A sibling pipeline aggregation which calculates a variety of stats - across all bucket of a specified metric in a sibling aggregation. - - :arg sigma: The number of standard deviations above/below the mean to - display. - :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 = "extended_stats_bucket" - - def __init__( - self, - *, - sigma: Union[float, "DefaultType"] = DEFAULT, - 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__( - sigma=sigma, - format=format, - gap_policy=gap_policy, - buckets_path=buckets_path, - **kwargs, - ) - - -class FrequentItemSets(Agg[_R]): - """ - A bucket aggregation which finds frequent item sets, a form of - association rules mining that identifies items that often occur - together. - - :arg fields: (required) Fields to analyze. - :arg minimum_set_size: The minimum size of one item set. Defaults to - `1` if omitted. - :arg minimum_support: The minimum support of one item set. Defaults to - `0.1` if omitted. - :arg size: The number of top item sets to return. Defaults to `10` if - omitted. - :arg filter: Query that filters documents from analysis. - """ - - name = "frequent_item_sets" - _param_defs = { - "filter": {"type": "query"}, - } - - def __init__( - self, - *, - fields: Union[ - Sequence["types.FrequentItemSetsField"], - Sequence[Dict[str, Any]], - "DefaultType", - ] = DEFAULT, - minimum_set_size: Union[int, "DefaultType"] = DEFAULT, - minimum_support: Union[float, "DefaultType"] = DEFAULT, - size: Union[int, "DefaultType"] = DEFAULT, - filter: Union[Query, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - fields=fields, - minimum_set_size=minimum_set_size, - minimum_support=minimum_support, - size=size, - filter=filter, - **kwargs, - ) - - -class Filter(Bucket[_R]): - """ - A single bucket aggregation that narrows the set of documents to those - that match a query. - - :arg filter: A single bucket aggregation that narrows the set of - documents to those that match a query. - """ - - name = "filter" - _param_defs = { - "filter": {"type": "query"}, - "aggs": {"type": "agg", "hash": True}, - } - - def __init__(self, filter: Union[Query, "DefaultType"] = DEFAULT, **kwargs: Any): - super().__init__(filter=filter, **kwargs) - - def to_dict(self) -> Dict[str, Any]: - d = super().to_dict() - if isinstance(d[self.name], dict): - n = cast(AttrDict[Any], d[self.name]) - n.update(n.pop("filter", {})) - return d - - -class Filters(Bucket[_R]): - """ - A multi-bucket aggregation where each bucket contains the documents - that match a query. - - :arg filters: Collection of queries from which to build buckets. - :arg other_bucket: Set to `true` to add a bucket to the response which - will contain all documents that do not match any of the given - filters. - :arg other_bucket_key: The key with which the other bucket is - returned. Defaults to `_other_` if omitted. - :arg keyed: By default, the named filters aggregation returns the - buckets as an object. Set to `false` to return the buckets as an - array of objects. Defaults to `True` if omitted. - """ - - name = "filters" - _param_defs = { - "filters": {"type": "query", "hash": True}, - "aggs": {"type": "agg", "hash": True}, - } - - def __init__( - self, - *, - filters: Union[Dict[str, Query], "DefaultType"] = DEFAULT, - other_bucket: Union[bool, "DefaultType"] = DEFAULT, - other_bucket_key: Union[str, "DefaultType"] = DEFAULT, - keyed: Union[bool, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - filters=filters, - other_bucket=other_bucket, - other_bucket_key=other_bucket_key, - keyed=keyed, - **kwargs, - ) - - -class GeoBounds(Agg[_R]): - """ - A metric aggregation that computes the geographic bounding box - containing all values for a Geopoint or Geoshape field. - - :arg wrap_longitude: Specifies whether the bounding box should be - allowed to overlap the international date line. Defaults to `True` - if omitted. - :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 = "geo_bounds" - - def __init__( - self, - *, - wrap_longitude: Union[bool, "DefaultType"] = DEFAULT, - 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__( - wrap_longitude=wrap_longitude, - field=field, - missing=missing, - script=script, - **kwargs, - ) - - -class GeoCentroid(Agg[_R]): - """ - A metric aggregation that computes the weighted centroid from all - coordinate values for geo fields. - - :arg count: - :arg location: - :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 = "geo_centroid" - - def __init__( - self, - *, - count: Union[int, "DefaultType"] = DEFAULT, - location: Union[ - "types.LatLonGeoLocation", - "types.GeoHashLocation", - Sequence[float], - str, - Dict[str, Any], - "DefaultType", - ] = DEFAULT, - 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__( - count=count, - location=location, - field=field, - missing=missing, - script=script, - **kwargs, - ) - - -class GeoDistance(Bucket[_R]): - """ - A multi-bucket aggregation that works on `geo_point` fields. Evaluates - the distance of each document value from an origin point and - determines the buckets it belongs to, based on ranges defined in the - request. - - :arg distance_type: The distance calculation type. Defaults to `arc` - if omitted. - :arg field: A field of type `geo_point` used to evaluate the distance. - :arg origin: The origin used to evaluate the distance. - :arg ranges: An array of ranges used to bucket documents. - :arg unit: The distance unit. Defaults to `m` if omitted. - """ - - name = "geo_distance" - - def __init__( - self, - *, - distance_type: Union[Literal["arc", "plane"], "DefaultType"] = DEFAULT, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - origin: Union[ - "types.LatLonGeoLocation", - "types.GeoHashLocation", - Sequence[float], - str, - Dict[str, Any], - "DefaultType", - ] = DEFAULT, - ranges: Union[ - Sequence["types.AggregationRange"], Sequence[Dict[str, Any]], "DefaultType" - ] = DEFAULT, - unit: Union[ - Literal["in", "ft", "yd", "mi", "nmi", "km", "m", "cm", "mm"], "DefaultType" - ] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - distance_type=distance_type, - field=field, - origin=origin, - ranges=ranges, - unit=unit, - **kwargs, - ) - - -class GeohashGrid(Bucket[_R]): - """ - A multi-bucket aggregation that groups `geo_point` and `geo_shape` - values into buckets that represent a grid. Each cell is labeled using - a geohash which is of user-definable precision. - - :arg bounds: The bounding box to filter the points in each bucket. - :arg field: Field containing indexed `geo_point` or `geo_shape` - values. If the field contains an array, `geohash_grid` aggregates - all array values. - :arg precision: The string length of the geohashes used to define - cells/buckets in the results. Defaults to `5` if omitted. - :arg shard_size: Allows for more accurate counting of the top cells - returned in the final result the aggregation. Defaults to - returning `max(10,(size x number-of-shards))` buckets from each - shard. - :arg size: The maximum number of geohash buckets to return. Defaults - to `10000` if omitted. - """ - - name = "geohash_grid" - - def __init__( - self, - *, - bounds: Union[ - "types.CoordsGeoBounds", - "types.TopLeftBottomRightGeoBounds", - "types.TopRightBottomLeftGeoBounds", - "types.WktGeoBounds", - Dict[str, Any], - "DefaultType", - ] = DEFAULT, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - precision: Union[float, str, "DefaultType"] = DEFAULT, - shard_size: Union[int, "DefaultType"] = DEFAULT, - size: Union[int, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - bounds=bounds, - field=field, - precision=precision, - shard_size=shard_size, - size=size, - **kwargs, - ) - - -class GeoLine(Agg[_R]): - """ - Aggregates all `geo_point` values within a bucket into a `LineString` - ordered by the chosen sort field. - - :arg point: (required) The name of the geo_point field. - :arg sort: (required) The name of the numeric field to use as the sort - key for ordering the points. When the `geo_line` aggregation is - nested inside a `time_series` aggregation, this field defaults to - `@timestamp`, and any other value will result in error. - :arg include_sort: When `true`, returns an additional array of the - sort values in the feature properties. - :arg sort_order: The order in which the line is sorted (ascending or - descending). Defaults to `asc` if omitted. - :arg size: The maximum length of the line represented in the - aggregation. Valid sizes are between 1 and 10000. Defaults to - `10000` if omitted. - """ - - name = "geo_line" - - def __init__( - self, - *, - point: Union["types.GeoLinePoint", Dict[str, Any], "DefaultType"] = DEFAULT, - sort: Union["types.GeoLineSort", Dict[str, Any], "DefaultType"] = DEFAULT, - include_sort: Union[bool, "DefaultType"] = DEFAULT, - sort_order: Union[Literal["asc", "desc"], "DefaultType"] = DEFAULT, - size: Union[int, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - point=point, - sort=sort, - include_sort=include_sort, - sort_order=sort_order, - size=size, - **kwargs, - ) - - -class GeotileGrid(Bucket[_R]): - """ - A multi-bucket aggregation that groups `geo_point` and `geo_shape` - values into buckets that represent a grid. Each cell corresponds to a - map tile as used by many online map sites. - - :arg field: Field containing indexed `geo_point` or `geo_shape` - values. If the field contains an array, `geotile_grid` aggregates - all array values. - :arg precision: Integer zoom of the key used to define cells/buckets - in the results. Values outside of the range [0,29] will be - rejected. Defaults to `7` if omitted. - :arg shard_size: Allows for more accurate counting of the top cells - returned in the final result the aggregation. Defaults to - returning `max(10,(size x number-of-shards))` buckets from each - shard. - :arg size: The maximum number of buckets to return. Defaults to - `10000` if omitted. - :arg bounds: A bounding box to filter the geo-points or geo-shapes in - each bucket. - """ - - name = "geotile_grid" - - def __init__( - self, - *, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - precision: Union[float, "DefaultType"] = DEFAULT, - shard_size: Union[int, "DefaultType"] = DEFAULT, - size: Union[int, "DefaultType"] = DEFAULT, - bounds: Union[ - "types.CoordsGeoBounds", - "types.TopLeftBottomRightGeoBounds", - "types.TopRightBottomLeftGeoBounds", - "types.WktGeoBounds", - Dict[str, Any], - "DefaultType", - ] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - field=field, - precision=precision, - shard_size=shard_size, - size=size, - bounds=bounds, - **kwargs, - ) - - -class GeohexGrid(Bucket[_R]): - """ - A multi-bucket aggregation that groups `geo_point` and `geo_shape` - values into buckets that represent a grid. Each cell corresponds to a - H3 cell index and is labeled using the H3Index representation. - - :arg field: (required) Field containing indexed `geo_point` or - `geo_shape` values. If the field contains an array, `geohex_grid` - aggregates all array values. - :arg precision: Integer zoom of the key used to defined cells or - buckets in the results. Value should be between 0-15. Defaults to - `6` if omitted. - :arg bounds: Bounding box used to filter the geo-points in each - bucket. - :arg size: Maximum number of buckets to return. Defaults to `10000` if - omitted. - :arg shard_size: Number of buckets returned from each shard. - """ - - name = "geohex_grid" - - def __init__( - self, - *, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - precision: Union[int, "DefaultType"] = DEFAULT, - bounds: Union[ - "types.CoordsGeoBounds", - "types.TopLeftBottomRightGeoBounds", - "types.TopRightBottomLeftGeoBounds", - "types.WktGeoBounds", - Dict[str, Any], - "DefaultType", - ] = DEFAULT, - size: Union[int, "DefaultType"] = DEFAULT, - shard_size: Union[int, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - field=field, - precision=precision, - bounds=bounds, - size=size, - shard_size=shard_size, - **kwargs, - ) - - -class Global(Bucket[_R]): - """ - Defines a single bucket of all the documents within the search - execution context. This context is defined by the indices and the - document types you’re searching on, but is not influenced by the - search query itself. - """ - - name = "global" - - def __init__(self, **kwargs: Any): - super().__init__(**kwargs) - - -class Histogram(Bucket[_R]): - """ - A multi-bucket values source based aggregation that can be applied on - numeric values or numeric range values extracted from the documents. - It dynamically builds fixed size (interval) buckets over the values. - - :arg extended_bounds: Enables extending the bounds of the histogram - beyond the data itself. - :arg hard_bounds: Limits the range of buckets in the histogram. It is - particularly useful in the case of open data ranges that can - result in a very large number of buckets. - :arg field: The name of the field to aggregate on. - :arg interval: The interval for the buckets. Must be a positive - decimal. - :arg min_doc_count: Only returns buckets that have `min_doc_count` - number of documents. By default, the response will fill gaps in - the histogram with empty buckets. - :arg missing: The value to apply to documents that do not have a - value. By default, documents without a value are ignored. - :arg offset: By default, the bucket keys start with 0 and then - continue in even spaced steps of `interval`. The bucket boundaries - can be shifted by using the `offset` option. - :arg order: The sort order of the returned buckets. By default, the - returned buckets are sorted by their key ascending. - :arg script: - :arg format: - :arg keyed: If `true`, returns buckets as a hash instead of an array, - keyed by the bucket keys. - """ - - name = "histogram" - - def __init__( - self, - *, - extended_bounds: Union[ - "types.ExtendedBounds", Dict[str, Any], "DefaultType" - ] = DEFAULT, - hard_bounds: Union[ - "types.ExtendedBounds", Dict[str, Any], "DefaultType" - ] = DEFAULT, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - interval: Union[float, "DefaultType"] = DEFAULT, - min_doc_count: Union[int, "DefaultType"] = DEFAULT, - missing: Union[float, "DefaultType"] = DEFAULT, - offset: Union[float, "DefaultType"] = DEFAULT, - order: Union[ - Mapping[Union[str, "InstrumentedField"], Literal["asc", "desc"]], - Sequence[Mapping[Union[str, "InstrumentedField"], Literal["asc", "desc"]]], - "DefaultType", - ] = DEFAULT, - script: Union["types.Script", Dict[str, Any], "DefaultType"] = DEFAULT, - format: Union[str, "DefaultType"] = DEFAULT, - keyed: Union[bool, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - extended_bounds=extended_bounds, - hard_bounds=hard_bounds, - field=field, - interval=interval, - min_doc_count=min_doc_count, - missing=missing, - offset=offset, - order=order, - script=script, - format=format, - keyed=keyed, - **kwargs, - ) - - def result(self, search: "SearchBase[_R]", data: Any) -> AttrDict[Any]: - return FieldBucketData(self, search, data) - - -class IPRange(Bucket[_R]): - """ - A multi-bucket value source based aggregation that enables the user to - define a set of IP ranges - each representing a bucket. - - :arg field: The date field whose values are used to build ranges. - :arg ranges: Array of IP ranges. - """ - - name = "ip_range" - - def __init__( - self, - *, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - ranges: Union[ - Sequence["types.IpRangeAggregationRange"], - Sequence[Dict[str, Any]], - "DefaultType", - ] = DEFAULT, - **kwargs: Any, - ): - super().__init__(field=field, ranges=ranges, **kwargs) - - -class IPPrefix(Bucket[_R]): - """ - A bucket aggregation that groups documents based on the network or - sub-network of an IP address. - - :arg field: (required) The IP address field to aggregation on. The - field mapping type must be `ip`. - :arg prefix_length: (required) Length of the network prefix. For IPv4 - addresses the accepted range is [0, 32]. For IPv6 addresses the - accepted range is [0, 128]. - :arg is_ipv6: Defines whether the prefix applies to IPv6 addresses. - :arg append_prefix_length: Defines whether the prefix length is - appended to IP address keys in the response. - :arg keyed: Defines whether buckets are returned as a hash rather than - an array in the response. - :arg min_doc_count: Minimum number of documents in a bucket for it to - be included in the response. Defaults to `1` if omitted. - """ - - name = "ip_prefix" - - def __init__( - self, - *, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - prefix_length: Union[int, "DefaultType"] = DEFAULT, - is_ipv6: Union[bool, "DefaultType"] = DEFAULT, - append_prefix_length: Union[bool, "DefaultType"] = DEFAULT, - keyed: Union[bool, "DefaultType"] = DEFAULT, - min_doc_count: Union[int, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - field=field, - prefix_length=prefix_length, - is_ipv6=is_ipv6, - append_prefix_length=append_prefix_length, - keyed=keyed, - min_doc_count=min_doc_count, - **kwargs, - ) - - -class Inference(Pipeline[_R]): - """ - A parent pipeline aggregation which loads a pre-trained model and - performs inference on the collated result fields from the parent - bucket aggregation. - - :arg model_id: (required) The ID or alias for the trained model. - :arg inference_config: Contains the inference type and its options. - :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 = "inference" - - def __init__( - self, - *, - model_id: Union[str, "DefaultType"] = DEFAULT, - inference_config: Union[ - "types.InferenceConfigContainer", Dict[str, Any], "DefaultType" - ] = DEFAULT, - 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__( - model_id=model_id, - inference_config=inference_config, - format=format, - gap_policy=gap_policy, - buckets_path=buckets_path, - **kwargs, - ) - - -class Line(Agg[_R]): - """ - :arg point: (required) The name of the geo_point field. - :arg sort: (required) The name of the numeric field to use as the sort - key for ordering the points. When the `geo_line` aggregation is - nested inside a `time_series` aggregation, this field defaults to - `@timestamp`, and any other value will result in error. - :arg include_sort: When `true`, returns an additional array of the - sort values in the feature properties. - :arg sort_order: The order in which the line is sorted (ascending or - descending). Defaults to `asc` if omitted. - :arg size: The maximum length of the line represented in the - aggregation. Valid sizes are between 1 and 10000. Defaults to - `10000` if omitted. - """ - - name = "line" - - def __init__( - self, - *, - point: Union["types.GeoLinePoint", Dict[str, Any], "DefaultType"] = DEFAULT, - sort: Union["types.GeoLineSort", Dict[str, Any], "DefaultType"] = DEFAULT, - include_sort: Union[bool, "DefaultType"] = DEFAULT, - sort_order: Union[Literal["asc", "desc"], "DefaultType"] = DEFAULT, - size: Union[int, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - point=point, - sort=sort, - include_sort=include_sort, - sort_order=sort_order, - size=size, - **kwargs, - ) - - -class MatrixStats(Agg[_R]): - """ - A numeric aggregation that computes the following statistics over a - set of document fields: `count`, `mean`, `variance`, `skewness`, - `kurtosis`, `covariance`, and `covariance`. - - :arg mode: Array value the aggregation will use for array or multi- - valued fields. Defaults to `avg` if omitted. - :arg fields: An array of fields for computing the statistics. - :arg missing: The value to apply to documents that do not have a - value. By default, documents without a value are ignored. - """ - - name = "matrix_stats" - - def __init__( - self, - *, - mode: Union[ - Literal["min", "max", "sum", "avg", "median"], "DefaultType" - ] = DEFAULT, - fields: Union[ - Union[str, "InstrumentedField"], - Sequence[Union[str, "InstrumentedField"]], - "DefaultType", - ] = DEFAULT, - missing: Union[ - Mapping[Union[str, "InstrumentedField"], float], "DefaultType" - ] = DEFAULT, - **kwargs: Any, - ): - super().__init__(mode=mode, fields=fields, missing=missing, **kwargs) - - -class Max(Agg[_R]): - """ - A single-value metrics aggregation that returns the maximum value - among the numeric values extracted from the aggregated documents. - - :arg format: - :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 = "max" - - def __init__( - self, - *, - format: Union[str, "DefaultType"] = DEFAULT, - 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__( - format=format, field=field, missing=missing, script=script, **kwargs - ) - - -class MaxBucket(Pipeline[_R]): - """ - A sibling pipeline aggregation which identifies the bucket(s) with the - maximum value of a specified metric in a sibling aggregation and - outputs both the value and the key(s) of the bucket(s). - - :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 = "max_bucket" - - 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 MedianAbsoluteDeviation(Agg[_R]): - """ - A single-value aggregation that approximates the median absolute - deviation of its search results. - - :arg compression: Limits the maximum number of nodes used by the - underlying TDigest algorithm to `20 * compression`, enabling - control of memory usage and approximation error. Defaults to - `1000` if omitted. - :arg format: - :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 = "median_absolute_deviation" - - def __init__( - self, - *, - compression: Union[float, "DefaultType"] = DEFAULT, - format: Union[str, "DefaultType"] = DEFAULT, - 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__( - compression=compression, - format=format, - field=field, - missing=missing, - script=script, - **kwargs, - ) - - -class Min(Agg[_R]): - """ - A single-value metrics aggregation that returns the minimum value - among numeric values extracted from the aggregated documents. - - :arg format: - :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 = "min" - - def __init__( - self, - *, - format: Union[str, "DefaultType"] = DEFAULT, - 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__( - format=format, field=field, missing=missing, script=script, **kwargs - ) - - -class MinBucket(Pipeline[_R]): - """ - A sibling pipeline aggregation which identifies the bucket(s) with the - minimum value of a specified metric in a sibling aggregation and - outputs both the value and the key(s) of the bucket(s). - - :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 = "min_bucket" - - 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 Missing(Bucket[_R]): - """ - A field data based single bucket aggregation, that creates a bucket of - all documents in the current document set context that are missing a - field value (effectively, missing a field or having the configured - NULL value set). - - :arg field: The name of the field. - :arg missing: - """ - - name = "missing" - - def __init__( - self, - *, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - missing: Union[str, int, float, bool, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(field=field, missing=missing, **kwargs) - - -class MovingAvg(Pipeline[_R]): - """ """ - - name = "moving_avg" - - def __init__(self, **kwargs: Any): - super().__init__(**kwargs) - - -class LinearMovingAverageAggregation(MovingAvg[_R]): - """ - :arg model: (required) - :arg settings: (required) - :arg minimize: - :arg predict: - :arg window: - :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. - """ - - def __init__( - self, - *, - model: Any = DEFAULT, - settings: Union["types.EmptyObject", Dict[str, Any], "DefaultType"] = DEFAULT, - minimize: Union[bool, "DefaultType"] = DEFAULT, - predict: Union[int, "DefaultType"] = DEFAULT, - window: Union[int, "DefaultType"] = DEFAULT, - 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__( - model=model, - settings=settings, - minimize=minimize, - predict=predict, - window=window, - format=format, - gap_policy=gap_policy, - buckets_path=buckets_path, - **kwargs, - ) - - -class SimpleMovingAverageAggregation(MovingAvg[_R]): - """ - :arg model: (required) - :arg settings: (required) - :arg minimize: - :arg predict: - :arg window: - :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. - """ - - def __init__( - self, - *, - model: Any = DEFAULT, - settings: Union["types.EmptyObject", Dict[str, Any], "DefaultType"] = DEFAULT, - minimize: Union[bool, "DefaultType"] = DEFAULT, - predict: Union[int, "DefaultType"] = DEFAULT, - window: Union[int, "DefaultType"] = DEFAULT, - 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__( - model=model, - settings=settings, - minimize=minimize, - predict=predict, - window=window, - format=format, - gap_policy=gap_policy, - buckets_path=buckets_path, - **kwargs, - ) - - -class EwmaMovingAverageAggregation(MovingAvg[_R]): - """ - :arg model: (required) - :arg settings: (required) - :arg minimize: - :arg predict: - :arg window: - :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. - """ - - def __init__( - self, - *, - model: Any = DEFAULT, - settings: Union[ - "types.EwmaModelSettings", Dict[str, Any], "DefaultType" - ] = DEFAULT, - minimize: Union[bool, "DefaultType"] = DEFAULT, - predict: Union[int, "DefaultType"] = DEFAULT, - window: Union[int, "DefaultType"] = DEFAULT, - 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__( - model=model, - settings=settings, - minimize=minimize, - predict=predict, - window=window, - format=format, - gap_policy=gap_policy, - buckets_path=buckets_path, - **kwargs, - ) - - -class HoltMovingAverageAggregation(MovingAvg[_R]): - """ - :arg model: (required) - :arg settings: (required) - :arg minimize: - :arg predict: - :arg window: - :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. - """ - - def __init__( - self, - *, - model: Any = DEFAULT, - settings: Union[ - "types.HoltLinearModelSettings", Dict[str, Any], "DefaultType" - ] = DEFAULT, - minimize: Union[bool, "DefaultType"] = DEFAULT, - predict: Union[int, "DefaultType"] = DEFAULT, - window: Union[int, "DefaultType"] = DEFAULT, - 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__( - model=model, - settings=settings, - minimize=minimize, - predict=predict, - window=window, - format=format, - gap_policy=gap_policy, - buckets_path=buckets_path, - **kwargs, - ) - - -class HoltWintersMovingAverageAggregation(MovingAvg[_R]): - """ - :arg model: (required) - :arg settings: (required) - :arg minimize: - :arg predict: - :arg window: - :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. - """ - - def __init__( - self, - *, - model: Any = DEFAULT, - settings: Union[ - "types.HoltWintersModelSettings", Dict[str, Any], "DefaultType" - ] = DEFAULT, - minimize: Union[bool, "DefaultType"] = DEFAULT, - predict: Union[int, "DefaultType"] = DEFAULT, - window: Union[int, "DefaultType"] = DEFAULT, - 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__( - model=model, - settings=settings, - minimize=minimize, - predict=predict, - window=window, - format=format, - gap_policy=gap_policy, - buckets_path=buckets_path, - **kwargs, - ) - - -class MovingPercentiles(Pipeline[_R]): - """ - Given an ordered series of percentiles, "slides" a window across those - percentiles and computes cumulative percentiles. - - :arg window: The size of window to "slide" across the histogram. - :arg shift: By default, the window consists of the last n values - excluding the current bucket. Increasing `shift` by 1, moves the - starting window position by 1 to the right. - :arg keyed: - :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 = "moving_percentiles" - - def __init__( - self, - *, - window: Union[int, "DefaultType"] = DEFAULT, - shift: Union[int, "DefaultType"] = DEFAULT, - keyed: Union[bool, "DefaultType"] = DEFAULT, - 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__( - window=window, - shift=shift, - keyed=keyed, - format=format, - gap_policy=gap_policy, - buckets_path=buckets_path, - **kwargs, - ) - - -class MovingFn(Pipeline[_R]): - """ - Given an ordered series of data, "slides" a window across the data and - runs a custom script on each window of data. For convenience, a number - of common functions are predefined such as `min`, `max`, and moving - averages. - - :arg script: The script that should be executed on each window of - data. - :arg shift: By default, the window consists of the last n values - excluding the current bucket. Increasing `shift` by 1, moves the - starting window position by 1 to the right. - :arg window: The size of window to "slide" across the histogram. - :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 = "moving_fn" - - def __init__( - self, - *, - script: Union[str, "DefaultType"] = DEFAULT, - shift: Union[int, "DefaultType"] = DEFAULT, - window: Union[int, "DefaultType"] = DEFAULT, - 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__( - script=script, - shift=shift, - window=window, - format=format, - gap_policy=gap_policy, - buckets_path=buckets_path, - **kwargs, - ) - - -class MultiTerms(Bucket[_R]): - """ - A multi-bucket value source based aggregation where buckets are - dynamically built - one per unique set of values. - - :arg terms: (required) The field from which to generate sets of terms. - :arg collect_mode: Specifies the strategy for data collection. - Defaults to `breadth_first` if omitted. - :arg order: Specifies the sort order of the buckets. Defaults to - sorting by descending document count. - :arg min_doc_count: The minimum number of documents in a bucket for it - to be returned. Defaults to `1` if omitted. - :arg shard_min_doc_count: The minimum number of documents in a bucket - on each shard for it to be returned. Defaults to `1` if omitted. - :arg shard_size: The number of candidate terms produced by each shard. - By default, `shard_size` will be automatically estimated based on - the number of shards and the `size` parameter. - :arg show_term_doc_count_error: Calculates the doc count error on per - term basis. - :arg size: The number of term buckets should be returned out of the - overall terms list. Defaults to `10` if omitted. - """ - - name = "multi_terms" - - def __init__( - self, - *, - terms: Union[ - Sequence["types.MultiTermLookup"], Sequence[Dict[str, Any]], "DefaultType" - ] = DEFAULT, - collect_mode: Union[ - Literal["depth_first", "breadth_first"], "DefaultType" - ] = DEFAULT, - order: Union[ - Mapping[Union[str, "InstrumentedField"], Literal["asc", "desc"]], - Sequence[Mapping[Union[str, "InstrumentedField"], Literal["asc", "desc"]]], - "DefaultType", - ] = DEFAULT, - min_doc_count: Union[int, "DefaultType"] = DEFAULT, - shard_min_doc_count: Union[int, "DefaultType"] = DEFAULT, - shard_size: Union[int, "DefaultType"] = DEFAULT, - show_term_doc_count_error: Union[bool, "DefaultType"] = DEFAULT, - size: Union[int, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - terms=terms, - collect_mode=collect_mode, - order=order, - min_doc_count=min_doc_count, - shard_min_doc_count=shard_min_doc_count, - shard_size=shard_size, - show_term_doc_count_error=show_term_doc_count_error, - size=size, - **kwargs, - ) - - -class Nested(Bucket[_R]): - """ - A special single bucket aggregation that enables aggregating nested - documents. - - :arg path: The path to the field of type `nested`. - """ - - name = "nested" - - def __init__( - self, - path: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(path=path, **kwargs) - - -class Normalize(Pipeline[_R]): - """ - A parent pipeline aggregation which calculates the specific - normalized/rescaled value for a specific bucket value. - - :arg method: The specific method to apply. - :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 = "normalize" - - def __init__( - self, - *, - method: Union[ - Literal[ - "rescale_0_1", - "rescale_0_100", - "percent_of_sum", - "mean", - "z-score", - "softmax", - ], - "DefaultType", - ] = DEFAULT, - 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__( - method=method, - format=format, - gap_policy=gap_policy, - buckets_path=buckets_path, - **kwargs, - ) - - -class Parent(Bucket[_R]): - """ - A special single bucket aggregation that selects parent documents that - have the specified type, as defined in a `join` field. - - :arg type: The child type that should be selected. - """ - - name = "parent" - - def __init__(self, type: Union[str, "DefaultType"] = DEFAULT, **kwargs: Any): - super().__init__(type=type, **kwargs) - - -class PercentileRanks(Agg[_R]): - """ - A multi-value metrics aggregation that calculates one or more - percentile ranks over numeric values extracted from the aggregated - documents. - - :arg keyed: By default, the aggregation associates a unique string key - with each bucket and returns the ranges as a hash rather than an - array. Set to `false` to disable this behavior. Defaults to `True` - if omitted. - :arg values: An array of values for which to calculate the percentile - ranks. - :arg hdr: Uses the alternative High Dynamic Range Histogram algorithm - to calculate percentile ranks. - :arg tdigest: Sets parameters for the default TDigest algorithm used - to calculate percentile ranks. - :arg format: - :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 = "percentile_ranks" - - def __init__( - self, - *, - keyed: Union[bool, "DefaultType"] = DEFAULT, - values: Union[Sequence[float], None, "DefaultType"] = DEFAULT, - hdr: Union["types.HdrMethod", Dict[str, Any], "DefaultType"] = DEFAULT, - tdigest: Union["types.TDigest", Dict[str, Any], "DefaultType"] = DEFAULT, - format: Union[str, "DefaultType"] = DEFAULT, - 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__( - keyed=keyed, - values=values, - hdr=hdr, - tdigest=tdigest, - format=format, - field=field, - missing=missing, - script=script, - **kwargs, - ) - - -class Percentiles(Agg[_R]): - """ - A multi-value metrics aggregation that calculates one or more - percentiles over numeric values extracted from the aggregated - documents. - - :arg keyed: By default, the aggregation associates a unique string key - with each bucket and returns the ranges as a hash rather than an - array. Set to `false` to disable this behavior. Defaults to `True` - if omitted. - :arg percents: The percentiles to calculate. - :arg hdr: Uses the alternative High Dynamic Range Histogram algorithm - to calculate percentiles. - :arg tdigest: Sets parameters for the default TDigest algorithm used - to calculate percentiles. - :arg format: - :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 = "percentiles" - - def __init__( - self, - *, - keyed: Union[bool, "DefaultType"] = DEFAULT, - percents: Union[Sequence[float], "DefaultType"] = DEFAULT, - hdr: Union["types.HdrMethod", Dict[str, Any], "DefaultType"] = DEFAULT, - tdigest: Union["types.TDigest", Dict[str, Any], "DefaultType"] = DEFAULT, - format: Union[str, "DefaultType"] = DEFAULT, - 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__( - keyed=keyed, - percents=percents, - hdr=hdr, - tdigest=tdigest, - format=format, - field=field, - missing=missing, - script=script, - **kwargs, - ) - - -class PercentilesBucket(Pipeline[_R]): - """ - A sibling pipeline aggregation which calculates percentiles across all - bucket of a specified metric in a sibling aggregation. - - :arg percents: The list of percentiles to calculate. - :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 = "percentiles_bucket" - - def __init__( - self, - *, - percents: Union[Sequence[float], "DefaultType"] = DEFAULT, - 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__( - percents=percents, - format=format, - gap_policy=gap_policy, - buckets_path=buckets_path, - **kwargs, - ) - - -class Range(Bucket[_R]): - """ - A multi-bucket value source based aggregation that enables the user to - define a set of ranges - each representing a bucket. - - :arg field: The date field whose values are use to build ranges. - :arg missing: The value to apply to documents that do not have a - value. By default, documents without a value are ignored. - :arg ranges: An array of ranges used to bucket documents. - :arg script: - :arg keyed: Set to `true` to associate a unique string key with each - bucket and return the ranges as a hash rather than an array. - :arg format: - """ - - name = "range" - - def __init__( - self, - *, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - missing: Union[int, "DefaultType"] = DEFAULT, - ranges: Union[ - Sequence["types.AggregationRange"], Sequence[Dict[str, Any]], "DefaultType" - ] = DEFAULT, - script: Union["types.Script", Dict[str, Any], "DefaultType"] = DEFAULT, - keyed: Union[bool, "DefaultType"] = DEFAULT, - format: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - field=field, - missing=missing, - ranges=ranges, - script=script, - keyed=keyed, - format=format, - **kwargs, - ) - - -class RareTerms(Bucket[_R]): - """ - A multi-bucket value source based aggregation which finds "rare" - terms — terms that are at the long-tail of the distribution and are - not frequent. - - :arg exclude: Terms that should be excluded from the aggregation. - :arg field: The field from which to return rare terms. - :arg include: Terms that should be included in the aggregation. - :arg max_doc_count: The maximum number of documents a term should - appear in. Defaults to `1` if omitted. - :arg missing: The value to apply to documents that do not have a - value. By default, documents without a value are ignored. - :arg precision: The precision of the internal CuckooFilters. Smaller - precision leads to better approximation, but higher memory usage. - Defaults to `0.001` if omitted. - :arg value_type: - """ - - name = "rare_terms" - - def __init__( - self, - *, - exclude: Union[str, Sequence[str], "DefaultType"] = DEFAULT, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - include: Union[ - str, Sequence[str], "types.TermsPartition", Dict[str, Any], "DefaultType" - ] = DEFAULT, - max_doc_count: Union[int, "DefaultType"] = DEFAULT, - missing: Union[str, int, float, bool, "DefaultType"] = DEFAULT, - precision: Union[float, "DefaultType"] = DEFAULT, - value_type: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - exclude=exclude, - field=field, - include=include, - max_doc_count=max_doc_count, - missing=missing, - precision=precision, - value_type=value_type, - **kwargs, - ) - - -class Rate(Agg[_R]): - """ - Calculates a rate of documents or a field in each bucket. Can only be - used inside a `date_histogram` or `composite` aggregation. - - :arg unit: The interval used to calculate the rate. By default, the - interval of the `date_histogram` is used. - :arg mode: How the rate is calculated. Defaults to `sum` if omitted. - :arg format: - :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 = "rate" - - def __init__( - self, - *, - unit: Union[ - Literal[ - "second", "minute", "hour", "day", "week", "month", "quarter", "year" - ], - "DefaultType", - ] = DEFAULT, - mode: Union[Literal["sum", "value_count"], "DefaultType"] = DEFAULT, - format: Union[str, "DefaultType"] = DEFAULT, - 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__( - unit=unit, - mode=mode, - format=format, - field=field, - missing=missing, - script=script, - **kwargs, - ) - - -class ReverseNested(Bucket[_R]): - """ - A special single bucket aggregation that enables aggregating on parent - documents from nested documents. Should only be defined inside a - `nested` aggregation. - - :arg path: Defines the nested object field that should be joined back - to. The default is empty, which means that it joins back to the - root/main document level. - """ - - name = "reverse_nested" - - def __init__( - self, - path: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(path=path, **kwargs) - - -class RandomSampler(Bucket[_R]): - """ - A single bucket aggregation that randomly includes documents in the - aggregated results. Sampling provides significant speed improvement at - the cost of accuracy. - - :arg probability: (required) The probability that a document will be - included in the aggregated data. Must be greater than 0, less than - 0.5, or exactly 1. The lower the probability, the fewer documents - are matched. - :arg seed: The seed to generate the random sampling of documents. When - a seed is provided, the random subset of documents is the same - between calls. - :arg shard_seed: When combined with seed, setting shard_seed ensures - 100% consistent sampling over shards where data is exactly the - same. - """ - - name = "random_sampler" - - def __init__( - self, - *, - probability: Union[float, "DefaultType"] = DEFAULT, - seed: Union[int, "DefaultType"] = DEFAULT, - shard_seed: Union[int, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - probability=probability, seed=seed, shard_seed=shard_seed, **kwargs - ) - - -class Sampler(Bucket[_R]): - """ - A filtering aggregation used to limit any sub aggregations' processing - to a sample of the top-scoring documents. - - :arg shard_size: Limits how many top-scoring documents are collected - in the sample processed on each shard. Defaults to `100` if - omitted. - """ - - name = "sampler" - - def __init__(self, shard_size: Union[int, "DefaultType"] = DEFAULT, **kwargs: Any): - super().__init__(shard_size=shard_size, **kwargs) - - -class ScriptedMetric(Agg[_R]): - """ - A metric aggregation that uses scripts to provide a metric output. - - :arg combine_script: Runs once on each shard after document collection - is complete. Allows the aggregation to consolidate the state - returned from each shard. - :arg init_script: Runs prior to any collection of documents. Allows - the aggregation to set up any initial state. - :arg map_script: Run once per document collected. If no - `combine_script` is specified, the resulting state needs to be - stored in the `state` object. - :arg params: A global object with script parameters for `init`, `map` - and `combine` scripts. It is shared between the scripts. - :arg reduce_script: Runs once on the coordinating node after all - shards have returned their results. The script is provided with - access to a variable `states`, which is an array of the result of - the `combine_script` on each shard. - :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 = "scripted_metric" - - def __init__( - self, - *, - combine_script: Union["types.Script", Dict[str, Any], "DefaultType"] = DEFAULT, - init_script: Union["types.Script", Dict[str, Any], "DefaultType"] = DEFAULT, - map_script: Union["types.Script", Dict[str, Any], "DefaultType"] = DEFAULT, - params: Union[Mapping[str, Any], "DefaultType"] = DEFAULT, - reduce_script: Union["types.Script", Dict[str, Any], "DefaultType"] = DEFAULT, - 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__( - combine_script=combine_script, - init_script=init_script, - map_script=map_script, - params=params, - reduce_script=reduce_script, - field=field, - missing=missing, - script=script, - **kwargs, - ) - - -class SerialDiff(Pipeline[_R]): - """ - An aggregation that subtracts values in a time series from themselves - at different time lags or periods. - - :arg lag: The historical bucket to subtract from the current value. - Must be a positive, non-zero integer. - :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 = "serial_diff" - - def __init__( - self, - *, - lag: Union[int, "DefaultType"] = DEFAULT, - 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__( - lag=lag, - format=format, - gap_policy=gap_policy, - buckets_path=buckets_path, - **kwargs, - ) - - -class SignificantTerms(Bucket[_R]): - """ - Returns interesting or unusual occurrences of terms in a set. - - :arg background_filter: A background filter that can be used to focus - in on significant terms within a narrower context, instead of the - entire index. - :arg chi_square: Use Chi square, as described in "Information - Retrieval", Manning et al., Chapter 13.5.2, as the significance - score. - :arg exclude: Terms to exclude. - :arg execution_hint: Mechanism by which the aggregation should be - executed: using field values directly or using global ordinals. - :arg field: The field from which to return significant terms. - :arg gnd: Use Google normalized distance as described in "The Google - Similarity Distance", Cilibrasi and Vitanyi, 2007, as the - significance score. - :arg include: Terms to include. - :arg jlh: Use JLH score as the significance score. - :arg min_doc_count: Only return terms that are found in more than - `min_doc_count` hits. Defaults to `3` if omitted. - :arg mutual_information: Use mutual information as described in - "Information Retrieval", Manning et al., Chapter 13.5.1, as the - significance score. - :arg percentage: A simple calculation of the number of documents in - 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 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 - their local shard frequency within the set is higher than the - `shard_min_doc_count`. - :arg shard_size: Can be used to control the volumes of candidate terms - produced by each shard. By default, `shard_size` will be - automatically estimated based on the number of shards and the - `size` parameter. - :arg size: The number of buckets returned out of the overall terms - list. - """ - - name = "significant_terms" - _param_defs = { - "background_filter": {"type": "query"}, - } - - def __init__( - self, - *, - background_filter: Union[Query, "DefaultType"] = DEFAULT, - chi_square: Union[ - "types.ChiSquareHeuristic", Dict[str, Any], "DefaultType" - ] = DEFAULT, - exclude: Union[str, Sequence[str], "DefaultType"] = DEFAULT, - execution_hint: Union[ - Literal[ - "map", - "global_ordinals", - "global_ordinals_hash", - "global_ordinals_low_cardinality", - ], - "DefaultType", - ] = DEFAULT, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - gnd: Union[ - "types.GoogleNormalizedDistanceHeuristic", Dict[str, Any], "DefaultType" - ] = DEFAULT, - include: Union[ - str, Sequence[str], "types.TermsPartition", Dict[str, Any], "DefaultType" - ] = DEFAULT, - jlh: Union["types.EmptyObject", Dict[str, Any], "DefaultType"] = DEFAULT, - min_doc_count: Union[int, "DefaultType"] = DEFAULT, - mutual_information: Union[ - "types.MutualInformationHeuristic", Dict[str, Any], "DefaultType" - ] = DEFAULT, - percentage: Union[ - "types.PercentageScoreHeuristic", Dict[str, Any], "DefaultType" - ] = DEFAULT, - script_heuristic: Union[ - "types.ScriptedHeuristic", Dict[str, Any], "DefaultType" - ] = DEFAULT, - shard_min_doc_count: Union[int, "DefaultType"] = DEFAULT, - shard_size: Union[int, "DefaultType"] = DEFAULT, - size: Union[int, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - background_filter=background_filter, - chi_square=chi_square, - exclude=exclude, - execution_hint=execution_hint, - field=field, - gnd=gnd, - include=include, - jlh=jlh, - min_doc_count=min_doc_count, - mutual_information=mutual_information, - percentage=percentage, - script_heuristic=script_heuristic, - shard_min_doc_count=shard_min_doc_count, - shard_size=shard_size, - size=size, - **kwargs, - ) - - -class SignificantText(Bucket[_R]): - """ - Returns interesting or unusual occurrences of free-text terms in a - set. - - :arg background_filter: A background filter that can be used to focus - in on significant terms within a narrower context, instead of the - entire index. - :arg chi_square: Use Chi square, as described in "Information - Retrieval", Manning et al., Chapter 13.5.2, as the significance - score. - :arg exclude: Values to exclude. - :arg execution_hint: Determines whether the aggregation will use field - values directly or global ordinals. - :arg field: The field from which to return significant text. - :arg filter_duplicate_text: Whether to out duplicate text to deal with - noisy data. - :arg gnd: Use Google normalized distance as described in "The Google - Similarity Distance", Cilibrasi and Vitanyi, 2007, as the - significance score. - :arg include: Values to include. - :arg jlh: Use JLH score as the significance score. - :arg min_doc_count: Only return values that are found in more than - `min_doc_count` hits. Defaults to `3` if omitted. - :arg mutual_information: Use mutual information as described in - "Information Retrieval", Manning et al., Chapter 13.5.1, as the - significance score. - :arg percentage: A simple calculation of the number of documents in - 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 shard_min_doc_count: Regulates the certainty a shard has if the - values should actually be added to the candidate list or not with - respect to the min_doc_count. Values will only be considered if - their local shard frequency within the set is higher than the - `shard_min_doc_count`. - :arg shard_size: The number of candidate terms produced by each shard. - By default, `shard_size` will be automatically estimated based on - the number of shards and the `size` parameter. - :arg size: The number of buckets returned out of the overall terms - list. - :arg source_fields: Overrides the JSON `_source` fields from which - text will be analyzed. - """ - - name = "significant_text" - _param_defs = { - "background_filter": {"type": "query"}, - } - - def __init__( - self, - *, - background_filter: Union[Query, "DefaultType"] = DEFAULT, - chi_square: Union[ - "types.ChiSquareHeuristic", Dict[str, Any], "DefaultType" - ] = DEFAULT, - exclude: Union[str, Sequence[str], "DefaultType"] = DEFAULT, - execution_hint: Union[ - Literal[ - "map", - "global_ordinals", - "global_ordinals_hash", - "global_ordinals_low_cardinality", - ], - "DefaultType", - ] = DEFAULT, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - filter_duplicate_text: Union[bool, "DefaultType"] = DEFAULT, - gnd: Union[ - "types.GoogleNormalizedDistanceHeuristic", Dict[str, Any], "DefaultType" - ] = DEFAULT, - include: Union[ - str, Sequence[str], "types.TermsPartition", Dict[str, Any], "DefaultType" - ] = DEFAULT, - jlh: Union["types.EmptyObject", Dict[str, Any], "DefaultType"] = DEFAULT, - min_doc_count: Union[int, "DefaultType"] = DEFAULT, - mutual_information: Union[ - "types.MutualInformationHeuristic", Dict[str, Any], "DefaultType" - ] = DEFAULT, - percentage: Union[ - "types.PercentageScoreHeuristic", Dict[str, Any], "DefaultType" - ] = DEFAULT, - script_heuristic: Union[ - "types.ScriptedHeuristic", Dict[str, Any], "DefaultType" - ] = DEFAULT, - shard_min_doc_count: Union[int, "DefaultType"] = DEFAULT, - shard_size: Union[int, "DefaultType"] = DEFAULT, - size: Union[int, "DefaultType"] = DEFAULT, - source_fields: Union[ - Union[str, "InstrumentedField"], - Sequence[Union[str, "InstrumentedField"]], - "DefaultType", - ] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - background_filter=background_filter, - chi_square=chi_square, - exclude=exclude, - execution_hint=execution_hint, - field=field, - filter_duplicate_text=filter_duplicate_text, - gnd=gnd, - include=include, - jlh=jlh, - min_doc_count=min_doc_count, - mutual_information=mutual_information, - percentage=percentage, - script_heuristic=script_heuristic, - shard_min_doc_count=shard_min_doc_count, - shard_size=shard_size, - size=size, - source_fields=source_fields, - **kwargs, - ) - - -class Stats(Agg[_R]): - """ - A multi-value metrics aggregation that computes stats over numeric - values extracted from the aggregated documents. - - :arg format: - :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 = "stats" - - def __init__( - self, - *, - format: Union[str, "DefaultType"] = DEFAULT, - 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__( - format=format, field=field, missing=missing, script=script, **kwargs - ) - - -class StatsBucket(Pipeline[_R]): - """ - A sibling pipeline aggregation which calculates a variety of stats - across all bucket of a specified metric in a sibling aggregation. - - :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 = "stats_bucket" - - 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 StringStats(Agg[_R]): - """ - A multi-value metrics aggregation that computes statistics over string - values extracted from the aggregated documents. - - :arg show_distribution: Shows the probability distribution for all - characters. - :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 = "string_stats" - - def __init__( - self, - *, - show_distribution: Union[bool, "DefaultType"] = DEFAULT, - 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__( - show_distribution=show_distribution, - field=field, - missing=missing, - script=script, - **kwargs, - ) - - -class Sum(Agg[_R]): - """ - A single-value metrics aggregation that sums numeric values that are - extracted from the aggregated documents. - - :arg format: - :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 = "sum" - - def __init__( - self, - *, - format: Union[str, "DefaultType"] = DEFAULT, - 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__( - format=format, field=field, missing=missing, script=script, **kwargs - ) - - -class SumBucket(Pipeline[_R]): - """ - A sibling pipeline aggregation which calculates the sum of a specified - metric across all buckets in a sibling aggregation. - - :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 = "sum_bucket" - - 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 Terms(Bucket[_R]): - """ - A multi-bucket value source based aggregation where buckets are - dynamically built - one per unique value. - - :arg collect_mode: Determines how child aggregations should be - calculated: breadth-first or depth-first. - :arg exclude: Values to exclude. Accepts regular expressions and - partitions. - :arg execution_hint: Determines whether the aggregation will use field - values directly or global ordinals. - :arg field: The field from which to return terms. - :arg include: Values to include. Accepts regular expressions and - partitions. - :arg min_doc_count: Only return values that are found in more than - `min_doc_count` hits. Defaults to `1` if omitted. - :arg missing: The value to apply to documents that do not have a - value. By default, documents without a value are ignored. - :arg missing_order: - :arg missing_bucket: - :arg value_type: Coerced unmapped fields into the specified type. - :arg order: Specifies the sort order of the buckets. Defaults to - sorting by descending document count. - :arg script: - :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 - their local shard frequency within the set is higher than the - `shard_min_doc_count`. - :arg shard_size: The number of candidate terms produced by each shard. - By default, `shard_size` will be automatically estimated based on - the number of shards and the `size` parameter. - :arg show_term_doc_count_error: Set to `true` to return the - `doc_count_error_upper_bound`, which is an upper bound to the - error on the `doc_count` returned by each shard. - :arg size: The number of buckets returned out of the overall terms - list. Defaults to `10` if omitted. - :arg format: - """ - - name = "terms" - - def __init__( - self, - *, - collect_mode: Union[ - Literal["depth_first", "breadth_first"], "DefaultType" - ] = DEFAULT, - exclude: Union[str, Sequence[str], "DefaultType"] = DEFAULT, - execution_hint: Union[ - Literal[ - "map", - "global_ordinals", - "global_ordinals_hash", - "global_ordinals_low_cardinality", - ], - "DefaultType", - ] = DEFAULT, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - include: Union[ - str, Sequence[str], "types.TermsPartition", Dict[str, Any], "DefaultType" - ] = DEFAULT, - min_doc_count: Union[int, "DefaultType"] = DEFAULT, - missing: Union[str, int, float, bool, "DefaultType"] = DEFAULT, - missing_order: Union[ - Literal["first", "last", "default"], "DefaultType" - ] = DEFAULT, - missing_bucket: Union[bool, "DefaultType"] = DEFAULT, - value_type: Union[str, "DefaultType"] = DEFAULT, - order: Union[ - Mapping[Union[str, "InstrumentedField"], Literal["asc", "desc"]], - Sequence[Mapping[Union[str, "InstrumentedField"], Literal["asc", "desc"]]], - "DefaultType", - ] = DEFAULT, - script: Union["types.Script", Dict[str, Any], "DefaultType"] = DEFAULT, - shard_min_doc_count: Union[int, "DefaultType"] = DEFAULT, - shard_size: Union[int, "DefaultType"] = DEFAULT, - show_term_doc_count_error: Union[bool, "DefaultType"] = DEFAULT, - size: Union[int, "DefaultType"] = DEFAULT, - format: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - collect_mode=collect_mode, - exclude=exclude, - execution_hint=execution_hint, - field=field, - include=include, - min_doc_count=min_doc_count, - missing=missing, - missing_order=missing_order, - missing_bucket=missing_bucket, - value_type=value_type, - order=order, - script=script, - shard_min_doc_count=shard_min_doc_count, - shard_size=shard_size, - show_term_doc_count_error=show_term_doc_count_error, - size=size, - format=format, - **kwargs, - ) - - def result(self, search: "SearchBase[_R]", data: Any) -> AttrDict[Any]: - return FieldBucketData(self, search, data) - - -class TimeSeries(Bucket[_R]): - """ - The time series aggregation queries data created using a time series - index. This is typically data such as metrics or other data streams - with a time component, and requires creating an index using the time - series mode. - - :arg size: The maximum number of results to return. Defaults to - `10000` if omitted. - :arg keyed: Set to `true` to associate a unique string key with each - bucket and returns the ranges as a hash rather than an array. - """ - - name = "time_series" - - def __init__( - self, - *, - size: Union[int, "DefaultType"] = DEFAULT, - keyed: Union[bool, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(size=size, keyed=keyed, **kwargs) - - -class TopHits(Agg[_R]): - """ - A metric aggregation that returns the top matching documents per - bucket. - - :arg docvalue_fields: Fields for which to return doc values. - :arg explain: If `true`, returns detailed information about score - computation as part of a hit. - :arg fields: Array of wildcard (*) patterns. The request returns - values for field names matching these patterns in the hits.fields - property of the response. - :arg from: Starting document offset. - :arg highlight: Specifies the highlighter to use for retrieving - highlighted snippets from one or more fields in the search - results. - :arg script_fields: Returns the result of one or more script - evaluations for each hit. - :arg size: The maximum number of top matching hits to return per - bucket. Defaults to `3` if omitted. - :arg sort: Sort order of the top matching hits. By default, the hits - are sorted by the score of the main query. - :arg _source: Selects the fields of the source that are returned. - :arg stored_fields: Returns values for the specified stored fields - (fields that use the `store` mapping option). - :arg track_scores: If `true`, calculates and returns document scores, - even if the scores are not used for sorting. - :arg version: If `true`, returns document version as part of a hit. - :arg seq_no_primary_term: If `true`, returns sequence number and - primary term of the last modification of each hit. - :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 = "top_hits" - - def __init__( - self, - *, - docvalue_fields: Union[ - Sequence["types.FieldAndFormat"], Sequence[Dict[str, Any]], "DefaultType" - ] = DEFAULT, - explain: Union[bool, "DefaultType"] = DEFAULT, - fields: Union[ - Sequence["types.FieldAndFormat"], Sequence[Dict[str, Any]], "DefaultType" - ] = DEFAULT, - from_: Union[int, "DefaultType"] = DEFAULT, - highlight: Union["types.Highlight", Dict[str, Any], "DefaultType"] = DEFAULT, - script_fields: Union[ - Mapping[str, "types.ScriptField"], Dict[str, Any], "DefaultType" - ] = DEFAULT, - size: Union[int, "DefaultType"] = DEFAULT, - sort: Union[ - Union[Union[str, "InstrumentedField"], "types.SortOptions"], - Sequence[Union[Union[str, "InstrumentedField"], "types.SortOptions"]], - Dict[str, Any], - "DefaultType", - ] = DEFAULT, - _source: Union[ - bool, "types.SourceFilter", Dict[str, Any], "DefaultType" - ] = DEFAULT, - stored_fields: Union[ - Union[str, "InstrumentedField"], - Sequence[Union[str, "InstrumentedField"]], - "DefaultType", - ] = DEFAULT, - track_scores: Union[bool, "DefaultType"] = DEFAULT, - version: Union[bool, "DefaultType"] = DEFAULT, - seq_no_primary_term: Union[bool, "DefaultType"] = DEFAULT, - 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__( - docvalue_fields=docvalue_fields, - explain=explain, - fields=fields, - from_=from_, - highlight=highlight, - script_fields=script_fields, - size=size, - sort=sort, - _source=_source, - stored_fields=stored_fields, - track_scores=track_scores, - version=version, - seq_no_primary_term=seq_no_primary_term, - field=field, - missing=missing, - script=script, - **kwargs, - ) - - def result(self, search: "SearchBase[_R]", data: Any) -> AttrDict[Any]: - return TopHitsData(self, search, data) - - -class TTest(Agg[_R]): - """ - A metrics aggregation that performs a statistical hypothesis test in - which the test statistic follows a Student’s t-distribution under the - null hypothesis on numeric values extracted from the aggregated - documents. - - :arg a: Test population A. - :arg b: Test population B. - :arg type: The type of test. Defaults to `heteroscedastic` if omitted. - """ - - name = "t_test" - - def __init__( - self, - *, - a: Union["types.TestPopulation", Dict[str, Any], "DefaultType"] = DEFAULT, - b: Union["types.TestPopulation", Dict[str, Any], "DefaultType"] = DEFAULT, - type: Union[ - Literal["paired", "homoscedastic", "heteroscedastic"], "DefaultType" - ] = DEFAULT, - **kwargs: Any, - ): - super().__init__(a=a, b=b, type=type, **kwargs) - - -class TopMetrics(Agg[_R]): - """ - A metric aggregation that selects metrics from the document with the - largest or smallest sort value. - - :arg metrics: The fields of the top document to return. - :arg size: The number of top documents from which to return metrics. - Defaults to `1` if omitted. - :arg sort: The sort order of the documents. - :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 = "top_metrics" - - def __init__( - self, - *, - metrics: Union[ - "types.TopMetricsValue", - Sequence["types.TopMetricsValue"], - Sequence[Dict[str, Any]], - "DefaultType", - ] = DEFAULT, - size: Union[int, "DefaultType"] = DEFAULT, - sort: Union[ - Union[Union[str, "InstrumentedField"], "types.SortOptions"], - Sequence[Union[Union[str, "InstrumentedField"], "types.SortOptions"]], - Dict[str, Any], - "DefaultType", - ] = DEFAULT, - 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__( - metrics=metrics, - size=size, - sort=sort, - field=field, - missing=missing, - script=script, - **kwargs, - ) - - -class ValueCount(Agg[_R]): - """ - A single-value metrics aggregation that counts the number of values - that are extracted from the aggregated documents. - - :arg format: - :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 = "value_count" - - def __init__( - self, - *, - format: Union[str, "DefaultType"] = DEFAULT, - 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__( - format=format, field=field, missing=missing, script=script, **kwargs - ) - - -class WeightedAvg(Agg[_R]): - """ - A single-value metrics aggregation that computes the weighted average - of numeric values that are extracted from the aggregated documents. - - :arg format: A numeric response formatter. - :arg value: Configuration for the field that provides the values. - :arg value_type: - :arg weight: Configuration for the field or script that provides the - weights. - """ - - name = "weighted_avg" - - def __init__( - self, - *, - format: Union[str, "DefaultType"] = DEFAULT, - value: Union[ - "types.WeightedAverageValue", Dict[str, Any], "DefaultType" - ] = DEFAULT, - value_type: Union[ - Literal[ - "string", - "long", - "double", - "number", - "date", - "date_nanos", - "ip", - "numeric", - "geo_point", - "boolean", - ], - "DefaultType", - ] = DEFAULT, - weight: Union[ - "types.WeightedAverageValue", Dict[str, Any], "DefaultType" - ] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - format=format, value=value, value_type=value_type, weight=weight, **kwargs - ) - - -class VariableWidthHistogram(Bucket[_R]): - """ - A multi-bucket aggregation similar to the histogram, except instead of - providing an interval to use as the width of each bucket, a target - number of buckets is provided. - - :arg field: The name of the field. - :arg buckets: The target number of buckets. Defaults to `10` if - omitted. - :arg shard_size: The number of buckets that the coordinating node will - request from each shard. Defaults to `buckets * 50`. - :arg initial_buffer: Specifies the number of individual documents that - will be stored in memory on a shard before the initial bucketing - algorithm is run. Defaults to `min(10 * shard_size, 50000)`. - :arg script: - """ - - name = "variable_width_histogram" - - def __init__( - self, - *, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - buckets: Union[int, "DefaultType"] = DEFAULT, - shard_size: Union[int, "DefaultType"] = DEFAULT, - initial_buffer: Union[int, "DefaultType"] = DEFAULT, - script: Union["types.Script", Dict[str, Any], "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - field=field, - buckets=buckets, - shard_size=shard_size, - initial_buffer=initial_buffer, - script=script, - **kwargs, - ) - - def result(self, search: "SearchBase[_R]", data: Any) -> AttrDict[Any]: - return FieldBucketData(self, search, data) diff --git a/elasticsearch_dsl/analysis.py b/elasticsearch_dsl/analysis.py deleted file mode 100644 index a810064e..00000000 --- a/elasticsearch_dsl/analysis.py +++ /dev/null @@ -1,341 +0,0 @@ -# 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, Union, cast - -from . import async_connections, connections -from .utils import AsyncUsingType, AttrDict, DslBase, UsingType, merge - -__all__ = ["tokenizer", "analyzer", "char_filter", "token_filter", "normalizer"] - - -class AnalysisBase: - @classmethod - def _type_shortcut( - cls, - name_or_instance: Union[str, "AnalysisBase"], - type: Optional[str] = None, - **kwargs: Any, - ) -> DslBase: - if isinstance(name_or_instance, cls): - if type or kwargs: - raise ValueError(f"{cls.__name__}() cannot accept parameters.") - return name_or_instance # type: ignore[return-value] - - if not (type or kwargs): - return cls.get_dsl_class("builtin")(name_or_instance) # type: ignore - - return cls.get_dsl_class(type, "custom")( # type: ignore - name_or_instance, type or "custom", **kwargs - ) - - -class CustomAnalysis: - name = "custom" - - def __init__(self, filter_name: str, builtin_type: str = "custom", **kwargs: Any): - self._builtin_type = builtin_type - self._name = filter_name - super().__init__(**kwargs) - - def to_dict(self) -> Dict[str, Any]: - # only name to present in lists - return self._name # type: ignore - - def get_definition(self) -> Dict[str, Any]: - d = super().to_dict() # type: ignore - d = d.pop(self.name) - d["type"] = self._builtin_type - return d # type: ignore - - -class CustomAnalysisDefinition(CustomAnalysis): - _type_name: str - _param_defs: ClassVar[Dict[str, Any]] - filter: List[Any] - char_filter: List[Any] - - def get_analysis_definition(self) -> Dict[str, Any]: - out = {self._type_name: {self._name: self.get_definition()}} - - t = cast("Tokenizer", getattr(self, "tokenizer", None)) - if "tokenizer" in self._param_defs and hasattr(t, "get_definition"): - out["tokenizer"] = {t._name: t.get_definition()} - - filters = { - f._name: f.get_definition() - for f in self.filter - if hasattr(f, "get_definition") - } - if filters: - out["filter"] = filters - - # any sub filter definitions like multiplexers etc? - for f in self.filter: - if hasattr(f, "get_analysis_definition"): - d = f.get_analysis_definition() - if d: - merge(out, d, True) - - char_filters = { - f._name: f.get_definition() - for f in self.char_filter - if hasattr(f, "get_definition") - } - if char_filters: - out["char_filter"] = char_filters - - return out - - -class BuiltinAnalysis: - name = "builtin" - - def __init__(self, name: str): - self._name = name - super().__init__() - - def to_dict(self) -> Dict[str, Any]: - # only name to present in lists - return self._name # type: ignore - - -class Analyzer(AnalysisBase, DslBase): - _type_name = "analyzer" - name = "" - - -class BuiltinAnalyzer(BuiltinAnalysis, Analyzer): - def get_analysis_definition(self) -> Dict[str, Any]: - return {} - - -class CustomAnalyzer(CustomAnalysisDefinition, Analyzer): - _param_defs = { - "filter": {"type": "token_filter", "multi": True}, - "char_filter": {"type": "char_filter", "multi": True}, - "tokenizer": {"type": "tokenizer"}, - } - - def _get_body( - self, text: str, explain: bool, attributes: Optional[Dict[str, Any]] - ) -> Dict[str, Any]: - body = {"text": text, "explain": explain} - if attributes: - body["attributes"] = attributes - - definition = self.get_analysis_definition() - analyzer_def = self.get_definition() - - for section in ("tokenizer", "char_filter", "filter"): - if section not in analyzer_def: - continue - sec_def = definition.get(section, {}) - sec_names = analyzer_def[section] - - if isinstance(sec_names, str): - body[section] = sec_def.get(sec_names, sec_names) - else: - body[section] = [ - sec_def.get(sec_name, sec_name) for sec_name in sec_names - ] - - if self._builtin_type != "custom": - body["analyzer"] = self._builtin_type - - return body - - def simulate( - self, - text: str, - using: UsingType = "default", - explain: bool = False, - attributes: Optional[Dict[str, Any]] = None, - ) -> AttrDict[Any]: - """ - Use the Analyze API of elasticsearch to test the outcome of this analyzer. - - :arg text: Text to be analyzed - :arg using: connection alias to use, defaults to ``'default'`` - :arg explain: will output all token attributes for each token. You can - filter token attributes you want to output by setting ``attributes`` - option. - :arg attributes: if ``explain`` is specified, filter the token - attributes to return. - """ - es = connections.get_connection(using) - return AttrDict( - cast( - Dict[str, Any], - es.indices.analyze(body=self._get_body(text, explain, attributes)), - ) - ) - - async def async_simulate( - self, - text: str, - using: AsyncUsingType = "default", - explain: bool = False, - attributes: Optional[Dict[str, Any]] = None, - ) -> AttrDict[Any]: - """ - Use the Analyze API of elasticsearch to test the outcome of this analyzer. - - :arg text: Text to be analyzed - :arg using: connection alias to use, defaults to ``'default'`` - :arg explain: will output all token attributes for each token. You can - filter token attributes you want to output by setting ``attributes`` - option. - :arg attributes: if ``explain`` is specified, filter the token - attributes to return. - """ - es = async_connections.get_connection(using) - return AttrDict( - cast( - Dict[str, Any], - await es.indices.analyze( - body=self._get_body(text, explain, attributes) - ), - ) - ) - - -class Normalizer(AnalysisBase, DslBase): - _type_name = "normalizer" - name = "" - - -class BuiltinNormalizer(BuiltinAnalysis, Normalizer): - def get_analysis_definition(self) -> Dict[str, Any]: - return {} - - -class CustomNormalizer(CustomAnalysisDefinition, Normalizer): - _param_defs = { - "filter": {"type": "token_filter", "multi": True}, - "char_filter": {"type": "char_filter", "multi": True}, - } - - -class Tokenizer(AnalysisBase, DslBase): - _type_name = "tokenizer" - name = "" - - -class BuiltinTokenizer(BuiltinAnalysis, Tokenizer): - pass - - -class CustomTokenizer(CustomAnalysis, Tokenizer): - pass - - -class TokenFilter(AnalysisBase, DslBase): - _type_name = "token_filter" - name = "" - - -class BuiltinTokenFilter(BuiltinAnalysis, TokenFilter): - pass - - -class CustomTokenFilter(CustomAnalysis, TokenFilter): - pass - - -class MultiplexerTokenFilter(CustomTokenFilter): - name = "multiplexer" - - def get_definition(self) -> Dict[str, Any]: - d = super(CustomTokenFilter, self).get_definition() - - if "filters" in d: - d["filters"] = [ - # comma delimited string given by user - ( - fs - if isinstance(fs, str) - else - # list of strings or TokenFilter objects - ", ".join(f.to_dict() if hasattr(f, "to_dict") else f for f in fs) - ) - for fs in self.filters - ] - return d - - def get_analysis_definition(self) -> Dict[str, Any]: - if not hasattr(self, "filters"): - return {} - - fs: Dict[str, Any] = {} - d = {"filter": fs} - for filters in self.filters: - if isinstance(filters, str): - continue - fs.update( - { - f._name: f.get_definition() - for f in filters - if hasattr(f, "get_definition") - } - ) - return d - - -class ConditionalTokenFilter(CustomTokenFilter): - name = "condition" - - def get_definition(self) -> Dict[str, Any]: - d = super(CustomTokenFilter, self).get_definition() - if "filter" in d: - d["filter"] = [ - f.to_dict() if hasattr(f, "to_dict") else f for f in self.filter - ] - return d - - def get_analysis_definition(self) -> Dict[str, Any]: - if not hasattr(self, "filter"): - return {} - - return { - "filter": { - f._name: f.get_definition() - for f in self.filter - if hasattr(f, "get_definition") - } - } - - -class CharFilter(AnalysisBase, DslBase): - _type_name = "char_filter" - name = "" - - -class BuiltinCharFilter(BuiltinAnalysis, CharFilter): - pass - - -class CustomCharFilter(CustomAnalysis, CharFilter): - pass - - -# shortcuts for direct use -analyzer = Analyzer._type_shortcut -tokenizer = Tokenizer._type_shortcut -token_filter = TokenFilter._type_shortcut -char_filter = CharFilter._type_shortcut -normalizer = Normalizer._type_shortcut diff --git a/elasticsearch_dsl/async_connections.py b/elasticsearch_dsl/async_connections.py deleted file mode 100644 index 8d44b2b4..00000000 --- a/elasticsearch_dsl/async_connections.py +++ /dev/null @@ -1,37 +0,0 @@ -# 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 - -from elasticsearch import AsyncElasticsearch - -from elasticsearch_dsl.connections import Connections - - -class AsyncElasticsearchConnections(Connections[AsyncElasticsearch]): - def __init__( - self, *, elasticsearch_class: Type[AsyncElasticsearch] = AsyncElasticsearch - ): - super().__init__(elasticsearch_class=elasticsearch_class) - - -connections = AsyncElasticsearchConnections(elasticsearch_class=AsyncElasticsearch) -configure = connections.configure -add_connection = connections.add_connection -remove_connection = connections.remove_connection -create_connection = connections.create_connection -get_connection = connections.get_connection diff --git a/elasticsearch_dsl/connections.py b/elasticsearch_dsl/connections.py deleted file mode 100644 index a3d34096..00000000 --- a/elasticsearch_dsl/connections.py +++ /dev/null @@ -1,144 +0,0 @@ -# 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, Dict, Generic, Type, TypeVar, Union - -from elasticsearch import Elasticsearch - -from .serializer import serializer - -_T = TypeVar("_T") - - -class Connections(Generic[_T]): - """ - Class responsible for holding connections to different clusters. Used as a - singleton in this module. - """ - - def __init__(self, *, elasticsearch_class: Type[_T]): - self._kwargs: Dict[str, Any] = {} - self._conns: Dict[str, _T] = {} - self.elasticsearch_class: Type[_T] = elasticsearch_class - - def configure(self, **kwargs: Any) -> None: - """ - Configure multiple connections at once, useful for passing in config - dictionaries obtained from other sources, like Django's settings or a - configuration management tool. - - Example:: - - connections.configure( - default={'hosts': 'localhost'}, - dev={'hosts': ['esdev1.example.com:9200'], 'sniff_on_start': True}, - ) - - Connections will only be constructed lazily when requested through - ``get_connection``. - """ - for k in list(self._conns): - # try and preserve existing client to keep the persistent connections alive - if k in self._kwargs and kwargs.get(k, None) == self._kwargs[k]: - continue - del self._conns[k] - self._kwargs = kwargs - - def add_connection(self, alias: str, conn: _T) -> None: - """ - Add a connection object, it will be passed through as-is. - """ - self._conns[alias] = self._with_user_agent(conn) - - def remove_connection(self, alias: str) -> None: - """ - Remove connection from the registry. Raises ``KeyError`` if connection - wasn't found. - """ - errors = 0 - for d in (self._conns, self._kwargs): - try: - del d[alias] - except KeyError: - errors += 1 - - if errors == 2: - raise KeyError(f"There is no connection with alias {alias!r}.") - - def create_connection(self, alias: str = "default", **kwargs: Any) -> _T: - """ - Construct an instance of ``elasticsearch.Elasticsearch`` and register - it under given alias. - """ - kwargs.setdefault("serializer", serializer) - conn = self._conns[alias] = self.elasticsearch_class(**kwargs) - return self._with_user_agent(conn) - - def get_connection(self, alias: Union[str, _T] = "default") -> _T: - """ - Retrieve a connection, construct it if necessary (only configuration - was passed to us). If a non-string alias has been passed through we - assume it's already a client instance and will just return it as-is. - - Raises ``KeyError`` if no client (or its definition) is registered - under the alias. - """ - # do not check isinstance(Elasticsearch) so that people can wrap their - # clients - if not isinstance(alias, str): - return self._with_user_agent(alias) - - # connection already established - try: - return self._conns[alias] - except KeyError: - pass - - # if not, try to create it - try: - return self.create_connection(alias, **self._kwargs[alias]) - except KeyError: - # no connection and no kwargs to set one up - raise KeyError(f"There is no connection with alias {alias!r}.") - - def _with_user_agent(self, conn: _T) -> _T: - from . import __versionstr__ # this is here to avoid circular imports - - # try to inject our user agent - if hasattr(conn, "_headers"): - is_frozen = conn._headers.frozen - if is_frozen: - conn._headers = conn._headers.copy() - conn._headers.update( - {"user-agent": f"elasticsearch-dsl-py/{__versionstr__}"} - ) - if is_frozen: - conn._headers.freeze() - return conn - - -class ElasticsearchConnections(Connections[Elasticsearch]): - def __init__(self, *, elasticsearch_class: Type[Elasticsearch] = Elasticsearch): - super().__init__(elasticsearch_class=elasticsearch_class) - - -connections = ElasticsearchConnections() -configure = connections.configure -add_connection = connections.add_connection -remove_connection = connections.remove_connection -create_connection = connections.create_connection -get_connection = connections.get_connection diff --git a/elasticsearch_dsl/document.py b/elasticsearch_dsl/document.py deleted file mode 100644 index 304313c9..00000000 --- a/elasticsearch_dsl/document.py +++ /dev/null @@ -1,20 +0,0 @@ -# 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 elasticsearch_dsl._async.document import AsyncDocument # noqa: F401 -from elasticsearch_dsl._sync.document import Document # noqa: F401 -from elasticsearch_dsl.document_base import InnerDoc, MetaField # noqa: F401 diff --git a/elasticsearch_dsl/document_base.py b/elasticsearch_dsl/document_base.py deleted file mode 100644 index a7026778..00000000 --- a/elasticsearch_dsl/document_base.py +++ /dev/null @@ -1,444 +0,0 @@ -# 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 datetime import date, datetime -from fnmatch import fnmatch -from typing import ( - TYPE_CHECKING, - Any, - Callable, - ClassVar, - Dict, - Generic, - List, - Optional, - Tuple, - TypeVar, - Union, - get_args, - overload, -) - -try: - from types import UnionType # type: ignore[attr-defined] -except ImportError: - UnionType = None - -from typing_extensions import dataclass_transform - -from .exceptions import ValidationException -from .field import Binary, Boolean, Date, Field, Float, Integer, Nested, Object, Text -from .mapping import Mapping -from .utils import DOC_META_FIELDS, ObjectBase - -if TYPE_CHECKING: - from elastic_transport import ObjectApiResponse - - from .index_base import IndexBase - - -class MetaField: - def __init__(self, *args: Any, **kwargs: Any): - self.args, self.kwargs = args, kwargs - - -class InstrumentedField: - """Proxy object for a mapped document field. - - An object of this instance is returned when a field is accessed as a class - attribute of a ``Document`` or ``InnerDoc`` subclass. These objects can - be used in any situation in which a reference to a field is required, such - as when specifying sort options in a search:: - - class MyDocument(Document): - name: str - - s = MyDocument.search() - s = s.sort(-MyDocument.name) # sort by name in descending order - """ - - def __init__(self, name: str, field: Field): - self._name = name - self._field = field - - # note that the return value type here assumes classes will only be used to - # access fields (I haven't found a way to make this type dynamic based on a - # decision taken at runtime) - def __getattr__(self, attr: str) -> "InstrumentedField": - try: - # first let's see if this is an attribute of this object - return super().__getattribute__(attr) # type: ignore - except AttributeError: - try: - # next we see if we have a sub-field with this name - return InstrumentedField(f"{self._name}.{attr}", self._field[attr]) - except KeyError: - # lastly we let the wrapped field resolve this attribute - return getattr(self._field, attr) # type: ignore - - def __pos__(self) -> str: - """Return the field name representation for ascending sort order""" - return f"{self._name}" - - def __neg__(self) -> str: - """Return the field name representation for descending sort order""" - return f"-{self._name}" - - def __str__(self) -> str: - return self._name - - def __repr__(self) -> str: - return f"InstrumentedField[{self._name}]" - - -class DocumentMeta(type): - _doc_type: "DocumentOptions" - _index: "IndexBase" - - def __new__( - cls, name: str, bases: Tuple[type, ...], attrs: Dict[str, Any] - ) -> "DocumentMeta": - # DocumentMeta filters attrs in place - attrs["_doc_type"] = DocumentOptions(name, bases, attrs) - return super().__new__(cls, name, bases, attrs) - - def __getattr__(cls, attr: str) -> Any: - if attr in cls._doc_type.mapping: - return InstrumentedField(attr, cls._doc_type.mapping[attr]) - return super().__getattribute__(attr) - - -class DocumentOptions: - type_annotation_map = { - int: (Integer, {}), - float: (Float, {}), - bool: (Boolean, {}), - str: (Text, {}), - bytes: (Binary, {}), - datetime: (Date, {}), - date: (Date, {"format": "yyyy-MM-dd"}), - } - - def __init__(self, name: str, bases: Tuple[type, ...], attrs: Dict[str, Any]): - meta = attrs.pop("Meta", None) - - # create the mapping instance - self.mapping: Mapping = getattr(meta, "mapping", Mapping()) - - # register the document's fields, which can be given in a few formats: - # - # class MyDocument(Document): - # # required field using native typing - # # (str, int, float, bool, datetime, date) - # field1: str - # - # # optional field using native typing - # field2: Optional[datetime] - # - # # array field using native typing - # field3: list[int] - # - # # sub-object, same as Object(MyInnerDoc) - # field4: MyInnerDoc - # - # # nested sub-objects, same as Nested(MyInnerDoc) - # field5: list[MyInnerDoc] - # - # # use typing, but override with any stock or custom field - # field6: bool = MyCustomField() - # - # # best mypy and pyright support and dataclass-like behavior - # field7: M[date] - # field8: M[str] = mapped_field(MyCustomText(), default="foo") - # - # # legacy format without Python typing - # field9 = Text() - # - # # ignore attributes - # field10: ClassVar[string] = "a regular class variable" - annotations = attrs.get("__annotations__", {}) - fields = set([n for n in attrs if isinstance(attrs[n], Field)]) - fields.update(annotations.keys()) - field_defaults = {} - for name in fields: - value: Any = None - required = None - multi = None - if name in annotations: - # the field has a type annotation, so next we try to figure out - # what field type we can use - type_ = annotations[name] - skip = False - required = True - multi = False - while hasattr(type_, "__origin__"): - if type_.__origin__ == ClassVar: - skip = True - break - elif type_.__origin__ == Mapped: - # M[type] -> extract the wrapped type - type_ = type_.__args__[0] - elif type_.__origin__ == Union: - if len(type_.__args__) == 2 and type_.__args__[1] is type(None): - # Optional[type] -> mark instance as optional - required = False - type_ = type_.__args__[0] - else: - raise TypeError("Unsupported union") - elif type_.__origin__ in [list, List]: - # List[type] -> mark instance as multi - multi = True - required = False - type_ = type_.__args__[0] - else: - break - if skip or type_ == ClassVar: - # skip ClassVar attributes - continue - if type(type_) is UnionType: - # a union given with the pipe syntax - args = get_args(type_) - if len(args) == 2 and args[1] is type(None): - required = False - type_ = type_.__args__[0] - else: - raise TypeError("Unsupported union") - field = None - field_args: List[Any] = [] - field_kwargs: Dict[str, Any] = {} - if isinstance(type_, type) and issubclass(type_, InnerDoc): - # object or nested field - field = Nested if multi else Object - field_args = [type_] - elif type_ in self.type_annotation_map: - # use best field type for the type hint provided - field, field_kwargs = self.type_annotation_map[type_] # type: ignore - - if field: - field_kwargs = { - "multi": multi, - "required": required, - **field_kwargs, - } - value = field(*field_args, **field_kwargs) - - if name in attrs: - # 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): - # the mapped_field() wrapper function was used so we need - # to look for the field instance and also record any - # dataclass-style defaults - 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: - value = attr_value - if required is not None: - value._required = required - if multi is not None: - value._multi = multi - - if value is None: - raise TypeError(f"Cannot map field {name}") - - self.mapping.field(name, value) - if name in attrs: - del attrs[name] - - # store dataclass-style defaults for ObjectBase.__init__ to assign - attrs["_defaults"] = field_defaults - - # add all the mappings for meta fields - for name in dir(meta): - if isinstance(getattr(meta, name, None), MetaField): - params = getattr(meta, name) - self.mapping.meta(name, *params.args, **params.kwargs) - - # document inheritance - include the fields from parents' mappings - for b in bases: - if hasattr(b, "_doc_type") and hasattr(b._doc_type, "mapping"): - self.mapping.update(b._doc_type.mapping, update_only=True) - - @property - def name(self) -> str: - return self.mapping.properties.name - - -_FieldType = TypeVar("_FieldType") - - -class Mapped(Generic[_FieldType]): - """Class that represents the type of a mapped field. - - This class can be used as an optional wrapper on a field type to help type - checkers assign the correct type when the field is used as a class - attribute. - - Consider the following definitions:: - - class MyDocument(Document): - first: str - second: M[str] - - mydoc = MyDocument(first="1", second="2") - - Type checkers have no trouble inferring the type of both ``mydoc.first`` - and ``mydoc.second`` as ``str``, but while ``MyDocument.first`` will be - incorrectly typed as ``str``, ``MyDocument.second`` should be assigned the - correct ``InstrumentedField`` type. - """ - - __slots__: Dict[str, Any] = {} - - if TYPE_CHECKING: - - @overload - def __get__(self, instance: None, owner: Any) -> InstrumentedField: ... - - @overload - def __get__(self, instance: object, owner: Any) -> _FieldType: ... - - def __get__( - self, instance: Optional[object], owner: Any - ) -> Union[InstrumentedField, _FieldType]: ... - - def __set__(self, instance: Optional[object], value: _FieldType) -> None: ... - - def __delete__(self, instance: Any) -> None: ... - - -M = Mapped - - -def mapped_field( - field: Optional[Field] = None, - *, - init: bool = True, - default: Any = None, - default_factory: Optional[Callable[[], Any]] = None, - **kwargs: Any, -) -> Any: - """Construct a field using dataclass behaviors - - This function can be used in the right side of a document field definition - as a wrapper for the field instance or as a way to provide dataclass-compatible - 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. - :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``. - :param default: a default value to use for this field when one is not provided - 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. - """ - return { - "_field": field, - "init": init, - "default": default, - "default_factory": default_factory, - **kwargs, - } - - -@dataclass_transform(field_specifiers=(mapped_field,)) -class InnerDoc(ObjectBase, metaclass=DocumentMeta): - """ - Common class for inner documents like Object or Nested - """ - - @classmethod - def from_es( - cls, - data: Union[Dict[str, Any], "ObjectApiResponse[Any]"], - data_only: bool = False, - ) -> "InnerDoc": - if data_only: - data = {"_source": data} - return super().from_es(data) - - -class DocumentBase(ObjectBase): - """ - Model-like class for persisting documents in elasticsearch. - """ - - @classmethod - def _matches(cls, hit: Dict[str, Any]) -> bool: - if cls._index._name is None: - return True - return fnmatch(hit.get("_index", ""), cls._index._name) - - @classmethod - def _default_index(cls, index: Optional[str] = None) -> str: - return index or cls._index._name - - def _get_index( - self, index: Optional[str] = None, required: bool = True - ) -> Optional[str]: - if index is None: - index = getattr(self.meta, "index", None) - if index is None: - index = getattr(self._index, "_name", None) - if index is None and required: - raise ValidationException("No index") - if index and "*" in index: - raise ValidationException("You cannot write to a wildcard index.") - return index - - def __repr__(self) -> str: - return "{}({})".format( - self.__class__.__name__, - ", ".join( - f"{key}={getattr(self.meta, key)!r}" - for key in ("index", "id") - if key in self.meta - ), - ) - - def to_dict(self, include_meta: bool = False, skip_empty: bool = True) -> Dict[str, Any]: # type: ignore[override] - """ - Serialize the instance into a dictionary so that it can be saved in elasticsearch. - - :arg include_meta: if set to ``True`` will include all the metadata - (``_index``, ``_id`` etc). Otherwise just the document's - data is serialized. This is useful when passing multiple instances into - ``elasticsearch.helpers.bulk``. - :arg skip_empty: if set to ``False`` will cause empty values (``None``, - ``[]``, ``{}``) to be left on the document. Those values will be - stripped out otherwise as they make no difference in elasticsearch. - """ - d = super().to_dict(skip_empty=skip_empty) - if not include_meta: - return d - - meta = {"_" + k: self.meta[k] for k in DOC_META_FIELDS if k in self.meta} - - # in case of to_dict include the index unlike save/update/delete - index = self._get_index(required=False) - if index is not None: - meta["_index"] = index - - meta["_source"] = d - return meta diff --git a/elasticsearch_dsl/exceptions.py b/elasticsearch_dsl/exceptions.py deleted file mode 100644 index 8aae0ffa..00000000 --- a/elasticsearch_dsl/exceptions.py +++ /dev/null @@ -1,32 +0,0 @@ -# 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. - - -class ElasticsearchDslException(Exception): - pass - - -class UnknownDslObject(ElasticsearchDslException): - pass - - -class ValidationException(ValueError, ElasticsearchDslException): - pass - - -class IllegalOperation(ElasticsearchDslException): - pass diff --git a/elasticsearch_dsl/faceted_search.py b/elasticsearch_dsl/faceted_search.py deleted file mode 100644 index 706be627..00000000 --- a/elasticsearch_dsl/faceted_search.py +++ /dev/null @@ -1,28 +0,0 @@ -# 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 elasticsearch_dsl._async.faceted_search import AsyncFacetedSearch # noqa: F401 -from elasticsearch_dsl._sync.faceted_search import FacetedSearch # noqa: F401 -from elasticsearch_dsl.faceted_search_base import ( # noqa: F401 - DateHistogramFacet, - Facet, - FacetedResponse, - HistogramFacet, - NestedFacet, - RangeFacet, - TermsFacet, -) diff --git a/elasticsearch_dsl/faceted_search_base.py b/elasticsearch_dsl/faceted_search_base.py deleted file mode 100644 index 45e00a00..00000000 --- a/elasticsearch_dsl/faceted_search_base.py +++ /dev/null @@ -1,489 +0,0 @@ -# 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 datetime import datetime, timedelta -from typing import ( - TYPE_CHECKING, - Any, - Dict, - Generic, - List, - Optional, - Sequence, - Tuple, - Type, - Union, - cast, -) - -from typing_extensions import Self - -from .aggs import A, Agg -from .query import MatchAll, Nested, Query, Range, Terms -from .response import Response -from .utils import _R, AttrDict - -if TYPE_CHECKING: - from .document_base import DocumentBase - from .response.aggs import BucketData - from .search_base import SearchBase - -FilterValueType = Union[str, datetime, Sequence[str]] - -__all__ = [ - "FacetedSearchBase", - "HistogramFacet", - "TermsFacet", - "DateHistogramFacet", - "RangeFacet", - "NestedFacet", -] - - -class Facet(Generic[_R]): - """ - A facet on faceted search. Wraps and aggregation and provides functionality - to create a filter for selected values and return a list of facet values - from the result of the aggregation. - """ - - agg_type: str = "" - - def __init__( - self, metric: Optional[Agg[_R]] = None, metric_sort: str = "desc", **kwargs: Any - ): - self.filter_values = () - self._params = kwargs - self._metric = metric - if metric and metric_sort: - self._params["order"] = {"metric": metric_sort} - - def get_aggregation(self) -> Agg[_R]: - """ - Return the aggregation object. - """ - agg: Agg[_R] = A(self.agg_type, **self._params) - if self._metric: - agg.metric("metric", self._metric) - return agg - - def add_filter(self, filter_values: List[FilterValueType]) -> Optional[Query]: - """ - Construct a filter. - """ - if not filter_values: - return None - - f = self.get_value_filter(filter_values[0]) - for v in filter_values[1:]: - f |= self.get_value_filter(v) - return f - - def get_value_filter(self, filter_value: FilterValueType) -> Query: # type: ignore - """ - Construct a filter for an individual value - """ - pass - - def is_filtered(self, key: str, filter_values: List[FilterValueType]) -> bool: - """ - Is a filter active on the given key. - """ - return key in filter_values - - def get_value(self, bucket: "BucketData[_R]") -> Any: - """ - return a value representing a bucket. Its key as default. - """ - return bucket["key"] - - def get_metric(self, bucket: "BucketData[_R]") -> int: - """ - Return a metric, by default doc_count for a bucket. - """ - if self._metric: - return cast(int, bucket["metric"]["value"]) - return cast(int, bucket["doc_count"]) - - def get_values( - self, data: "BucketData[_R]", filter_values: List[FilterValueType] - ) -> List[Tuple[Any, int, bool]]: - """ - Turn the raw bucket data into a list of tuples containing the key, - number of documents and a flag indicating whether this value has been - selected or not. - """ - out = [] - for bucket in data.buckets: - b = cast("BucketData[_R]", bucket) - key = self.get_value(b) - out.append((key, self.get_metric(b), self.is_filtered(key, filter_values))) - return out - - -class TermsFacet(Facet[_R]): - agg_type = "terms" - - def add_filter(self, filter_values: List[FilterValueType]) -> Optional[Query]: - """Create a terms filter instead of bool containing term filters.""" - if filter_values: - return Terms(self._params["field"], filter_values, _expand__to_dot=False) - return None - - -class RangeFacet(Facet[_R]): - agg_type = "range" - - def _range_to_dict( - self, range: Tuple[Any, Tuple[Optional[int], Optional[int]]] - ) -> Dict[str, Any]: - key, _range = range - out: Dict[str, Any] = {"key": key} - if _range[0] is not None: - out["from"] = _range[0] - if _range[1] is not None: - out["to"] = _range[1] - return out - - def __init__( - self, - ranges: Sequence[Tuple[Any, Tuple[Optional[int], Optional[int]]]], - **kwargs: Any, - ): - super().__init__(**kwargs) - self._params["ranges"] = list(map(self._range_to_dict, ranges)) - self._params["keyed"] = False - self._ranges = dict(ranges) - - def get_value_filter(self, filter_value: FilterValueType) -> Query: - f, t = self._ranges[filter_value] - limits: Dict[str, Any] = {} - if f is not None: - limits["gte"] = f - if t is not None: - limits["lt"] = t - - return Range(self._params["field"], limits, _expand__to_dot=False) - - -class HistogramFacet(Facet[_R]): - agg_type = "histogram" - - def get_value_filter(self, filter_value: FilterValueType) -> Range: - return Range( - self._params["field"], - { - "gte": filter_value, - "lt": filter_value + self._params["interval"], - }, - _expand__to_dot=False, - ) - - -def _date_interval_year(d: datetime) -> datetime: - return d.replace( - year=d.year + 1, day=(28 if d.month == 2 and d.day == 29 else d.day) - ) - - -def _date_interval_month(d: datetime) -> datetime: - return (d + timedelta(days=32)).replace(day=1) - - -def _date_interval_week(d: datetime) -> datetime: - return d + timedelta(days=7) - - -def _date_interval_day(d: datetime) -> datetime: - return d + timedelta(days=1) - - -def _date_interval_hour(d: datetime) -> datetime: - return d + timedelta(hours=1) - - -class DateHistogramFacet(Facet[_R]): - agg_type = "date_histogram" - - DATE_INTERVALS = { - "year": _date_interval_year, - "1Y": _date_interval_year, - "month": _date_interval_month, - "1M": _date_interval_month, - "week": _date_interval_week, - "1w": _date_interval_week, - "day": _date_interval_day, - "1d": _date_interval_day, - "hour": _date_interval_hour, - "1h": _date_interval_hour, - } - - def __init__(self, **kwargs: Any): - kwargs.setdefault("min_doc_count", 0) - super().__init__(**kwargs) - - def get_value(self, bucket: "BucketData[_R]") -> Any: - if not isinstance(bucket["key"], datetime): - # Elasticsearch returns key=None instead of 0 for date 1970-01-01, - # so we need to set key to 0 to avoid TypeError exception - if bucket["key"] is None: - bucket["key"] = 0 - # Preserve milliseconds in the datetime - return datetime.utcfromtimestamp(int(cast(int, bucket["key"])) / 1000.0) - else: - return bucket["key"] - - def get_value_filter(self, filter_value: Any) -> Range: - for interval_type in ("calendar_interval", "fixed_interval"): - if interval_type in self._params: - break - else: - interval_type = "interval" - - return Range( - self._params["field"], - { - "gte": filter_value, - "lt": self.DATE_INTERVALS[self._params[interval_type]](filter_value), - }, - _expand__to_dot=False, - ) - - -class NestedFacet(Facet[_R]): - agg_type = "nested" - - def __init__(self, path: str, nested_facet: Facet[_R]): - self._path = path - self._inner = nested_facet - super().__init__(path=path, aggs={"inner": nested_facet.get_aggregation()}) - - def get_values( - self, data: "BucketData[_R]", filter_values: List[FilterValueType] - ) -> List[Tuple[Any, int, bool]]: - return self._inner.get_values(data.inner, filter_values) - - def add_filter(self, filter_values: List[FilterValueType]) -> Optional[Query]: - inner_q = self._inner.add_filter(filter_values) - if inner_q: - return Nested(path=self._path, query=inner_q) - return None - - -class FacetedResponse(Response[_R]): - if TYPE_CHECKING: - _faceted_search: "FacetedSearchBase[_R]" - _facets: Dict[str, List[Tuple[Any, int, bool]]] - - @property - def query_string(self) -> Optional[Union[str, Query]]: - return self._faceted_search._query - - @property - def facets(self) -> Dict[str, List[Tuple[Any, int, bool]]]: - if not hasattr(self, "_facets"): - super(AttrDict, self).__setattr__("_facets", AttrDict({})) - for name, facet in self._faceted_search.facets.items(): - self._facets[name] = facet.get_values( - getattr(getattr(self.aggregations, "_filter_" + name), name), - self._faceted_search.filter_values.get(name, []), - ) - return self._facets - - -class FacetedSearchBase(Generic[_R]): - """ - Abstraction for creating faceted navigation searches that takes care of - composing the queries, aggregations and filters as needed as well as - presenting the results in an easy-to-consume fashion:: - - class BlogSearch(FacetedSearch): - index = 'blogs' - doc_types = [Blog, Post] - fields = ['title^5', 'category', 'description', 'body'] - - facets = { - 'type': TermsFacet(field='_type'), - 'category': TermsFacet(field='category'), - 'weekly_posts': DateHistogramFacet(field='published_from', interval='week') - } - - def search(self): - ' Override search to add your own filters ' - s = super(BlogSearch, self).search() - return s.filter('term', published=True) - - # when using: - blog_search = BlogSearch("web framework", filters={"category": "python"}) - - # supports pagination - blog_search[10:20] - - response = blog_search.execute() - - # easy access to aggregation results: - for category, hit_count, is_selected in response.facets.category: - print( - "Category %s has %d hits%s." % ( - category, - hit_count, - ' and is chosen' if is_selected else '' - ) - ) - - """ - - index: Optional[str] = None - doc_types: Optional[List[Union[str, Type["DocumentBase"]]]] = None - fields: Sequence[str] = [] - facets: Dict[str, Facet[_R]] = {} - using = "default" - - if TYPE_CHECKING: - - def search(self) -> "SearchBase[_R]": ... - - def __init__( - self, - query: Optional[Union[str, Query]] = None, - filters: Dict[str, FilterValueType] = {}, - sort: Sequence[str] = [], - ): - """ - :arg query: the text to search for - :arg filters: facet values to filter - :arg sort: sort information to be passed to :class:`~elasticsearch_dsl.Search` - """ - self._query = query - self._filters: Dict[str, Query] = {} - self._sort = sort - self.filter_values: Dict[str, List[FilterValueType]] = {} - for name, value in filters.items(): - self.add_filter(name, value) - - self._s = self.build_search() - - def __getitem__(self, k: Union[int, slice]) -> Self: - self._s = self._s[k] - return self - - def add_filter( - self, name: str, filter_values: Union[FilterValueType, List[FilterValueType]] - ) -> None: - """ - Add a filter for a facet. - """ - # normalize the value into a list - if not isinstance(filter_values, (tuple, list)): - if filter_values is None: - return - filter_values = [ - filter_values, - ] - - # remember the filter values for use in FacetedResponse - self.filter_values[name] = filter_values # type: ignore[assignment] - - # get the filter from the facet - f = self.facets[name].add_filter(filter_values) # type: ignore[arg-type] - if f is None: - return - - self._filters[name] = f - - def query( - self, search: "SearchBase[_R]", query: Union[str, Query] - ) -> "SearchBase[_R]": - """ - Add query part to ``search``. - - Override this if you wish to customize the query used. - """ - if query: - if self.fields: - return search.query("multi_match", fields=self.fields, query=query) - else: - return search.query("multi_match", query=query) - return search - - def aggregate(self, search: "SearchBase[_R]") -> None: - """ - Add aggregations representing the facets selected, including potential - filters. - """ - for f, facet in self.facets.items(): - agg = facet.get_aggregation() - agg_filter: Query = MatchAll() - for field, filter in self._filters.items(): - if f == field: - continue - agg_filter &= filter - search.aggs.bucket("_filter_" + f, "filter", filter=agg_filter).bucket( - f, agg - ) - - def filter(self, search: "SearchBase[_R]") -> "SearchBase[_R]": - """ - Add a ``post_filter`` to the search request narrowing the results based - on the facet filters. - """ - if not self._filters: - return search - - post_filter: Query = MatchAll() - for f in self._filters.values(): - post_filter &= f - return search.post_filter(post_filter) - - def highlight(self, search: "SearchBase[_R]") -> "SearchBase[_R]": - """ - Add highlighting for all the fields - """ - return search.highlight( - *(f if "^" not in f else f.split("^", 1)[0] for f in self.fields) - ) - - def sort(self, search: "SearchBase[_R]") -> "SearchBase[_R]": - """ - Add sorting information to the request. - """ - if self._sort: - search = search.sort(*self._sort) - return search - - def params(self, **kwargs: Any) -> None: - """ - Specify query params to be used when executing the search. All the - keyword arguments will override the current values. See - https://elasticsearch-py.readthedocs.io/en/master/api.html#elasticsearch.Elasticsearch.search - for all available parameters. - """ - self._s = self._s.params(**kwargs) - - def build_search(self) -> "SearchBase[_R]": - """ - Construct the ``Search`` object. - """ - s = self.search() - if self._query is not None: - s = self.query(s, self._query) - s = self.filter(s) - if self.fields: - s = self.highlight(s) - s = self.sort(s) - self.aggregate(s) - return s diff --git a/elasticsearch_dsl/field.py b/elasticsearch_dsl/field.py deleted file mode 100644 index 55ab4f7f..00000000 --- a/elasticsearch_dsl/field.py +++ /dev/null @@ -1,587 +0,0 @@ -# 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 base64 -import collections.abc -import ipaddress -from copy import deepcopy -from datetime import date, datetime -from typing import ( - TYPE_CHECKING, - Any, - Dict, - Iterable, - Iterator, - Optional, - Tuple, - Type, - Union, - cast, -) - -from dateutil import parser, tz - -from .exceptions import ValidationException -from .query import Q -from .utils import AttrDict, AttrList, DslBase -from .wrappers import Range - -if TYPE_CHECKING: - from datetime import tzinfo - from ipaddress import IPv4Address, IPv6Address - - from _operator import _SupportsComparison - - from .document import InnerDoc - from .mapping_base import MappingBase - from .query import Query - -unicode = str - - -def construct_field( - name_or_field: Union[ - str, - "Field", - Dict[str, Any], - ], - **params: Any, -) -> "Field": - # {"type": "text", "analyzer": "snowball"} - if isinstance(name_or_field, collections.abc.Mapping): - if params: - raise ValueError( - "construct_field() cannot accept parameters when passing in a dict." - ) - params = deepcopy(name_or_field) - if "type" not in params: - # inner object can be implicitly defined - if "properties" in params: - name = "object" - else: - raise ValueError('construct_field() needs to have a "type" key.') - else: - name = params.pop("type") - return Field.get_dsl_class(name)(**params) - - # Text() - if isinstance(name_or_field, Field): - if params: - raise ValueError( - "construct_field() cannot accept parameters " - "when passing in a construct_field object." - ) - return name_or_field - - # "text", analyzer="snowball" - return Field.get_dsl_class(name_or_field)(**params) - - -class Field(DslBase): - _type_name = "field" - _type_shortcut = staticmethod(construct_field) - # all fields can be multifields - _param_defs = {"fields": {"type": "field", "hash": True}} - name = "" - _coerce = False - - def __init__( - self, multi: bool = False, required: bool = False, *args: Any, **kwargs: Any - ): - """ - :arg bool multi: specifies whether field can contain array of values - :arg bool required: specifies whether field is required - """ - self._multi = multi - self._required = required - super().__init__(*args, **kwargs) - - def __getitem__(self, subfield: str) -> "Field": - return cast(Field, self._params.get("fields", {})[subfield]) - - def _serialize(self, data: Any) -> Any: - return data - - def _deserialize(self, data: Any) -> Any: - return data - - def _empty(self) -> Optional[Any]: - return None - - def empty(self) -> Optional[Any]: - if self._multi: - return AttrList([]) - return self._empty() - - def serialize(self, data: Any) -> Any: - if isinstance(data, (list, AttrList, tuple)): - return list(map(self._serialize, cast(Iterable[Any], data))) - return self._serialize(data) - - def deserialize(self, data: Any) -> Any: - if isinstance(data, (list, AttrList, tuple)): - data = [ - None if d is None else self._deserialize(d) - for d in cast(Iterable[Any], data) - ] - return data - if data is None: - return None - return self._deserialize(data) - - def clean(self, data: Any) -> Any: - if data is not None: - data = self.deserialize(data) - if data in (None, [], {}) and self._required: - raise ValidationException("Value required for this field.") - return data - - def to_dict(self) -> Dict[str, Any]: - d = super().to_dict() - name, value = cast(Tuple[str, Dict[str, Any]], d.popitem()) - value["type"] = name - return value - - -class CustomField(Field): - name = "custom" - _coerce = True - - def to_dict(self) -> Dict[str, Any]: - if isinstance(self.builtin_type, Field): - return self.builtin_type.to_dict() - - d = super().to_dict() - d["type"] = self.builtin_type - return d - - -class Object(Field): - name = "object" - _coerce = True - - def __init__( - self, - doc_class: Optional[Type["InnerDoc"]] = None, - dynamic: Optional[Union[bool, str]] = None, - properties: Optional[Dict[str, Any]] = None, - **kwargs: Any, - ): - """ - :arg document.InnerDoc doc_class: base doc class that handles mapping. - If no `doc_class` is provided, new instance of `InnerDoc` will be created, - populated with `properties` and used. Can not be provided together with `properties` - :arg dynamic: whether new properties may be created dynamically. - Valid values are `True`, `False`, `'strict'`. - Can not be provided together with `doc_class`. - See https://www.elastic.co/guide/en/elasticsearch/reference/current/dynamic.html - for more details - :arg dict properties: used to construct underlying mapping if no `doc_class` is provided. - Can not be provided together with `doc_class` - """ - if doc_class and (properties or dynamic is not None): - raise ValidationException( - "doc_class and properties/dynamic should not be provided together" - ) - if doc_class: - self._doc_class: Type["InnerDoc"] = doc_class - else: - # FIXME import - from .document import InnerDoc - - # no InnerDoc subclass, creating one instead... - self._doc_class = type("InnerDoc", (InnerDoc,), {}) - for name, field in (properties or {}).items(): - self._doc_class._doc_type.mapping.field(name, field) - if dynamic is not None: - self._doc_class._doc_type.mapping.meta("dynamic", dynamic) - - self._mapping: "MappingBase" = deepcopy(self._doc_class._doc_type.mapping) - super().__init__(**kwargs) - - def __getitem__(self, name: str) -> Field: - return self._mapping[name] - - def __contains__(self, name: str) -> bool: - return name in self._mapping - - def _empty(self) -> "InnerDoc": - return self._wrap({}) - - def _wrap(self, data: Dict[str, Any]) -> "InnerDoc": - return self._doc_class.from_es(data, data_only=True) - - def empty(self) -> Union["InnerDoc", AttrList[Any]]: - if self._multi: - return AttrList[Any]([], self._wrap) - return self._empty() - - def to_dict(self) -> Dict[str, Any]: - d = self._mapping.to_dict() - d.update(super().to_dict()) - return d - - def _collect_fields(self) -> Iterator[Field]: - return self._mapping.properties._collect_fields() - - def _deserialize(self, data: Any) -> "InnerDoc": - # don't wrap already wrapped data - if isinstance(data, self._doc_class): - return data - - if isinstance(data, AttrDict): - data = data._d_ - - return self._wrap(data) - - def _serialize( - self, data: Optional[Union[Dict[str, Any], "InnerDoc"]] - ) -> Optional[Dict[str, Any]]: - if data is None: - return None - - # somebody assigned raw dict to the field, we should tolerate that - if isinstance(data, collections.abc.Mapping): - return data - - return data.to_dict() - - def clean(self, data: Any) -> Any: - data = super().clean(data) - if data is None: - return None - if isinstance(data, (list, AttrList)): - for d in cast(Iterator["InnerDoc"], data): - d.full_clean() - else: - data.full_clean() - return data - - def update(self, other: Any, update_only: bool = False) -> None: - if not isinstance(other, Object): - # not an inner/nested object, no merge possible - return - - self._mapping.update(other._mapping, update_only) - - -class Nested(Object): - name = "nested" - - def __init__(self, *args: Any, **kwargs: Any): - kwargs.setdefault("multi", True) - super().__init__(*args, **kwargs) - - -class Date(Field): - name = "date" - _coerce = True - - def __init__( - self, - default_timezone: Optional[Union[str, "tzinfo"]] = None, - *args: Any, - **kwargs: Any, - ): - """ - :arg default_timezone: timezone that will be automatically used for tz-naive values - May be instance of `datetime.tzinfo` or string containing TZ offset - """ - if isinstance(default_timezone, str): - self._default_timezone = tz.gettz(default_timezone) - else: - self._default_timezone = default_timezone - super().__init__(*args, **kwargs) - - def _deserialize(self, data: Any) -> Union[datetime, date]: - if isinstance(data, str): - try: - data = parser.parse(data) - except Exception as e: - raise ValidationException( - f"Could not parse date from the value ({data!r})", e - ) - # we treat the yyyy-MM-dd format as a special case - if hasattr(self, "format") and self.format == "yyyy-MM-dd": - data = data.date() - - if isinstance(data, datetime): - if self._default_timezone and data.tzinfo is None: - data = data.replace(tzinfo=self._default_timezone) - return data - if isinstance(data, date): - return data - if isinstance(data, int): - # Divide by a float to preserve milliseconds on the datetime. - return datetime.utcfromtimestamp(data / 1000.0) - - raise ValidationException(f"Could not parse date from the value ({data!r})") - - -class Text(Field): - _param_defs = { - "fields": {"type": "field", "hash": True}, - "analyzer": {"type": "analyzer"}, - "search_analyzer": {"type": "analyzer"}, - "search_quote_analyzer": {"type": "analyzer"}, - } - name = "text" - - -class SearchAsYouType(Field): - _param_defs = { - "analyzer": {"type": "analyzer"}, - "search_analyzer": {"type": "analyzer"}, - "search_quote_analyzer": {"type": "analyzer"}, - } - name = "search_as_you_type" - - -class Keyword(Field): - _param_defs = { - "fields": {"type": "field", "hash": True}, - "search_analyzer": {"type": "analyzer"}, - "normalizer": {"type": "normalizer"}, - } - name = "keyword" - - -class ConstantKeyword(Keyword): - name = "constant_keyword" - - -class Boolean(Field): - name = "boolean" - _coerce = True - - def _deserialize(self, data: Any) -> bool: - if data == "false": - return False - return bool(data) - - def clean(self, data: Any) -> Optional[bool]: - if data is not None: - data = self.deserialize(data) - if data is None and self._required: - raise ValidationException("Value required for this field.") - return data # type: ignore - - -class Float(Field): - name = "float" - _coerce = True - - def _deserialize(self, data: Any) -> float: - return float(data) - - -class DenseVector(Field): - name = "dense_vector" - _coerce = True - - def __init__(self, **kwargs: Any): - self._element_type = kwargs.get("element_type", "float") - if self._element_type in ["float", "byte"]: - kwargs["multi"] = True - super().__init__(**kwargs) - - def _deserialize(self, data: Any) -> Any: - if self._element_type == "float": - return float(data) - elif self._element_type == "byte": - return int(data) - return data - - -class SparseVector(Field): - name = "sparse_vector" - - -class HalfFloat(Float): - name = "half_float" - - -class ScaledFloat(Float): - name = "scaled_float" - - def __init__(self, scaling_factor: int, *args: Any, **kwargs: Any): - super().__init__(scaling_factor=scaling_factor, *args, **kwargs) - - -class Double(Float): - name = "double" - - -class RankFeature(Float): - name = "rank_feature" - - -class RankFeatures(Field): - name = "rank_features" - - -class Integer(Field): - name = "integer" - _coerce = True - - def _deserialize(self, data: Any) -> int: - return int(data) - - -class Byte(Integer): - name = "byte" - - -class Short(Integer): - name = "short" - - -class Long(Integer): - name = "long" - - -class Ip(Field): - name = "ip" - _coerce = True - - def _deserialize(self, data: Any) -> Union["IPv4Address", "IPv6Address"]: - # the ipaddress library for pypy only accepts unicode. - return ipaddress.ip_address(unicode(data)) - - def _serialize(self, data: Any) -> Optional[str]: - if data is None: - return None - return str(data) - - -class Binary(Field): - name = "binary" - _coerce = True - - def clean(self, data: str) -> str: - # Binary fields are opaque, so there's not much cleaning - # that can be done. - return data - - def _deserialize(self, data: Any) -> bytes: - return base64.b64decode(data) - - def _serialize(self, data: Any) -> Optional[str]: - if data is None: - return None - return base64.b64encode(data).decode() - - -class Point(Field): - name = "point" - - -class Shape(Field): - name = "shape" - - -class GeoPoint(Field): - name = "geo_point" - - -class GeoShape(Field): - name = "geo_shape" - - -class Completion(Field): - _param_defs = { - "analyzer": {"type": "analyzer"}, - "search_analyzer": {"type": "analyzer"}, - } - name = "completion" - - -class Percolator(Field): - name = "percolator" - _coerce = True - - def _deserialize(self, data: Any) -> "Query": - return Q(data) # type: ignore - - def _serialize(self, data: Any) -> Optional[Dict[str, Any]]: - if data is None: - return None - return data.to_dict() # type: ignore - - -class RangeField(Field): - _coerce = True - _core_field: Optional[Field] = None - - def _deserialize(self, data: Any) -> Range["_SupportsComparison"]: - if isinstance(data, Range): - return data - data = {k: self._core_field.deserialize(v) for k, v in data.items()} # type: ignore - return Range(data) - - def _serialize(self, data: Any) -> Optional[Dict[str, Any]]: - if data is None: - return None - if not isinstance(data, collections.abc.Mapping): - data = data.to_dict() - return {k: self._core_field.serialize(v) for k, v in data.items()} # type: ignore - - -class IntegerRange(RangeField): - name = "integer_range" - _core_field = Integer() - - -class FloatRange(RangeField): - name = "float_range" - _core_field = Float() - - -class LongRange(RangeField): - name = "long_range" - _core_field = Long() - - -class DoubleRange(RangeField): - name = "double_range" - _core_field = Double() - - -class DateRange(RangeField): - name = "date_range" - _core_field = Date() - - -class IpRange(Field): - # not a RangeField since ip_range supports CIDR ranges - name = "ip_range" - - -class Join(Field): - name = "join" - - -class TokenCount(Field): - name = "token_count" - - -class Murmur3(Field): - name = "murmur3" - - -class SemanticText(Field): - name = "semantic_text" diff --git a/elasticsearch_dsl/function.py b/elasticsearch_dsl/function.py deleted file mode 100644 index 9744e6f8..00000000 --- a/elasticsearch_dsl/function.py +++ /dev/null @@ -1,180 +0,0 @@ -# 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 collections.abc -from copy import deepcopy -from typing import ( - Any, - ClassVar, - Dict, - Literal, - MutableMapping, - Optional, - Union, - overload, -) - -from elastic_transport.client_utils import DEFAULT, DefaultType - -from .utils import AttrDict, DslBase - - -@overload -def SF(name_or_sf: MutableMapping[str, Any]) -> "ScoreFunction": ... - - -@overload -def SF(name_or_sf: "ScoreFunction") -> "ScoreFunction": ... - - -@overload -def SF(name_or_sf: str, **params: Any) -> "ScoreFunction": ... - - -def SF( - name_or_sf: Union[str, "ScoreFunction", MutableMapping[str, Any]], - **params: Any, -) -> "ScoreFunction": - # {"script_score": {"script": "_score"}, "filter": {}} - if isinstance(name_or_sf, collections.abc.MutableMapping): - if params: - raise ValueError("SF() cannot accept parameters when passing in a dict.") - - kwargs: Dict[str, Any] = {} - sf = deepcopy(name_or_sf) - for k in ScoreFunction._param_defs: - if k in name_or_sf: - kwargs[k] = sf.pop(k) - - # not sf, so just filter+weight, which used to be boost factor - sf_params = params - if not sf: - name = "boost_factor" - # {'FUNCTION': {...}} - elif len(sf) == 1: - name, sf_params = sf.popitem() - else: - raise ValueError(f"SF() got an unexpected fields in the dictionary: {sf!r}") - - # boost factor special case, see elasticsearch #6343 - if not isinstance(sf_params, collections.abc.Mapping): - sf_params = {"value": sf_params} - - # mix known params (from _param_defs) and from inside the function - kwargs.update(sf_params) - return ScoreFunction.get_dsl_class(name)(**kwargs) - - # ScriptScore(script="_score", filter=Q()) - if isinstance(name_or_sf, ScoreFunction): - if params: - raise ValueError( - "SF() cannot accept parameters when passing in a ScoreFunction object." - ) - return name_or_sf - - # "script_score", script="_score", filter=Q() - return ScoreFunction.get_dsl_class(name_or_sf)(**params) - - -class ScoreFunction(DslBase): - _type_name = "score_function" - _type_shortcut = staticmethod(SF) - _param_defs = { - "query": {"type": "query"}, - "filter": {"type": "query"}, - "weight": {}, - } - name: ClassVar[Optional[str]] = None - - def to_dict(self) -> Dict[str, Any]: - d = super().to_dict() - # filter and query dicts should be at the same level as us - for k in self._param_defs: - if self.name is not None: - val = d[self.name] - if isinstance(val, dict) and k in val: - d[k] = val.pop(k) - return d - - -class ScriptScore(ScoreFunction): - name = "script_score" - - -class BoostFactor(ScoreFunction): - name = "boost_factor" - - def to_dict(self) -> Dict[str, Any]: - d = super().to_dict() - if self.name is not None: - val = d[self.name] - if isinstance(val, dict): - if "value" in val: - d[self.name] = val.pop("value") - else: - del d[self.name] - return d - - -class RandomScore(ScoreFunction): - name = "random_score" - - -class FieldValueFactorScore(ScoreFunction): - name = "field_value_factor" - - -class FieldValueFactor(FieldValueFactorScore): # alias of the above - pass - - -class Linear(ScoreFunction): - name = "linear" - - -class Gauss(ScoreFunction): - name = "gauss" - - -class Exp(ScoreFunction): - name = "exp" - - -class DecayFunction(AttrDict[Any]): - def __init__( - self, - *, - decay: Union[float, "DefaultType"] = DEFAULT, - offset: Any = DEFAULT, - scale: Any = DEFAULT, - origin: Any = DEFAULT, - multi_value_mode: Union[ - Literal["min", "max", "avg", "sum"], "DefaultType" - ] = DEFAULT, - **kwargs: Any, - ): - if decay != DEFAULT: - kwargs["decay"] = decay - if offset != DEFAULT: - kwargs["offset"] = offset - if scale != DEFAULT: - kwargs["scale"] = scale - if origin != DEFAULT: - kwargs["origin"] = origin - if multi_value_mode != DEFAULT: - kwargs["multi_value_mode"] = multi_value_mode - super().__init__(kwargs) diff --git a/elasticsearch_dsl/index.py b/elasticsearch_dsl/index.py deleted file mode 100644 index 368e58d4..00000000 --- a/elasticsearch_dsl/index.py +++ /dev/null @@ -1,23 +0,0 @@ -# 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 ._async.index import ( # noqa: F401 - AsyncComposableIndexTemplate, - AsyncIndex, - AsyncIndexTemplate, -) -from ._sync.index import ComposableIndexTemplate, Index, IndexTemplate # noqa: F401 diff --git a/elasticsearch_dsl/index_base.py b/elasticsearch_dsl/index_base.py deleted file mode 100644 index d34c352a..00000000 --- a/elasticsearch_dsl/index_base.py +++ /dev/null @@ -1,178 +0,0 @@ -# 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, Any, Dict, List, Optional, Tuple - -from typing_extensions import Self - -from . import analysis -from .utils import AnyUsingType, merge - -if TYPE_CHECKING: - from .document_base import DocumentMeta - from .field import Field - from .mapping_base import MappingBase - - -class IndexBase: - def __init__(self, name: str, mapping_class: type, using: AnyUsingType = "default"): - """ - :arg name: name of the index - :arg using: connection alias to use, defaults to ``'default'`` - """ - self._name = name - self._doc_types: List["DocumentMeta"] = [] - self._using = using - self._settings: Dict[str, Any] = {} - self._aliases: Dict[str, Any] = {} - self._analysis: Dict[str, Any] = {} - self._mapping_class = mapping_class - self._mapping: Optional["MappingBase"] = None - - def resolve_nested( - self, field_path: str - ) -> Tuple[List[str], Optional["MappingBase"]]: - for doc in self._doc_types: - nested, field = doc._doc_type.mapping.resolve_nested(field_path) - if field is not None: - return nested, field - if self._mapping: - return self._mapping.resolve_nested(field_path) - return [], None - - def resolve_field(self, field_path: str) -> Optional["Field"]: - for doc in self._doc_types: - field = doc._doc_type.mapping.resolve_field(field_path) - if field is not None: - return field - if self._mapping: - return self._mapping.resolve_field(field_path) - return None - - def get_or_create_mapping(self) -> "MappingBase": - if self._mapping is None: - self._mapping = self._mapping_class() - return self._mapping - - def mapping(self, mapping: "MappingBase") -> None: - """ - Associate a mapping (an instance of - :class:`~elasticsearch_dsl.Mapping`) with this index. - This means that, when this index is created, it will contain the - mappings for the document type defined by those mappings. - """ - self.get_or_create_mapping().update(mapping) - - def document(self, document: "DocumentMeta") -> "DocumentMeta": - """ - Associate a :class:`~elasticsearch_dsl.Document` subclass with an index. - This means that, when this index is created, it will contain the - mappings for the ``Document``. If the ``Document`` class doesn't have a - default index yet (by defining ``class Index``), this instance will be - used. Can be used as a decorator:: - - i = Index('blog') - - @i.document - class Post(Document): - title = Text() - - # create the index, including Post mappings - i.create() - - # .search() will now return a Search object that will return - # properly deserialized Post instances - s = i.search() - """ - self._doc_types.append(document) - - # If the document index does not have any name, that means the user - # did not set any index already to the document. - # So set this index as document index - if document._index._name is None: - document._index = self - - return document - - def settings(self, **kwargs: Any) -> Self: - """ - Add settings to the index:: - - i = Index('i') - i.settings(number_of_shards=1, number_of_replicas=0) - - Multiple calls to ``settings`` will merge the keys, later overriding - the earlier. - """ - self._settings.update(kwargs) - return self - - def aliases(self, **kwargs: Any) -> Self: - """ - Add aliases to the index definition:: - - i = Index('blog-v2') - i.aliases(blog={}, published={'filter': Q('term', published=True)}) - """ - self._aliases.update(kwargs) - return self - - def analyzer(self, *args: Any, **kwargs: Any) -> None: - """ - Explicitly add an analyzer to an index. Note that all custom analyzers - defined in mappings will also be created. This is useful for search analyzers. - - Example:: - - from elasticsearch_dsl import analyzer, tokenizer - - my_analyzer = analyzer('my_analyzer', - tokenizer=tokenizer('trigram', 'nGram', min_gram=3, max_gram=3), - filter=['lowercase'] - ) - - i = Index('blog') - i.analyzer(my_analyzer) - - """ - analyzer = analysis.analyzer(*args, **kwargs) - d = analyzer.get_analysis_definition() - # empty custom analyzer, probably already defined out of our control - if not d: - return - - # merge the definition - merge(self._analysis, d, True) - - def to_dict(self) -> Dict[str, Any]: - out = {} - if self._settings: - out["settings"] = self._settings - if self._aliases: - out["aliases"] = self._aliases - mappings = self._mapping.to_dict() if self._mapping else {} - analysis = self._mapping._collect_analysis() if self._mapping else {} - for d in self._doc_types: - mapping = d._doc_type.mapping - merge(mappings, mapping.to_dict(), True) - merge(analysis, mapping._collect_analysis(), True) - if mappings: - out["mappings"] = mappings - if analysis or self._analysis: - merge(analysis, self._analysis) - out.setdefault("settings", {})["analysis"] = analysis - return out diff --git a/elasticsearch_dsl/mapping.py b/elasticsearch_dsl/mapping.py deleted file mode 100644 index 301de281..00000000 --- a/elasticsearch_dsl/mapping.py +++ /dev/null @@ -1,19 +0,0 @@ -# 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 elasticsearch_dsl._async.mapping import AsyncMapping # noqa: F401 -from elasticsearch_dsl._sync.mapping import Mapping # noqa: F401 diff --git a/elasticsearch_dsl/mapping_base.py b/elasticsearch_dsl/mapping_base.py deleted file mode 100644 index 658cf6cf..00000000 --- a/elasticsearch_dsl/mapping_base.py +++ /dev/null @@ -1,219 +0,0 @@ -# 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 collections.abc -from itertools import chain -from typing import Any, Dict, Iterator, List, Optional, Tuple, cast - -from typing_extensions import Self - -from .field import Field, Nested, Text, construct_field -from .utils import DslBase - -META_FIELDS = frozenset( - ( - "dynamic", - "transform", - "dynamic_date_formats", - "date_detection", - "numeric_detection", - "dynamic_templates", - "enabled", - ) -) - - -class Properties(DslBase): - name = "properties" - _param_defs = {"properties": {"type": "field", "hash": True}} - - properties: Dict[str, Field] - - def __init__(self) -> None: - super().__init__() - - def __repr__(self) -> str: - return "Properties()" - - def __getitem__(self, name: str) -> Field: - return self.properties[name] - - def __contains__(self, name: str) -> bool: - return name in self.properties - - def to_dict(self) -> Dict[str, Any]: - return cast(Dict[str, Field], super().to_dict()["properties"]) - - def field(self, name: str, *args: Any, **kwargs: Any) -> Self: - self.properties[name] = construct_field(*args, **kwargs) - return self - - def _collect_fields(self) -> Iterator[Field]: - """Iterate over all Field objects within, including multi fields.""" - fields = cast(Dict[str, Field], self.properties.to_dict()) # type: ignore - for f in fields.values(): - yield f - # multi fields - if hasattr(f, "fields"): - yield from f.fields.to_dict().values() - # nested and inner objects - if hasattr(f, "_collect_fields"): - yield from f._collect_fields() - - def update(self, other_object: Any) -> None: - if not hasattr(other_object, "properties"): - # not an inner/nested object, no merge possible - return - - our, other = self.properties, other_object.properties - for name in other: - if name in our: - if hasattr(our[name], "update"): - our[name].update(other[name]) - continue - our[name] = other[name] - - -class MappingBase: - def __init__(self) -> None: - self.properties = Properties() - self._meta: Dict[str, Any] = {} - - def __repr__(self) -> str: - return "Mapping()" - - def _clone(self) -> Self: - m = self.__class__() - m.properties._params = self.properties._params.copy() - return m - - def resolve_nested( - self, field_path: str - ) -> Tuple[List[str], Optional["MappingBase"]]: - field = self - nested = [] - parts = field_path.split(".") - for i, step in enumerate(parts): - try: - field = field[step] # type: ignore[assignment] - except KeyError: - return [], None - if isinstance(field, Nested): - nested.append(".".join(parts[: i + 1])) - return nested, field - - def resolve_field(self, field_path: str) -> Optional[Field]: - field = self - for step in field_path.split("."): - try: - field = field[step] # type: ignore[assignment] - except KeyError: - return None - return cast(Field, field) - - def _collect_analysis(self) -> Dict[str, Any]: - analysis: Dict[str, Any] = {} - fields = [] - if "_all" in self._meta: - fields.append(Text(**self._meta["_all"])) - - for f in chain(fields, self.properties._collect_fields()): - for analyzer_name in ( - "analyzer", - "normalizer", - "search_analyzer", - "search_quote_analyzer", - ): - if not hasattr(f, analyzer_name): - continue - analyzer = getattr(f, analyzer_name) - d = analyzer.get_analysis_definition() - # empty custom analyzer, probably already defined out of our control - if not d: - continue - - # merge the definition - # TODO: conflict detection/resolution - for key in d: - analysis.setdefault(key, {}).update(d[key]) - - return analysis - - def _update_from_dict(self, raw: Dict[str, Any]) -> None: - for name, definition in raw.get("properties", {}).items(): - self.field(name, definition) - - # metadata like _all etc - for name, value in raw.items(): - if name != "properties": - if isinstance(value, collections.abc.Mapping): - self.meta(name, **value) - else: - self.meta(name, value) - - def update(self, mapping: "MappingBase", update_only: bool = False) -> None: - for name in mapping: - if update_only and name in self: - # nested and inner objects, merge recursively - if hasattr(self[name], "update"): - # FIXME only merge subfields, not the settings - self[name].update(mapping[name], update_only) - continue - self.field(name, mapping[name]) - - if update_only: - for name in mapping._meta: - if name not in self._meta: - self._meta[name] = mapping._meta[name] - else: - self._meta.update(mapping._meta) - - def __contains__(self, name: str) -> bool: - return name in self.properties.properties - - def __getitem__(self, name: str) -> Field: - return self.properties.properties[name] - - def __iter__(self) -> Iterator[str]: - return iter(self.properties.properties) - - def field(self, *args: Any, **kwargs: Any) -> Self: - self.properties.field(*args, **kwargs) - return self - - def meta(self, name: str, params: Any = None, **kwargs: Any) -> Self: - if not name.startswith("_") and name not in META_FIELDS: - name = "_" + name - - if params and kwargs: - raise ValueError("Meta configs cannot have both value and a dictionary.") - - self._meta[name] = kwargs if params is None else params - return self - - def to_dict(self) -> Dict[str, Any]: - meta = self._meta - - # hard coded serialization of analyzers in _all - if "_all" in meta: - meta = meta.copy() - _all = meta["_all"] = meta["_all"].copy() - for f in ("analyzer", "search_analyzer", "search_quote_analyzer"): - if hasattr(_all.get(f, None), "to_dict"): - _all[f] = _all[f].to_dict() - meta.update(self.properties.to_dict()) - return meta diff --git a/elasticsearch_dsl/py.typed b/elasticsearch_dsl/py.typed deleted file mode 100644 index e69de29b..00000000 diff --git a/elasticsearch_dsl/query.py b/elasticsearch_dsl/query.py deleted file mode 100644 index 868610da..00000000 --- a/elasticsearch_dsl/query.py +++ /dev/null @@ -1,2795 +0,0 @@ -# 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 collections.abc -from copy import deepcopy -from itertools import chain -from typing import ( - TYPE_CHECKING, - Any, - Callable, - ClassVar, - Dict, - List, - Literal, - Mapping, - MutableMapping, - Optional, - Protocol, - Sequence, - TypeVar, - Union, - cast, - overload, -) - -from elastic_transport.client_utils import DEFAULT - -# 'SF' looks unused but the test suite assumes it's available -# from this module so others are liable to do so as well. -from .function import SF # noqa: F401 -from .function import ScoreFunction -from .utils import DslBase - -if TYPE_CHECKING: - from elastic_transport.client_utils import DefaultType - - from elasticsearch_dsl import types, wrappers - - from .document_base import InstrumentedField - -_T = TypeVar("_T") -_M = TypeVar("_M", bound=Mapping[str, Any]) - - -class QProxiedProtocol(Protocol[_T]): - _proxied: _T - - -@overload -def Q(name_or_query: MutableMapping[str, _M]) -> "Query": ... - - -@overload -def Q(name_or_query: "Query") -> "Query": ... - - -@overload -def Q(name_or_query: QProxiedProtocol[_T]) -> _T: ... - - -@overload -def Q(name_or_query: str = "match_all", **params: Any) -> "Query": ... - - -def Q( - name_or_query: Union[ - str, - "Query", - QProxiedProtocol[_T], - MutableMapping[str, _M], - ] = "match_all", - **params: Any, -) -> Union["Query", _T]: - # {"match": {"title": "python"}} - if isinstance(name_or_query, collections.abc.MutableMapping): - if params: - raise ValueError("Q() cannot accept parameters when passing in a dict.") - if len(name_or_query) != 1: - raise ValueError( - 'Q() can only accept dict with a single query ({"match": {...}}). ' - "Instead it got (%r)" % name_or_query - ) - name, q_params = deepcopy(name_or_query).popitem() - return Query.get_dsl_class(name)(_expand__to_dot=False, **q_params) - - # MatchAll() - if isinstance(name_or_query, Query): - if params: - raise ValueError( - "Q() cannot accept parameters when passing in a Query object." - ) - return name_or_query - - # s.query = Q('filtered', query=s.query) - if hasattr(name_or_query, "_proxied"): - return cast(QProxiedProtocol[_T], name_or_query)._proxied - - # "match", title="python" - return Query.get_dsl_class(name_or_query)(**params) - - -class Query(DslBase): - _type_name = "query" - _type_shortcut = staticmethod(Q) - name: ClassVar[Optional[str]] = None - - # Add type annotations for methods not defined in every subclass - __ror__: ClassVar[Callable[["Query", "Query"], "Query"]] - __radd__: ClassVar[Callable[["Query", "Query"], "Query"]] - __rand__: ClassVar[Callable[["Query", "Query"], "Query"]] - - def __add__(self, other: "Query") -> "Query": - # make sure we give queries that know how to combine themselves - # preference - if hasattr(other, "__radd__"): - return other.__radd__(self) - return Bool(must=[self, other]) - - def __invert__(self) -> "Query": - return Bool(must_not=[self]) - - def __or__(self, other: "Query") -> "Query": - # make sure we give queries that know how to combine themselves - # preference - if hasattr(other, "__ror__"): - return other.__ror__(self) - return Bool(should=[self, other]) - - def __and__(self, other: "Query") -> "Query": - # make sure we give queries that know how to combine themselves - # preference - if hasattr(other, "__rand__"): - return other.__rand__(self) - return Bool(must=[self, other]) - - -class Bool(Query): - """ - matches documents matching boolean combinations of other queries. - - :arg filter: The clause (query) must appear in matching documents. - However, unlike `must`, the score of the query will be ignored. - :arg minimum_should_match: Specifies the number or percentage of - `should` clauses returned documents must match. - :arg must: The clause (query) must appear in matching documents and - will contribute to the score. - :arg must_not: The clause (query) must not appear in the matching - documents. Because scoring is ignored, a score of `0` is returned - for all documents. - :arg should: The clause (query) should appear in the matching - document. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "bool" - _param_defs = { - "filter": {"type": "query", "multi": True}, - "must": {"type": "query", "multi": True}, - "must_not": {"type": "query", "multi": True}, - "should": {"type": "query", "multi": True}, - } - - def __init__( - self, - *, - filter: Union[Query, Sequence[Query], "DefaultType"] = DEFAULT, - minimum_should_match: Union[int, str, "DefaultType"] = DEFAULT, - must: Union[Query, Sequence[Query], "DefaultType"] = DEFAULT, - must_not: Union[Query, Sequence[Query], "DefaultType"] = DEFAULT, - should: Union[Query, Sequence[Query], "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - filter=filter, - minimum_should_match=minimum_should_match, - must=must, - must_not=must_not, - should=should, - boost=boost, - _name=_name, - **kwargs, - ) - - def __add__(self, other: Query) -> "Bool": - q = self._clone() - if isinstance(other, Bool): - q.must += other.must - q.should += other.should - q.must_not += other.must_not - q.filter += other.filter - else: - q.must.append(other) - return q - - __radd__ = __add__ - - def __or__(self, other: Query) -> Query: - for q in (self, other): - if isinstance(q, Bool) and not any( - (q.must, q.must_not, q.filter, getattr(q, "minimum_should_match", None)) - ): - other = self if q is other else other - q = q._clone() - if isinstance(other, Bool) and not any( - ( - other.must, - other.must_not, - other.filter, - getattr(other, "minimum_should_match", None), - ) - ): - q.should.extend(other.should) - else: - q.should.append(other) - return q - - return Bool(should=[self, other]) - - __ror__ = __or__ - - @property - def _min_should_match(self) -> int: - return getattr( - self, - "minimum_should_match", - 0 if not self.should or (self.must or self.filter) else 1, - ) - - def __invert__(self) -> Query: - # Because an empty Bool query is treated like - # MatchAll the inverse should be MatchNone - if not any(chain(self.must, self.filter, self.should, self.must_not)): - return MatchNone() - - negations: List[Query] = [] - for q in chain(self.must, self.filter): - negations.append(~q) - - for q in self.must_not: - negations.append(q) - - if self.should and self._min_should_match: - negations.append(Bool(must_not=self.should[:])) - - if len(negations) == 1: - return negations[0] - return Bool(should=negations) - - def __and__(self, other: Query) -> Query: - q = self._clone() - if isinstance(other, Bool): - q.must += other.must - q.must_not += other.must_not - q.filter += other.filter - q.should = [] - - # reset minimum_should_match as it will get calculated below - if "minimum_should_match" in q._params: - del q._params["minimum_should_match"] - - for qx in (self, other): - min_should_match = qx._min_should_match - # TODO: percentages or negative numbers will fail here - # for now we report an error - if not isinstance(min_should_match, int) or min_should_match < 0: - raise ValueError( - "Can only combine queries with positive integer values for minimum_should_match" - ) - # all subqueries are required - if len(qx.should) <= min_should_match: - q.must.extend(qx.should) - # not all of them are required, use it and remember min_should_match - elif not q.should: - q.minimum_should_match = min_should_match - q.should = qx.should - # all queries are optional, just extend should - elif q._min_should_match == 0 and min_should_match == 0: - q.should.extend(qx.should) - # not all are required, add a should list to the must with proper min_should_match - else: - q.must.append( - Bool(should=qx.should, minimum_should_match=min_should_match) - ) - else: - if not (q.must or q.filter) and q.should: - q._params.setdefault("minimum_should_match", 1) - q.must.append(other) - return q - - __rand__ = __and__ - - -class Boosting(Query): - """ - Returns documents matching a `positive` query while reducing the - relevance score of documents that also match a `negative` query. - - :arg negative_boost: (required) Floating point number between 0 and - 1.0 used to decrease the relevance scores of documents matching - the `negative` query. - :arg negative: (required) Query used to decrease the relevance score - of matching documents. - :arg positive: (required) Any returned documents must match this - query. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "boosting" - _param_defs = { - "negative": {"type": "query"}, - "positive": {"type": "query"}, - } - - def __init__( - self, - *, - negative_boost: Union[float, "DefaultType"] = DEFAULT, - negative: Union[Query, "DefaultType"] = DEFAULT, - positive: Union[Query, "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - negative_boost=negative_boost, - negative=negative, - positive=positive, - boost=boost, - _name=_name, - **kwargs, - ) - - -class Common(Query): - """ - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - """ - - name = "common" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union[ - "types.CommonTermsQuery", Dict[str, Any], "DefaultType" - ] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__(**kwargs) - - -class CombinedFields(Query): - """ - The `combined_fields` query supports searching multiple text fields as - if their contents had been indexed into one combined field. - - :arg fields: (required) List of fields to search. Field wildcard - patterns are allowed. Only `text` fields are supported, and they - must all have the same search `analyzer`. - :arg query: (required) Text to search for in the provided `fields`. - The `combined_fields` query analyzes the provided text before - performing a search. - :arg auto_generate_synonyms_phrase_query: If true, match phrase - queries are automatically created for multi-term synonyms. - Defaults to `True` if omitted. - :arg operator: Boolean logic used to interpret text in the query - value. Defaults to `or` if omitted. - :arg minimum_should_match: Minimum number of clauses that must match - for a document to be returned. - :arg zero_terms_query: Indicates whether no documents are returned if - the analyzer removes all tokens, such as when using a `stop` - filter. Defaults to `none` if omitted. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "combined_fields" - - def __init__( - self, - *, - fields: Union[ - Sequence[Union[str, "InstrumentedField"]], "DefaultType" - ] = DEFAULT, - query: Union[str, "DefaultType"] = DEFAULT, - auto_generate_synonyms_phrase_query: Union[bool, "DefaultType"] = DEFAULT, - operator: Union[Literal["or", "and"], "DefaultType"] = DEFAULT, - minimum_should_match: Union[int, str, "DefaultType"] = DEFAULT, - zero_terms_query: Union[Literal["none", "all"], "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - fields=fields, - query=query, - auto_generate_synonyms_phrase_query=auto_generate_synonyms_phrase_query, - operator=operator, - minimum_should_match=minimum_should_match, - zero_terms_query=zero_terms_query, - boost=boost, - _name=_name, - **kwargs, - ) - - -class ConstantScore(Query): - """ - Wraps a filter query and returns every matching document with a - relevance score equal to the `boost` parameter value. - - :arg filter: (required) Filter query you wish to run. Any returned - documents must match this query. Filter queries do not calculate - relevance scores. To speed up performance, Elasticsearch - automatically caches frequently used filter queries. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "constant_score" - _param_defs = { - "filter": {"type": "query"}, - } - - def __init__( - self, - *, - filter: Union[Query, "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(filter=filter, boost=boost, _name=_name, **kwargs) - - -class DisMax(Query): - """ - Returns documents matching one or more wrapped queries, called query - clauses or clauses. If a returned document matches multiple query - clauses, the `dis_max` query assigns the document the highest - relevance score from any matching clause, plus a tie breaking - increment for any additional matching subqueries. - - :arg queries: (required) One or more query clauses. Returned documents - must match one or more of these queries. If a document matches - multiple queries, Elasticsearch uses the highest relevance score. - :arg tie_breaker: Floating point number between 0 and 1.0 used to - increase the relevance scores of documents matching multiple query - clauses. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "dis_max" - _param_defs = { - "queries": {"type": "query", "multi": True}, - } - - def __init__( - self, - *, - queries: Union[Sequence[Query], "DefaultType"] = DEFAULT, - tie_breaker: Union[float, "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - queries=queries, tie_breaker=tie_breaker, boost=boost, _name=_name, **kwargs - ) - - -class DistanceFeature(Query): - """ - Boosts the relevance score of documents closer to a provided origin - date or point. For example, you can use this query to give more weight - to documents closer to a certain date or location. - - :arg origin: (required) Date or point of origin used to calculate - distances. If the `field` value is a `date` or `date_nanos` field, - the `origin` value must be a date. Date Math, such as `now-1h`, is - supported. If the field value is a `geo_point` field, the `origin` - value must be a geopoint. - :arg pivot: (required) Distance from the `origin` at which relevance - scores receive half of the `boost` value. If the `field` value is - a `date` or `date_nanos` field, the `pivot` value must be a time - unit, such as `1h` or `10d`. If the `field` value is a `geo_point` - field, the `pivot` value must be a distance unit, such as `1km` or - `12m`. - :arg field: (required) Name of the field used to calculate distances. - This field must meet the following criteria: be a `date`, - `date_nanos` or `geo_point` field; have an `index` mapping - parameter value of `true`, which is the default; have an - `doc_values` mapping parameter value of `true`, which is the - default. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "distance_feature" - - def __init__( - self, - *, - origin: Any = DEFAULT, - pivot: Any = DEFAULT, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - origin=origin, pivot=pivot, field=field, boost=boost, _name=_name, **kwargs - ) - - -class Exists(Query): - """ - Returns documents that contain an indexed value for a field. - - :arg field: (required) Name of the field you wish to search. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "exists" - - def __init__( - self, - *, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(field=field, boost=boost, _name=_name, **kwargs) - - -class FunctionScore(Query): - """ - The `function_score` enables you to modify the score of documents that - are retrieved by a query. - - :arg boost_mode: Defines how he newly computed score is combined with - the score of the query Defaults to `multiply` if omitted. - :arg functions: One or more functions that compute a new score for - each document returned by the query. - :arg max_boost: Restricts the new score to not exceed the provided - limit. - :arg min_score: Excludes documents that do not meet the provided score - threshold. - :arg query: A query that determines the documents for which a new - score is computed. - :arg score_mode: Specifies how the computed scores are combined - Defaults to `multiply` if omitted. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "function_score" - _param_defs = { - "functions": {"type": "score_function", "multi": True}, - "query": {"type": "query"}, - "filter": {"type": "query"}, - } - - def __init__( - self, - *, - boost_mode: Union[ - Literal["multiply", "replace", "sum", "avg", "max", "min"], "DefaultType" - ] = DEFAULT, - functions: Union[Sequence[ScoreFunction], "DefaultType"] = DEFAULT, - max_boost: Union[float, "DefaultType"] = DEFAULT, - min_score: Union[float, "DefaultType"] = DEFAULT, - query: Union[Query, "DefaultType"] = DEFAULT, - score_mode: Union[ - Literal["multiply", "sum", "avg", "first", "max", "min"], "DefaultType" - ] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - if functions is DEFAULT: - functions = [] - for name in ScoreFunction._classes: - if name in kwargs: - functions.append({name: kwargs.pop(name)}) # type: ignore - super().__init__( - boost_mode=boost_mode, - functions=functions, - max_boost=max_boost, - min_score=min_score, - query=query, - score_mode=score_mode, - boost=boost, - _name=_name, - **kwargs, - ) - - -class Fuzzy(Query): - """ - Returns documents that contain terms similar to the search term, as - measured by a Levenshtein edit distance. - - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - """ - - name = "fuzzy" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union["types.FuzzyQuery", Dict[str, Any], "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__(**kwargs) - - -class GeoBoundingBox(Query): - """ - Matches geo_point and geo_shape values that intersect a bounding box. - - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - :arg type: - :arg validation_method: Set to `IGNORE_MALFORMED` to accept geo points - with invalid latitude or longitude. Set to `COERCE` to also try to - infer correct latitude or longitude. Defaults to `'strict'` if - omitted. - :arg ignore_unmapped: Set to `true` to ignore an unmapped field and - not match any documents for this query. Set to `false` to throw an - exception if the field is not mapped. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "geo_bounding_box" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union[ - "types.CoordsGeoBounds", - "types.TopLeftBottomRightGeoBounds", - "types.TopRightBottomLeftGeoBounds", - "types.WktGeoBounds", - Dict[str, Any], - "DefaultType", - ] = DEFAULT, - *, - type: Union[Literal["memory", "indexed"], "DefaultType"] = DEFAULT, - validation_method: Union[ - Literal["coerce", "ignore_malformed", "strict"], "DefaultType" - ] = DEFAULT, - ignore_unmapped: Union[bool, "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__( - type=type, - validation_method=validation_method, - ignore_unmapped=ignore_unmapped, - boost=boost, - _name=_name, - **kwargs, - ) - - -class GeoDistance(Query): - """ - Matches `geo_point` and `geo_shape` values within a given distance of - a geopoint. - - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - :arg distance: (required) The radius of the circle centred on the - specified location. Points which fall into this circle are - considered to be matches. - :arg distance_type: How to compute the distance. Set to `plane` for a - faster calculation that's inaccurate on long distances and close - to the poles. Defaults to `'arc'` if omitted. - :arg validation_method: Set to `IGNORE_MALFORMED` to accept geo points - with invalid latitude or longitude. Set to `COERCE` to also try to - infer correct latitude or longitude. Defaults to `'strict'` if - omitted. - :arg ignore_unmapped: Set to `true` to ignore an unmapped field and - not match any documents for this query. Set to `false` to throw an - exception if the field is not mapped. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "geo_distance" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union[ - "types.LatLonGeoLocation", - "types.GeoHashLocation", - Sequence[float], - str, - Dict[str, Any], - "DefaultType", - ] = DEFAULT, - *, - distance: Union[str, "DefaultType"] = DEFAULT, - distance_type: Union[Literal["arc", "plane"], "DefaultType"] = DEFAULT, - validation_method: Union[ - Literal["coerce", "ignore_malformed", "strict"], "DefaultType" - ] = DEFAULT, - ignore_unmapped: Union[bool, "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__( - distance=distance, - distance_type=distance_type, - validation_method=validation_method, - ignore_unmapped=ignore_unmapped, - boost=boost, - _name=_name, - **kwargs, - ) - - -class GeoPolygon(Query): - """ - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - :arg validation_method: Defaults to `'strict'` if omitted. - :arg ignore_unmapped: - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "geo_polygon" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union[ - "types.GeoPolygonPoints", Dict[str, Any], "DefaultType" - ] = DEFAULT, - *, - validation_method: Union[ - Literal["coerce", "ignore_malformed", "strict"], "DefaultType" - ] = DEFAULT, - ignore_unmapped: Union[bool, "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__( - validation_method=validation_method, - ignore_unmapped=ignore_unmapped, - boost=boost, - _name=_name, - **kwargs, - ) - - -class GeoShape(Query): - """ - Filter documents indexed using either the `geo_shape` or the - `geo_point` type. - - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - :arg ignore_unmapped: Set to `true` to ignore an unmapped field and - not match any documents for this query. Set to `false` to throw an - exception if the field is not mapped. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "geo_shape" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union[ - "types.GeoShapeFieldQuery", Dict[str, Any], "DefaultType" - ] = DEFAULT, - *, - ignore_unmapped: Union[bool, "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__( - ignore_unmapped=ignore_unmapped, boost=boost, _name=_name, **kwargs - ) - - -class HasChild(Query): - """ - Returns parent documents whose joined child documents match a provided - query. - - :arg query: (required) Query you wish to run on child documents of the - `type` field. If a child document matches the search, the query - returns the parent document. - :arg type: (required) Name of the child relationship mapped for the - `join` field. - :arg ignore_unmapped: Indicates whether to ignore an unmapped `type` - and not return any documents instead of an error. - :arg inner_hits: If defined, each search hit will contain inner hits. - :arg max_children: Maximum number of child documents that match the - query allowed for a returned parent document. If the parent - document exceeds this limit, it is excluded from the search - results. - :arg min_children: Minimum number of child documents that match the - query required to match the query for a returned parent document. - If the parent document does not meet this limit, it is excluded - from the search results. - :arg score_mode: Indicates how scores for matching child documents - affect the root parent document’s relevance score. Defaults to - `'none'` if omitted. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "has_child" - _param_defs = { - "query": {"type": "query"}, - } - - def __init__( - self, - *, - query: Union[Query, "DefaultType"] = DEFAULT, - type: Union[str, "DefaultType"] = DEFAULT, - ignore_unmapped: Union[bool, "DefaultType"] = DEFAULT, - inner_hits: Union["types.InnerHits", Dict[str, Any], "DefaultType"] = DEFAULT, - max_children: Union[int, "DefaultType"] = DEFAULT, - min_children: Union[int, "DefaultType"] = DEFAULT, - score_mode: Union[ - Literal["none", "avg", "sum", "max", "min"], "DefaultType" - ] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - query=query, - type=type, - ignore_unmapped=ignore_unmapped, - inner_hits=inner_hits, - max_children=max_children, - min_children=min_children, - score_mode=score_mode, - boost=boost, - _name=_name, - **kwargs, - ) - - -class HasParent(Query): - """ - Returns child documents whose joined parent document matches a - provided query. - - :arg parent_type: (required) Name of the parent relationship mapped - for the `join` field. - :arg query: (required) Query you wish to run on parent documents of - the `parent_type` field. If a parent document matches the search, - the query returns its child documents. - :arg ignore_unmapped: Indicates whether to ignore an unmapped - `parent_type` and not return any documents instead of an error. - You can use this parameter to query multiple indices that may not - contain the `parent_type`. - :arg inner_hits: If defined, each search hit will contain inner hits. - :arg score: Indicates whether the relevance score of a matching parent - document is aggregated into its child documents. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "has_parent" - _param_defs = { - "query": {"type": "query"}, - } - - def __init__( - self, - *, - parent_type: Union[str, "DefaultType"] = DEFAULT, - query: Union[Query, "DefaultType"] = DEFAULT, - ignore_unmapped: Union[bool, "DefaultType"] = DEFAULT, - inner_hits: Union["types.InnerHits", Dict[str, Any], "DefaultType"] = DEFAULT, - score: Union[bool, "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - parent_type=parent_type, - query=query, - ignore_unmapped=ignore_unmapped, - inner_hits=inner_hits, - score=score, - boost=boost, - _name=_name, - **kwargs, - ) - - -class Ids(Query): - """ - Returns documents based on their IDs. This query uses document IDs - stored in the `_id` field. - - :arg values: An array of document IDs. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "ids" - - def __init__( - self, - *, - values: Union[str, Sequence[str], "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(values=values, boost=boost, _name=_name, **kwargs) - - -class Intervals(Query): - """ - Returns documents based on the order and proximity of matching terms. - - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - """ - - name = "intervals" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union["types.IntervalsQuery", Dict[str, Any], "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__(**kwargs) - - -class Knn(Query): - """ - Finds the k nearest vectors to a query vector, as measured by a - similarity metric. knn query finds nearest vectors through approximate - search on indexed dense_vectors. - - :arg field: (required) The name of the vector field to search against - :arg query_vector: The query vector - :arg query_vector_builder: The query vector builder. You must provide - a query_vector_builder or query_vector, but not both. - :arg num_candidates: The number of nearest neighbor candidates to - consider per shard - :arg k: The final number of nearest neighbors to return as top hits - :arg filter: Filters for the kNN search query - :arg similarity: The minimum similarity for a vector to be considered - a match - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "knn" - _param_defs = { - "filter": {"type": "query", "multi": True}, - } - - def __init__( - self, - *, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - query_vector: Union[Sequence[float], "DefaultType"] = DEFAULT, - query_vector_builder: Union[ - "types.QueryVectorBuilder", Dict[str, Any], "DefaultType" - ] = DEFAULT, - num_candidates: Union[int, "DefaultType"] = DEFAULT, - k: Union[int, "DefaultType"] = DEFAULT, - filter: Union[Query, Sequence[Query], "DefaultType"] = DEFAULT, - similarity: Union[float, "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - field=field, - query_vector=query_vector, - query_vector_builder=query_vector_builder, - num_candidates=num_candidates, - k=k, - filter=filter, - similarity=similarity, - boost=boost, - _name=_name, - **kwargs, - ) - - -class Match(Query): - """ - Returns documents that match a provided text, number, date or boolean - value. The provided text is analyzed before matching. - - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - """ - - name = "match" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union["types.MatchQuery", Dict[str, Any], "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__(**kwargs) - - -class MatchAll(Query): - """ - Matches all documents, giving them all a `_score` of 1.0. - - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "match_all" - - def __init__( - self, - *, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(boost=boost, _name=_name, **kwargs) - - def __add__(self, other: "Query") -> "Query": - return other._clone() - - __and__ = __rand__ = __radd__ = __add__ - - def __or__(self, other: "Query") -> "MatchAll": - return self - - __ror__ = __or__ - - def __invert__(self) -> "MatchNone": - return MatchNone() - - -EMPTY_QUERY = MatchAll() - - -class MatchBoolPrefix(Query): - """ - Analyzes its input and constructs a `bool` query from the terms. Each - term except the last is used in a `term` query. The last term is used - in a prefix query. - - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - """ - - name = "match_bool_prefix" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union[ - "types.MatchBoolPrefixQuery", Dict[str, Any], "DefaultType" - ] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__(**kwargs) - - -class MatchNone(Query): - """ - Matches no documents. - - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "match_none" - - def __init__( - self, - *, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(boost=boost, _name=_name, **kwargs) - - def __add__(self, other: "Query") -> "MatchNone": - return self - - __and__ = __rand__ = __radd__ = __add__ - - def __or__(self, other: "Query") -> "Query": - return other._clone() - - __ror__ = __or__ - - def __invert__(self) -> MatchAll: - return MatchAll() - - -class MatchPhrase(Query): - """ - Analyzes the text and creates a phrase query out of the analyzed text. - - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - """ - - name = "match_phrase" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union[ - "types.MatchPhraseQuery", Dict[str, Any], "DefaultType" - ] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__(**kwargs) - - -class MatchPhrasePrefix(Query): - """ - Returns documents that contain the words of a provided text, in the - same order as provided. The last term of the provided text is treated - as a prefix, matching any words that begin with that term. - - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - """ - - name = "match_phrase_prefix" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union[ - "types.MatchPhrasePrefixQuery", Dict[str, Any], "DefaultType" - ] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__(**kwargs) - - -class MoreLikeThis(Query): - """ - Returns documents that are "like" a given set of documents. - - :arg like: (required) Specifies free form text and/or a single or - multiple documents for which you want to find similar documents. - :arg analyzer: The analyzer that is used to analyze the free form - text. Defaults to the analyzer associated with the first field in - fields. - :arg boost_terms: Each term in the formed query could be further - boosted by their tf-idf score. This sets the boost factor to use - when using this feature. Defaults to deactivated (0). - :arg fail_on_unsupported_field: Controls whether the query should fail - (throw an exception) if any of the specified fields are not of the - supported types (`text` or `keyword`). Defaults to `True` if - omitted. - :arg fields: A list of fields to fetch and analyze the text from. - Defaults to the `index.query.default_field` index setting, which - has a default value of `*`. - :arg include: Specifies whether the input documents should also be - included in the search results returned. - :arg max_doc_freq: The maximum document frequency above which the - terms are ignored from the input document. - :arg max_query_terms: The maximum number of query terms that can be - selected. Defaults to `25` if omitted. - :arg max_word_length: The maximum word length above which the terms - are ignored. Defaults to unbounded (`0`). - :arg min_doc_freq: The minimum document frequency below which the - terms are ignored from the input document. Defaults to `5` if - omitted. - :arg minimum_should_match: After the disjunctive query has been - formed, this parameter controls the number of terms that must - match. - :arg min_term_freq: The minimum term frequency below which the terms - are ignored from the input document. Defaults to `2` if omitted. - :arg min_word_length: The minimum word length below which the terms - are ignored. - :arg routing: - :arg stop_words: An array of stop words. Any word in this set is - ignored. - :arg unlike: Used in combination with `like` to exclude documents that - match a set of terms. - :arg version: - :arg version_type: Defaults to `'internal'` if omitted. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "more_like_this" - - def __init__( - self, - *, - like: Union[ - Union[str, "types.LikeDocument"], - Sequence[Union[str, "types.LikeDocument"]], - Dict[str, Any], - "DefaultType", - ] = DEFAULT, - analyzer: Union[str, "DefaultType"] = DEFAULT, - boost_terms: Union[float, "DefaultType"] = DEFAULT, - fail_on_unsupported_field: Union[bool, "DefaultType"] = DEFAULT, - fields: Union[ - Sequence[Union[str, "InstrumentedField"]], "DefaultType" - ] = DEFAULT, - include: Union[bool, "DefaultType"] = DEFAULT, - max_doc_freq: Union[int, "DefaultType"] = DEFAULT, - max_query_terms: Union[int, "DefaultType"] = DEFAULT, - max_word_length: Union[int, "DefaultType"] = DEFAULT, - min_doc_freq: Union[int, "DefaultType"] = DEFAULT, - minimum_should_match: Union[int, str, "DefaultType"] = DEFAULT, - 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, - unlike: Union[ - Union[str, "types.LikeDocument"], - Sequence[Union[str, "types.LikeDocument"]], - Dict[str, Any], - "DefaultType", - ] = DEFAULT, - version: Union[int, "DefaultType"] = DEFAULT, - version_type: Union[ - Literal["internal", "external", "external_gte", "force"], "DefaultType" - ] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - like=like, - analyzer=analyzer, - boost_terms=boost_terms, - fail_on_unsupported_field=fail_on_unsupported_field, - fields=fields, - include=include, - max_doc_freq=max_doc_freq, - max_query_terms=max_query_terms, - max_word_length=max_word_length, - min_doc_freq=min_doc_freq, - minimum_should_match=minimum_should_match, - min_term_freq=min_term_freq, - min_word_length=min_word_length, - routing=routing, - stop_words=stop_words, - unlike=unlike, - version=version, - version_type=version_type, - boost=boost, - _name=_name, - **kwargs, - ) - - -class MultiMatch(Query): - """ - Enables you to search for a provided text, number, date or boolean - value across multiple fields. The provided text is analyzed before - matching. - - :arg query: (required) Text, number, boolean value or date you wish to - find in the provided field. - :arg analyzer: Analyzer used to convert the text in the query value - into tokens. - :arg auto_generate_synonyms_phrase_query: If `true`, match phrase - queries are automatically created for multi-term synonyms. - Defaults to `True` if omitted. - :arg cutoff_frequency: - :arg fields: The fields to be queried. Defaults to the - `index.query.default_field` index settings, which in turn defaults - to `*`. - :arg fuzziness: Maximum edit distance allowed for matching. - :arg fuzzy_rewrite: Method used to rewrite the query. - :arg fuzzy_transpositions: If `true`, edits for fuzzy matching include - transpositions of two adjacent characters (for example, `ab` to - `ba`). Can be applied to the term subqueries constructed for all - terms but the final term. Defaults to `True` if omitted. - :arg lenient: If `true`, format-based errors, such as providing a text - query value for a numeric field, are ignored. - :arg max_expansions: Maximum number of terms to which the query will - expand. Defaults to `50` if omitted. - :arg minimum_should_match: Minimum number of clauses that must match - for a document to be returned. - :arg operator: Boolean logic used to interpret text in the query - value. Defaults to `'or'` if omitted. - :arg prefix_length: Number of beginning characters left unchanged for - fuzzy matching. - :arg slop: Maximum number of positions allowed between matching - tokens. - :arg tie_breaker: Determines how scores for each per-term blended - query and scores across groups are combined. - :arg type: How `the` multi_match query is executed internally. - Defaults to `'best_fields'` if omitted. - :arg zero_terms_query: Indicates whether no documents are returned if - the `analyzer` removes all tokens, such as when using a `stop` - filter. Defaults to `'none'` if omitted. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "multi_match" - - def __init__( - self, - *, - query: Union[str, "DefaultType"] = DEFAULT, - analyzer: Union[str, "DefaultType"] = DEFAULT, - auto_generate_synonyms_phrase_query: Union[bool, "DefaultType"] = DEFAULT, - cutoff_frequency: Union[float, "DefaultType"] = DEFAULT, - fields: Union[ - Union[str, "InstrumentedField"], - Sequence[Union[str, "InstrumentedField"]], - "DefaultType", - ] = DEFAULT, - fuzziness: Union[str, int, "DefaultType"] = DEFAULT, - fuzzy_rewrite: Union[str, "DefaultType"] = DEFAULT, - fuzzy_transpositions: Union[bool, "DefaultType"] = DEFAULT, - lenient: Union[bool, "DefaultType"] = DEFAULT, - max_expansions: Union[int, "DefaultType"] = DEFAULT, - minimum_should_match: Union[int, str, "DefaultType"] = DEFAULT, - operator: Union[Literal["and", "or"], "DefaultType"] = DEFAULT, - prefix_length: Union[int, "DefaultType"] = DEFAULT, - slop: Union[int, "DefaultType"] = DEFAULT, - tie_breaker: Union[float, "DefaultType"] = DEFAULT, - type: Union[ - Literal[ - "best_fields", - "most_fields", - "cross_fields", - "phrase", - "phrase_prefix", - "bool_prefix", - ], - "DefaultType", - ] = DEFAULT, - zero_terms_query: Union[Literal["all", "none"], "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - query=query, - analyzer=analyzer, - auto_generate_synonyms_phrase_query=auto_generate_synonyms_phrase_query, - cutoff_frequency=cutoff_frequency, - fields=fields, - fuzziness=fuzziness, - fuzzy_rewrite=fuzzy_rewrite, - fuzzy_transpositions=fuzzy_transpositions, - lenient=lenient, - max_expansions=max_expansions, - minimum_should_match=minimum_should_match, - operator=operator, - prefix_length=prefix_length, - slop=slop, - tie_breaker=tie_breaker, - type=type, - zero_terms_query=zero_terms_query, - boost=boost, - _name=_name, - **kwargs, - ) - - -class Nested(Query): - """ - Wraps another query to search nested fields. If an object matches the - search, the nested query returns the root parent document. - - :arg path: (required) Path to the nested object you wish to search. - :arg query: (required) Query you wish to run on nested objects in the - path. - :arg ignore_unmapped: Indicates whether to ignore an unmapped path and - not return any documents instead of an error. - :arg inner_hits: If defined, each search hit will contain inner hits. - :arg score_mode: How scores for matching child objects affect the root - parent document’s relevance score. Defaults to `'avg'` if omitted. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "nested" - _param_defs = { - "query": {"type": "query"}, - } - - def __init__( - self, - *, - path: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - query: Union[Query, "DefaultType"] = DEFAULT, - ignore_unmapped: Union[bool, "DefaultType"] = DEFAULT, - inner_hits: Union["types.InnerHits", Dict[str, Any], "DefaultType"] = DEFAULT, - score_mode: Union[ - Literal["none", "avg", "sum", "max", "min"], "DefaultType" - ] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - path=path, - query=query, - ignore_unmapped=ignore_unmapped, - inner_hits=inner_hits, - score_mode=score_mode, - boost=boost, - _name=_name, - **kwargs, - ) - - -class ParentId(Query): - """ - Returns child documents joined to a specific parent document. - - :arg id: ID of the parent document. - :arg ignore_unmapped: Indicates whether to ignore an unmapped `type` - and not return any documents instead of an error. - :arg type: Name of the child relationship mapped for the `join` field. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "parent_id" - - def __init__( - self, - *, - id: Union[str, "DefaultType"] = DEFAULT, - ignore_unmapped: Union[bool, "DefaultType"] = DEFAULT, - type: Union[str, "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - id=id, - ignore_unmapped=ignore_unmapped, - type=type, - boost=boost, - _name=_name, - **kwargs, - ) - - -class Percolate(Query): - """ - Matches queries stored in an index. - - :arg field: (required) Field that holds the indexed queries. The field - must use the `percolator` mapping type. - :arg document: The source of the document being percolated. - :arg documents: An array of sources of the documents being percolated. - :arg id: The ID of a stored document to percolate. - :arg index: The index of a stored document to percolate. - :arg name: The suffix used for the `_percolator_document_slot` field - when multiple `percolate` queries are specified. - :arg preference: Preference used to fetch document to percolate. - :arg routing: Routing used to fetch document to percolate. - :arg version: The expected version of a stored document to percolate. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "percolate" - - def __init__( - self, - *, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - document: Any = DEFAULT, - documents: Union[Sequence[Any], "DefaultType"] = DEFAULT, - id: Union[str, "DefaultType"] = DEFAULT, - index: Union[str, "DefaultType"] = DEFAULT, - name: Union[str, "DefaultType"] = DEFAULT, - preference: Union[str, "DefaultType"] = DEFAULT, - routing: Union[str, "DefaultType"] = DEFAULT, - version: Union[int, "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - field=field, - document=document, - documents=documents, - id=id, - index=index, - name=name, - preference=preference, - routing=routing, - version=version, - boost=boost, - _name=_name, - **kwargs, - ) - - -class Pinned(Query): - """ - Promotes selected documents to rank higher than those matching a given - query. - - :arg organic: (required) Any choice of query used to rank documents - which will be ranked below the "pinned" documents. - :arg ids: Document IDs listed in the order they are to appear in - results. Required if `docs` is not specified. - :arg docs: Documents listed in the order they are to appear in - results. Required if `ids` is not specified. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "pinned" - _param_defs = { - "organic": {"type": "query"}, - } - - def __init__( - self, - *, - organic: Union[Query, "DefaultType"] = DEFAULT, - ids: Union[Sequence[str], "DefaultType"] = DEFAULT, - docs: Union[ - Sequence["types.PinnedDoc"], Sequence[Dict[str, Any]], "DefaultType" - ] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - organic=organic, ids=ids, docs=docs, boost=boost, _name=_name, **kwargs - ) - - -class Prefix(Query): - """ - Returns documents that contain a specific prefix in a provided field. - - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - """ - - name = "prefix" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union["types.PrefixQuery", Dict[str, Any], "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__(**kwargs) - - -class QueryString(Query): - """ - Returns documents based on a provided query string, using a parser - with a strict syntax. - - :arg query: (required) Query string you wish to parse and use for - search. - :arg allow_leading_wildcard: If `true`, the wildcard characters `*` - and `?` are allowed as the first character of the query string. - Defaults to `True` if omitted. - :arg analyzer: Analyzer used to convert text in the query string into - tokens. - :arg analyze_wildcard: If `true`, the query attempts to analyze - wildcard terms in the query string. - :arg auto_generate_synonyms_phrase_query: If `true`, match phrase - queries are automatically created for multi-term synonyms. - Defaults to `True` if omitted. - :arg default_field: Default field to search if no field is provided in - the query string. Supports wildcards (`*`). Defaults to the - `index.query.default_field` index setting, which has a default - value of `*`. - :arg default_operator: Default boolean logic used to interpret text in - the query string if no operators are specified. Defaults to `'or'` - if omitted. - :arg enable_position_increments: If `true`, enable position increments - in queries constructed from a `query_string` search. Defaults to - `True` if omitted. - :arg escape: - :arg fields: Array of fields to search. Supports wildcards (`*`). - :arg fuzziness: Maximum edit distance allowed for fuzzy matching. - :arg fuzzy_max_expansions: Maximum number of terms to which the query - expands for fuzzy matching. Defaults to `50` if omitted. - :arg fuzzy_prefix_length: Number of beginning characters left - unchanged for fuzzy matching. - :arg fuzzy_rewrite: Method used to rewrite the query. - :arg fuzzy_transpositions: If `true`, edits for fuzzy matching include - transpositions of two adjacent characters (for example, `ab` to - `ba`). Defaults to `True` if omitted. - :arg lenient: If `true`, format-based errors, such as providing a text - value for a numeric field, are ignored. - :arg max_determinized_states: Maximum number of automaton states - required for the query. Defaults to `10000` if omitted. - :arg minimum_should_match: Minimum number of clauses that must match - for a document to be returned. - :arg phrase_slop: Maximum number of positions allowed between matching - tokens for phrases. - :arg quote_analyzer: Analyzer used to convert quoted text in the query - string into tokens. For quoted text, this parameter overrides the - analyzer specified in the `analyzer` parameter. - :arg quote_field_suffix: Suffix appended to quoted text in the query - string. You can use this suffix to use a different analysis method - for exact matches. - :arg rewrite: Method used to rewrite the query. - :arg tie_breaker: How to combine the queries generated from the - individual search terms in the resulting `dis_max` query. - :arg time_zone: Coordinated Universal Time (UTC) offset or IANA time - zone used to convert date values in the query string to UTC. - :arg type: Determines how the query matches and scores documents. - Defaults to `'best_fields'` if omitted. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "query_string" - - def __init__( - self, - *, - query: Union[str, "DefaultType"] = DEFAULT, - allow_leading_wildcard: Union[bool, "DefaultType"] = DEFAULT, - analyzer: Union[str, "DefaultType"] = DEFAULT, - analyze_wildcard: Union[bool, "DefaultType"] = DEFAULT, - auto_generate_synonyms_phrase_query: Union[bool, "DefaultType"] = DEFAULT, - default_field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - default_operator: Union[Literal["and", "or"], "DefaultType"] = DEFAULT, - enable_position_increments: Union[bool, "DefaultType"] = DEFAULT, - escape: Union[bool, "DefaultType"] = DEFAULT, - fields: Union[ - Sequence[Union[str, "InstrumentedField"]], "DefaultType" - ] = DEFAULT, - fuzziness: Union[str, int, "DefaultType"] = DEFAULT, - fuzzy_max_expansions: Union[int, "DefaultType"] = DEFAULT, - fuzzy_prefix_length: Union[int, "DefaultType"] = DEFAULT, - fuzzy_rewrite: Union[str, "DefaultType"] = DEFAULT, - fuzzy_transpositions: Union[bool, "DefaultType"] = DEFAULT, - lenient: Union[bool, "DefaultType"] = DEFAULT, - max_determinized_states: Union[int, "DefaultType"] = DEFAULT, - minimum_should_match: Union[int, str, "DefaultType"] = DEFAULT, - phrase_slop: Union[float, "DefaultType"] = DEFAULT, - quote_analyzer: Union[str, "DefaultType"] = DEFAULT, - quote_field_suffix: Union[str, "DefaultType"] = DEFAULT, - rewrite: Union[str, "DefaultType"] = DEFAULT, - tie_breaker: Union[float, "DefaultType"] = DEFAULT, - time_zone: Union[str, "DefaultType"] = DEFAULT, - type: Union[ - Literal[ - "best_fields", - "most_fields", - "cross_fields", - "phrase", - "phrase_prefix", - "bool_prefix", - ], - "DefaultType", - ] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - query=query, - allow_leading_wildcard=allow_leading_wildcard, - analyzer=analyzer, - analyze_wildcard=analyze_wildcard, - auto_generate_synonyms_phrase_query=auto_generate_synonyms_phrase_query, - default_field=default_field, - default_operator=default_operator, - enable_position_increments=enable_position_increments, - escape=escape, - fields=fields, - fuzziness=fuzziness, - fuzzy_max_expansions=fuzzy_max_expansions, - fuzzy_prefix_length=fuzzy_prefix_length, - fuzzy_rewrite=fuzzy_rewrite, - fuzzy_transpositions=fuzzy_transpositions, - lenient=lenient, - max_determinized_states=max_determinized_states, - minimum_should_match=minimum_should_match, - phrase_slop=phrase_slop, - quote_analyzer=quote_analyzer, - quote_field_suffix=quote_field_suffix, - rewrite=rewrite, - tie_breaker=tie_breaker, - time_zone=time_zone, - type=type, - boost=boost, - _name=_name, - **kwargs, - ) - - -class Range(Query): - """ - Returns documents that contain terms within a provided range. - - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - """ - - name = "range" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union["wrappers.Range[Any]", Dict[str, Any], "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__(**kwargs) - - -class RankFeature(Query): - """ - Boosts the relevance score of documents based on the numeric value of - a `rank_feature` or `rank_features` field. - - :arg field: (required) `rank_feature` or `rank_features` field used to - boost relevance scores. - :arg saturation: Saturation function used to boost relevance scores - based on the value of the rank feature `field`. - :arg log: Logarithmic function used to boost relevance scores based on - the value of the rank feature `field`. - :arg linear: Linear function used to boost relevance scores based on - the value of the rank feature `field`. - :arg sigmoid: Sigmoid function used to boost relevance scores based on - the value of the rank feature `field`. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "rank_feature" - - def __init__( - self, - *, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - saturation: Union[ - "types.RankFeatureFunctionSaturation", Dict[str, Any], "DefaultType" - ] = DEFAULT, - log: Union[ - "types.RankFeatureFunctionLogarithm", Dict[str, Any], "DefaultType" - ] = DEFAULT, - linear: Union[ - "types.RankFeatureFunctionLinear", Dict[str, Any], "DefaultType" - ] = DEFAULT, - sigmoid: Union[ - "types.RankFeatureFunctionSigmoid", Dict[str, Any], "DefaultType" - ] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - field=field, - saturation=saturation, - log=log, - linear=linear, - sigmoid=sigmoid, - boost=boost, - _name=_name, - **kwargs, - ) - - -class Regexp(Query): - """ - Returns documents that contain terms matching a regular expression. - - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - """ - - name = "regexp" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union["types.RegexpQuery", Dict[str, Any], "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__(**kwargs) - - -class Rule(Query): - """ - :arg organic: (required) - :arg ruleset_ids: (required) - :arg match_criteria: (required) - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "rule" - _param_defs = { - "organic": {"type": "query"}, - } - - def __init__( - self, - *, - organic: Union[Query, "DefaultType"] = DEFAULT, - ruleset_ids: Union[Sequence[str], "DefaultType"] = DEFAULT, - match_criteria: Any = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - organic=organic, - ruleset_ids=ruleset_ids, - match_criteria=match_criteria, - boost=boost, - _name=_name, - **kwargs, - ) - - -class Script(Query): - """ - Filters documents based on a provided script. The script query is - typically used in a filter context. - - :arg script: (required) Contains a script to run as a query. This - script must return a boolean value, `true` or `false`. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "script" - - def __init__( - self, - *, - script: Union["types.Script", Dict[str, Any], "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(script=script, boost=boost, _name=_name, **kwargs) - - -class ScriptScore(Query): - """ - Uses a script to provide a custom score for returned documents. - - :arg query: (required) Query used to return documents. - :arg script: (required) Script used to compute the score of documents - returned by the query. Important: final relevance scores from the - `script_score` query cannot be negative. - :arg min_score: Documents with a score lower than this floating point - number are excluded from the search results. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "script_score" - _param_defs = { - "query": {"type": "query"}, - } - - def __init__( - self, - *, - query: Union[Query, "DefaultType"] = DEFAULT, - script: Union["types.Script", Dict[str, Any], "DefaultType"] = DEFAULT, - min_score: Union[float, "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - query=query, - script=script, - min_score=min_score, - boost=boost, - _name=_name, - **kwargs, - ) - - -class Semantic(Query): - """ - A semantic query to semantic_text field types - - :arg field: (required) The field to query, which must be a - semantic_text field type - :arg query: (required) The query text - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "semantic" - - def __init__( - self, - *, - field: Union[str, "DefaultType"] = DEFAULT, - query: Union[str, "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(field=field, query=query, boost=boost, _name=_name, **kwargs) - - -class Shape(Query): - """ - Queries documents that contain fields indexed using the `shape` type. - - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - :arg ignore_unmapped: When set to `true` the query ignores an unmapped - field and will not match any documents. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "shape" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union["types.ShapeFieldQuery", Dict[str, Any], "DefaultType"] = DEFAULT, - *, - ignore_unmapped: Union[bool, "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__( - ignore_unmapped=ignore_unmapped, boost=boost, _name=_name, **kwargs - ) - - -class SimpleQueryString(Query): - """ - Returns documents based on a provided query string, using a parser - with a limited but fault-tolerant syntax. - - :arg query: (required) Query string in the simple query string syntax - you wish to parse and use for search. - :arg analyzer: Analyzer used to convert text in the query string into - tokens. - :arg analyze_wildcard: If `true`, the query attempts to analyze - wildcard terms in the query string. - :arg auto_generate_synonyms_phrase_query: If `true`, the parser - creates a match_phrase query for each multi-position token. - Defaults to `True` if omitted. - :arg default_operator: Default boolean logic used to interpret text in - the query string if no operators are specified. Defaults to `'or'` - if omitted. - :arg fields: Array of fields you wish to search. Accepts wildcard - expressions. You also can boost relevance scores for matches to - particular fields using a caret (`^`) notation. Defaults to the - `index.query.default_field index` setting, which has a default - value of `*`. - :arg flags: List of enabled operators for the simple query string - syntax. Defaults to `ALL` if omitted. - :arg fuzzy_max_expansions: Maximum number of terms to which the query - expands for fuzzy matching. Defaults to `50` if omitted. - :arg fuzzy_prefix_length: Number of beginning characters left - unchanged for fuzzy matching. - :arg fuzzy_transpositions: If `true`, edits for fuzzy matching include - transpositions of two adjacent characters (for example, `ab` to - `ba`). - :arg lenient: If `true`, format-based errors, such as providing a text - value for a numeric field, are ignored. - :arg minimum_should_match: Minimum number of clauses that must match - for a document to be returned. - :arg quote_field_suffix: Suffix appended to quoted text in the query - string. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "simple_query_string" - - def __init__( - self, - *, - query: Union[str, "DefaultType"] = DEFAULT, - analyzer: Union[str, "DefaultType"] = DEFAULT, - analyze_wildcard: Union[bool, "DefaultType"] = DEFAULT, - auto_generate_synonyms_phrase_query: Union[bool, "DefaultType"] = DEFAULT, - default_operator: Union[Literal["and", "or"], "DefaultType"] = DEFAULT, - fields: Union[ - Sequence[Union[str, "InstrumentedField"]], "DefaultType" - ] = DEFAULT, - flags: Union[ - "types.PipeSeparatedFlags", Dict[str, Any], "DefaultType" - ] = DEFAULT, - fuzzy_max_expansions: Union[int, "DefaultType"] = DEFAULT, - fuzzy_prefix_length: Union[int, "DefaultType"] = DEFAULT, - fuzzy_transpositions: Union[bool, "DefaultType"] = DEFAULT, - lenient: Union[bool, "DefaultType"] = DEFAULT, - minimum_should_match: Union[int, str, "DefaultType"] = DEFAULT, - quote_field_suffix: Union[str, "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - query=query, - analyzer=analyzer, - analyze_wildcard=analyze_wildcard, - auto_generate_synonyms_phrase_query=auto_generate_synonyms_phrase_query, - default_operator=default_operator, - fields=fields, - flags=flags, - fuzzy_max_expansions=fuzzy_max_expansions, - fuzzy_prefix_length=fuzzy_prefix_length, - fuzzy_transpositions=fuzzy_transpositions, - lenient=lenient, - minimum_should_match=minimum_should_match, - quote_field_suffix=quote_field_suffix, - boost=boost, - _name=_name, - **kwargs, - ) - - -class SpanContaining(Query): - """ - Returns matches which enclose another span query. - - :arg big: (required) Can be any span query. Matching spans from `big` - that contain matches from `little` are returned. - :arg little: (required) Can be any span query. Matching spans from - `big` that contain matches from `little` are returned. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "span_containing" - - def __init__( - self, - *, - big: Union["types.SpanQuery", Dict[str, Any], "DefaultType"] = DEFAULT, - little: Union["types.SpanQuery", Dict[str, Any], "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(big=big, little=little, boost=boost, _name=_name, **kwargs) - - -class SpanFieldMasking(Query): - """ - Wrapper to allow span queries to participate in composite single-field - span queries by _lying_ about their search field. - - :arg field: (required) - :arg query: (required) - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "span_field_masking" - - def __init__( - self, - *, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - query: Union["types.SpanQuery", Dict[str, Any], "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(field=field, query=query, boost=boost, _name=_name, **kwargs) - - -class SpanFirst(Query): - """ - Matches spans near the beginning of a field. - - :arg end: (required) Controls the maximum end position permitted in a - match. - :arg match: (required) Can be any other span type query. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "span_first" - - def __init__( - self, - *, - end: Union[int, "DefaultType"] = DEFAULT, - match: Union["types.SpanQuery", Dict[str, Any], "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(end=end, match=match, boost=boost, _name=_name, **kwargs) - - -class SpanMulti(Query): - """ - Allows you to wrap a multi term query (one of `wildcard`, `fuzzy`, - `prefix`, `range`, or `regexp` query) as a `span` query, so it can be - nested. - - :arg match: (required) Should be a multi term query (one of - `wildcard`, `fuzzy`, `prefix`, `range`, or `regexp` query). - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "span_multi" - _param_defs = { - "match": {"type": "query"}, - } - - def __init__( - self, - *, - match: Union[Query, "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(match=match, boost=boost, _name=_name, **kwargs) - - -class SpanNear(Query): - """ - Matches spans which are near one another. You can specify `slop`, the - maximum number of intervening unmatched positions, as well as whether - matches are required to be in-order. - - :arg clauses: (required) Array of one or more other span type queries. - :arg in_order: Controls whether matches are required to be in-order. - :arg slop: Controls the maximum number of intervening unmatched - positions permitted. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "span_near" - - def __init__( - self, - *, - clauses: Union[ - Sequence["types.SpanQuery"], Sequence[Dict[str, Any]], "DefaultType" - ] = DEFAULT, - in_order: Union[bool, "DefaultType"] = DEFAULT, - slop: Union[int, "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - clauses=clauses, - in_order=in_order, - slop=slop, - boost=boost, - _name=_name, - **kwargs, - ) - - -class SpanNot(Query): - """ - Removes matches which overlap with another span query or which are - within x tokens before (controlled by the parameter `pre`) or y tokens - after (controlled by the parameter `post`) another span query. - - :arg exclude: (required) Span query whose matches must not overlap - those returned. - :arg include: (required) Span query whose matches are filtered. - :arg dist: The number of tokens from within the include span that - can’t have overlap with the exclude span. Equivalent to setting - both `pre` and `post`. - :arg post: The number of tokens after the include span that can’t have - overlap with the exclude span. - :arg pre: The number of tokens before the include span that can’t have - overlap with the exclude span. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "span_not" - - def __init__( - self, - *, - exclude: Union["types.SpanQuery", Dict[str, Any], "DefaultType"] = DEFAULT, - include: Union["types.SpanQuery", Dict[str, Any], "DefaultType"] = DEFAULT, - dist: Union[int, "DefaultType"] = DEFAULT, - post: Union[int, "DefaultType"] = DEFAULT, - pre: Union[int, "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - exclude=exclude, - include=include, - dist=dist, - post=post, - pre=pre, - boost=boost, - _name=_name, - **kwargs, - ) - - -class SpanOr(Query): - """ - Matches the union of its span clauses. - - :arg clauses: (required) Array of one or more other span type queries. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "span_or" - - def __init__( - self, - *, - clauses: Union[ - Sequence["types.SpanQuery"], Sequence[Dict[str, Any]], "DefaultType" - ] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(clauses=clauses, boost=boost, _name=_name, **kwargs) - - -class SpanTerm(Query): - """ - Matches spans containing a term. - - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - """ - - name = "span_term" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union["types.SpanTermQuery", Dict[str, Any], "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__(**kwargs) - - -class SpanWithin(Query): - """ - Returns matches which are enclosed inside another span query. - - :arg big: (required) Can be any span query. Matching spans from - `little` that are enclosed within `big` are returned. - :arg little: (required) Can be any span query. Matching spans from - `little` that are enclosed within `big` are returned. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "span_within" - - def __init__( - self, - *, - big: Union["types.SpanQuery", Dict[str, Any], "DefaultType"] = DEFAULT, - little: Union["types.SpanQuery", Dict[str, Any], "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(big=big, little=little, boost=boost, _name=_name, **kwargs) - - -class SparseVector(Query): - """ - Using input query vectors or a natural language processing model to - convert a query into a list of token-weight pairs, queries against a - sparse vector field. - - :arg field: (required) The name of the field that contains the token- - weight pairs to be searched against. This field must be a mapped - sparse_vector field. - :arg query_vector: Dictionary of precomputed sparse vectors and their - associated weights. Only one of inference_id or query_vector may - be supplied in a request. - :arg inference_id: The inference ID to use to convert the query text - into token-weight pairs. It must be the same inference ID that was - used to create the tokens from the input text. Only one of - inference_id and query_vector is allowed. If inference_id is - specified, query must also be specified. Only one of inference_id - or query_vector may be supplied in a request. - :arg query: The query text you want to use for search. If inference_id - is specified, query must also be specified. - :arg prune: Whether to perform pruning, omitting the non-significant - tokens from the query to improve query performance. If prune is - true but the pruning_config is not specified, pruning will occur - but default values will be used. Default: false - :arg pruning_config: Optional pruning configuration. If enabled, this - will omit non-significant tokens from the query in order to - improve query performance. This is only used if prune is set to - true. If prune is set to true but pruning_config is not specified, - default values will be used. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "sparse_vector" - - def __init__( - self, - *, - field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - query_vector: Union[Mapping[str, float], "DefaultType"] = DEFAULT, - inference_id: Union[str, "DefaultType"] = DEFAULT, - query: Union[str, "DefaultType"] = DEFAULT, - prune: Union[bool, "DefaultType"] = DEFAULT, - pruning_config: Union[ - "types.TokenPruningConfig", Dict[str, Any], "DefaultType" - ] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__( - field=field, - query_vector=query_vector, - inference_id=inference_id, - query=query, - prune=prune, - pruning_config=pruning_config, - boost=boost, - _name=_name, - **kwargs, - ) - - -class Term(Query): - """ - Returns documents that contain an exact term in a provided field. To - return a document, the query term must exactly match the queried - field's value, including whitespace and capitalization. - - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - """ - - name = "term" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union["types.TermQuery", Dict[str, Any], "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__(**kwargs) - - -class Terms(Query): - """ - Returns documents that contain one or more exact terms in a provided - field. To return a document, one or more terms must exactly match a - field value, including whitespace and capitalization. - - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "terms" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union[ - Sequence[Union[int, float, str, bool, None, Any]], - "types.TermsLookup", - Dict[str, Any], - "DefaultType", - ] = DEFAULT, - *, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__(boost=boost, _name=_name, **kwargs) - - def _setattr(self, name: str, value: Any) -> None: - # here we convert any iterables that are not strings to lists - if hasattr(value, "__iter__") and not isinstance(value, (str, list, dict)): - value = list(value) - super()._setattr(name, value) - - -class TermsSet(Query): - """ - Returns documents that contain a minimum number of exact terms in a - provided field. To return a document, a required number of terms must - exactly match the field values, including whitespace and - capitalization. - - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - """ - - name = "terms_set" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union["types.TermsSetQuery", Dict[str, Any], "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__(**kwargs) - - -class TextExpansion(Query): - """ - Uses a natural language processing model to convert the query text - into a list of token-weight pairs which are then used in a query - against a sparse vector or rank features field. - - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - """ - - name = "text_expansion" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union[ - "types.TextExpansionQuery", Dict[str, Any], "DefaultType" - ] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__(**kwargs) - - -class WeightedTokens(Query): - """ - Supports returning text_expansion query results by sending in - precomputed tokens with the query. - - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - """ - - name = "weighted_tokens" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union[ - "types.WeightedTokensQuery", Dict[str, Any], "DefaultType" - ] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__(**kwargs) - - -class Wildcard(Query): - """ - Returns documents that contain terms matching a wildcard pattern. - - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - """ - - name = "wildcard" - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union["types.WildcardQuery", Dict[str, Any], "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - super().__init__(**kwargs) - - -class Wrapper(Query): - """ - A query that accepts any other query as base64 encoded string. - - :arg query: (required) A base64 encoded query. The binary data format - can be any of JSON, YAML, CBOR or SMILE encodings - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "wrapper" - - def __init__( - self, - *, - query: Union[str, "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(query=query, boost=boost, _name=_name, **kwargs) - - -class Type(Query): - """ - :arg value: (required) - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - name = "type" - - def __init__( - self, - *, - value: Union[str, "DefaultType"] = DEFAULT, - boost: Union[float, "DefaultType"] = DEFAULT, - _name: Union[str, "DefaultType"] = DEFAULT, - **kwargs: Any, - ): - super().__init__(value=value, boost=boost, _name=_name, **kwargs) diff --git a/elasticsearch_dsl/response/__init__.py b/elasticsearch_dsl/response/__init__.py deleted file mode 100644 index eea1b87f..00000000 --- a/elasticsearch_dsl/response/__init__.py +++ /dev/null @@ -1,354 +0,0 @@ -# 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, - Any, - Dict, - Generic, - Iterator, - List, - Mapping, - Optional, - Sequence, - Tuple, - Union, - cast, -) - -from ..utils import _R, AttrDict, AttrList, _wrap -from .hit import Hit, HitMeta - -if TYPE_CHECKING: - from .. import types - from ..aggs import Agg - from ..faceted_search_base import FacetedSearchBase - from ..search_base import Request, SearchBase - from ..update_by_query_base import UpdateByQueryBase - -__all__ = [ - "Response", - "AggResponse", - "UpdateByQueryResponse", - "Hit", - "HitMeta", - "AggregateResponseType", -] - - -class Response(AttrDict[Any], Generic[_R]): - """An Elasticsearch search response. - - :arg took: (required) - :arg timed_out: (required) - :arg _shards: (required) - :arg hits: search results - :arg aggregations: aggregation results - :arg _clusters: - :arg fields: - :arg max_score: - :arg num_reduce_phases: - :arg profile: - :arg pit_id: - :arg _scroll_id: - :arg suggest: - :arg terminated_early: - """ - - _search: "SearchBase[_R]" - _faceted_search: "FacetedSearchBase[_R]" - _doc_class: Optional[_R] - _hits: List[_R] - - took: int - timed_out: bool - _shards: "types.ShardStatistics" - _clusters: "types.ClusterStatistics" - fields: Mapping[str, Any] - max_score: float - num_reduce_phases: int - profile: "types.Profile" - pit_id: str - _scroll_id: str - suggest: Mapping[ - str, - Sequence[ - Union["types.CompletionSuggest", "types.PhraseSuggest", "types.TermSuggest"] - ], - ] - terminated_early: bool - - def __init__( - self, - search: "Request[_R]", - response: Dict[str, Any], - doc_class: Optional[_R] = None, - ): - super(AttrDict, self).__setattr__("_search", search) - super(AttrDict, self).__setattr__("_doc_class", doc_class) - super().__init__(response) - - def __iter__(self) -> Iterator[_R]: # type: ignore[override] - return iter(self.hits) - - def __getitem__(self, key: Union[slice, int, str]) -> Any: - if isinstance(key, (slice, int)): - # for slicing etc - return self.hits[key] - return super().__getitem__(key) - - def __nonzero__(self) -> bool: - return bool(self.hits) - - __bool__ = __nonzero__ - - def __repr__(self) -> str: - return "" % (self.hits or self.aggregations) - - def __len__(self) -> int: - return len(self.hits) - - def __getstate__(self) -> Tuple[Dict[str, Any], "Request[_R]", Optional[_R]]: # type: ignore[override] - return self._d_, self._search, self._doc_class - - def __setstate__( - self, state: Tuple[Dict[str, Any], "Request[_R]", Optional[_R]] # type: ignore[override] - ) -> None: - super(AttrDict, self).__setattr__("_d_", state[0]) - super(AttrDict, self).__setattr__("_search", state[1]) - super(AttrDict, self).__setattr__("_doc_class", state[2]) - - def success(self) -> bool: - return self._shards.total == self._shards.successful and not self.timed_out - - @property - def hits(self) -> List[_R]: - if not hasattr(self, "_hits"): - h = cast(AttrDict[Any], self._d_["hits"]) - - try: - hits = AttrList(list(map(self._search._get_result, h["hits"]))) - except AttributeError as e: - # avoid raising AttributeError since it will be hidden by the property - raise TypeError("Could not parse hits.", e) - - # avoid assigning _hits into self._d_ - super(AttrDict, self).__setattr__("_hits", hits) - for k in h: - setattr(self._hits, k, _wrap(h[k])) - return self._hits - - @property - def aggregations(self) -> "AggResponse[_R]": - return self.aggs - - @property - def aggs(self) -> "AggResponse[_R]": - if not hasattr(self, "_aggs"): - aggs = AggResponse[_R]( - cast("Agg[_R]", self._search.aggs), - self._search, - cast(Dict[str, Any], self._d_.get("aggregations", {})), - ) - - # avoid assigning _aggs into self._d_ - super(AttrDict, self).__setattr__("_aggs", aggs) - return cast("AggResponse[_R]", self._aggs) - - def search_after(self) -> "SearchBase[_R]": - """ - Return a ``Search`` instance that retrieves the next page of results. - - This method provides an easy way to paginate a long list of results using - the ``search_after`` option. For example:: - - page_size = 20 - s = Search()[:page_size].sort("date") - - while True: - # get a page of results - r = await s.execute() - - # do something with this page of results - - # exit the loop if we reached the end - if len(r.hits) < page_size: - break - - # get a search object with the next page of results - s = r.search_after() - - Note that the ``search_after`` option requires the search to have an - explicit ``sort`` order. - """ - if len(self.hits) == 0: - raise ValueError("Cannot use search_after when there are no search results") - if not hasattr(self.hits[-1].meta, "sort"): # type: ignore - raise ValueError("Cannot use search_after when results are not sorted") - return self._search.extra(search_after=self.hits[-1].meta.sort) # type: ignore - - -AggregateResponseType = Union[ - "types.CardinalityAggregate", - "types.HdrPercentilesAggregate", - "types.HdrPercentileRanksAggregate", - "types.TDigestPercentilesAggregate", - "types.TDigestPercentileRanksAggregate", - "types.PercentilesBucketAggregate", - "types.MedianAbsoluteDeviationAggregate", - "types.MinAggregate", - "types.MaxAggregate", - "types.SumAggregate", - "types.AvgAggregate", - "types.WeightedAvgAggregate", - "types.ValueCountAggregate", - "types.SimpleValueAggregate", - "types.DerivativeAggregate", - "types.BucketMetricValueAggregate", - "types.StatsAggregate", - "types.StatsBucketAggregate", - "types.ExtendedStatsAggregate", - "types.ExtendedStatsBucketAggregate", - "types.GeoBoundsAggregate", - "types.GeoCentroidAggregate", - "types.HistogramAggregate", - "types.DateHistogramAggregate", - "types.AutoDateHistogramAggregate", - "types.VariableWidthHistogramAggregate", - "types.StringTermsAggregate", - "types.LongTermsAggregate", - "types.DoubleTermsAggregate", - "types.UnmappedTermsAggregate", - "types.LongRareTermsAggregate", - "types.StringRareTermsAggregate", - "types.UnmappedRareTermsAggregate", - "types.MultiTermsAggregate", - "types.MissingAggregate", - "types.NestedAggregate", - "types.ReverseNestedAggregate", - "types.GlobalAggregate", - "types.FilterAggregate", - "types.ChildrenAggregate", - "types.ParentAggregate", - "types.SamplerAggregate", - "types.UnmappedSamplerAggregate", - "types.GeoHashGridAggregate", - "types.GeoTileGridAggregate", - "types.GeoHexGridAggregate", - "types.RangeAggregate", - "types.DateRangeAggregate", - "types.GeoDistanceAggregate", - "types.IpRangeAggregate", - "types.IpPrefixAggregate", - "types.FiltersAggregate", - "types.AdjacencyMatrixAggregate", - "types.SignificantLongTermsAggregate", - "types.SignificantStringTermsAggregate", - "types.UnmappedSignificantTermsAggregate", - "types.CompositeAggregate", - "types.FrequentItemSetsAggregate", - "types.TimeSeriesAggregate", - "types.ScriptedMetricAggregate", - "types.TopHitsAggregate", - "types.InferenceAggregate", - "types.StringStatsAggregate", - "types.BoxPlotAggregate", - "types.TopMetricsAggregate", - "types.TTestAggregate", - "types.RateAggregate", - "types.CumulativeCardinalityAggregate", - "types.MatrixStatsAggregate", - "types.GeoLineAggregate", -] - - -class AggResponse(AttrDict[Any], Generic[_R]): - """An Elasticsearch aggregation response.""" - - _meta: Dict[str, Any] - - def __init__(self, aggs: "Agg[_R]", search: "Request[_R]", data: Dict[str, Any]): - super(AttrDict, self).__setattr__("_meta", {"search": search, "aggs": aggs}) - super().__init__(data) - - def __getitem__(self, attr_name: str) -> AggregateResponseType: - if attr_name in self._meta["aggs"]: - # don't do self._meta['aggs'][attr_name] to avoid copying - agg = self._meta["aggs"].aggs[attr_name] - return cast( - AggregateResponseType, - agg.result(self._meta["search"], self._d_[attr_name]), - ) - return super().__getitem__(attr_name) # type: ignore - - def __iter__(self) -> Iterator[AggregateResponseType]: # type: ignore[override] - for name in self._meta["aggs"]: - yield self[name] - - -class UpdateByQueryResponse(AttrDict[Any], Generic[_R]): - """An Elasticsearch update by query response. - - :arg batches: - :arg failures: - :arg noops: - :arg deleted: - :arg requests_per_second: - :arg retries: - :arg task: - :arg timed_out: - :arg took: - :arg total: - :arg updated: - :arg version_conflicts: - :arg throttled: - :arg throttled_millis: - :arg throttled_until: - :arg throttled_until_millis: - """ - - _search: "UpdateByQueryBase[_R]" - - batches: int - failures: Sequence["types.BulkIndexByScrollFailure"] - noops: int - deleted: int - requests_per_second: float - retries: "types.Retries" - task: Union[str, int] - timed_out: bool - took: Any - total: int - updated: int - version_conflicts: int - throttled: Any - throttled_millis: Any - throttled_until: Any - throttled_until_millis: Any - - def __init__( - self, - search: "Request[_R]", - response: Dict[str, Any], - doc_class: Optional[_R] = None, - ): - super(AttrDict, self).__setattr__("_search", search) - super(AttrDict, self).__setattr__("_doc_class", doc_class) - super().__init__(response) - - def success(self) -> bool: - return not self.timed_out and not self.failures diff --git a/elasticsearch_dsl/response/aggs.py b/elasticsearch_dsl/response/aggs.py deleted file mode 100644 index 3525e1f9..00000000 --- a/elasticsearch_dsl/response/aggs.py +++ /dev/null @@ -1,100 +0,0 @@ -# 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, Any, Dict, Iterator, List, Optional, Union, cast - -from ..utils import _R, AttrDict, AttrList -from . import AggResponse, Response - -if TYPE_CHECKING: - from ..aggs import Agg - from ..field import Field - from ..search_base import SearchBase - - -class Bucket(AggResponse[_R]): - def __init__( - self, - aggs: "Agg[_R]", - search: "SearchBase[_R]", - data: Dict[str, Any], - field: Optional["Field"] = None, - ): - super().__init__(aggs, search, data) - - -class FieldBucket(Bucket[_R]): - def __init__( - self, - aggs: "Agg[_R]", - search: "SearchBase[_R]", - data: Dict[str, Any], - field: Optional["Field"] = None, - ): - if field: - data["key"] = field.deserialize(data["key"]) - super().__init__(aggs, search, data, field) - - -class BucketData(AggResponse[_R]): - _bucket_class = Bucket - _buckets: Union[AttrDict[Any], AttrList[Any]] - - def _wrap_bucket(self, data: Dict[str, Any]) -> Bucket[_R]: - return self._bucket_class( - self._meta["aggs"], - self._meta["search"], - data, - field=self._meta.get("field"), - ) - - def __iter__(self) -> Iterator["Agg"]: # type: ignore[override] - return iter(self.buckets) # type: ignore - - def __len__(self) -> int: - return len(self.buckets) - - def __getitem__(self, key: Any) -> Any: - if isinstance(key, (int, slice)): - return cast(AttrList[Any], self.buckets)[key] - return super().__getitem__(key) - - @property - def buckets(self) -> Union[AttrDict[Any], AttrList[Any]]: - if not hasattr(self, "_buckets"): - field = getattr(self._meta["aggs"], "field", None) - if field: - self._meta["field"] = self._meta["search"]._resolve_field(field) - bs = cast(Union[Dict[str, Any], List[Any]], self._d_["buckets"]) - if isinstance(bs, list): - ret = AttrList(bs, obj_wrapper=self._wrap_bucket) - else: - ret = AttrDict[Any]({k: self._wrap_bucket(bs[k]) for k in bs}) # type: ignore - super(AttrDict, self).__setattr__("_buckets", ret) - return self._buckets - - -class FieldBucketData(BucketData[_R]): - _bucket_class = FieldBucket - - -class TopHitsData(Response[_R]): - def __init__(self, agg: "Agg[_R]", search: "SearchBase[_R]", data: Any): - super(AttrDict, self).__setattr__( - "meta", AttrDict({"agg": agg, "search": search}) - ) - super().__init__(search, data) diff --git a/elasticsearch_dsl/response/hit.py b/elasticsearch_dsl/response/hit.py deleted file mode 100644 index a09d36e9..00000000 --- a/elasticsearch_dsl/response/hit.py +++ /dev/null @@ -1,53 +0,0 @@ -# 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, Dict, List, Tuple, cast - -from ..utils import AttrDict, HitMeta - - -class Hit(AttrDict[Any]): - def __init__(self, document: Dict[str, Any]): - data: Dict[str, Any] = {} - if "_source" in document: - data = cast(Dict[str, Any], document["_source"]) - if "fields" in document: - data.update(cast(Dict[str, Any], document["fields"])) - - super().__init__(data) - # assign meta as attribute and not as key in self._d_ - super(AttrDict, self).__setattr__("meta", HitMeta(document)) - - def __getstate__(self) -> Tuple[Dict[str, Any], HitMeta]: # type: ignore[override] - # add self.meta since it is not in self.__dict__ - return super().__getstate__() + (self.meta,) - - def __setstate__(self, state: Tuple[Dict[str, Any], HitMeta]) -> None: # type: ignore[override] - super(AttrDict, self).__setattr__("meta", state[-1]) - super().__setstate__(state[:-1]) - - def __dir__(self) -> List[str]: - # be sure to expose meta in dir(self) - return super().__dir__() + ["meta"] - - def __repr__(self) -> str: - return "".format( - "/".join( - getattr(self.meta, key) for key in ("index", "id") if key in self.meta - ), - super().__repr__(), - ) diff --git a/elasticsearch_dsl/search.py b/elasticsearch_dsl/search.py deleted file mode 100644 index 04307294..00000000 --- a/elasticsearch_dsl/search.py +++ /dev/null @@ -1,28 +0,0 @@ -# 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 elasticsearch_dsl._async.search import ( # noqa: F401 - AsyncEmptySearch, - AsyncMultiSearch, - AsyncSearch, -) -from elasticsearch_dsl._sync.search import ( # noqa: F401 - EmptySearch, - MultiSearch, - Search, -) -from elasticsearch_dsl.search_base import Q # noqa: F401 diff --git a/elasticsearch_dsl/search_base.py b/elasticsearch_dsl/search_base.py deleted file mode 100644 index 739635f8..00000000 --- a/elasticsearch_dsl/search_base.py +++ /dev/null @@ -1,1040 +0,0 @@ -# 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 collections.abc -import copy -from typing import ( - TYPE_CHECKING, - Any, - Callable, - Dict, - Generic, - Iterator, - List, - Optional, - Protocol, - Tuple, - Type, - Union, - cast, - overload, -) - -from typing_extensions import Self, TypeVar - -from .aggs import A, Agg, AggBase -from .document_base import InstrumentedField -from .exceptions import IllegalOperation -from .query import Bool, Q, Query -from .response import Hit, Response -from .utils import _R, AnyUsingType, AttrDict, DslBase, recursive_to_dict - -if TYPE_CHECKING: - from .field import Field, Object - - -class SupportsClone(Protocol): - def _clone(self) -> Self: ... - - -_S = TypeVar("_S", bound=SupportsClone) - - -class QueryProxy(Generic[_S]): - """ - Simple proxy around DSL objects (queries) that can be called - (to add query/post_filter) and also allows attribute access which is proxied to - the wrapped query. - """ - - def __init__(self, search: _S, attr_name: str): - self._search = search - self._proxied: Optional[Query] = None - self._attr_name = attr_name - - def __nonzero__(self) -> bool: - return self._proxied is not None - - __bool__ = __nonzero__ - - def __call__(self, *args: Any, **kwargs: Any) -> _S: - s = self._search._clone() - - # we cannot use self._proxied since we just cloned self._search and - # need to access the new self on the clone - proxied = getattr(s, self._attr_name) - if proxied._proxied is None: - proxied._proxied = Q(*args, **kwargs) - else: - proxied._proxied &= Q(*args, **kwargs) - - # always return search to be chainable - return s - - def __getattr__(self, attr_name: str) -> Any: - return getattr(self._proxied, attr_name) - - def __setattr__(self, attr_name: str, value: Any) -> None: - if not attr_name.startswith("_"): - if self._proxied is not None: - self._proxied = Q(self._proxied.to_dict()) - setattr(self._proxied, attr_name, value) - super().__setattr__(attr_name, value) - - def __getstate__(self) -> Tuple[_S, Optional[Query], str]: - return self._search, self._proxied, self._attr_name - - def __setstate__(self, state: Tuple[_S, Optional[Query], str]) -> None: - self._search, self._proxied, self._attr_name = state - - -class ProxyDescriptor(Generic[_S]): - """ - Simple descriptor to enable setting of queries and filters as: - - s = Search() - s.query = Q(...) - - """ - - def __init__(self, name: str): - self._attr_name = f"_{name}_proxy" - - def __get__(self, instance: Any, owner: object) -> QueryProxy[_S]: - return cast(QueryProxy[_S], getattr(instance, self._attr_name)) - - def __set__(self, instance: _S, value: Dict[str, Any]) -> None: - proxy: QueryProxy[_S] = getattr(instance, self._attr_name) - proxy._proxied = Q(value) - - -class AggsProxy(AggBase[_R], DslBase): - name = "aggs" - - def __init__(self, search: "SearchBase[_R]"): - self._base = cast("Agg[_R]", self) - self._search = search - self._params = {"aggs": {}} - - def to_dict(self) -> Dict[str, Any]: - return cast(Dict[str, Any], super().to_dict().get("aggs", {})) - - -class Request(Generic[_R]): - def __init__( - self, - using: AnyUsingType = "default", - index: Optional[Union[str, List[str]]] = None, - doc_type: Optional[ - Union[type, str, List[Union[type, str]], Dict[str, Union[type, str]]] - ] = None, - extra: Optional[Dict[str, Any]] = None, - ): - self._using = using - - self._index = None - if isinstance(index, (tuple, list)): - self._index = list(index) - elif index: - self._index = [index] - - self._doc_type: List[Union[type, str]] = [] - self._doc_type_map: Dict[str, Any] = {} - if isinstance(doc_type, (tuple, list)): - self._doc_type.extend(doc_type) - elif isinstance(doc_type, collections.abc.Mapping): - self._doc_type.extend(doc_type.keys()) - self._doc_type_map.update(doc_type) - elif doc_type: - self._doc_type.append(doc_type) - - self._params: Dict[str, Any] = {} - self._extra: Dict[str, Any] = extra or {} - - def __eq__(self, other: Any) -> bool: - return ( - isinstance(other, Request) - and other._params == self._params - and other._index == self._index - and other._doc_type == self._doc_type - and other.to_dict() == self.to_dict() - ) - - def __copy__(self) -> Self: - return self._clone() - - def params(self, **kwargs: Any) -> Self: - """ - Specify query params to be used when executing the search. All the - keyword arguments will override the current values. See - https://elasticsearch-py.readthedocs.io/en/latest/api/elasticsearch.html#elasticsearch.Elasticsearch.search - for all available parameters. - - Example:: - - s = Search() - s = s.params(routing='user-1', preference='local') - """ - s = self._clone() - s._params.update(kwargs) - return s - - def index(self, *index: Union[str, List[str], Tuple[str, ...]]) -> Self: - """ - Set the index for the search. If called empty it will remove all information. - - Example:: - - s = Search() - s = s.index('twitter-2015.01.01', 'twitter-2015.01.02') - s = s.index(['twitter-2015.01.01', 'twitter-2015.01.02']) - """ - # .index() resets - s = self._clone() - if not index: - s._index = None - else: - indexes = [] - for i in index: - if isinstance(i, str): - indexes.append(i) - elif isinstance(i, list): - indexes += i - elif isinstance(i, tuple): - indexes += list(i) - - s._index = (self._index or []) + indexes - - return s - - def _resolve_field(self, path: str) -> Optional["Field"]: - for dt in self._doc_type: - if not hasattr(dt, "_index"): - continue - field = dt._index.resolve_field(path) - if field is not None: - return cast("Field", field) - return None - - def _resolve_nested( - self, hit: AttrDict[Any], parent_class: Optional[type] = None - ) -> Type[_R]: - doc_class = Hit - - nested_path = [] - nesting = hit["_nested"] - while nesting and "field" in nesting: - nested_path.append(nesting["field"]) - nesting = nesting.get("_nested") - nested_path_str = ".".join(nested_path) - - nested_field: Optional["Object"] - if parent_class is not None and hasattr(parent_class, "_index"): - nested_field = cast( - Optional["Object"], parent_class._index.resolve_field(nested_path_str) - ) - else: - nested_field = cast( - Optional["Object"], self._resolve_field(nested_path_str) - ) - - if nested_field is not None: - return cast(Type[_R], nested_field._doc_class) - - return cast(Type[_R], doc_class) - - def _get_result( - self, hit: AttrDict[Any], parent_class: Optional[type] = None - ) -> _R: - doc_class: Any = Hit - dt = hit.get("_type") - - if "_nested" in hit: - doc_class = self._resolve_nested(hit, parent_class) - - elif dt in self._doc_type_map: - doc_class = self._doc_type_map[dt] - - else: - for doc_type in self._doc_type: - if hasattr(doc_type, "_matches") and doc_type._matches(hit): - doc_class = doc_type - break - - for t in hit.get("inner_hits", ()): - hit["inner_hits"][t] = Response[_R]( - self, hit["inner_hits"][t], doc_class=doc_class - ) - - callback = getattr(doc_class, "from_es", doc_class) - return cast(_R, callback(hit)) - - def doc_type( - self, *doc_type: Union[type, str], **kwargs: Callable[[AttrDict[Any]], Any] - ) -> Self: - """ - Set the type to search through. You can supply a single value or - multiple. Values can be strings or subclasses of ``Document``. - - You can also pass in any keyword arguments, mapping a doc_type to a - callback that should be used instead of the Hit class. - - If no doc_type is supplied any information stored on the instance will - be erased. - - Example: - - s = Search().doc_type('product', 'store', User, custom=my_callback) - """ - # .doc_type() resets - s = self._clone() - if not doc_type and not kwargs: - s._doc_type = [] - s._doc_type_map = {} - else: - s._doc_type.extend(doc_type) - s._doc_type.extend(kwargs.keys()) - s._doc_type_map.update(kwargs) - return s - - def using(self, client: AnyUsingType) -> Self: - """ - Associate the search request with an elasticsearch client. A fresh copy - will be returned with current instance remaining unchanged. - - :arg client: an instance of ``elasticsearch.Elasticsearch`` to use or - an alias to look up in ``elasticsearch_dsl.connections`` - - """ - s = self._clone() - s._using = client - return s - - def extra(self, **kwargs: Any) -> Self: - """ - Add extra keys to the request body. Mostly here for backwards - compatibility. - """ - s = self._clone() - if "from_" in kwargs: - kwargs["from"] = kwargs.pop("from_") - s._extra.update(kwargs) - return s - - def _clone(self) -> Self: - s = self.__class__( - using=self._using, index=self._index, doc_type=self._doc_type - ) - s._doc_type_map = self._doc_type_map.copy() - s._extra = self._extra.copy() - s._params = self._params.copy() - return s - - if TYPE_CHECKING: - - def to_dict(self) -> Dict[str, Any]: ... - - -class SearchBase(Request[_R]): - query = ProxyDescriptor[Self]("query") - post_filter = ProxyDescriptor[Self]("post_filter") - _response: Response[_R] - - def __init__(self, **kwargs: Any): - """ - Search request to elasticsearch. - - :arg using: `Elasticsearch` instance to use - :arg index: limit the search to index - :arg doc_type: only query this type. - - All the parameters supplied (or omitted) at creation type can be later - overridden by methods (`using`, `index` and `doc_type` respectively). - """ - super().__init__(**kwargs) - - self.aggs = AggsProxy[_R](self) - self._sort: List[Union[str, Dict[str, Dict[str, str]]]] = [] - self._knn: List[Dict[str, Any]] = [] - self._rank: Dict[str, Any] = {} - self._collapse: Dict[str, Any] = {} - self._source: Optional[Union[bool, List[str], Dict[str, List[str]]]] = None - self._highlight: Dict[str, Any] = {} - self._highlight_opts: Dict[str, Any] = {} - self._suggest: Dict[str, Any] = {} - self._script_fields: Dict[str, Any] = {} - self._response_class = Response[_R] - - self._query_proxy = QueryProxy(self, "query") - self._post_filter_proxy = QueryProxy(self, "post_filter") - - def filter(self, *args: Any, **kwargs: Any) -> Self: - return self.query(Bool(filter=[Q(*args, **kwargs)])) - - def exclude(self, *args: Any, **kwargs: Any) -> Self: - return self.query(Bool(filter=[~Q(*args, **kwargs)])) - - def __getitem__(self, n: Union[int, slice]) -> Self: - """ - Support slicing the `Search` instance for pagination. - - Slicing equates to the from/size parameters. E.g.:: - - s = Search().query(...)[0:25] - - is equivalent to:: - - s = Search().query(...).extra(from_=0, size=25) - - """ - s = self._clone() - - if isinstance(n, slice): - # If negative slicing, abort. - if n.start and n.start < 0 or n.stop and n.stop < 0: - raise ValueError("Search does not support negative slicing.") - slice_start = n.start - slice_stop = n.stop - else: # This is an index lookup, equivalent to slicing by [n:n+1]. - # If negative index, abort. - if n < 0: - raise ValueError("Search does not support negative indexing.") - slice_start = n - slice_stop = n + 1 - - old_from = s._extra.get("from") - old_to = None - if "size" in s._extra: - old_to = (old_from or 0) + s._extra["size"] - - new_from = old_from - if slice_start is not None: - new_from = (old_from or 0) + slice_start - new_to = old_to - if slice_stop is not None: - new_to = (old_from or 0) + slice_stop - if old_to is not None and old_to < new_to: - new_to = old_to - - if new_from is not None: - s._extra["from"] = new_from - if new_to is not None: - s._extra["size"] = max(0, new_to - (new_from or 0)) - return s - - @classmethod - def from_dict(cls, d: Dict[str, Any]) -> Self: - """ - Construct a new `Search` instance from a raw dict containing the search - body. Useful when migrating from raw dictionaries. - - Example:: - - s = Search.from_dict({ - "query": { - "bool": { - "must": [...] - } - }, - "aggs": {...} - }) - s = s.filter('term', published=True) - """ - s = cls() - s.update_from_dict(d) - return s - - def _clone(self) -> Self: - """ - Return a clone of the current search request. Performs a shallow copy - of all the underlying objects. Used internally by most state modifying - APIs. - """ - s = super()._clone() - - s._response_class = self._response_class - s._knn = [knn.copy() for knn in self._knn] - s._rank = self._rank.copy() - s._collapse = self._collapse.copy() - s._sort = self._sort[:] - s._source = copy.copy(self._source) if self._source is not None else None - s._highlight = self._highlight.copy() - s._highlight_opts = self._highlight_opts.copy() - s._suggest = self._suggest.copy() - s._script_fields = self._script_fields.copy() - for x in ("query", "post_filter"): - getattr(s, x)._proxied = getattr(self, x)._proxied - - # copy top-level bucket definitions - if self.aggs._params.get("aggs"): - s.aggs._params = {"aggs": self.aggs._params["aggs"].copy()} - return s - - def response_class(self, cls: Type[Response[_R]]) -> Self: - """ - Override the default wrapper used for the response. - """ - s = self._clone() - s._response_class = cls - return s - - def update_from_dict(self, d: Dict[str, Any]) -> Self: - """ - Apply options from a serialized body to the current instance. Modifies - the object in-place. Used mostly by ``from_dict``. - """ - d = d.copy() - if "query" in d: - self.query._proxied = Q(d.pop("query")) - if "post_filter" in d: - self.post_filter._proxied = Q(d.pop("post_filter")) - - aggs = d.pop("aggs", d.pop("aggregations", {})) - if aggs: - self.aggs._params = { - "aggs": {name: A(value) for (name, value) in aggs.items()} - } - if "knn" in d: - self._knn = d.pop("knn") - if isinstance(self._knn, dict): - self._knn = [self._knn] - if "rank" in d: - self._rank = d.pop("rank") - if "collapse" in d: - self._collapse = d.pop("collapse") - if "sort" in d: - self._sort = d.pop("sort") - if "_source" in d: - self._source = d.pop("_source") - if "highlight" in d: - high = d.pop("highlight").copy() - self._highlight = high.pop("fields") - self._highlight_opts = high - if "suggest" in d: - self._suggest = d.pop("suggest") - if "text" in self._suggest: - text = self._suggest.pop("text") - for s in self._suggest.values(): - s.setdefault("text", text) - if "script_fields" in d: - self._script_fields = d.pop("script_fields") - self._extra.update(d) - return self - - def script_fields(self, **kwargs: Any) -> Self: - """ - Define script fields to be calculated on hits. See - https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-script-fields.html - for more details. - - Example:: - - s = Search() - s = s.script_fields(times_two="doc['field'].value * 2") - s = s.script_fields( - times_three={ - 'script': { - 'lang': 'painless', - 'source': "doc['field'].value * params.n", - 'params': {'n': 3} - } - } - ) - - """ - s = self._clone() - for name in kwargs: - if isinstance(kwargs[name], str): - kwargs[name] = {"script": kwargs[name]} - s._script_fields.update(kwargs) - return s - - def knn( - self, - field: Union[str, "InstrumentedField"], - k: int, - num_candidates: int, - query_vector: Optional[List[float]] = None, - query_vector_builder: Optional[Dict[str, Any]] = None, - boost: Optional[float] = None, - filter: Optional[Query] = None, - similarity: Optional[float] = None, - inner_hits: Optional[Dict[str, Any]] = None, - ) -> Self: - """ - Add a k-nearest neighbor (kNN) search. - - :arg field: the vector field to search against as a string or document class attribute - :arg k: number of nearest neighbors to return as top hits - :arg num_candidates: number of nearest neighbor candidates to consider per shard - :arg query_vector: the vector to search for - :arg query_vector_builder: A dictionary indicating how to build a query vector - :arg boost: A floating-point boost factor for kNN scores - :arg filter: query to filter the documents that can match - :arg similarity: the minimum similarity required for a document to be considered a match, as a float value - :arg inner_hits: retrieve hits from nested field - - Example:: - - s = Search() - s = s.knn(field='embedding', k=5, num_candidates=10, query_vector=vector, - filter=Q('term', category='blog'))) - """ - s = self._clone() - s._knn.append( - { - "field": str(field), # str() is for InstrumentedField instances - "k": k, - "num_candidates": num_candidates, - } - ) - if query_vector is None and query_vector_builder is None: - raise ValueError("one of query_vector and query_vector_builder is required") - if query_vector is not None and query_vector_builder is not None: - raise ValueError( - "only one of query_vector and query_vector_builder must be given" - ) - if query_vector is not None: - s._knn[-1]["query_vector"] = cast(Any, query_vector) - if query_vector_builder is not None: - s._knn[-1]["query_vector_builder"] = query_vector_builder - if boost is not None: - s._knn[-1]["boost"] = boost - if filter is not None: - if isinstance(filter, Query): - s._knn[-1]["filter"] = filter.to_dict() - else: - s._knn[-1]["filter"] = filter - if similarity is not None: - s._knn[-1]["similarity"] = similarity - if inner_hits is not None: - s._knn[-1]["inner_hits"] = inner_hits - return s - - def rank(self, rrf: Optional[Union[bool, Dict[str, Any]]] = None) -> Self: - """ - Defines a method for combining and ranking results sets from a combination - of searches. Requires a minimum of 2 results sets. - - :arg rrf: Set to ``True`` or an options dictionary to set the rank method to reciprocal rank fusion (RRF). - - Example:: - - s = Search() - s = s.query('match', content='search text') - s = s.knn(field='embedding', k=5, num_candidates=10, query_vector=vector) - s = s.rank(rrf=True) - - Note: This option is in technical preview and may change in the future. The syntax will likely change before GA. - """ - s = self._clone() - s._rank = {} - if rrf is not None and rrf is not False: - s._rank["rrf"] = {} if rrf is True else rrf - return s - - def source( - self, - fields: Optional[ - Union[ - bool, - str, - "InstrumentedField", - List[Union[str, "InstrumentedField"]], - Dict[str, List[Union[str, "InstrumentedField"]]], - ] - ] = None, - **kwargs: Any, - ) -> Self: - """ - Selectively control how the _source field is returned. - - :arg fields: field name, wildcard string, list of field names or wildcards, - or dictionary of includes and excludes - :arg kwargs: ``includes`` or ``excludes`` arguments, when ``fields`` is ``None``. - - When no arguments are given, the entire document will be returned for - each hit. If ``fields`` is a string or list of strings, the field names or field - wildcards given will be included. If ``fields`` is a dictionary with keys of - 'includes' and/or 'excludes' the fields will be either included or excluded - appropriately. - - Calling this multiple times with the same named parameter will override the - previous values with the new ones. - - Example:: - - s = Search() - s = s.source(includes=['obj1.*'], excludes=["*.description"]) - - s = Search() - s = s.source(includes=['obj1.*']).source(excludes=["*.description"]) - - """ - s = self._clone() - - if fields and kwargs: - raise ValueError("You cannot specify fields and kwargs at the same time.") - - @overload - def ensure_strings(fields: str) -> str: ... - - @overload - def ensure_strings(fields: "InstrumentedField") -> str: ... - - @overload - def ensure_strings( - fields: List[Union[str, "InstrumentedField"]] - ) -> List[str]: ... - - @overload - def ensure_strings( - fields: Dict[str, List[Union[str, "InstrumentedField"]]] - ) -> Dict[str, List[str]]: ... - - def ensure_strings( - fields: Union[ - str, - "InstrumentedField", - List[Union[str, "InstrumentedField"]], - Dict[str, List[Union[str, "InstrumentedField"]]], - ] - ) -> Union[str, List[str], Dict[str, List[str]]]: - if isinstance(fields, dict): - return {k: ensure_strings(v) for k, v in fields.items()} - elif not isinstance(fields, (str, InstrumentedField)): - # we assume that if `fields` is not a any of [dict, str, - # InstrumentedField] then it is an iterable of strings or - # InstrumentedFields, so we convert them to a plain list of - # strings - return [str(f) for f in fields] - else: - return str(fields) - - if fields is not None: - s._source = fields if isinstance(fields, bool) else ensure_strings(fields) # type: ignore[assignment] - return s - - if kwargs and not isinstance(s._source, dict): - s._source = {} - - if isinstance(s._source, dict): - for key, value in kwargs.items(): - if value is None: - try: - del s._source[key] - except KeyError: - pass - else: - s._source[key] = ensure_strings(value) - - return s - - def sort( - self, *keys: Union[str, "InstrumentedField", Dict[str, Dict[str, str]]] - ) -> Self: - """ - Add sorting information to the search request. If called without - arguments it will remove all sort requirements. Otherwise it will - replace them. Acceptable arguments are:: - - 'some.field' - '-some.other.field' - {'different.field': {'any': 'dict'}} - - so for example:: - - s = Search().sort( - 'category', - '-title', - {"price" : {"order" : "asc", "mode" : "avg"}} - ) - - will sort by ``category``, ``title`` (in descending order) and - ``price`` in ascending order using the ``avg`` mode. - - The API returns a copy of the Search object and can thus be chained. - """ - s = self._clone() - s._sort = [] - for k in keys: - if not isinstance(k, dict): - sort_field = str(k) - if sort_field.startswith("-"): - if sort_field[1:] == "_score": - raise IllegalOperation("Sorting by `-_score` is not allowed.") - s._sort.append({sort_field[1:]: {"order": "desc"}}) - else: - s._sort.append(sort_field) - else: - s._sort.append(k) - return s - - def collapse( - self, - field: Optional[Union[str, "InstrumentedField"]] = None, - inner_hits: Optional[Dict[str, Any]] = None, - max_concurrent_group_searches: Optional[int] = None, - ) -> Self: - """ - Add collapsing information to the search request. - If called without providing ``field``, it will remove all collapse - requirements, otherwise it will replace them with the provided - arguments. - The API returns a copy of the Search object and can thus be chained. - """ - s = self._clone() - s._collapse = {} - - if field is None: - return s - - s._collapse["field"] = str(field) - if inner_hits: - s._collapse["inner_hits"] = inner_hits - if max_concurrent_group_searches: - s._collapse["max_concurrent_group_searches"] = max_concurrent_group_searches - return s - - def highlight_options(self, **kwargs: Any) -> Self: - """ - Update the global highlighting options used for this request. For - example:: - - s = Search() - s = s.highlight_options(order='score') - """ - s = self._clone() - s._highlight_opts.update(kwargs) - return s - - def highlight( - self, *fields: Union[str, "InstrumentedField"], **kwargs: Any - ) -> Self: - """ - Request highlighting of some fields. All keyword arguments passed in will be - used as parameters for all the fields in the ``fields`` parameter. Example:: - - Search().highlight('title', 'body', fragment_size=50) - - will produce the equivalent of:: - - { - "highlight": { - "fields": { - "body": {"fragment_size": 50}, - "title": {"fragment_size": 50} - } - } - } - - If you want to have different options for different fields - you can call ``highlight`` twice:: - - Search().highlight('title', fragment_size=50).highlight('body', fragment_size=100) - - which will produce:: - - { - "highlight": { - "fields": { - "body": {"fragment_size": 100}, - "title": {"fragment_size": 50} - } - } - } - - """ - s = self._clone() - for f in fields: - s._highlight[str(f)] = kwargs - return s - - def suggest( - self, - name: str, - text: Optional[str] = None, - regex: Optional[str] = None, - **kwargs: Any, - ) -> Self: - """ - Add a suggestions request to the search. - - :arg name: name of the suggestion - :arg text: text to suggest on - - All keyword arguments will be added to the suggestions body. For example:: - - 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() - if regex: - s._suggest[name] = {"regex": regex} - elif text: - if "completion" in kwargs: - s._suggest[name] = {"prefix": text} - else: - s._suggest[name] = {"text": text} - s._suggest[name].update(kwargs) - return s - - def search_after(self) -> Self: - """ - Return a ``Search`` instance that retrieves the next page of results. - - This method provides an easy way to paginate a long list of results using - the ``search_after`` option. For example:: - - page_size = 20 - s = Search()[:page_size].sort("date") - - while True: - # get a page of results - r = await s.execute() - - # do something with this page of results - - # exit the loop if we reached the end - if len(r.hits) < page_size: - break - - # get a search object with the next page of results - s = s.search_after() - - Note that the ``search_after`` option requires the search to have an - explicit ``sort`` order. - """ - if not hasattr(self, "_response"): - raise ValueError("A search must be executed before using search_after") - return cast(Self, self._response.search_after()) - - def to_dict(self, count: bool = False, **kwargs: Any) -> Dict[str, Any]: - """ - Serialize the search into the dictionary that will be sent over as the - request's body. - - :arg count: a flag to specify if we are interested in a body for count - - no aggregations, no pagination bounds etc. - - All additional keyword arguments will be included into the dictionary. - """ - d = {} - - if self.query: - d["query"] = recursive_to_dict(self.query) - - if self._knn: - if len(self._knn) == 1: - d["knn"] = self._knn[0] - else: - d["knn"] = self._knn - - if self._rank: - d["rank"] = self._rank - - # count request doesn't care for sorting and other things - if not count: - if self.post_filter: - d["post_filter"] = recursive_to_dict(self.post_filter.to_dict()) - - if self.aggs.aggs: - d.update(recursive_to_dict(self.aggs.to_dict())) - - if self._sort: - d["sort"] = self._sort - - if self._collapse: - d["collapse"] = self._collapse - - d.update(recursive_to_dict(self._extra)) - - if self._source not in (None, {}): - d["_source"] = self._source - - if self._highlight: - d["highlight"] = {"fields": self._highlight} - d["highlight"].update(self._highlight_opts) - - if self._suggest: - d["suggest"] = self._suggest - - if self._script_fields: - d["script_fields"] = self._script_fields - - d.update(recursive_to_dict(kwargs)) - return d - - -class MultiSearchBase(Request[_R]): - """ - Combine multiple :class:`~elasticsearch_dsl.Search` objects into a single - request. - """ - - def __init__(self, **kwargs: Any): - super().__init__(**kwargs) - self._searches: List[SearchBase[_R]] = [] - - def __getitem__(self, key: Union[int, slice]) -> Any: - return self._searches[key] - - def __iter__(self) -> Iterator[SearchBase[_R]]: - return iter(self._searches) - - def _clone(self) -> Self: - ms = super()._clone() - ms._searches = self._searches[:] - return ms - - def add(self, search: SearchBase[_R]) -> Self: - """ - Adds a new :class:`~elasticsearch_dsl.Search` object to the request:: - - ms = MultiSearch(index='my-index') - ms = ms.add(Search(doc_type=Category).filter('term', category='python')) - ms = ms.add(Search(doc_type=Blog)) - """ - ms = self._clone() - ms._searches.append(search) - return ms - - def to_dict(self) -> List[Dict[str, Any]]: # type: ignore[override] - out: List[Dict[str, Any]] = [] - for s in self._searches: - meta: Dict[str, Any] = {} - if s._index: - meta["index"] = cast(Any, s._index) - meta.update(s._params) - - out.append(meta) - out.append(s.to_dict()) - - return out diff --git a/elasticsearch_dsl/serializer.py b/elasticsearch_dsl/serializer.py deleted file mode 100644 index 3080f1da..00000000 --- a/elasticsearch_dsl/serializer.py +++ /dev/null @@ -1,34 +0,0 @@ -# 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 - -from elasticsearch.serializer import JSONSerializer - -from .utils import AttrList - - -class AttrJSONSerializer(JSONSerializer): - def default(self, data: Any) -> Any: - if isinstance(data, AttrList): - return data._l_ - if hasattr(data, "to_dict"): - return data.to_dict() - return super().default(data) - - -serializer = AttrJSONSerializer() diff --git a/elasticsearch_dsl/types.py b/elasticsearch_dsl/types.py deleted file mode 100644 index 57521543..00000000 --- a/elasticsearch_dsl/types.py +++ /dev/null @@ -1,6272 +0,0 @@ -# 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, Dict, Literal, Mapping, Sequence, Union - -from elastic_transport.client_utils import DEFAULT, DefaultType - -from elasticsearch_dsl import Query -from elasticsearch_dsl.document_base import InstrumentedField -from elasticsearch_dsl.utils import AttrDict - -PipeSeparatedFlags = str - - -class AggregationRange(AttrDict[Any]): - """ - :arg from: Start of the range (inclusive). - :arg key: Custom key to return the range with. - :arg to: End of the range (exclusive). - """ - - from_: Union[float, None, DefaultType] - key: Union[str, DefaultType] - to: Union[float, None, DefaultType] - - def __init__( - self, - *, - from_: Union[float, None, DefaultType] = DEFAULT, - key: Union[str, DefaultType] = DEFAULT, - to: Union[float, None, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if from_ is not DEFAULT: - kwargs["from_"] = from_ - if key is not DEFAULT: - kwargs["key"] = key - if to is not DEFAULT: - kwargs["to"] = to - super().__init__(kwargs) - - -class BucketCorrelationFunction(AttrDict[Any]): - """ - :arg count_correlation: (required) The configuration to calculate a - count correlation. This function is designed for determining the - correlation of a term value and a given metric. - """ - - count_correlation: Union[ - "BucketCorrelationFunctionCountCorrelation", Dict[str, Any], DefaultType - ] - - def __init__( - self, - *, - count_correlation: Union[ - "BucketCorrelationFunctionCountCorrelation", Dict[str, Any], DefaultType - ] = DEFAULT, - **kwargs: Any, - ): - if count_correlation is not DEFAULT: - kwargs["count_correlation"] = count_correlation - super().__init__(kwargs) - - -class BucketCorrelationFunctionCountCorrelation(AttrDict[Any]): - """ - :arg indicator: (required) The indicator with which to correlate the - configured `bucket_path` values. - """ - - indicator: Union[ - "BucketCorrelationFunctionCountCorrelationIndicator", - Dict[str, Any], - DefaultType, - ] - - def __init__( - self, - *, - indicator: Union[ - "BucketCorrelationFunctionCountCorrelationIndicator", - Dict[str, Any], - DefaultType, - ] = DEFAULT, - **kwargs: Any, - ): - if indicator is not DEFAULT: - kwargs["indicator"] = indicator - super().__init__(kwargs) - - -class BucketCorrelationFunctionCountCorrelationIndicator(AttrDict[Any]): - """ - :arg doc_count: (required) The total number of documents that - initially created the expectations. It’s required to be greater - than or equal to the sum of all values in the buckets_path as this - is the originating superset of data to which the term values are - correlated. - :arg expectations: (required) An array of numbers with which to - correlate the configured `bucket_path` values. The length of this - value must always equal the number of buckets returned by the - `bucket_path`. - :arg fractions: An array of fractions to use when averaging and - calculating variance. This should be used if the pre-calculated - data and the buckets_path have known gaps. The length of - fractions, if provided, must equal expectations. - """ - - doc_count: Union[int, DefaultType] - expectations: Union[Sequence[float], DefaultType] - fractions: Union[Sequence[float], DefaultType] - - def __init__( - self, - *, - doc_count: Union[int, DefaultType] = DEFAULT, - expectations: Union[Sequence[float], DefaultType] = DEFAULT, - fractions: Union[Sequence[float], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if doc_count is not DEFAULT: - kwargs["doc_count"] = doc_count - if expectations is not DEFAULT: - kwargs["expectations"] = expectations - if fractions is not DEFAULT: - kwargs["fractions"] = fractions - super().__init__(kwargs) - - -class ChiSquareHeuristic(AttrDict[Any]): - """ - :arg background_is_superset: (required) Set to `false` if you defined - a custom background filter that represents a different set of - documents that you want to compare to. - :arg include_negatives: (required) Set to `false` to filter out the - terms that appear less often in the subset than in documents - outside the subset. - """ - - background_is_superset: Union[bool, DefaultType] - include_negatives: Union[bool, DefaultType] - - def __init__( - self, - *, - background_is_superset: Union[bool, DefaultType] = DEFAULT, - include_negatives: Union[bool, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if background_is_superset is not DEFAULT: - kwargs["background_is_superset"] = background_is_superset - if include_negatives is not DEFAULT: - kwargs["include_negatives"] = include_negatives - super().__init__(kwargs) - - -class ClassificationInferenceOptions(AttrDict[Any]): - """ - :arg num_top_classes: Specifies the number of top class predictions to - return. Defaults to 0. - :arg num_top_feature_importance_values: Specifies the maximum number - of feature importance values per document. - :arg prediction_field_type: Specifies the type of the predicted field - to write. Acceptable values are: string, number, boolean. When - boolean is provided 1.0 is transformed to true and 0.0 to false. - :arg results_field: The field that is added to incoming documents to - contain the inference prediction. Defaults to predicted_value. - :arg top_classes_results_field: Specifies the field to which the top - classes are written. Defaults to top_classes. - """ - - num_top_classes: Union[int, DefaultType] - num_top_feature_importance_values: Union[int, DefaultType] - prediction_field_type: Union[str, DefaultType] - results_field: Union[str, DefaultType] - top_classes_results_field: Union[str, DefaultType] - - def __init__( - self, - *, - num_top_classes: Union[int, DefaultType] = DEFAULT, - num_top_feature_importance_values: Union[int, DefaultType] = DEFAULT, - prediction_field_type: Union[str, DefaultType] = DEFAULT, - results_field: Union[str, DefaultType] = DEFAULT, - top_classes_results_field: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if num_top_classes is not DEFAULT: - kwargs["num_top_classes"] = num_top_classes - if num_top_feature_importance_values is not DEFAULT: - kwargs["num_top_feature_importance_values"] = ( - num_top_feature_importance_values - ) - if prediction_field_type is not DEFAULT: - kwargs["prediction_field_type"] = prediction_field_type - if results_field is not DEFAULT: - kwargs["results_field"] = results_field - if top_classes_results_field is not DEFAULT: - kwargs["top_classes_results_field"] = top_classes_results_field - super().__init__(kwargs) - - -class CommonTermsQuery(AttrDict[Any]): - """ - :arg query: (required) - :arg analyzer: - :arg cutoff_frequency: - :arg high_freq_operator: - :arg low_freq_operator: - :arg minimum_should_match: - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - query: Union[str, DefaultType] - analyzer: Union[str, DefaultType] - cutoff_frequency: Union[float, DefaultType] - high_freq_operator: Union[Literal["and", "or"], DefaultType] - low_freq_operator: Union[Literal["and", "or"], DefaultType] - minimum_should_match: Union[int, str, DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - query: Union[str, DefaultType] = DEFAULT, - analyzer: Union[str, DefaultType] = DEFAULT, - cutoff_frequency: Union[float, DefaultType] = DEFAULT, - high_freq_operator: Union[Literal["and", "or"], DefaultType] = DEFAULT, - low_freq_operator: Union[Literal["and", "or"], DefaultType] = DEFAULT, - minimum_should_match: Union[int, str, DefaultType] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if query is not DEFAULT: - kwargs["query"] = query - if analyzer is not DEFAULT: - kwargs["analyzer"] = analyzer - if cutoff_frequency is not DEFAULT: - kwargs["cutoff_frequency"] = cutoff_frequency - if high_freq_operator is not DEFAULT: - kwargs["high_freq_operator"] = high_freq_operator - if low_freq_operator is not DEFAULT: - kwargs["low_freq_operator"] = low_freq_operator - if minimum_should_match is not DEFAULT: - kwargs["minimum_should_match"] = minimum_should_match - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class CoordsGeoBounds(AttrDict[Any]): - """ - :arg top: (required) - :arg bottom: (required) - :arg left: (required) - :arg right: (required) - """ - - top: Union[float, DefaultType] - bottom: Union[float, DefaultType] - left: Union[float, DefaultType] - right: Union[float, DefaultType] - - def __init__( - self, - *, - top: Union[float, DefaultType] = DEFAULT, - bottom: Union[float, DefaultType] = DEFAULT, - left: Union[float, DefaultType] = DEFAULT, - right: Union[float, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if top is not DEFAULT: - kwargs["top"] = top - if bottom is not DEFAULT: - kwargs["bottom"] = bottom - if left is not DEFAULT: - kwargs["left"] = left - if right is not DEFAULT: - kwargs["right"] = right - super().__init__(kwargs) - - -class CustomCategorizeTextAnalyzer(AttrDict[Any]): - """ - :arg char_filter: - :arg tokenizer: - :arg filter: - """ - - char_filter: Union[Sequence[str], DefaultType] - tokenizer: Union[str, DefaultType] - filter: Union[Sequence[str], DefaultType] - - def __init__( - self, - *, - char_filter: Union[Sequence[str], DefaultType] = DEFAULT, - tokenizer: Union[str, DefaultType] = DEFAULT, - filter: Union[Sequence[str], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if char_filter is not DEFAULT: - kwargs["char_filter"] = char_filter - if tokenizer is not DEFAULT: - kwargs["tokenizer"] = tokenizer - if filter is not DEFAULT: - kwargs["filter"] = filter - super().__init__(kwargs) - - -class DateRangeExpression(AttrDict[Any]): - """ - :arg from: Start of the range (inclusive). - :arg key: Custom key to return the range with. - :arg to: End of the range (exclusive). - """ - - from_: Union[str, float, DefaultType] - key: Union[str, DefaultType] - to: Union[str, float, DefaultType] - - def __init__( - self, - *, - from_: Union[str, float, DefaultType] = DEFAULT, - key: Union[str, DefaultType] = DEFAULT, - to: Union[str, float, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if from_ is not DEFAULT: - kwargs["from_"] = from_ - if key is not DEFAULT: - kwargs["key"] = key - if to is not DEFAULT: - kwargs["to"] = to - super().__init__(kwargs) - - -class EmptyObject(AttrDict[Any]): - """ - For empty Class assignments - """ - - def __init__(self, **kwargs: Any): - super().__init__(kwargs) - - -class EwmaModelSettings(AttrDict[Any]): - """ - :arg alpha: - """ - - alpha: Union[float, DefaultType] - - def __init__(self, *, alpha: Union[float, DefaultType] = DEFAULT, **kwargs: Any): - if alpha is not DEFAULT: - kwargs["alpha"] = alpha - super().__init__(kwargs) - - -class ExtendedBounds(AttrDict[Any]): - """ - :arg max: Maximum value for the bound. - :arg min: Minimum value for the bound. - """ - - max: Any - min: Any - - def __init__(self, *, max: Any = DEFAULT, min: Any = DEFAULT, **kwargs: Any): - if max is not DEFAULT: - kwargs["max"] = max - if min is not DEFAULT: - kwargs["min"] = min - super().__init__(kwargs) - - -class FieldAndFormat(AttrDict[Any]): - """ - A reference to a field with formatting instructions on how to return - the value - - :arg field: (required) Wildcard pattern. The request returns values - for field names matching this pattern. - :arg format: Format in which the values are returned. - :arg include_unmapped: - """ - - field: Union[str, InstrumentedField, DefaultType] - format: Union[str, DefaultType] - include_unmapped: Union[bool, DefaultType] - - def __init__( - self, - *, - field: Union[str, InstrumentedField, DefaultType] = DEFAULT, - format: Union[str, DefaultType] = DEFAULT, - include_unmapped: Union[bool, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if field is not DEFAULT: - kwargs["field"] = str(field) - if format is not DEFAULT: - kwargs["format"] = format - if include_unmapped is not DEFAULT: - kwargs["include_unmapped"] = include_unmapped - super().__init__(kwargs) - - -class FieldCollapse(AttrDict[Any]): - """ - :arg field: (required) The field to collapse the result set on - :arg inner_hits: The number of inner hits and their sort order - :arg max_concurrent_group_searches: The number of concurrent requests - allowed to retrieve the inner_hits per group - :arg collapse: - """ - - field: Union[str, InstrumentedField, DefaultType] - inner_hits: Union[ - "InnerHits", Sequence["InnerHits"], Sequence[Dict[str, Any]], DefaultType - ] - max_concurrent_group_searches: Union[int, DefaultType] - collapse: Union["FieldCollapse", Dict[str, Any], DefaultType] - - def __init__( - self, - *, - field: Union[str, InstrumentedField, DefaultType] = DEFAULT, - inner_hits: Union[ - "InnerHits", Sequence["InnerHits"], Sequence[Dict[str, Any]], DefaultType - ] = DEFAULT, - max_concurrent_group_searches: Union[int, DefaultType] = DEFAULT, - collapse: Union["FieldCollapse", Dict[str, Any], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if field is not DEFAULT: - kwargs["field"] = str(field) - if inner_hits is not DEFAULT: - kwargs["inner_hits"] = inner_hits - if max_concurrent_group_searches is not DEFAULT: - kwargs["max_concurrent_group_searches"] = max_concurrent_group_searches - if collapse is not DEFAULT: - kwargs["collapse"] = collapse - super().__init__(kwargs) - - -class FieldLookup(AttrDict[Any]): - """ - :arg id: (required) `id` of the document. - :arg index: Index from which to retrieve the document. - :arg path: Name of the field. - :arg routing: Custom routing value. - """ - - id: Union[str, DefaultType] - index: Union[str, DefaultType] - path: Union[str, InstrumentedField, DefaultType] - routing: Union[str, DefaultType] - - def __init__( - self, - *, - id: Union[str, DefaultType] = DEFAULT, - index: Union[str, DefaultType] = DEFAULT, - path: Union[str, InstrumentedField, DefaultType] = DEFAULT, - routing: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if id is not DEFAULT: - kwargs["id"] = id - if index is not DEFAULT: - kwargs["index"] = index - if path is not DEFAULT: - kwargs["path"] = str(path) - if routing is not DEFAULT: - kwargs["routing"] = routing - super().__init__(kwargs) - - -class FieldSort(AttrDict[Any]): - """ - :arg missing: - :arg mode: - :arg nested: - :arg order: - :arg unmapped_type: - :arg numeric_type: - :arg format: - """ - - missing: Union[str, int, float, bool, DefaultType] - mode: Union[Literal["min", "max", "sum", "avg", "median"], DefaultType] - nested: Union["NestedSortValue", Dict[str, Any], DefaultType] - order: Union[Literal["asc", "desc"], DefaultType] - unmapped_type: Union[ - Literal[ - "none", - "geo_point", - "geo_shape", - "ip", - "binary", - "keyword", - "text", - "search_as_you_type", - "date", - "date_nanos", - "boolean", - "completion", - "nested", - "object", - "version", - "murmur3", - "token_count", - "percolator", - "integer", - "long", - "short", - "byte", - "float", - "half_float", - "scaled_float", - "double", - "integer_range", - "float_range", - "long_range", - "double_range", - "date_range", - "ip_range", - "alias", - "join", - "rank_feature", - "rank_features", - "flattened", - "shape", - "histogram", - "constant_keyword", - "aggregate_metric_double", - "dense_vector", - "semantic_text", - "sparse_vector", - "match_only_text", - "icu_collation_keyword", - ], - DefaultType, - ] - numeric_type: Union[Literal["long", "double", "date", "date_nanos"], DefaultType] - format: Union[str, DefaultType] - - def __init__( - self, - *, - missing: Union[str, int, float, bool, DefaultType] = DEFAULT, - mode: Union[ - Literal["min", "max", "sum", "avg", "median"], DefaultType - ] = DEFAULT, - nested: Union["NestedSortValue", Dict[str, Any], DefaultType] = DEFAULT, - order: Union[Literal["asc", "desc"], DefaultType] = DEFAULT, - unmapped_type: Union[ - Literal[ - "none", - "geo_point", - "geo_shape", - "ip", - "binary", - "keyword", - "text", - "search_as_you_type", - "date", - "date_nanos", - "boolean", - "completion", - "nested", - "object", - "version", - "murmur3", - "token_count", - "percolator", - "integer", - "long", - "short", - "byte", - "float", - "half_float", - "scaled_float", - "double", - "integer_range", - "float_range", - "long_range", - "double_range", - "date_range", - "ip_range", - "alias", - "join", - "rank_feature", - "rank_features", - "flattened", - "shape", - "histogram", - "constant_keyword", - "aggregate_metric_double", - "dense_vector", - "semantic_text", - "sparse_vector", - "match_only_text", - "icu_collation_keyword", - ], - DefaultType, - ] = DEFAULT, - numeric_type: Union[ - Literal["long", "double", "date", "date_nanos"], DefaultType - ] = DEFAULT, - format: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if missing is not DEFAULT: - kwargs["missing"] = missing - if mode is not DEFAULT: - kwargs["mode"] = mode - if nested is not DEFAULT: - kwargs["nested"] = nested - if order is not DEFAULT: - kwargs["order"] = order - if unmapped_type is not DEFAULT: - kwargs["unmapped_type"] = unmapped_type - if numeric_type is not DEFAULT: - kwargs["numeric_type"] = numeric_type - if format is not DEFAULT: - kwargs["format"] = format - super().__init__(kwargs) - - -class FrequentItemSetsField(AttrDict[Any]): - """ - :arg field: (required) - :arg exclude: Values to exclude. Can be regular expression strings or - arrays of strings of exact terms. - :arg include: Values to include. Can be regular expression strings or - arrays of strings of exact terms. - """ - - field: Union[str, InstrumentedField, DefaultType] - exclude: Union[str, Sequence[str], DefaultType] - include: Union[str, Sequence[str], "TermsPartition", Dict[str, Any], DefaultType] - - def __init__( - self, - *, - field: Union[str, InstrumentedField, DefaultType] = DEFAULT, - exclude: Union[str, Sequence[str], DefaultType] = DEFAULT, - include: Union[ - str, Sequence[str], "TermsPartition", Dict[str, Any], DefaultType - ] = DEFAULT, - **kwargs: Any, - ): - if field is not DEFAULT: - kwargs["field"] = str(field) - if exclude is not DEFAULT: - kwargs["exclude"] = exclude - if include is not DEFAULT: - kwargs["include"] = include - super().__init__(kwargs) - - -class FuzzyQuery(AttrDict[Any]): - """ - :arg value: (required) Term you wish to find in the provided field. - :arg max_expansions: Maximum number of variations created. Defaults to - `50` if omitted. - :arg prefix_length: Number of beginning characters left unchanged when - creating expansions. - :arg rewrite: Number of beginning characters left unchanged when - creating expansions. Defaults to `constant_score` if omitted. - :arg transpositions: Indicates whether edits include transpositions of - two adjacent characters (for example `ab` to `ba`). Defaults to - `True` if omitted. - :arg fuzziness: Maximum edit distance allowed for matching. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - value: Union[str, float, bool, DefaultType] - max_expansions: Union[int, DefaultType] - prefix_length: Union[int, DefaultType] - rewrite: Union[str, DefaultType] - transpositions: Union[bool, DefaultType] - fuzziness: Union[str, int, DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - value: Union[str, float, bool, DefaultType] = DEFAULT, - max_expansions: Union[int, DefaultType] = DEFAULT, - prefix_length: Union[int, DefaultType] = DEFAULT, - rewrite: Union[str, DefaultType] = DEFAULT, - transpositions: Union[bool, DefaultType] = DEFAULT, - fuzziness: Union[str, int, DefaultType] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if value is not DEFAULT: - kwargs["value"] = value - if max_expansions is not DEFAULT: - kwargs["max_expansions"] = max_expansions - if prefix_length is not DEFAULT: - kwargs["prefix_length"] = prefix_length - if rewrite is not DEFAULT: - kwargs["rewrite"] = rewrite - if transpositions is not DEFAULT: - kwargs["transpositions"] = transpositions - if fuzziness is not DEFAULT: - kwargs["fuzziness"] = fuzziness - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class GeoDistanceSort(AttrDict[Any]): - """ - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - :arg mode: - :arg distance_type: - :arg ignore_unmapped: - :arg order: - :arg unit: - :arg nested: - """ - - _field: Union[str, "InstrumentedField", "DefaultType"] - _value: Union[ - Union["LatLonGeoLocation", "GeoHashLocation", Sequence[float], str], - Sequence[Union["LatLonGeoLocation", "GeoHashLocation", Sequence[float], str]], - Dict[str, Any], - "DefaultType", - ] - mode: Union[Literal["min", "max", "sum", "avg", "median"], DefaultType] - distance_type: Union[Literal["arc", "plane"], DefaultType] - ignore_unmapped: Union[bool, DefaultType] - order: Union[Literal["asc", "desc"], DefaultType] - unit: Union[ - Literal["in", "ft", "yd", "mi", "nmi", "km", "m", "cm", "mm"], DefaultType - ] - nested: Union["NestedSortValue", Dict[str, Any], DefaultType] - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union[ - Union["LatLonGeoLocation", "GeoHashLocation", Sequence[float], str], - Sequence[ - Union["LatLonGeoLocation", "GeoHashLocation", Sequence[float], str] - ], - Dict[str, Any], - "DefaultType", - ] = DEFAULT, - *, - mode: Union[ - Literal["min", "max", "sum", "avg", "median"], DefaultType - ] = DEFAULT, - distance_type: Union[Literal["arc", "plane"], DefaultType] = DEFAULT, - ignore_unmapped: Union[bool, DefaultType] = DEFAULT, - order: Union[Literal["asc", "desc"], DefaultType] = DEFAULT, - unit: Union[ - Literal["in", "ft", "yd", "mi", "nmi", "km", "m", "cm", "mm"], DefaultType - ] = DEFAULT, - nested: Union["NestedSortValue", Dict[str, Any], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - if mode is not DEFAULT: - kwargs["mode"] = mode - if distance_type is not DEFAULT: - kwargs["distance_type"] = distance_type - if ignore_unmapped is not DEFAULT: - kwargs["ignore_unmapped"] = ignore_unmapped - if order is not DEFAULT: - kwargs["order"] = order - if unit is not DEFAULT: - kwargs["unit"] = unit - if nested is not DEFAULT: - kwargs["nested"] = nested - super().__init__(kwargs) - - -class GeoHashLocation(AttrDict[Any]): - """ - :arg geohash: (required) - """ - - geohash: Union[str, DefaultType] - - def __init__(self, *, geohash: Union[str, DefaultType] = DEFAULT, **kwargs: Any): - if geohash is not DEFAULT: - kwargs["geohash"] = geohash - super().__init__(kwargs) - - -class GeoLinePoint(AttrDict[Any]): - """ - :arg field: (required) The name of the geo_point field. - """ - - field: Union[str, InstrumentedField, DefaultType] - - def __init__( - self, - *, - field: Union[str, InstrumentedField, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if field is not DEFAULT: - kwargs["field"] = str(field) - super().__init__(kwargs) - - -class GeoLineSort(AttrDict[Any]): - """ - :arg field: (required) The name of the numeric field to use as the - sort key for ordering the points. - """ - - field: Union[str, InstrumentedField, DefaultType] - - def __init__( - self, - *, - field: Union[str, InstrumentedField, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if field is not DEFAULT: - kwargs["field"] = str(field) - super().__init__(kwargs) - - -class GeoPolygonPoints(AttrDict[Any]): - """ - :arg points: (required) - """ - - points: Union[ - Sequence[Union["LatLonGeoLocation", "GeoHashLocation", Sequence[float], str]], - Dict[str, Any], - DefaultType, - ] - - def __init__( - self, - *, - points: Union[ - Sequence[ - Union["LatLonGeoLocation", "GeoHashLocation", Sequence[float], str] - ], - Dict[str, Any], - DefaultType, - ] = DEFAULT, - **kwargs: Any, - ): - if points is not DEFAULT: - kwargs["points"] = points - super().__init__(kwargs) - - -class GeoShapeFieldQuery(AttrDict[Any]): - """ - :arg shape: - :arg indexed_shape: Query using an indexed shape retrieved from the - the specified document and path. - :arg relation: Spatial relation operator used to search a geo field. - Defaults to `intersects` if omitted. - """ - - shape: Any - indexed_shape: Union["FieldLookup", Dict[str, Any], DefaultType] - relation: Union[ - Literal["intersects", "disjoint", "within", "contains"], DefaultType - ] - - def __init__( - self, - *, - shape: Any = DEFAULT, - indexed_shape: Union["FieldLookup", Dict[str, Any], DefaultType] = DEFAULT, - relation: Union[ - Literal["intersects", "disjoint", "within", "contains"], DefaultType - ] = DEFAULT, - **kwargs: Any, - ): - if shape is not DEFAULT: - kwargs["shape"] = shape - if indexed_shape is not DEFAULT: - kwargs["indexed_shape"] = indexed_shape - if relation is not DEFAULT: - kwargs["relation"] = relation - super().__init__(kwargs) - - -class GoogleNormalizedDistanceHeuristic(AttrDict[Any]): - """ - :arg background_is_superset: Set to `false` if you defined a custom - background filter that represents a different set of documents - that you want to compare to. - """ - - background_is_superset: Union[bool, DefaultType] - - def __init__( - self, - *, - background_is_superset: Union[bool, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if background_is_superset is not DEFAULT: - kwargs["background_is_superset"] = background_is_superset - super().__init__(kwargs) - - -class HdrMethod(AttrDict[Any]): - """ - :arg number_of_significant_value_digits: Specifies the resolution of - values for the histogram in number of significant digits. - """ - - number_of_significant_value_digits: Union[int, DefaultType] - - def __init__( - self, - *, - number_of_significant_value_digits: Union[int, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if number_of_significant_value_digits is not DEFAULT: - kwargs["number_of_significant_value_digits"] = ( - number_of_significant_value_digits - ) - super().__init__(kwargs) - - -class Highlight(AttrDict[Any]): - """ - :arg fields: (required) - :arg encoder: - :arg type: - :arg boundary_chars: A string that contains each boundary character. - Defaults to `.,!? \t\n` if omitted. - :arg boundary_max_scan: How far to scan for boundary characters. - Defaults to `20` if omitted. - :arg boundary_scanner: Specifies how to break the highlighted - fragments: chars, sentence, or word. Only valid for the unified - and fvh highlighters. Defaults to `sentence` for the `unified` - highlighter. Defaults to `chars` for the `fvh` highlighter. - :arg boundary_scanner_locale: Controls which locale is used to search - for sentence and word boundaries. This parameter takes a form of a - language tag, for example: `"en-US"`, `"fr-FR"`, `"ja-JP"`. - Defaults to `Locale.ROOT` if omitted. - :arg force_source: - :arg fragmenter: Specifies how text should be broken up in highlight - snippets: `simple` or `span`. Only valid for the `plain` - highlighter. Defaults to `span` if omitted. - :arg fragment_size: The size of the highlighted fragment in - characters. Defaults to `100` if omitted. - :arg highlight_filter: - :arg highlight_query: Highlight matches for a query other than the - search query. This is especially useful if you use a rescore query - because those are not taken into account by highlighting by - default. - :arg max_fragment_length: - :arg max_analyzed_offset: If set to a non-negative value, highlighting - stops at this defined maximum limit. The rest of the text is not - processed, thus not highlighted and no error is returned The - `max_analyzed_offset` query setting does not override the - `index.highlight.max_analyzed_offset` setting, which prevails when - it’s set to lower value than the query setting. - :arg no_match_size: The amount of text you want to return from the - beginning of the field if there are no matching fragments to - highlight. - :arg number_of_fragments: The maximum number of fragments to return. - If the number of fragments is set to `0`, no fragments are - returned. Instead, the entire field contents are highlighted and - returned. This can be handy when you need to highlight short texts - such as a title or address, but fragmentation is not required. If - `number_of_fragments` is `0`, `fragment_size` is ignored. Defaults - to `5` if omitted. - :arg options: - :arg order: Sorts highlighted fragments by score when set to `score`. - By default, fragments will be output in the order they appear in - the field (order: `none`). Setting this option to `score` will - output the most relevant fragments first. Each highlighter applies - its own logic to compute relevancy scores. Defaults to `none` if - omitted. - :arg phrase_limit: Controls the number of matching phrases in a - document that are considered. Prevents the `fvh` highlighter from - analyzing too many phrases and consuming too much memory. When - using `matched_fields`, `phrase_limit` phrases per matched field - are considered. Raising the limit increases query time and - consumes more memory. Only supported by the `fvh` highlighter. - Defaults to `256` if omitted. - :arg post_tags: Use in conjunction with `pre_tags` to define the HTML - tags to use for the highlighted text. By default, highlighted text - is wrapped in `` and `` tags. - :arg pre_tags: Use in conjunction with `post_tags` to define the HTML - tags to use for the highlighted text. By default, highlighted text - is wrapped in `` and `` tags. - :arg require_field_match: By default, only fields that contains a - query match are highlighted. Set to `false` to highlight all - fields. Defaults to `True` if omitted. - :arg tags_schema: Set to `styled` to use the built-in tag schema. - """ - - fields: Union[ - Mapping[Union[str, InstrumentedField], "HighlightField"], - Dict[str, Any], - DefaultType, - ] - encoder: Union[Literal["default", "html"], DefaultType] - type: Union[Literal["plain", "fvh", "unified"], DefaultType] - boundary_chars: Union[str, DefaultType] - boundary_max_scan: Union[int, DefaultType] - boundary_scanner: Union[Literal["chars", "sentence", "word"], DefaultType] - boundary_scanner_locale: Union[str, DefaultType] - force_source: Union[bool, DefaultType] - fragmenter: Union[Literal["simple", "span"], DefaultType] - fragment_size: Union[int, DefaultType] - highlight_filter: Union[bool, DefaultType] - highlight_query: Union[Query, DefaultType] - max_fragment_length: Union[int, DefaultType] - max_analyzed_offset: Union[int, DefaultType] - no_match_size: Union[int, DefaultType] - number_of_fragments: Union[int, DefaultType] - options: Union[Mapping[str, Any], DefaultType] - order: Union[Literal["score"], DefaultType] - phrase_limit: Union[int, DefaultType] - post_tags: Union[Sequence[str], DefaultType] - pre_tags: Union[Sequence[str], DefaultType] - require_field_match: Union[bool, DefaultType] - tags_schema: Union[Literal["styled"], DefaultType] - - def __init__( - self, - *, - fields: Union[ - Mapping[Union[str, InstrumentedField], "HighlightField"], - Dict[str, Any], - DefaultType, - ] = DEFAULT, - encoder: Union[Literal["default", "html"], DefaultType] = DEFAULT, - type: Union[Literal["plain", "fvh", "unified"], DefaultType] = DEFAULT, - boundary_chars: Union[str, DefaultType] = DEFAULT, - boundary_max_scan: Union[int, DefaultType] = DEFAULT, - boundary_scanner: Union[ - Literal["chars", "sentence", "word"], DefaultType - ] = DEFAULT, - boundary_scanner_locale: Union[str, DefaultType] = DEFAULT, - force_source: Union[bool, DefaultType] = DEFAULT, - fragmenter: Union[Literal["simple", "span"], DefaultType] = DEFAULT, - fragment_size: Union[int, DefaultType] = DEFAULT, - highlight_filter: Union[bool, DefaultType] = DEFAULT, - highlight_query: Union[Query, DefaultType] = DEFAULT, - max_fragment_length: Union[int, DefaultType] = DEFAULT, - max_analyzed_offset: Union[int, DefaultType] = DEFAULT, - no_match_size: Union[int, DefaultType] = DEFAULT, - number_of_fragments: Union[int, DefaultType] = DEFAULT, - options: Union[Mapping[str, Any], DefaultType] = DEFAULT, - order: Union[Literal["score"], DefaultType] = DEFAULT, - phrase_limit: Union[int, DefaultType] = DEFAULT, - post_tags: Union[Sequence[str], DefaultType] = DEFAULT, - pre_tags: Union[Sequence[str], DefaultType] = DEFAULT, - require_field_match: Union[bool, DefaultType] = DEFAULT, - tags_schema: Union[Literal["styled"], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if fields is not DEFAULT: - kwargs["fields"] = str(fields) - if encoder is not DEFAULT: - kwargs["encoder"] = encoder - if type is not DEFAULT: - kwargs["type"] = type - if boundary_chars is not DEFAULT: - kwargs["boundary_chars"] = boundary_chars - if boundary_max_scan is not DEFAULT: - kwargs["boundary_max_scan"] = boundary_max_scan - if boundary_scanner is not DEFAULT: - kwargs["boundary_scanner"] = boundary_scanner - if boundary_scanner_locale is not DEFAULT: - kwargs["boundary_scanner_locale"] = boundary_scanner_locale - if force_source is not DEFAULT: - kwargs["force_source"] = force_source - if fragmenter is not DEFAULT: - kwargs["fragmenter"] = fragmenter - if fragment_size is not DEFAULT: - kwargs["fragment_size"] = fragment_size - if highlight_filter is not DEFAULT: - kwargs["highlight_filter"] = highlight_filter - if highlight_query is not DEFAULT: - kwargs["highlight_query"] = highlight_query - if max_fragment_length is not DEFAULT: - kwargs["max_fragment_length"] = max_fragment_length - if max_analyzed_offset is not DEFAULT: - kwargs["max_analyzed_offset"] = max_analyzed_offset - if no_match_size is not DEFAULT: - kwargs["no_match_size"] = no_match_size - if number_of_fragments is not DEFAULT: - kwargs["number_of_fragments"] = number_of_fragments - if options is not DEFAULT: - kwargs["options"] = options - if order is not DEFAULT: - kwargs["order"] = order - if phrase_limit is not DEFAULT: - kwargs["phrase_limit"] = phrase_limit - if post_tags is not DEFAULT: - kwargs["post_tags"] = post_tags - if pre_tags is not DEFAULT: - kwargs["pre_tags"] = pre_tags - if require_field_match is not DEFAULT: - kwargs["require_field_match"] = require_field_match - if tags_schema is not DEFAULT: - kwargs["tags_schema"] = tags_schema - super().__init__(kwargs) - - -class HighlightField(AttrDict[Any]): - """ - :arg fragment_offset: - :arg matched_fields: - :arg type: - :arg boundary_chars: A string that contains each boundary character. - Defaults to `.,!? \t\n` if omitted. - :arg boundary_max_scan: How far to scan for boundary characters. - Defaults to `20` if omitted. - :arg boundary_scanner: Specifies how to break the highlighted - fragments: chars, sentence, or word. Only valid for the unified - and fvh highlighters. Defaults to `sentence` for the `unified` - highlighter. Defaults to `chars` for the `fvh` highlighter. - :arg boundary_scanner_locale: Controls which locale is used to search - for sentence and word boundaries. This parameter takes a form of a - language tag, for example: `"en-US"`, `"fr-FR"`, `"ja-JP"`. - Defaults to `Locale.ROOT` if omitted. - :arg force_source: - :arg fragmenter: Specifies how text should be broken up in highlight - snippets: `simple` or `span`. Only valid for the `plain` - highlighter. Defaults to `span` if omitted. - :arg fragment_size: The size of the highlighted fragment in - characters. Defaults to `100` if omitted. - :arg highlight_filter: - :arg highlight_query: Highlight matches for a query other than the - search query. This is especially useful if you use a rescore query - because those are not taken into account by highlighting by - default. - :arg max_fragment_length: - :arg max_analyzed_offset: If set to a non-negative value, highlighting - stops at this defined maximum limit. The rest of the text is not - processed, thus not highlighted and no error is returned The - `max_analyzed_offset` query setting does not override the - `index.highlight.max_analyzed_offset` setting, which prevails when - it’s set to lower value than the query setting. - :arg no_match_size: The amount of text you want to return from the - beginning of the field if there are no matching fragments to - highlight. - :arg number_of_fragments: The maximum number of fragments to return. - If the number of fragments is set to `0`, no fragments are - returned. Instead, the entire field contents are highlighted and - returned. This can be handy when you need to highlight short texts - such as a title or address, but fragmentation is not required. If - `number_of_fragments` is `0`, `fragment_size` is ignored. Defaults - to `5` if omitted. - :arg options: - :arg order: Sorts highlighted fragments by score when set to `score`. - By default, fragments will be output in the order they appear in - the field (order: `none`). Setting this option to `score` will - output the most relevant fragments first. Each highlighter applies - its own logic to compute relevancy scores. Defaults to `none` if - omitted. - :arg phrase_limit: Controls the number of matching phrases in a - document that are considered. Prevents the `fvh` highlighter from - analyzing too many phrases and consuming too much memory. When - using `matched_fields`, `phrase_limit` phrases per matched field - are considered. Raising the limit increases query time and - consumes more memory. Only supported by the `fvh` highlighter. - Defaults to `256` if omitted. - :arg post_tags: Use in conjunction with `pre_tags` to define the HTML - tags to use for the highlighted text. By default, highlighted text - is wrapped in `` and `` tags. - :arg pre_tags: Use in conjunction with `post_tags` to define the HTML - tags to use for the highlighted text. By default, highlighted text - is wrapped in `` and `` tags. - :arg require_field_match: By default, only fields that contains a - query match are highlighted. Set to `false` to highlight all - fields. Defaults to `True` if omitted. - :arg tags_schema: Set to `styled` to use the built-in tag schema. - """ - - fragment_offset: Union[int, DefaultType] - matched_fields: Union[ - Union[str, InstrumentedField], - Sequence[Union[str, InstrumentedField]], - DefaultType, - ] - type: Union[Literal["plain", "fvh", "unified"], DefaultType] - boundary_chars: Union[str, DefaultType] - boundary_max_scan: Union[int, DefaultType] - boundary_scanner: Union[Literal["chars", "sentence", "word"], DefaultType] - boundary_scanner_locale: Union[str, DefaultType] - force_source: Union[bool, DefaultType] - fragmenter: Union[Literal["simple", "span"], DefaultType] - fragment_size: Union[int, DefaultType] - highlight_filter: Union[bool, DefaultType] - highlight_query: Union[Query, DefaultType] - max_fragment_length: Union[int, DefaultType] - max_analyzed_offset: Union[int, DefaultType] - no_match_size: Union[int, DefaultType] - number_of_fragments: Union[int, DefaultType] - options: Union[Mapping[str, Any], DefaultType] - order: Union[Literal["score"], DefaultType] - phrase_limit: Union[int, DefaultType] - post_tags: Union[Sequence[str], DefaultType] - pre_tags: Union[Sequence[str], DefaultType] - require_field_match: Union[bool, DefaultType] - tags_schema: Union[Literal["styled"], DefaultType] - - def __init__( - self, - *, - fragment_offset: Union[int, DefaultType] = DEFAULT, - matched_fields: Union[ - Union[str, InstrumentedField], - Sequence[Union[str, InstrumentedField]], - DefaultType, - ] = DEFAULT, - type: Union[Literal["plain", "fvh", "unified"], DefaultType] = DEFAULT, - boundary_chars: Union[str, DefaultType] = DEFAULT, - boundary_max_scan: Union[int, DefaultType] = DEFAULT, - boundary_scanner: Union[ - Literal["chars", "sentence", "word"], DefaultType - ] = DEFAULT, - boundary_scanner_locale: Union[str, DefaultType] = DEFAULT, - force_source: Union[bool, DefaultType] = DEFAULT, - fragmenter: Union[Literal["simple", "span"], DefaultType] = DEFAULT, - fragment_size: Union[int, DefaultType] = DEFAULT, - highlight_filter: Union[bool, DefaultType] = DEFAULT, - highlight_query: Union[Query, DefaultType] = DEFAULT, - max_fragment_length: Union[int, DefaultType] = DEFAULT, - max_analyzed_offset: Union[int, DefaultType] = DEFAULT, - no_match_size: Union[int, DefaultType] = DEFAULT, - number_of_fragments: Union[int, DefaultType] = DEFAULT, - options: Union[Mapping[str, Any], DefaultType] = DEFAULT, - order: Union[Literal["score"], DefaultType] = DEFAULT, - phrase_limit: Union[int, DefaultType] = DEFAULT, - post_tags: Union[Sequence[str], DefaultType] = DEFAULT, - pre_tags: Union[Sequence[str], DefaultType] = DEFAULT, - require_field_match: Union[bool, DefaultType] = DEFAULT, - tags_schema: Union[Literal["styled"], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if fragment_offset is not DEFAULT: - kwargs["fragment_offset"] = fragment_offset - if matched_fields is not DEFAULT: - kwargs["matched_fields"] = str(matched_fields) - if type is not DEFAULT: - kwargs["type"] = type - if boundary_chars is not DEFAULT: - kwargs["boundary_chars"] = boundary_chars - if boundary_max_scan is not DEFAULT: - kwargs["boundary_max_scan"] = boundary_max_scan - if boundary_scanner is not DEFAULT: - kwargs["boundary_scanner"] = boundary_scanner - if boundary_scanner_locale is not DEFAULT: - kwargs["boundary_scanner_locale"] = boundary_scanner_locale - if force_source is not DEFAULT: - kwargs["force_source"] = force_source - if fragmenter is not DEFAULT: - kwargs["fragmenter"] = fragmenter - if fragment_size is not DEFAULT: - kwargs["fragment_size"] = fragment_size - if highlight_filter is not DEFAULT: - kwargs["highlight_filter"] = highlight_filter - if highlight_query is not DEFAULT: - kwargs["highlight_query"] = highlight_query - if max_fragment_length is not DEFAULT: - kwargs["max_fragment_length"] = max_fragment_length - if max_analyzed_offset is not DEFAULT: - kwargs["max_analyzed_offset"] = max_analyzed_offset - if no_match_size is not DEFAULT: - kwargs["no_match_size"] = no_match_size - if number_of_fragments is not DEFAULT: - kwargs["number_of_fragments"] = number_of_fragments - if options is not DEFAULT: - kwargs["options"] = options - if order is not DEFAULT: - kwargs["order"] = order - if phrase_limit is not DEFAULT: - kwargs["phrase_limit"] = phrase_limit - if post_tags is not DEFAULT: - kwargs["post_tags"] = post_tags - if pre_tags is not DEFAULT: - kwargs["pre_tags"] = pre_tags - if require_field_match is not DEFAULT: - kwargs["require_field_match"] = require_field_match - if tags_schema is not DEFAULT: - kwargs["tags_schema"] = tags_schema - super().__init__(kwargs) - - -class HoltLinearModelSettings(AttrDict[Any]): - """ - :arg alpha: - :arg beta: - """ - - alpha: Union[float, DefaultType] - beta: Union[float, DefaultType] - - def __init__( - self, - *, - alpha: Union[float, DefaultType] = DEFAULT, - beta: Union[float, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if alpha is not DEFAULT: - kwargs["alpha"] = alpha - if beta is not DEFAULT: - kwargs["beta"] = beta - super().__init__(kwargs) - - -class HoltWintersModelSettings(AttrDict[Any]): - """ - :arg alpha: - :arg beta: - :arg gamma: - :arg pad: - :arg period: - :arg type: - """ - - alpha: Union[float, DefaultType] - beta: Union[float, DefaultType] - gamma: Union[float, DefaultType] - pad: Union[bool, DefaultType] - period: Union[int, DefaultType] - type: Union[Literal["add", "mult"], DefaultType] - - def __init__( - self, - *, - alpha: Union[float, DefaultType] = DEFAULT, - beta: Union[float, DefaultType] = DEFAULT, - gamma: Union[float, DefaultType] = DEFAULT, - pad: Union[bool, DefaultType] = DEFAULT, - period: Union[int, DefaultType] = DEFAULT, - type: Union[Literal["add", "mult"], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if alpha is not DEFAULT: - kwargs["alpha"] = alpha - if beta is not DEFAULT: - kwargs["beta"] = beta - if gamma is not DEFAULT: - kwargs["gamma"] = gamma - if pad is not DEFAULT: - kwargs["pad"] = pad - if period is not DEFAULT: - kwargs["period"] = period - if type is not DEFAULT: - kwargs["type"] = type - super().__init__(kwargs) - - -class InferenceConfigContainer(AttrDict[Any]): - """ - :arg regression: Regression configuration for inference. - :arg classification: Classification configuration for inference. - """ - - regression: Union["RegressionInferenceOptions", Dict[str, Any], DefaultType] - classification: Union["ClassificationInferenceOptions", Dict[str, Any], DefaultType] - - def __init__( - self, - *, - regression: Union[ - "RegressionInferenceOptions", Dict[str, Any], DefaultType - ] = DEFAULT, - classification: Union[ - "ClassificationInferenceOptions", Dict[str, Any], DefaultType - ] = DEFAULT, - **kwargs: Any, - ): - if regression is not DEFAULT: - kwargs["regression"] = regression - if classification is not DEFAULT: - kwargs["classification"] = classification - super().__init__(kwargs) - - -class InnerHits(AttrDict[Any]): - """ - :arg name: The name for the particular inner hit definition in the - response. Useful when a search request contains multiple inner - hits. - :arg size: The maximum number of hits to return per `inner_hits`. - Defaults to `3` if omitted. - :arg from: Inner hit starting document offset. - :arg collapse: - :arg docvalue_fields: - :arg explain: - :arg highlight: - :arg ignore_unmapped: - :arg script_fields: - :arg seq_no_primary_term: - :arg fields: - :arg sort: How the inner hits should be sorted per `inner_hits`. By - default, inner hits are sorted by score. - :arg _source: - :arg stored_fields: - :arg track_scores: - :arg version: - """ - - name: Union[str, DefaultType] - size: Union[int, DefaultType] - from_: Union[int, DefaultType] - collapse: Union["FieldCollapse", Dict[str, Any], DefaultType] - docvalue_fields: Union[ - Sequence["FieldAndFormat"], Sequence[Dict[str, Any]], DefaultType - ] - explain: Union[bool, DefaultType] - highlight: Union["Highlight", Dict[str, Any], DefaultType] - ignore_unmapped: Union[bool, DefaultType] - script_fields: Union[ - Mapping[Union[str, InstrumentedField], "ScriptField"], - Dict[str, Any], - DefaultType, - ] - seq_no_primary_term: Union[bool, DefaultType] - fields: Union[ - Union[str, InstrumentedField], - Sequence[Union[str, InstrumentedField]], - DefaultType, - ] - sort: Union[ - Union[Union[str, InstrumentedField], "SortOptions"], - Sequence[Union[Union[str, InstrumentedField], "SortOptions"]], - Dict[str, Any], - DefaultType, - ] - _source: Union[bool, "SourceFilter", Dict[str, Any], DefaultType] - stored_fields: Union[ - Union[str, InstrumentedField], - Sequence[Union[str, InstrumentedField]], - DefaultType, - ] - track_scores: Union[bool, DefaultType] - version: Union[bool, DefaultType] - - def __init__( - self, - *, - name: Union[str, DefaultType] = DEFAULT, - size: Union[int, DefaultType] = DEFAULT, - from_: Union[int, DefaultType] = DEFAULT, - collapse: Union["FieldCollapse", Dict[str, Any], DefaultType] = DEFAULT, - docvalue_fields: Union[ - Sequence["FieldAndFormat"], Sequence[Dict[str, Any]], DefaultType - ] = DEFAULT, - explain: Union[bool, DefaultType] = DEFAULT, - highlight: Union["Highlight", Dict[str, Any], DefaultType] = DEFAULT, - ignore_unmapped: Union[bool, DefaultType] = DEFAULT, - script_fields: Union[ - Mapping[Union[str, InstrumentedField], "ScriptField"], - Dict[str, Any], - DefaultType, - ] = DEFAULT, - seq_no_primary_term: Union[bool, DefaultType] = DEFAULT, - fields: Union[ - Union[str, InstrumentedField], - Sequence[Union[str, InstrumentedField]], - DefaultType, - ] = DEFAULT, - sort: Union[ - Union[Union[str, InstrumentedField], "SortOptions"], - Sequence[Union[Union[str, InstrumentedField], "SortOptions"]], - Dict[str, Any], - DefaultType, - ] = DEFAULT, - _source: Union[bool, "SourceFilter", Dict[str, Any], DefaultType] = DEFAULT, - stored_fields: Union[ - Union[str, InstrumentedField], - Sequence[Union[str, InstrumentedField]], - DefaultType, - ] = DEFAULT, - track_scores: Union[bool, DefaultType] = DEFAULT, - version: Union[bool, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if name is not DEFAULT: - kwargs["name"] = name - if size is not DEFAULT: - kwargs["size"] = size - if from_ is not DEFAULT: - kwargs["from_"] = from_ - if collapse is not DEFAULT: - kwargs["collapse"] = collapse - if docvalue_fields is not DEFAULT: - kwargs["docvalue_fields"] = docvalue_fields - if explain is not DEFAULT: - kwargs["explain"] = explain - if highlight is not DEFAULT: - kwargs["highlight"] = highlight - if ignore_unmapped is not DEFAULT: - kwargs["ignore_unmapped"] = ignore_unmapped - if script_fields is not DEFAULT: - kwargs["script_fields"] = str(script_fields) - if seq_no_primary_term is not DEFAULT: - kwargs["seq_no_primary_term"] = seq_no_primary_term - if fields is not DEFAULT: - kwargs["fields"] = str(fields) - if sort is not DEFAULT: - kwargs["sort"] = str(sort) - if _source is not DEFAULT: - kwargs["_source"] = _source - if stored_fields is not DEFAULT: - kwargs["stored_fields"] = str(stored_fields) - if track_scores is not DEFAULT: - kwargs["track_scores"] = track_scores - if version is not DEFAULT: - kwargs["version"] = version - super().__init__(kwargs) - - -class IntervalsAllOf(AttrDict[Any]): - """ - :arg intervals: (required) An array of rules to combine. All rules - must produce a match in a document for the overall source to - match. - :arg max_gaps: Maximum number of positions between the matching terms. - Intervals produced by the rules further apart than this are not - considered matches. Defaults to `-1` if omitted. - :arg ordered: If `true`, intervals produced by the rules should appear - in the order in which they are specified. - :arg filter: Rule used to filter returned intervals. - """ - - intervals: Union[ - Sequence["IntervalsContainer"], Sequence[Dict[str, Any]], DefaultType - ] - max_gaps: Union[int, DefaultType] - ordered: Union[bool, DefaultType] - filter: Union["IntervalsFilter", Dict[str, Any], DefaultType] - - def __init__( - self, - *, - intervals: Union[ - Sequence["IntervalsContainer"], Sequence[Dict[str, Any]], DefaultType - ] = DEFAULT, - max_gaps: Union[int, DefaultType] = DEFAULT, - ordered: Union[bool, DefaultType] = DEFAULT, - filter: Union["IntervalsFilter", Dict[str, Any], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if intervals is not DEFAULT: - kwargs["intervals"] = intervals - if max_gaps is not DEFAULT: - kwargs["max_gaps"] = max_gaps - if ordered is not DEFAULT: - kwargs["ordered"] = ordered - if filter is not DEFAULT: - kwargs["filter"] = filter - super().__init__(kwargs) - - -class IntervalsAnyOf(AttrDict[Any]): - """ - :arg intervals: (required) An array of rules to match. - :arg filter: Rule used to filter returned intervals. - """ - - intervals: Union[ - Sequence["IntervalsContainer"], Sequence[Dict[str, Any]], DefaultType - ] - filter: Union["IntervalsFilter", Dict[str, Any], DefaultType] - - def __init__( - self, - *, - intervals: Union[ - Sequence["IntervalsContainer"], Sequence[Dict[str, Any]], DefaultType - ] = DEFAULT, - filter: Union["IntervalsFilter", Dict[str, Any], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if intervals is not DEFAULT: - kwargs["intervals"] = intervals - if filter is not DEFAULT: - kwargs["filter"] = filter - super().__init__(kwargs) - - -class IntervalsContainer(AttrDict[Any]): - """ - :arg all_of: Returns matches that span a combination of other rules. - :arg any_of: Returns intervals produced by any of its sub-rules. - :arg fuzzy: Matches analyzed text. - :arg match: Matches analyzed text. - :arg prefix: Matches terms that start with a specified set of - characters. - :arg wildcard: Matches terms using a wildcard pattern. - """ - - all_of: Union["IntervalsAllOf", Dict[str, Any], DefaultType] - any_of: Union["IntervalsAnyOf", Dict[str, Any], DefaultType] - fuzzy: Union["IntervalsFuzzy", Dict[str, Any], DefaultType] - match: Union["IntervalsMatch", Dict[str, Any], DefaultType] - prefix: Union["IntervalsPrefix", Dict[str, Any], DefaultType] - wildcard: Union["IntervalsWildcard", Dict[str, Any], DefaultType] - - def __init__( - self, - *, - all_of: Union["IntervalsAllOf", Dict[str, Any], DefaultType] = DEFAULT, - any_of: Union["IntervalsAnyOf", Dict[str, Any], DefaultType] = DEFAULT, - fuzzy: Union["IntervalsFuzzy", Dict[str, Any], DefaultType] = DEFAULT, - match: Union["IntervalsMatch", Dict[str, Any], DefaultType] = DEFAULT, - prefix: Union["IntervalsPrefix", Dict[str, Any], DefaultType] = DEFAULT, - wildcard: Union["IntervalsWildcard", Dict[str, Any], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if all_of is not DEFAULT: - kwargs["all_of"] = all_of - if any_of is not DEFAULT: - kwargs["any_of"] = any_of - if fuzzy is not DEFAULT: - kwargs["fuzzy"] = fuzzy - if match is not DEFAULT: - kwargs["match"] = match - if prefix is not DEFAULT: - kwargs["prefix"] = prefix - if wildcard is not DEFAULT: - kwargs["wildcard"] = wildcard - super().__init__(kwargs) - - -class IntervalsFilter(AttrDict[Any]): - """ - :arg after: Query used to return intervals that follow an interval - from the `filter` rule. - :arg before: Query used to return intervals that occur before an - interval from the `filter` rule. - :arg contained_by: Query used to return intervals contained by an - interval from the `filter` rule. - :arg containing: Query used to return intervals that contain an - interval from the `filter` rule. - :arg not_contained_by: Query used to return intervals that are **not** - contained by an interval from the `filter` rule. - :arg not_containing: Query used to return intervals that do **not** - contain an interval from the `filter` rule. - :arg not_overlapping: Query used to return intervals that do **not** - overlap with an interval from the `filter` rule. - :arg overlapping: Query used to return intervals that overlap with an - interval from the `filter` rule. - :arg script: Script used to return matching documents. This script - must return a boolean value: `true` or `false`. - """ - - after: Union["IntervalsContainer", Dict[str, Any], DefaultType] - before: Union["IntervalsContainer", Dict[str, Any], DefaultType] - contained_by: Union["IntervalsContainer", Dict[str, Any], DefaultType] - containing: Union["IntervalsContainer", Dict[str, Any], DefaultType] - not_contained_by: Union["IntervalsContainer", Dict[str, Any], DefaultType] - not_containing: Union["IntervalsContainer", Dict[str, Any], DefaultType] - not_overlapping: Union["IntervalsContainer", Dict[str, Any], DefaultType] - overlapping: Union["IntervalsContainer", Dict[str, Any], DefaultType] - script: Union["Script", Dict[str, Any], DefaultType] - - def __init__( - self, - *, - after: Union["IntervalsContainer", Dict[str, Any], DefaultType] = DEFAULT, - before: Union["IntervalsContainer", Dict[str, Any], DefaultType] = DEFAULT, - contained_by: Union[ - "IntervalsContainer", Dict[str, Any], DefaultType - ] = DEFAULT, - containing: Union["IntervalsContainer", Dict[str, Any], DefaultType] = DEFAULT, - not_contained_by: Union[ - "IntervalsContainer", Dict[str, Any], DefaultType - ] = DEFAULT, - not_containing: Union[ - "IntervalsContainer", Dict[str, Any], DefaultType - ] = DEFAULT, - not_overlapping: Union[ - "IntervalsContainer", Dict[str, Any], DefaultType - ] = DEFAULT, - overlapping: Union["IntervalsContainer", Dict[str, Any], DefaultType] = DEFAULT, - script: Union["Script", Dict[str, Any], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if after is not DEFAULT: - kwargs["after"] = after - if before is not DEFAULT: - kwargs["before"] = before - if contained_by is not DEFAULT: - kwargs["contained_by"] = contained_by - if containing is not DEFAULT: - kwargs["containing"] = containing - if not_contained_by is not DEFAULT: - kwargs["not_contained_by"] = not_contained_by - if not_containing is not DEFAULT: - kwargs["not_containing"] = not_containing - if not_overlapping is not DEFAULT: - kwargs["not_overlapping"] = not_overlapping - if overlapping is not DEFAULT: - kwargs["overlapping"] = overlapping - if script is not DEFAULT: - kwargs["script"] = script - super().__init__(kwargs) - - -class IntervalsFuzzy(AttrDict[Any]): - """ - :arg term: (required) The term to match. - :arg analyzer: Analyzer used to normalize the term. - :arg fuzziness: Maximum edit distance allowed for matching. Defaults - to `auto` if omitted. - :arg prefix_length: Number of beginning characters left unchanged when - creating expansions. - :arg transpositions: Indicates whether edits include transpositions of - two adjacent characters (for example, `ab` to `ba`). Defaults to - `True` if omitted. - :arg use_field: If specified, match intervals from this field rather - than the top-level field. The `term` is normalized using the - search analyzer from this field, unless `analyzer` is specified - separately. - """ - - term: Union[str, DefaultType] - analyzer: Union[str, DefaultType] - fuzziness: Union[str, int, DefaultType] - prefix_length: Union[int, DefaultType] - transpositions: Union[bool, DefaultType] - use_field: Union[str, InstrumentedField, DefaultType] - - def __init__( - self, - *, - term: Union[str, DefaultType] = DEFAULT, - analyzer: Union[str, DefaultType] = DEFAULT, - fuzziness: Union[str, int, DefaultType] = DEFAULT, - prefix_length: Union[int, DefaultType] = DEFAULT, - transpositions: Union[bool, DefaultType] = DEFAULT, - use_field: Union[str, InstrumentedField, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if term is not DEFAULT: - kwargs["term"] = term - if analyzer is not DEFAULT: - kwargs["analyzer"] = analyzer - if fuzziness is not DEFAULT: - kwargs["fuzziness"] = fuzziness - if prefix_length is not DEFAULT: - kwargs["prefix_length"] = prefix_length - if transpositions is not DEFAULT: - kwargs["transpositions"] = transpositions - if use_field is not DEFAULT: - kwargs["use_field"] = str(use_field) - super().__init__(kwargs) - - -class IntervalsMatch(AttrDict[Any]): - """ - :arg query: (required) Text you wish to find in the provided field. - :arg analyzer: Analyzer used to analyze terms in the query. - :arg max_gaps: Maximum number of positions between the matching terms. - Terms further apart than this are not considered matches. Defaults - to `-1` if omitted. - :arg ordered: If `true`, matching terms must appear in their specified - order. - :arg use_field: If specified, match intervals from this field rather - than the top-level field. The `term` is normalized using the - search analyzer from this field, unless `analyzer` is specified - separately. - :arg filter: An optional interval filter. - """ - - query: Union[str, DefaultType] - analyzer: Union[str, DefaultType] - max_gaps: Union[int, DefaultType] - ordered: Union[bool, DefaultType] - use_field: Union[str, InstrumentedField, DefaultType] - filter: Union["IntervalsFilter", Dict[str, Any], DefaultType] - - def __init__( - self, - *, - query: Union[str, DefaultType] = DEFAULT, - analyzer: Union[str, DefaultType] = DEFAULT, - max_gaps: Union[int, DefaultType] = DEFAULT, - ordered: Union[bool, DefaultType] = DEFAULT, - use_field: Union[str, InstrumentedField, DefaultType] = DEFAULT, - filter: Union["IntervalsFilter", Dict[str, Any], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if query is not DEFAULT: - kwargs["query"] = query - if analyzer is not DEFAULT: - kwargs["analyzer"] = analyzer - if max_gaps is not DEFAULT: - kwargs["max_gaps"] = max_gaps - if ordered is not DEFAULT: - kwargs["ordered"] = ordered - if use_field is not DEFAULT: - kwargs["use_field"] = str(use_field) - if filter is not DEFAULT: - kwargs["filter"] = filter - super().__init__(kwargs) - - -class IntervalsPrefix(AttrDict[Any]): - """ - :arg prefix: (required) Beginning characters of terms you wish to find - in the top-level field. - :arg analyzer: Analyzer used to analyze the `prefix`. - :arg use_field: If specified, match intervals from this field rather - than the top-level field. The `prefix` is normalized using the - search analyzer from this field, unless `analyzer` is specified - separately. - """ - - prefix: Union[str, DefaultType] - analyzer: Union[str, DefaultType] - use_field: Union[str, InstrumentedField, DefaultType] - - def __init__( - self, - *, - prefix: Union[str, DefaultType] = DEFAULT, - analyzer: Union[str, DefaultType] = DEFAULT, - use_field: Union[str, InstrumentedField, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if prefix is not DEFAULT: - kwargs["prefix"] = prefix - if analyzer is not DEFAULT: - kwargs["analyzer"] = analyzer - if use_field is not DEFAULT: - kwargs["use_field"] = str(use_field) - super().__init__(kwargs) - - -class IntervalsQuery(AttrDict[Any]): - """ - :arg all_of: Returns matches that span a combination of other rules. - :arg any_of: Returns intervals produced by any of its sub-rules. - :arg fuzzy: Matches terms that are similar to the provided term, - within an edit distance defined by `fuzziness`. - :arg match: Matches analyzed text. - :arg prefix: Matches terms that start with a specified set of - characters. - :arg wildcard: Matches terms using a wildcard pattern. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - all_of: Union["IntervalsAllOf", Dict[str, Any], DefaultType] - any_of: Union["IntervalsAnyOf", Dict[str, Any], DefaultType] - fuzzy: Union["IntervalsFuzzy", Dict[str, Any], DefaultType] - match: Union["IntervalsMatch", Dict[str, Any], DefaultType] - prefix: Union["IntervalsPrefix", Dict[str, Any], DefaultType] - wildcard: Union["IntervalsWildcard", Dict[str, Any], DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - all_of: Union["IntervalsAllOf", Dict[str, Any], DefaultType] = DEFAULT, - any_of: Union["IntervalsAnyOf", Dict[str, Any], DefaultType] = DEFAULT, - fuzzy: Union["IntervalsFuzzy", Dict[str, Any], DefaultType] = DEFAULT, - match: Union["IntervalsMatch", Dict[str, Any], DefaultType] = DEFAULT, - prefix: Union["IntervalsPrefix", Dict[str, Any], DefaultType] = DEFAULT, - wildcard: Union["IntervalsWildcard", Dict[str, Any], DefaultType] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if all_of is not DEFAULT: - kwargs["all_of"] = all_of - if any_of is not DEFAULT: - kwargs["any_of"] = any_of - if fuzzy is not DEFAULT: - kwargs["fuzzy"] = fuzzy - if match is not DEFAULT: - kwargs["match"] = match - if prefix is not DEFAULT: - kwargs["prefix"] = prefix - if wildcard is not DEFAULT: - kwargs["wildcard"] = wildcard - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class IntervalsWildcard(AttrDict[Any]): - """ - :arg pattern: (required) Wildcard pattern used to find matching terms. - :arg analyzer: Analyzer used to analyze the `pattern`. Defaults to the - top-level field's analyzer. - :arg use_field: If specified, match intervals from this field rather - than the top-level field. The `pattern` is normalized using the - search analyzer from this field, unless `analyzer` is specified - separately. - """ - - pattern: Union[str, DefaultType] - analyzer: Union[str, DefaultType] - use_field: Union[str, InstrumentedField, DefaultType] - - def __init__( - self, - *, - pattern: Union[str, DefaultType] = DEFAULT, - analyzer: Union[str, DefaultType] = DEFAULT, - use_field: Union[str, InstrumentedField, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if pattern is not DEFAULT: - kwargs["pattern"] = pattern - if analyzer is not DEFAULT: - kwargs["analyzer"] = analyzer - if use_field is not DEFAULT: - kwargs["use_field"] = str(use_field) - super().__init__(kwargs) - - -class IpRangeAggregationRange(AttrDict[Any]): - """ - :arg from: Start of the range. - :arg mask: IP range defined as a CIDR mask. - :arg to: End of the range. - """ - - from_: Union[str, None, DefaultType] - mask: Union[str, DefaultType] - to: Union[str, None, DefaultType] - - def __init__( - self, - *, - from_: Union[str, None, DefaultType] = DEFAULT, - mask: Union[str, DefaultType] = DEFAULT, - to: Union[str, None, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if from_ is not DEFAULT: - kwargs["from_"] = from_ - if mask is not DEFAULT: - kwargs["mask"] = mask - if to is not DEFAULT: - kwargs["to"] = to - super().__init__(kwargs) - - -class LatLonGeoLocation(AttrDict[Any]): - """ - :arg lat: (required) Latitude - :arg lon: (required) Longitude - """ - - lat: Union[float, DefaultType] - lon: Union[float, DefaultType] - - def __init__( - self, - *, - lat: Union[float, DefaultType] = DEFAULT, - lon: Union[float, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if lat is not DEFAULT: - kwargs["lat"] = lat - if lon is not DEFAULT: - kwargs["lon"] = lon - super().__init__(kwargs) - - -class LikeDocument(AttrDict[Any]): - """ - :arg doc: A document not present in the index. - :arg fields: - :arg _id: ID of a document. - :arg _index: Index of a document. - :arg per_field_analyzer: Overrides the default analyzer. - :arg routing: - :arg version: - :arg version_type: Defaults to `'internal'` if omitted. - """ - - doc: Any - fields: Union[Sequence[Union[str, InstrumentedField]], DefaultType] - _id: Union[str, DefaultType] - _index: Union[str, DefaultType] - per_field_analyzer: Union[Mapping[Union[str, InstrumentedField], str], DefaultType] - routing: Union[str, DefaultType] - version: Union[int, DefaultType] - version_type: Union[ - Literal["internal", "external", "external_gte", "force"], DefaultType - ] - - def __init__( - self, - *, - doc: Any = DEFAULT, - fields: Union[Sequence[Union[str, InstrumentedField]], DefaultType] = DEFAULT, - _id: Union[str, DefaultType] = DEFAULT, - _index: Union[str, DefaultType] = DEFAULT, - per_field_analyzer: Union[ - Mapping[Union[str, InstrumentedField], str], DefaultType - ] = DEFAULT, - routing: Union[str, DefaultType] = DEFAULT, - version: Union[int, DefaultType] = DEFAULT, - version_type: Union[ - Literal["internal", "external", "external_gte", "force"], DefaultType - ] = DEFAULT, - **kwargs: Any, - ): - if doc is not DEFAULT: - kwargs["doc"] = doc - if fields is not DEFAULT: - kwargs["fields"] = str(fields) - if _id is not DEFAULT: - kwargs["_id"] = _id - if _index is not DEFAULT: - kwargs["_index"] = _index - if per_field_analyzer is not DEFAULT: - kwargs["per_field_analyzer"] = str(per_field_analyzer) - if routing is not DEFAULT: - kwargs["routing"] = routing - if version is not DEFAULT: - kwargs["version"] = version - if version_type is not DEFAULT: - kwargs["version_type"] = version_type - super().__init__(kwargs) - - -class MatchBoolPrefixQuery(AttrDict[Any]): - """ - :arg query: (required) Terms you wish to find in the provided field. - The last term is used in a prefix query. - :arg analyzer: Analyzer used to convert the text in the query value - into tokens. - :arg fuzziness: Maximum edit distance allowed for matching. Can be - applied to the term subqueries constructed for all terms but the - final term. - :arg fuzzy_rewrite: Method used to rewrite the query. Can be applied - to the term subqueries constructed for all terms but the final - term. - :arg fuzzy_transpositions: If `true`, edits for fuzzy matching include - transpositions of two adjacent characters (for example, `ab` to - `ba`). Can be applied to the term subqueries constructed for all - terms but the final term. Defaults to `True` if omitted. - :arg max_expansions: Maximum number of terms to which the query will - expand. Can be applied to the term subqueries constructed for all - terms but the final term. Defaults to `50` if omitted. - :arg minimum_should_match: Minimum number of clauses that must match - for a document to be returned. Applied to the constructed bool - query. - :arg operator: Boolean logic used to interpret text in the query - value. Applied to the constructed bool query. Defaults to `'or'` - if omitted. - :arg prefix_length: Number of beginning characters left unchanged for - fuzzy matching. Can be applied to the term subqueries constructed - for all terms but the final term. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - query: Union[str, DefaultType] - analyzer: Union[str, DefaultType] - fuzziness: Union[str, int, DefaultType] - fuzzy_rewrite: Union[str, DefaultType] - fuzzy_transpositions: Union[bool, DefaultType] - max_expansions: Union[int, DefaultType] - minimum_should_match: Union[int, str, DefaultType] - operator: Union[Literal["and", "or"], DefaultType] - prefix_length: Union[int, DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - query: Union[str, DefaultType] = DEFAULT, - analyzer: Union[str, DefaultType] = DEFAULT, - fuzziness: Union[str, int, DefaultType] = DEFAULT, - fuzzy_rewrite: Union[str, DefaultType] = DEFAULT, - fuzzy_transpositions: Union[bool, DefaultType] = DEFAULT, - max_expansions: Union[int, DefaultType] = DEFAULT, - minimum_should_match: Union[int, str, DefaultType] = DEFAULT, - operator: Union[Literal["and", "or"], DefaultType] = DEFAULT, - prefix_length: Union[int, DefaultType] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if query is not DEFAULT: - kwargs["query"] = query - if analyzer is not DEFAULT: - kwargs["analyzer"] = analyzer - if fuzziness is not DEFAULT: - kwargs["fuzziness"] = fuzziness - if fuzzy_rewrite is not DEFAULT: - kwargs["fuzzy_rewrite"] = fuzzy_rewrite - if fuzzy_transpositions is not DEFAULT: - kwargs["fuzzy_transpositions"] = fuzzy_transpositions - if max_expansions is not DEFAULT: - kwargs["max_expansions"] = max_expansions - if minimum_should_match is not DEFAULT: - kwargs["minimum_should_match"] = minimum_should_match - if operator is not DEFAULT: - kwargs["operator"] = operator - if prefix_length is not DEFAULT: - kwargs["prefix_length"] = prefix_length - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class MatchPhrasePrefixQuery(AttrDict[Any]): - """ - :arg query: (required) Text you wish to find in the provided field. - :arg analyzer: Analyzer used to convert text in the query value into - tokens. - :arg max_expansions: Maximum number of terms to which the last - provided term of the query value will expand. Defaults to `50` if - omitted. - :arg slop: Maximum number of positions allowed between matching - tokens. - :arg zero_terms_query: Indicates whether no documents are returned if - the analyzer removes all tokens, such as when using a `stop` - filter. Defaults to `none` if omitted. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - query: Union[str, DefaultType] - analyzer: Union[str, DefaultType] - max_expansions: Union[int, DefaultType] - slop: Union[int, DefaultType] - zero_terms_query: Union[Literal["all", "none"], DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - query: Union[str, DefaultType] = DEFAULT, - analyzer: Union[str, DefaultType] = DEFAULT, - max_expansions: Union[int, DefaultType] = DEFAULT, - slop: Union[int, DefaultType] = DEFAULT, - zero_terms_query: Union[Literal["all", "none"], DefaultType] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if query is not DEFAULT: - kwargs["query"] = query - if analyzer is not DEFAULT: - kwargs["analyzer"] = analyzer - if max_expansions is not DEFAULT: - kwargs["max_expansions"] = max_expansions - if slop is not DEFAULT: - kwargs["slop"] = slop - if zero_terms_query is not DEFAULT: - kwargs["zero_terms_query"] = zero_terms_query - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class MatchPhraseQuery(AttrDict[Any]): - """ - :arg query: (required) Query terms that are analyzed and turned into a - phrase query. - :arg analyzer: Analyzer used to convert the text in the query value - into tokens. - :arg slop: Maximum number of positions allowed between matching - tokens. - :arg zero_terms_query: Indicates whether no documents are returned if - the `analyzer` removes all tokens, such as when using a `stop` - filter. Defaults to `'none'` if omitted. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - query: Union[str, DefaultType] - analyzer: Union[str, DefaultType] - slop: Union[int, DefaultType] - zero_terms_query: Union[Literal["all", "none"], DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - query: Union[str, DefaultType] = DEFAULT, - analyzer: Union[str, DefaultType] = DEFAULT, - slop: Union[int, DefaultType] = DEFAULT, - zero_terms_query: Union[Literal["all", "none"], DefaultType] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if query is not DEFAULT: - kwargs["query"] = query - if analyzer is not DEFAULT: - kwargs["analyzer"] = analyzer - if slop is not DEFAULT: - kwargs["slop"] = slop - if zero_terms_query is not DEFAULT: - kwargs["zero_terms_query"] = zero_terms_query - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class MatchQuery(AttrDict[Any]): - """ - :arg query: (required) Text, number, boolean value or date you wish to - find in the provided field. - :arg analyzer: Analyzer used to convert the text in the query value - into tokens. - :arg auto_generate_synonyms_phrase_query: If `true`, match phrase - queries are automatically created for multi-term synonyms. - Defaults to `True` if omitted. - :arg cutoff_frequency: - :arg fuzziness: Maximum edit distance allowed for matching. - :arg fuzzy_rewrite: Method used to rewrite the query. - :arg fuzzy_transpositions: If `true`, edits for fuzzy matching include - transpositions of two adjacent characters (for example, `ab` to - `ba`). Defaults to `True` if omitted. - :arg lenient: If `true`, format-based errors, such as providing a text - query value for a numeric field, are ignored. - :arg max_expansions: Maximum number of terms to which the query will - expand. Defaults to `50` if omitted. - :arg minimum_should_match: Minimum number of clauses that must match - for a document to be returned. - :arg operator: Boolean logic used to interpret text in the query - value. Defaults to `'or'` if omitted. - :arg prefix_length: Number of beginning characters left unchanged for - fuzzy matching. - :arg zero_terms_query: Indicates whether no documents are returned if - the `analyzer` removes all tokens, such as when using a `stop` - filter. Defaults to `'none'` if omitted. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - query: Union[str, float, bool, DefaultType] - analyzer: Union[str, DefaultType] - auto_generate_synonyms_phrase_query: Union[bool, DefaultType] - cutoff_frequency: Union[float, DefaultType] - fuzziness: Union[str, int, DefaultType] - fuzzy_rewrite: Union[str, DefaultType] - fuzzy_transpositions: Union[bool, DefaultType] - lenient: Union[bool, DefaultType] - max_expansions: Union[int, DefaultType] - minimum_should_match: Union[int, str, DefaultType] - operator: Union[Literal["and", "or"], DefaultType] - prefix_length: Union[int, DefaultType] - zero_terms_query: Union[Literal["all", "none"], DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - query: Union[str, float, bool, DefaultType] = DEFAULT, - analyzer: Union[str, DefaultType] = DEFAULT, - auto_generate_synonyms_phrase_query: Union[bool, DefaultType] = DEFAULT, - cutoff_frequency: Union[float, DefaultType] = DEFAULT, - fuzziness: Union[str, int, DefaultType] = DEFAULT, - fuzzy_rewrite: Union[str, DefaultType] = DEFAULT, - fuzzy_transpositions: Union[bool, DefaultType] = DEFAULT, - lenient: Union[bool, DefaultType] = DEFAULT, - max_expansions: Union[int, DefaultType] = DEFAULT, - minimum_should_match: Union[int, str, DefaultType] = DEFAULT, - operator: Union[Literal["and", "or"], DefaultType] = DEFAULT, - prefix_length: Union[int, DefaultType] = DEFAULT, - zero_terms_query: Union[Literal["all", "none"], DefaultType] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if query is not DEFAULT: - kwargs["query"] = query - if analyzer is not DEFAULT: - kwargs["analyzer"] = analyzer - if auto_generate_synonyms_phrase_query is not DEFAULT: - kwargs["auto_generate_synonyms_phrase_query"] = ( - auto_generate_synonyms_phrase_query - ) - if cutoff_frequency is not DEFAULT: - kwargs["cutoff_frequency"] = cutoff_frequency - if fuzziness is not DEFAULT: - kwargs["fuzziness"] = fuzziness - if fuzzy_rewrite is not DEFAULT: - kwargs["fuzzy_rewrite"] = fuzzy_rewrite - if fuzzy_transpositions is not DEFAULT: - kwargs["fuzzy_transpositions"] = fuzzy_transpositions - if lenient is not DEFAULT: - kwargs["lenient"] = lenient - if max_expansions is not DEFAULT: - kwargs["max_expansions"] = max_expansions - if minimum_should_match is not DEFAULT: - kwargs["minimum_should_match"] = minimum_should_match - if operator is not DEFAULT: - kwargs["operator"] = operator - if prefix_length is not DEFAULT: - kwargs["prefix_length"] = prefix_length - if zero_terms_query is not DEFAULT: - kwargs["zero_terms_query"] = zero_terms_query - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class MultiTermLookup(AttrDict[Any]): - """ - :arg field: (required) A fields from which to retrieve terms. - :arg missing: The value to apply to documents that do not have a - value. By default, documents without a value are ignored. - """ - - field: Union[str, InstrumentedField, DefaultType] - missing: Union[str, int, float, bool, DefaultType] - - def __init__( - self, - *, - field: Union[str, InstrumentedField, DefaultType] = DEFAULT, - missing: Union[str, int, float, bool, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if field is not DEFAULT: - kwargs["field"] = str(field) - if missing is not DEFAULT: - kwargs["missing"] = missing - super().__init__(kwargs) - - -class MutualInformationHeuristic(AttrDict[Any]): - """ - :arg background_is_superset: Set to `false` if you defined a custom - background filter that represents a different set of documents - that you want to compare to. - :arg include_negatives: Set to `false` to filter out the terms that - appear less often in the subset than in documents outside the - subset. - """ - - background_is_superset: Union[bool, DefaultType] - include_negatives: Union[bool, DefaultType] - - def __init__( - self, - *, - background_is_superset: Union[bool, DefaultType] = DEFAULT, - include_negatives: Union[bool, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if background_is_superset is not DEFAULT: - kwargs["background_is_superset"] = background_is_superset - if include_negatives is not DEFAULT: - kwargs["include_negatives"] = include_negatives - super().__init__(kwargs) - - -class NestedSortValue(AttrDict[Any]): - """ - :arg path: (required) - :arg filter: - :arg max_children: - :arg nested: - """ - - path: Union[str, InstrumentedField, DefaultType] - filter: Union[Query, DefaultType] - max_children: Union[int, DefaultType] - nested: Union["NestedSortValue", Dict[str, Any], DefaultType] - - def __init__( - self, - *, - path: Union[str, InstrumentedField, DefaultType] = DEFAULT, - filter: Union[Query, DefaultType] = DEFAULT, - max_children: Union[int, DefaultType] = DEFAULT, - nested: Union["NestedSortValue", Dict[str, Any], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if path is not DEFAULT: - kwargs["path"] = str(path) - if filter is not DEFAULT: - kwargs["filter"] = filter - if max_children is not DEFAULT: - kwargs["max_children"] = max_children - if nested is not DEFAULT: - kwargs["nested"] = nested - super().__init__(kwargs) - - -class PercentageScoreHeuristic(AttrDict[Any]): - pass - - -class PinnedDoc(AttrDict[Any]): - """ - :arg _id: (required) The unique document ID. - :arg _index: (required) The index that contains the document. - """ - - _id: Union[str, DefaultType] - _index: Union[str, DefaultType] - - def __init__( - self, - *, - _id: Union[str, DefaultType] = DEFAULT, - _index: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if _id is not DEFAULT: - kwargs["_id"] = _id - if _index is not DEFAULT: - kwargs["_index"] = _index - super().__init__(kwargs) - - -class PrefixQuery(AttrDict[Any]): - """ - :arg value: (required) Beginning characters of terms you wish to find - in the provided field. - :arg rewrite: Method used to rewrite the query. - :arg case_insensitive: Allows ASCII case insensitive matching of the - value with the indexed field values when set to `true`. Default is - `false` which means the case sensitivity of matching depends on - the underlying field’s mapping. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - value: Union[str, DefaultType] - rewrite: Union[str, DefaultType] - case_insensitive: Union[bool, DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - value: Union[str, DefaultType] = DEFAULT, - rewrite: Union[str, DefaultType] = DEFAULT, - case_insensitive: Union[bool, DefaultType] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if value is not DEFAULT: - kwargs["value"] = value - if rewrite is not DEFAULT: - kwargs["rewrite"] = rewrite - if case_insensitive is not DEFAULT: - kwargs["case_insensitive"] = case_insensitive - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class QueryVectorBuilder(AttrDict[Any]): - """ - :arg text_embedding: - """ - - text_embedding: Union["TextEmbedding", Dict[str, Any], DefaultType] - - def __init__( - self, - *, - text_embedding: Union["TextEmbedding", Dict[str, Any], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if text_embedding is not DEFAULT: - kwargs["text_embedding"] = text_embedding - super().__init__(kwargs) - - -class RankFeatureFunctionLinear(AttrDict[Any]): - pass - - -class RankFeatureFunctionLogarithm(AttrDict[Any]): - """ - :arg scaling_factor: (required) Configurable scaling factor. - """ - - scaling_factor: Union[float, DefaultType] - - def __init__( - self, *, scaling_factor: Union[float, DefaultType] = DEFAULT, **kwargs: Any - ): - if scaling_factor is not DEFAULT: - kwargs["scaling_factor"] = scaling_factor - super().__init__(kwargs) - - -class RankFeatureFunctionSaturation(AttrDict[Any]): - """ - :arg pivot: Configurable pivot value so that the result will be less - than 0.5. - """ - - pivot: Union[float, DefaultType] - - def __init__(self, *, pivot: Union[float, DefaultType] = DEFAULT, **kwargs: Any): - if pivot is not DEFAULT: - kwargs["pivot"] = pivot - super().__init__(kwargs) - - -class RankFeatureFunctionSigmoid(AttrDict[Any]): - """ - :arg pivot: (required) Configurable pivot value so that the result - will be less than 0.5. - :arg exponent: (required) Configurable Exponent. - """ - - pivot: Union[float, DefaultType] - exponent: Union[float, DefaultType] - - def __init__( - self, - *, - pivot: Union[float, DefaultType] = DEFAULT, - exponent: Union[float, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if pivot is not DEFAULT: - kwargs["pivot"] = pivot - if exponent is not DEFAULT: - kwargs["exponent"] = exponent - super().__init__(kwargs) - - -class RegexpQuery(AttrDict[Any]): - """ - :arg value: (required) Regular expression for terms you wish to find - in the provided field. - :arg case_insensitive: Allows case insensitive matching of the regular - expression value with the indexed field values when set to `true`. - When `false`, case sensitivity of matching depends on the - underlying field’s mapping. - :arg flags: Enables optional operators for the regular expression. - :arg max_determinized_states: Maximum number of automaton states - required for the query. Defaults to `10000` if omitted. - :arg rewrite: Method used to rewrite the query. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - value: Union[str, DefaultType] - case_insensitive: Union[bool, DefaultType] - flags: Union[str, DefaultType] - max_determinized_states: Union[int, DefaultType] - rewrite: Union[str, DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - value: Union[str, DefaultType] = DEFAULT, - case_insensitive: Union[bool, DefaultType] = DEFAULT, - flags: Union[str, DefaultType] = DEFAULT, - max_determinized_states: Union[int, DefaultType] = DEFAULT, - rewrite: Union[str, DefaultType] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if value is not DEFAULT: - kwargs["value"] = value - if case_insensitive is not DEFAULT: - kwargs["case_insensitive"] = case_insensitive - if flags is not DEFAULT: - kwargs["flags"] = flags - if max_determinized_states is not DEFAULT: - kwargs["max_determinized_states"] = max_determinized_states - if rewrite is not DEFAULT: - kwargs["rewrite"] = rewrite - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class RegressionInferenceOptions(AttrDict[Any]): - """ - :arg results_field: The field that is added to incoming documents to - contain the inference prediction. Defaults to predicted_value. - :arg num_top_feature_importance_values: Specifies the maximum number - of feature importance values per document. - """ - - results_field: Union[str, InstrumentedField, DefaultType] - num_top_feature_importance_values: Union[int, DefaultType] - - def __init__( - self, - *, - results_field: Union[str, InstrumentedField, DefaultType] = DEFAULT, - num_top_feature_importance_values: Union[int, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if results_field is not DEFAULT: - kwargs["results_field"] = str(results_field) - if num_top_feature_importance_values is not DEFAULT: - kwargs["num_top_feature_importance_values"] = ( - num_top_feature_importance_values - ) - super().__init__(kwargs) - - -class ScoreSort(AttrDict[Any]): - """ - :arg order: - """ - - order: Union[Literal["asc", "desc"], DefaultType] - - def __init__( - self, - *, - order: Union[Literal["asc", "desc"], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if order is not DEFAULT: - kwargs["order"] = order - super().__init__(kwargs) - - -class Script(AttrDict[Any]): - """ - :arg source: The script source. - :arg id: The `id` for a stored script. - :arg params: Specifies any named parameters that are passed into the - script as variables. Use parameters instead of hard-coded values - to decrease compile time. - :arg lang: Specifies the language the script is written in. Defaults - to `painless` if omitted. - :arg options: - """ - - source: Union[str, DefaultType] - id: Union[str, DefaultType] - params: Union[Mapping[str, Any], DefaultType] - lang: Union[Literal["painless", "expression", "mustache", "java"], DefaultType] - options: Union[Mapping[str, str], DefaultType] - - def __init__( - self, - *, - source: Union[str, DefaultType] = DEFAULT, - id: Union[str, DefaultType] = DEFAULT, - params: Union[Mapping[str, Any], DefaultType] = DEFAULT, - lang: Union[ - Literal["painless", "expression", "mustache", "java"], DefaultType - ] = DEFAULT, - options: Union[Mapping[str, str], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if source is not DEFAULT: - kwargs["source"] = source - if id is not DEFAULT: - kwargs["id"] = id - if params is not DEFAULT: - kwargs["params"] = params - if lang is not DEFAULT: - kwargs["lang"] = lang - if options is not DEFAULT: - kwargs["options"] = options - super().__init__(kwargs) - - -class ScriptField(AttrDict[Any]): - """ - :arg script: (required) - :arg ignore_failure: - """ - - script: Union["Script", Dict[str, Any], DefaultType] - ignore_failure: Union[bool, DefaultType] - - def __init__( - self, - *, - script: Union["Script", Dict[str, Any], DefaultType] = DEFAULT, - ignore_failure: Union[bool, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if script is not DEFAULT: - kwargs["script"] = script - if ignore_failure is not DEFAULT: - kwargs["ignore_failure"] = ignore_failure - super().__init__(kwargs) - - -class ScriptSort(AttrDict[Any]): - """ - :arg script: (required) - :arg order: - :arg type: - :arg mode: - :arg nested: - """ - - script: Union["Script", Dict[str, Any], DefaultType] - order: Union[Literal["asc", "desc"], DefaultType] - type: Union[Literal["string", "number", "version"], DefaultType] - mode: Union[Literal["min", "max", "sum", "avg", "median"], DefaultType] - nested: Union["NestedSortValue", Dict[str, Any], DefaultType] - - def __init__( - self, - *, - script: Union["Script", Dict[str, Any], DefaultType] = DEFAULT, - order: Union[Literal["asc", "desc"], DefaultType] = DEFAULT, - type: Union[Literal["string", "number", "version"], DefaultType] = DEFAULT, - mode: Union[ - Literal["min", "max", "sum", "avg", "median"], DefaultType - ] = DEFAULT, - nested: Union["NestedSortValue", Dict[str, Any], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if script is not DEFAULT: - kwargs["script"] = script - if order is not DEFAULT: - kwargs["order"] = order - if type is not DEFAULT: - kwargs["type"] = type - if mode is not DEFAULT: - kwargs["mode"] = mode - if nested is not DEFAULT: - kwargs["nested"] = nested - super().__init__(kwargs) - - -class ScriptedHeuristic(AttrDict[Any]): - """ - :arg script: (required) - """ - - script: Union["Script", Dict[str, Any], DefaultType] - - def __init__( - self, - *, - script: Union["Script", Dict[str, Any], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if script is not DEFAULT: - kwargs["script"] = script - super().__init__(kwargs) - - -class ShapeFieldQuery(AttrDict[Any]): - """ - :arg indexed_shape: Queries using a pre-indexed shape. - :arg relation: Spatial relation between the query shape and the - document shape. - :arg shape: Queries using an inline shape definition in GeoJSON or - Well Known Text (WKT) format. - """ - - indexed_shape: Union["FieldLookup", Dict[str, Any], DefaultType] - relation: Union[ - Literal["intersects", "disjoint", "within", "contains"], DefaultType - ] - shape: Any - - def __init__( - self, - *, - indexed_shape: Union["FieldLookup", Dict[str, Any], DefaultType] = DEFAULT, - relation: Union[ - Literal["intersects", "disjoint", "within", "contains"], DefaultType - ] = DEFAULT, - shape: Any = DEFAULT, - **kwargs: Any, - ): - if indexed_shape is not DEFAULT: - kwargs["indexed_shape"] = indexed_shape - if relation is not DEFAULT: - kwargs["relation"] = relation - if shape is not DEFAULT: - kwargs["shape"] = shape - super().__init__(kwargs) - - -class SortOptions(AttrDict[Any]): - """ - :arg _field: The field to use in this query. - :arg _value: The query value for the field. - :arg _score: - :arg _doc: - :arg _geo_distance: - :arg _script: - """ - - _field: Union[str, "InstrumentedField", "DefaultType"] - _value: Union["FieldSort", Dict[str, Any], "DefaultType"] - _score: Union["ScoreSort", Dict[str, Any], DefaultType] - _doc: Union["ScoreSort", Dict[str, Any], DefaultType] - _geo_distance: Union["GeoDistanceSort", Dict[str, Any], DefaultType] - _script: Union["ScriptSort", Dict[str, Any], DefaultType] - - def __init__( - self, - _field: Union[str, "InstrumentedField", "DefaultType"] = DEFAULT, - _value: Union["FieldSort", Dict[str, Any], "DefaultType"] = DEFAULT, - *, - _score: Union["ScoreSort", Dict[str, Any], DefaultType] = DEFAULT, - _doc: Union["ScoreSort", Dict[str, Any], DefaultType] = DEFAULT, - _geo_distance: Union["GeoDistanceSort", Dict[str, Any], DefaultType] = DEFAULT, - _script: Union["ScriptSort", Dict[str, Any], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if _field is not DEFAULT: - kwargs[str(_field)] = _value - if _score is not DEFAULT: - kwargs["_score"] = _score - if _doc is not DEFAULT: - kwargs["_doc"] = _doc - if _geo_distance is not DEFAULT: - kwargs["_geo_distance"] = _geo_distance - if _script is not DEFAULT: - kwargs["_script"] = _script - super().__init__(kwargs) - - -class SourceFilter(AttrDict[Any]): - """ - :arg excludes: - :arg includes: - """ - - excludes: Union[ - Union[str, InstrumentedField], - Sequence[Union[str, InstrumentedField]], - DefaultType, - ] - includes: Union[ - Union[str, InstrumentedField], - Sequence[Union[str, InstrumentedField]], - DefaultType, - ] - - def __init__( - self, - *, - excludes: Union[ - Union[str, InstrumentedField], - Sequence[Union[str, InstrumentedField]], - DefaultType, - ] = DEFAULT, - includes: Union[ - Union[str, InstrumentedField], - Sequence[Union[str, InstrumentedField]], - DefaultType, - ] = DEFAULT, - **kwargs: Any, - ): - if excludes is not DEFAULT: - kwargs["excludes"] = str(excludes) - if includes is not DEFAULT: - kwargs["includes"] = str(includes) - super().__init__(kwargs) - - -class SpanContainingQuery(AttrDict[Any]): - """ - :arg big: (required) Can be any span query. Matching spans from `big` - that contain matches from `little` are returned. - :arg little: (required) Can be any span query. Matching spans from - `big` that contain matches from `little` are returned. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - big: Union["SpanQuery", Dict[str, Any], DefaultType] - little: Union["SpanQuery", Dict[str, Any], DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - big: Union["SpanQuery", Dict[str, Any], DefaultType] = DEFAULT, - little: Union["SpanQuery", Dict[str, Any], DefaultType] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if big is not DEFAULT: - kwargs["big"] = big - if little is not DEFAULT: - kwargs["little"] = little - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class SpanFieldMaskingQuery(AttrDict[Any]): - """ - :arg field: (required) - :arg query: (required) - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - field: Union[str, InstrumentedField, DefaultType] - query: Union["SpanQuery", Dict[str, Any], DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - field: Union[str, InstrumentedField, DefaultType] = DEFAULT, - query: Union["SpanQuery", Dict[str, Any], DefaultType] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if field is not DEFAULT: - kwargs["field"] = str(field) - if query is not DEFAULT: - kwargs["query"] = query - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class SpanFirstQuery(AttrDict[Any]): - """ - :arg end: (required) Controls the maximum end position permitted in a - match. - :arg match: (required) Can be any other span type query. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - end: Union[int, DefaultType] - match: Union["SpanQuery", Dict[str, Any], DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - end: Union[int, DefaultType] = DEFAULT, - match: Union["SpanQuery", Dict[str, Any], DefaultType] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if end is not DEFAULT: - kwargs["end"] = end - if match is not DEFAULT: - kwargs["match"] = match - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class SpanMultiTermQuery(AttrDict[Any]): - """ - :arg match: (required) Should be a multi term query (one of - `wildcard`, `fuzzy`, `prefix`, `range`, or `regexp` query). - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - match: Union[Query, DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - match: Union[Query, DefaultType] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if match is not DEFAULT: - kwargs["match"] = match - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class SpanNearQuery(AttrDict[Any]): - """ - :arg clauses: (required) Array of one or more other span type queries. - :arg in_order: Controls whether matches are required to be in-order. - :arg slop: Controls the maximum number of intervening unmatched - positions permitted. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - clauses: Union[Sequence["SpanQuery"], Sequence[Dict[str, Any]], DefaultType] - in_order: Union[bool, DefaultType] - slop: Union[int, DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - clauses: Union[ - Sequence["SpanQuery"], Sequence[Dict[str, Any]], DefaultType - ] = DEFAULT, - in_order: Union[bool, DefaultType] = DEFAULT, - slop: Union[int, DefaultType] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if clauses is not DEFAULT: - kwargs["clauses"] = clauses - if in_order is not DEFAULT: - kwargs["in_order"] = in_order - if slop is not DEFAULT: - kwargs["slop"] = slop - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class SpanNotQuery(AttrDict[Any]): - """ - :arg exclude: (required) Span query whose matches must not overlap - those returned. - :arg include: (required) Span query whose matches are filtered. - :arg dist: The number of tokens from within the include span that - can’t have overlap with the exclude span. Equivalent to setting - both `pre` and `post`. - :arg post: The number of tokens after the include span that can’t have - overlap with the exclude span. - :arg pre: The number of tokens before the include span that can’t have - overlap with the exclude span. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - exclude: Union["SpanQuery", Dict[str, Any], DefaultType] - include: Union["SpanQuery", Dict[str, Any], DefaultType] - dist: Union[int, DefaultType] - post: Union[int, DefaultType] - pre: Union[int, DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - exclude: Union["SpanQuery", Dict[str, Any], DefaultType] = DEFAULT, - include: Union["SpanQuery", Dict[str, Any], DefaultType] = DEFAULT, - dist: Union[int, DefaultType] = DEFAULT, - post: Union[int, DefaultType] = DEFAULT, - pre: Union[int, DefaultType] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if exclude is not DEFAULT: - kwargs["exclude"] = exclude - if include is not DEFAULT: - kwargs["include"] = include - if dist is not DEFAULT: - kwargs["dist"] = dist - if post is not DEFAULT: - kwargs["post"] = post - if pre is not DEFAULT: - kwargs["pre"] = pre - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class SpanOrQuery(AttrDict[Any]): - """ - :arg clauses: (required) Array of one or more other span type queries. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - clauses: Union[Sequence["SpanQuery"], Sequence[Dict[str, Any]], DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - clauses: Union[ - Sequence["SpanQuery"], Sequence[Dict[str, Any]], DefaultType - ] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if clauses is not DEFAULT: - kwargs["clauses"] = clauses - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class SpanQuery(AttrDict[Any]): - """ - :arg span_containing: Accepts a list of span queries, but only returns - those spans which also match a second span query. - :arg span_field_masking: Allows queries like `span_near` or `span_or` - across different fields. - :arg span_first: Accepts another span query whose matches must appear - within the first N positions of the field. - :arg span_gap: - :arg span_multi: Wraps a `term`, `range`, `prefix`, `wildcard`, - `regexp`, or `fuzzy` query. - :arg span_near: Accepts multiple span queries whose matches must be - within the specified distance of each other, and possibly in the - same order. - :arg span_not: Wraps another span query, and excludes any documents - which match that query. - :arg span_or: Combines multiple span queries and returns documents - which match any of the specified queries. - :arg span_term: The equivalent of the `term` query but for use with - other span queries. - :arg span_within: The result from a single span query is returned as - long is its span falls within the spans returned by a list of - other span queries. - """ - - span_containing: Union["SpanContainingQuery", Dict[str, Any], DefaultType] - span_field_masking: Union["SpanFieldMaskingQuery", Dict[str, Any], DefaultType] - span_first: Union["SpanFirstQuery", Dict[str, Any], DefaultType] - span_gap: Union[Mapping[Union[str, InstrumentedField], int], DefaultType] - span_multi: Union["SpanMultiTermQuery", Dict[str, Any], DefaultType] - span_near: Union["SpanNearQuery", Dict[str, Any], DefaultType] - span_not: Union["SpanNotQuery", Dict[str, Any], DefaultType] - span_or: Union["SpanOrQuery", Dict[str, Any], DefaultType] - span_term: Union[ - Mapping[Union[str, InstrumentedField], "SpanTermQuery"], - Dict[str, Any], - DefaultType, - ] - span_within: Union["SpanWithinQuery", Dict[str, Any], DefaultType] - - def __init__( - self, - *, - span_containing: Union[ - "SpanContainingQuery", Dict[str, Any], DefaultType - ] = DEFAULT, - span_field_masking: Union[ - "SpanFieldMaskingQuery", Dict[str, Any], DefaultType - ] = DEFAULT, - span_first: Union["SpanFirstQuery", Dict[str, Any], DefaultType] = DEFAULT, - span_gap: Union[ - Mapping[Union[str, InstrumentedField], int], DefaultType - ] = DEFAULT, - span_multi: Union["SpanMultiTermQuery", Dict[str, Any], DefaultType] = DEFAULT, - span_near: Union["SpanNearQuery", Dict[str, Any], DefaultType] = DEFAULT, - span_not: Union["SpanNotQuery", Dict[str, Any], DefaultType] = DEFAULT, - span_or: Union["SpanOrQuery", Dict[str, Any], DefaultType] = DEFAULT, - span_term: Union[ - Mapping[Union[str, InstrumentedField], "SpanTermQuery"], - Dict[str, Any], - DefaultType, - ] = DEFAULT, - span_within: Union["SpanWithinQuery", Dict[str, Any], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if span_containing is not DEFAULT: - kwargs["span_containing"] = span_containing - if span_field_masking is not DEFAULT: - kwargs["span_field_masking"] = span_field_masking - if span_first is not DEFAULT: - kwargs["span_first"] = span_first - if span_gap is not DEFAULT: - kwargs["span_gap"] = str(span_gap) - if span_multi is not DEFAULT: - kwargs["span_multi"] = span_multi - if span_near is not DEFAULT: - kwargs["span_near"] = span_near - if span_not is not DEFAULT: - kwargs["span_not"] = span_not - if span_or is not DEFAULT: - kwargs["span_or"] = span_or - if span_term is not DEFAULT: - kwargs["span_term"] = str(span_term) - if span_within is not DEFAULT: - kwargs["span_within"] = span_within - super().__init__(kwargs) - - -class SpanTermQuery(AttrDict[Any]): - """ - :arg value: (required) - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - value: Union[str, DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - value: Union[str, DefaultType] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if value is not DEFAULT: - kwargs["value"] = value - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class SpanWithinQuery(AttrDict[Any]): - """ - :arg big: (required) Can be any span query. Matching spans from - `little` that are enclosed within `big` are returned. - :arg little: (required) Can be any span query. Matching spans from - `little` that are enclosed within `big` are returned. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - big: Union["SpanQuery", Dict[str, Any], DefaultType] - little: Union["SpanQuery", Dict[str, Any], DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - big: Union["SpanQuery", Dict[str, Any], DefaultType] = DEFAULT, - little: Union["SpanQuery", Dict[str, Any], DefaultType] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if big is not DEFAULT: - kwargs["big"] = big - if little is not DEFAULT: - kwargs["little"] = little - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class TDigest(AttrDict[Any]): - """ - :arg compression: Limits the maximum number of nodes used by the - underlying TDigest algorithm to `20 * compression`, enabling - control of memory usage and approximation error. - """ - - compression: Union[int, DefaultType] - - def __init__( - self, *, compression: Union[int, DefaultType] = DEFAULT, **kwargs: Any - ): - if compression is not DEFAULT: - kwargs["compression"] = compression - super().__init__(kwargs) - - -class TermQuery(AttrDict[Any]): - """ - :arg value: (required) Term you wish to find in the provided field. - :arg case_insensitive: Allows ASCII case insensitive matching of the - value with the indexed field values when set to `true`. When - `false`, the case sensitivity of matching depends on the - underlying field’s mapping. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - value: Union[int, float, str, bool, None, Any, DefaultType] - case_insensitive: Union[bool, DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - value: Union[int, float, str, bool, None, Any, DefaultType] = DEFAULT, - case_insensitive: Union[bool, DefaultType] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if value is not DEFAULT: - kwargs["value"] = value - if case_insensitive is not DEFAULT: - kwargs["case_insensitive"] = case_insensitive - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class TermsLookup(AttrDict[Any]): - """ - :arg index: (required) - :arg id: (required) - :arg path: (required) - :arg routing: - """ - - index: Union[str, DefaultType] - id: Union[str, DefaultType] - path: Union[str, InstrumentedField, DefaultType] - routing: Union[str, DefaultType] - - def __init__( - self, - *, - index: Union[str, DefaultType] = DEFAULT, - id: Union[str, DefaultType] = DEFAULT, - path: Union[str, InstrumentedField, DefaultType] = DEFAULT, - routing: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if index is not DEFAULT: - kwargs["index"] = index - if id is not DEFAULT: - kwargs["id"] = id - if path is not DEFAULT: - kwargs["path"] = str(path) - if routing is not DEFAULT: - kwargs["routing"] = routing - super().__init__(kwargs) - - -class TermsPartition(AttrDict[Any]): - """ - :arg num_partitions: (required) The number of partitions. - :arg partition: (required) The partition number for this request. - """ - - num_partitions: Union[int, DefaultType] - partition: Union[int, DefaultType] - - def __init__( - self, - *, - num_partitions: Union[int, DefaultType] = DEFAULT, - partition: Union[int, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if num_partitions is not DEFAULT: - kwargs["num_partitions"] = num_partitions - if partition is not DEFAULT: - kwargs["partition"] = partition - super().__init__(kwargs) - - -class TermsSetQuery(AttrDict[Any]): - """ - :arg terms: (required) Array of terms you wish to find in the provided - field. - :arg minimum_should_match: Specification describing number of matching - terms required to return a document. - :arg minimum_should_match_field: Numeric field containing the number - of matching terms required to return a document. - :arg minimum_should_match_script: Custom script containing the number - of matching terms required to return a document. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - terms: Union[Sequence[str], DefaultType] - minimum_should_match: Union[int, str, DefaultType] - minimum_should_match_field: Union[str, InstrumentedField, DefaultType] - minimum_should_match_script: Union["Script", Dict[str, Any], DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - terms: Union[Sequence[str], DefaultType] = DEFAULT, - minimum_should_match: Union[int, str, DefaultType] = DEFAULT, - minimum_should_match_field: Union[ - str, InstrumentedField, DefaultType - ] = DEFAULT, - minimum_should_match_script: Union[ - "Script", Dict[str, Any], DefaultType - ] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if terms is not DEFAULT: - kwargs["terms"] = terms - if minimum_should_match is not DEFAULT: - kwargs["minimum_should_match"] = minimum_should_match - if minimum_should_match_field is not DEFAULT: - kwargs["minimum_should_match_field"] = str(minimum_should_match_field) - if minimum_should_match_script is not DEFAULT: - kwargs["minimum_should_match_script"] = minimum_should_match_script - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class TestPopulation(AttrDict[Any]): - """ - :arg field: (required) The field to aggregate. - :arg script: - :arg filter: A filter used to define a set of records to run unpaired - t-test on. - """ - - field: Union[str, InstrumentedField, DefaultType] - script: Union["Script", Dict[str, Any], DefaultType] - filter: Union[Query, DefaultType] - - def __init__( - self, - *, - field: Union[str, InstrumentedField, DefaultType] = DEFAULT, - script: Union["Script", Dict[str, Any], DefaultType] = DEFAULT, - filter: Union[Query, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if field is not DEFAULT: - kwargs["field"] = str(field) - if script is not DEFAULT: - kwargs["script"] = script - if filter is not DEFAULT: - kwargs["filter"] = filter - super().__init__(kwargs) - - -class TextEmbedding(AttrDict[Any]): - """ - :arg model_id: (required) - :arg model_text: (required) - """ - - model_id: Union[str, DefaultType] - model_text: Union[str, DefaultType] - - def __init__( - self, - *, - model_id: Union[str, DefaultType] = DEFAULT, - model_text: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if model_id is not DEFAULT: - kwargs["model_id"] = model_id - if model_text is not DEFAULT: - kwargs["model_text"] = model_text - super().__init__(kwargs) - - -class TextExpansionQuery(AttrDict[Any]): - """ - :arg model_id: (required) The text expansion NLP model to use - :arg model_text: (required) The query text - :arg pruning_config: Token pruning configurations - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - model_id: Union[str, DefaultType] - model_text: Union[str, DefaultType] - pruning_config: Union["TokenPruningConfig", Dict[str, Any], DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - model_id: Union[str, DefaultType] = DEFAULT, - model_text: Union[str, DefaultType] = DEFAULT, - pruning_config: Union[ - "TokenPruningConfig", Dict[str, Any], DefaultType - ] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if model_id is not DEFAULT: - kwargs["model_id"] = model_id - if model_text is not DEFAULT: - kwargs["model_text"] = model_text - if pruning_config is not DEFAULT: - kwargs["pruning_config"] = pruning_config - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class TokenPruningConfig(AttrDict[Any]): - """ - :arg tokens_freq_ratio_threshold: Tokens whose frequency is more than - this threshold times the average frequency of all tokens in the - specified field are considered outliers and pruned. Defaults to - `5` if omitted. - :arg tokens_weight_threshold: Tokens whose weight is less than this - threshold are considered nonsignificant and pruned. Defaults to - `0.4` if omitted. - :arg only_score_pruned_tokens: Whether to only score pruned tokens, vs - only scoring kept tokens. - """ - - tokens_freq_ratio_threshold: Union[int, DefaultType] - tokens_weight_threshold: Union[float, DefaultType] - only_score_pruned_tokens: Union[bool, DefaultType] - - def __init__( - self, - *, - tokens_freq_ratio_threshold: Union[int, DefaultType] = DEFAULT, - tokens_weight_threshold: Union[float, DefaultType] = DEFAULT, - only_score_pruned_tokens: Union[bool, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if tokens_freq_ratio_threshold is not DEFAULT: - kwargs["tokens_freq_ratio_threshold"] = tokens_freq_ratio_threshold - if tokens_weight_threshold is not DEFAULT: - kwargs["tokens_weight_threshold"] = tokens_weight_threshold - if only_score_pruned_tokens is not DEFAULT: - kwargs["only_score_pruned_tokens"] = only_score_pruned_tokens - super().__init__(kwargs) - - -class TopLeftBottomRightGeoBounds(AttrDict[Any]): - """ - :arg top_left: (required) - :arg bottom_right: (required) - """ - - top_left: Union[ - "LatLonGeoLocation", - "GeoHashLocation", - Sequence[float], - str, - Dict[str, Any], - DefaultType, - ] - bottom_right: Union[ - "LatLonGeoLocation", - "GeoHashLocation", - Sequence[float], - str, - Dict[str, Any], - DefaultType, - ] - - def __init__( - self, - *, - top_left: Union[ - "LatLonGeoLocation", - "GeoHashLocation", - Sequence[float], - str, - Dict[str, Any], - DefaultType, - ] = DEFAULT, - bottom_right: Union[ - "LatLonGeoLocation", - "GeoHashLocation", - Sequence[float], - str, - Dict[str, Any], - DefaultType, - ] = DEFAULT, - **kwargs: Any, - ): - if top_left is not DEFAULT: - kwargs["top_left"] = top_left - if bottom_right is not DEFAULT: - kwargs["bottom_right"] = bottom_right - super().__init__(kwargs) - - -class TopMetricsValue(AttrDict[Any]): - """ - :arg field: (required) A field to return as a metric. - """ - - field: Union[str, InstrumentedField, DefaultType] - - def __init__( - self, - *, - field: Union[str, InstrumentedField, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if field is not DEFAULT: - kwargs["field"] = str(field) - super().__init__(kwargs) - - -class TopRightBottomLeftGeoBounds(AttrDict[Any]): - """ - :arg top_right: (required) - :arg bottom_left: (required) - """ - - top_right: Union[ - "LatLonGeoLocation", - "GeoHashLocation", - Sequence[float], - str, - Dict[str, Any], - DefaultType, - ] - bottom_left: Union[ - "LatLonGeoLocation", - "GeoHashLocation", - Sequence[float], - str, - Dict[str, Any], - DefaultType, - ] - - def __init__( - self, - *, - top_right: Union[ - "LatLonGeoLocation", - "GeoHashLocation", - Sequence[float], - str, - Dict[str, Any], - DefaultType, - ] = DEFAULT, - bottom_left: Union[ - "LatLonGeoLocation", - "GeoHashLocation", - Sequence[float], - str, - Dict[str, Any], - DefaultType, - ] = DEFAULT, - **kwargs: Any, - ): - if top_right is not DEFAULT: - kwargs["top_right"] = top_right - if bottom_left is not DEFAULT: - kwargs["bottom_left"] = bottom_left - super().__init__(kwargs) - - -class WeightedAverageValue(AttrDict[Any]): - """ - :arg field: The field from which to extract the values or weights. - :arg missing: A value or weight to use if the field is missing. - :arg script: - """ - - field: Union[str, InstrumentedField, DefaultType] - missing: Union[float, DefaultType] - script: Union["Script", Dict[str, Any], DefaultType] - - def __init__( - self, - *, - field: Union[str, InstrumentedField, DefaultType] = DEFAULT, - missing: Union[float, DefaultType] = DEFAULT, - script: Union["Script", Dict[str, Any], DefaultType] = DEFAULT, - **kwargs: Any, - ): - if field is not DEFAULT: - kwargs["field"] = str(field) - if missing is not DEFAULT: - kwargs["missing"] = missing - if script is not DEFAULT: - kwargs["script"] = script - super().__init__(kwargs) - - -class WeightedTokensQuery(AttrDict[Any]): - """ - :arg tokens: (required) The tokens representing this query - :arg pruning_config: Token pruning configurations - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - tokens: Union[Mapping[str, float], DefaultType] - pruning_config: Union["TokenPruningConfig", Dict[str, Any], DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - tokens: Union[Mapping[str, float], DefaultType] = DEFAULT, - pruning_config: Union[ - "TokenPruningConfig", Dict[str, Any], DefaultType - ] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if tokens is not DEFAULT: - kwargs["tokens"] = tokens - if pruning_config is not DEFAULT: - kwargs["pruning_config"] = pruning_config - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class WildcardQuery(AttrDict[Any]): - """ - :arg case_insensitive: Allows case insensitive matching of the pattern - with the indexed field values when set to true. Default is false - which means the case sensitivity of matching depends on the - underlying field’s mapping. - :arg rewrite: Method used to rewrite the query. - :arg value: Wildcard pattern for terms you wish to find in the - provided field. Required, when wildcard is not set. - :arg wildcard: Wildcard pattern for terms you wish to find in the - provided field. Required, when value is not set. - :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 - the relevance score. A value greater than 1.0 increases the - relevance score. Defaults to `1` if omitted. - :arg _name: - """ - - case_insensitive: Union[bool, DefaultType] - rewrite: Union[str, DefaultType] - value: Union[str, DefaultType] - wildcard: Union[str, DefaultType] - boost: Union[float, DefaultType] - _name: Union[str, DefaultType] - - def __init__( - self, - *, - case_insensitive: Union[bool, DefaultType] = DEFAULT, - rewrite: Union[str, DefaultType] = DEFAULT, - value: Union[str, DefaultType] = DEFAULT, - wildcard: Union[str, DefaultType] = DEFAULT, - boost: Union[float, DefaultType] = DEFAULT, - _name: Union[str, DefaultType] = DEFAULT, - **kwargs: Any, - ): - if case_insensitive is not DEFAULT: - kwargs["case_insensitive"] = case_insensitive - if rewrite is not DEFAULT: - kwargs["rewrite"] = rewrite - if value is not DEFAULT: - kwargs["value"] = value - if wildcard is not DEFAULT: - kwargs["wildcard"] = wildcard - if boost is not DEFAULT: - kwargs["boost"] = boost - if _name is not DEFAULT: - kwargs["_name"] = _name - super().__init__(kwargs) - - -class WktGeoBounds(AttrDict[Any]): - """ - :arg wkt: (required) - """ - - wkt: Union[str, DefaultType] - - def __init__(self, *, wkt: Union[str, DefaultType] = DEFAULT, **kwargs: Any): - if wkt is not DEFAULT: - kwargs["wkt"] = wkt - super().__init__(kwargs) - - -class AdjacencyMatrixAggregate(AttrDict[Any]): - """ - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - buckets: Sequence["AdjacencyMatrixBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "AdjacencyMatrixBucket"]: - return self.buckets # type: ignore - - -class AdjacencyMatrixBucket(AttrDict[Any]): - """ - :arg key: (required) - :arg doc_count: (required) - """ - - key: str - doc_count: int - - -class AggregationBreakdown(AttrDict[Any]): - """ - :arg build_aggregation: (required) - :arg build_aggregation_count: (required) - :arg build_leaf_collector: (required) - :arg build_leaf_collector_count: (required) - :arg collect: (required) - :arg collect_count: (required) - :arg initialize: (required) - :arg initialize_count: (required) - :arg reduce: (required) - :arg reduce_count: (required) - :arg post_collection: - :arg post_collection_count: - """ - - build_aggregation: int - build_aggregation_count: int - build_leaf_collector: int - build_leaf_collector_count: int - collect: int - collect_count: int - initialize: int - initialize_count: int - reduce: int - reduce_count: int - post_collection: int - post_collection_count: int - - -class AggregationProfile(AttrDict[Any]): - """ - :arg breakdown: (required) - :arg description: (required) - :arg time_in_nanos: (required) - :arg type: (required) - :arg debug: - :arg children: - """ - - breakdown: "AggregationBreakdown" - description: str - time_in_nanos: Any - type: str - debug: "AggregationProfileDebug" - children: Sequence["AggregationProfile"] - - -class AggregationProfileDebug(AttrDict[Any]): - """ - :arg segments_with_multi_valued_ords: - :arg collection_strategy: - :arg segments_with_single_valued_ords: - :arg total_buckets: - :arg built_buckets: - :arg result_strategy: - :arg has_filter: - :arg delegate: - :arg delegate_debug: - :arg chars_fetched: - :arg extract_count: - :arg extract_ns: - :arg values_fetched: - :arg collect_analyzed_ns: - :arg collect_analyzed_count: - :arg surviving_buckets: - :arg ordinals_collectors_used: - :arg ordinals_collectors_overhead_too_high: - :arg string_hashing_collectors_used: - :arg numeric_collectors_used: - :arg empty_collectors_used: - :arg deferred_aggregators: - :arg segments_with_doc_count_field: - :arg segments_with_deleted_docs: - :arg filters: - :arg segments_counted: - :arg segments_collected: - :arg map_reducer: - :arg brute_force_used: - :arg dynamic_pruning_attempted: - :arg dynamic_pruning_used: - :arg skipped_due_to_no_data: - """ - - segments_with_multi_valued_ords: int - collection_strategy: str - segments_with_single_valued_ords: int - total_buckets: int - built_buckets: int - result_strategy: str - has_filter: bool - delegate: str - delegate_debug: "AggregationProfileDebug" - chars_fetched: int - extract_count: int - extract_ns: int - values_fetched: int - collect_analyzed_ns: int - collect_analyzed_count: int - surviving_buckets: int - ordinals_collectors_used: int - ordinals_collectors_overhead_too_high: int - string_hashing_collectors_used: int - numeric_collectors_used: int - empty_collectors_used: int - deferred_aggregators: Sequence[str] - segments_with_doc_count_field: int - segments_with_deleted_docs: int - filters: Sequence["AggregationProfileDelegateDebugFilter"] - segments_counted: int - segments_collected: int - map_reducer: str - brute_force_used: int - dynamic_pruning_attempted: int - dynamic_pruning_used: int - skipped_due_to_no_data: int - - -class AggregationProfileDelegateDebugFilter(AttrDict[Any]): - """ - :arg results_from_metadata: - :arg query: - :arg specialized_for: - :arg segments_counted_in_constant_time: - """ - - results_from_metadata: int - query: str - specialized_for: str - segments_counted_in_constant_time: int - - -class ArrayPercentilesItem(AttrDict[Any]): - """ - :arg key: (required) - :arg value: (required) - :arg value_as_string: - """ - - key: str - value: Union[float, None] - value_as_string: str - - -class AutoDateHistogramAggregate(AttrDict[Any]): - """ - :arg interval: (required) - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - interval: str - buckets: Sequence["DateHistogramBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "DateHistogramBucket"]: - return self.buckets # type: ignore - - -class AvgAggregate(AttrDict[Any]): - """ - :arg value: (required) The metric value. A missing value generally - means that there was no data to aggregate, unless specified - otherwise. - :arg value_as_string: - :arg meta: - """ - - value: Union[float, None] - value_as_string: str - meta: Mapping[str, Any] - - -class BoxPlotAggregate(AttrDict[Any]): - """ - :arg min: (required) - :arg max: (required) - :arg q1: (required) - :arg q2: (required) - :arg q3: (required) - :arg lower: (required) - :arg upper: (required) - :arg min_as_string: - :arg max_as_string: - :arg q1_as_string: - :arg q2_as_string: - :arg q3_as_string: - :arg lower_as_string: - :arg upper_as_string: - :arg meta: - """ - - min: float - max: float - q1: float - q2: float - q3: float - lower: float - upper: float - min_as_string: str - max_as_string: str - q1_as_string: str - q2_as_string: str - q3_as_string: str - lower_as_string: str - upper_as_string: str - meta: Mapping[str, Any] - - -class BucketMetricValueAggregate(AttrDict[Any]): - """ - :arg keys: (required) - :arg value: (required) The metric value. A missing value generally - means that there was no data to aggregate, unless specified - otherwise. - :arg value_as_string: - :arg meta: - """ - - keys: Sequence[str] # type: ignore[assignment] - value: Union[float, None] - value_as_string: str - meta: Mapping[str, Any] - - -class BulkIndexByScrollFailure(AttrDict[Any]): - """ - :arg cause: (required) - :arg id: (required) - :arg index: (required) - :arg status: (required) - :arg type: (required) - """ - - cause: "ErrorCause" - id: str - index: str - status: int - type: str - - -class CardinalityAggregate(AttrDict[Any]): - """ - :arg value: (required) - :arg meta: - """ - - value: int - meta: Mapping[str, Any] - - -class ChildrenAggregate(AttrDict[Any]): - """ - :arg doc_count: (required) - :arg meta: - """ - - doc_count: int - meta: Mapping[str, Any] - - -class ClusterDetails(AttrDict[Any]): - """ - :arg status: (required) - :arg indices: (required) - :arg timed_out: (required) - :arg took: - :arg _shards: - :arg failures: - """ - - status: Literal["running", "successful", "partial", "skipped", "failed"] - indices: str - timed_out: bool - took: Any - _shards: "ShardStatistics" - failures: Sequence["ShardFailure"] - - -class ClusterStatistics(AttrDict[Any]): - """ - :arg skipped: (required) - :arg successful: (required) - :arg total: (required) - :arg running: (required) - :arg partial: (required) - :arg failed: (required) - :arg details: - """ - - skipped: int - successful: int - total: int - running: int - partial: int - failed: int - details: Mapping[str, "ClusterDetails"] - - -class Collector(AttrDict[Any]): - """ - :arg name: (required) - :arg reason: (required) - :arg time_in_nanos: (required) - :arg children: - """ - - name: str - reason: str - time_in_nanos: Any - children: Sequence["Collector"] - - -class CompletionSuggest(AttrDict[Any]): - """ - :arg options: (required) - :arg length: (required) - :arg offset: (required) - :arg text: (required) - """ - - options: Sequence["CompletionSuggestOption"] - length: int - offset: int - text: str - - -class CompletionSuggestOption(AttrDict[Any]): - """ - :arg text: (required) - :arg collate_match: - :arg contexts: - :arg fields: - :arg _id: - :arg _index: - :arg _routing: - :arg _score: - :arg _source: - :arg score: - """ - - text: str - collate_match: bool - contexts: Mapping[ - str, - Sequence[ - Union[ - str, Union["LatLonGeoLocation", "GeoHashLocation", Sequence[float], str] - ] - ], - ] - fields: Mapping[str, Any] - _id: str - _index: str - _routing: str - _score: float - _source: Any - score: float - - -class CompositeAggregate(AttrDict[Any]): - """ - :arg after_key: - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - after_key: Mapping[str, Union[int, float, str, bool, None, Any]] - buckets: Sequence["CompositeBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "CompositeBucket"]: - return self.buckets # type: ignore - - -class CompositeBucket(AttrDict[Any]): - """ - :arg key: (required) - :arg doc_count: (required) - """ - - key: Mapping[str, Union[int, float, str, bool, None, Any]] - doc_count: int - - -class CumulativeCardinalityAggregate(AttrDict[Any]): - """ - Result of the `cumulative_cardinality` aggregation - - :arg value: (required) - :arg value_as_string: - :arg meta: - """ - - value: int - value_as_string: str - meta: Mapping[str, Any] - - -class DateHistogramAggregate(AttrDict[Any]): - """ - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - buckets: Sequence["DateHistogramBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "DateHistogramBucket"]: - return self.buckets # type: ignore - - -class DateHistogramBucket(AttrDict[Any]): - """ - :arg key: (required) - :arg doc_count: (required) - :arg key_as_string: - """ - - key: Any - doc_count: int - key_as_string: str - - -class DateRangeAggregate(AttrDict[Any]): - """ - Result of a `date_range` aggregation. Same format as a for a `range` - aggregation: `from` and `to` in `buckets` are milliseconds since the - Epoch, represented as a floating point number. - - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - buckets: Sequence["RangeBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "RangeBucket"]: - return self.buckets # type: ignore - - -class DerivativeAggregate(AttrDict[Any]): - """ - :arg value: (required) The metric value. A missing value generally - means that there was no data to aggregate, unless specified - otherwise. - :arg normalized_value: - :arg normalized_value_as_string: - :arg value_as_string: - :arg meta: - """ - - value: Union[float, None] - normalized_value: float - normalized_value_as_string: str - value_as_string: str - meta: Mapping[str, Any] - - -class DfsKnnProfile(AttrDict[Any]): - """ - :arg query: (required) - :arg rewrite_time: (required) - :arg collector: (required) - :arg vector_operations_count: - """ - - query: Sequence["KnnQueryProfileResult"] - rewrite_time: int - collector: Sequence["KnnCollectorResult"] - vector_operations_count: int - - -class DfsProfile(AttrDict[Any]): - """ - :arg statistics: - :arg knn: - """ - - statistics: "DfsStatisticsProfile" - knn: Sequence["DfsKnnProfile"] - - -class DfsStatisticsBreakdown(AttrDict[Any]): - """ - :arg collection_statistics: (required) - :arg collection_statistics_count: (required) - :arg create_weight: (required) - :arg create_weight_count: (required) - :arg rewrite: (required) - :arg rewrite_count: (required) - :arg term_statistics: (required) - :arg term_statistics_count: (required) - """ - - collection_statistics: int - collection_statistics_count: int - create_weight: int - create_weight_count: int - rewrite: int - rewrite_count: int - term_statistics: int - term_statistics_count: int - - -class DfsStatisticsProfile(AttrDict[Any]): - """ - :arg type: (required) - :arg description: (required) - :arg time_in_nanos: (required) - :arg breakdown: (required) - :arg time: - :arg debug: - :arg children: - """ - - type: str - description: str - time_in_nanos: Any - breakdown: "DfsStatisticsBreakdown" - time: Any - debug: Mapping[str, Any] - children: Sequence["DfsStatisticsProfile"] - - -class DoubleTermsAggregate(AttrDict[Any]): - """ - Result of a `terms` aggregation when the field is some kind of decimal - number like a float, double, or distance. - - :arg doc_count_error_upper_bound: - :arg sum_other_doc_count: - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - doc_count_error_upper_bound: int - sum_other_doc_count: int - buckets: Sequence["DoubleTermsBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "DoubleTermsBucket"]: - return self.buckets # type: ignore - - -class DoubleTermsBucket(AttrDict[Any]): - """ - :arg key: (required) - :arg doc_count: (required) - :arg key_as_string: - :arg doc_count_error_upper_bound: - """ - - key: float - doc_count: int - key_as_string: str - doc_count_error_upper_bound: int - - -class ErrorCause(AttrDict[Any]): - """ - Cause and details about a request failure. This class defines the - properties common to all error types. Additional details are also - provided, that depend on the error type. - - :arg type: (required) The type of error - :arg reason: A human-readable explanation of the error, in english - :arg stack_trace: The server stack trace. Present only if the - `error_trace=true` parameter was sent with the request. - :arg caused_by: - :arg root_cause: - :arg suppressed: - """ - - type: str - reason: str - stack_trace: str - caused_by: "ErrorCause" - root_cause: Sequence["ErrorCause"] - suppressed: Sequence["ErrorCause"] - - -class Explanation(AttrDict[Any]): - """ - :arg description: (required) - :arg details: (required) - :arg value: (required) - """ - - description: str - details: Sequence["ExplanationDetail"] - value: float - - -class ExplanationDetail(AttrDict[Any]): - """ - :arg description: (required) - :arg value: (required) - :arg details: - """ - - description: str - value: float - details: Sequence["ExplanationDetail"] - - -class ExtendedStatsAggregate(AttrDict[Any]): - """ - :arg sum_of_squares: (required) - :arg variance: (required) - :arg variance_population: (required) - :arg variance_sampling: (required) - :arg std_deviation: (required) - :arg std_deviation_population: (required) - :arg std_deviation_sampling: (required) - :arg count: (required) - :arg min: (required) - :arg max: (required) - :arg avg: (required) - :arg sum: (required) - :arg std_deviation_bounds: - :arg sum_of_squares_as_string: - :arg variance_as_string: - :arg variance_population_as_string: - :arg variance_sampling_as_string: - :arg std_deviation_as_string: - :arg std_deviation_bounds_as_string: - :arg min_as_string: - :arg max_as_string: - :arg avg_as_string: - :arg sum_as_string: - :arg meta: - """ - - sum_of_squares: Union[float, None] - variance: Union[float, None] - variance_population: Union[float, None] - variance_sampling: Union[float, None] - std_deviation: Union[float, None] - std_deviation_population: Union[float, None] - std_deviation_sampling: Union[float, None] - count: int - min: Union[float, None] - max: Union[float, None] - avg: Union[float, None] - sum: float - std_deviation_bounds: "StandardDeviationBounds" - sum_of_squares_as_string: str - variance_as_string: str - variance_population_as_string: str - variance_sampling_as_string: str - std_deviation_as_string: str - std_deviation_bounds_as_string: "StandardDeviationBoundsAsString" - min_as_string: str - max_as_string: str - avg_as_string: str - sum_as_string: str - meta: Mapping[str, Any] - - -class ExtendedStatsBucketAggregate(AttrDict[Any]): - """ - :arg sum_of_squares: (required) - :arg variance: (required) - :arg variance_population: (required) - :arg variance_sampling: (required) - :arg std_deviation: (required) - :arg std_deviation_population: (required) - :arg std_deviation_sampling: (required) - :arg count: (required) - :arg min: (required) - :arg max: (required) - :arg avg: (required) - :arg sum: (required) - :arg std_deviation_bounds: - :arg sum_of_squares_as_string: - :arg variance_as_string: - :arg variance_population_as_string: - :arg variance_sampling_as_string: - :arg std_deviation_as_string: - :arg std_deviation_bounds_as_string: - :arg min_as_string: - :arg max_as_string: - :arg avg_as_string: - :arg sum_as_string: - :arg meta: - """ - - sum_of_squares: Union[float, None] - variance: Union[float, None] - variance_population: Union[float, None] - variance_sampling: Union[float, None] - std_deviation: Union[float, None] - std_deviation_population: Union[float, None] - std_deviation_sampling: Union[float, None] - count: int - min: Union[float, None] - max: Union[float, None] - avg: Union[float, None] - sum: float - std_deviation_bounds: "StandardDeviationBounds" - sum_of_squares_as_string: str - variance_as_string: str - variance_population_as_string: str - variance_sampling_as_string: str - std_deviation_as_string: str - std_deviation_bounds_as_string: "StandardDeviationBoundsAsString" - min_as_string: str - max_as_string: str - avg_as_string: str - sum_as_string: str - meta: Mapping[str, Any] - - -class FetchProfile(AttrDict[Any]): - """ - :arg type: (required) - :arg description: (required) - :arg time_in_nanos: (required) - :arg breakdown: (required) - :arg debug: - :arg children: - """ - - type: str - description: str - time_in_nanos: Any - breakdown: "FetchProfileBreakdown" - debug: "FetchProfileDebug" - children: Sequence["FetchProfile"] - - -class FetchProfileBreakdown(AttrDict[Any]): - """ - :arg load_source: - :arg load_source_count: - :arg load_stored_fields: - :arg load_stored_fields_count: - :arg next_reader: - :arg next_reader_count: - :arg process_count: - :arg process: - """ - - load_source: int - load_source_count: int - load_stored_fields: int - load_stored_fields_count: int - next_reader: int - next_reader_count: int - process_count: int - process: int - - -class FetchProfileDebug(AttrDict[Any]): - """ - :arg stored_fields: - :arg fast_path: - """ - - stored_fields: Sequence[str] - fast_path: int - - -class FilterAggregate(AttrDict[Any]): - """ - :arg doc_count: (required) - :arg meta: - """ - - doc_count: int - meta: Mapping[str, Any] - - -class FiltersAggregate(AttrDict[Any]): - """ - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - buckets: Sequence["FiltersBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "FiltersBucket"]: - return self.buckets # type: ignore - - -class FiltersBucket(AttrDict[Any]): - """ - :arg doc_count: (required) - """ - - doc_count: int - - -class FrequentItemSetsAggregate(AttrDict[Any]): - """ - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - buckets: Sequence["FrequentItemSetsBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "FrequentItemSetsBucket"]: - return self.buckets # type: ignore - - -class FrequentItemSetsBucket(AttrDict[Any]): - """ - :arg key: (required) - :arg support: (required) - :arg doc_count: (required) - """ - - key: Mapping[str, Sequence[str]] - support: float - doc_count: int - - -class GeoBoundsAggregate(AttrDict[Any]): - """ - :arg bounds: - :arg meta: - """ - - bounds: Union[ - "CoordsGeoBounds", - "TopLeftBottomRightGeoBounds", - "TopRightBottomLeftGeoBounds", - "WktGeoBounds", - ] - meta: Mapping[str, Any] - - -class GeoCentroidAggregate(AttrDict[Any]): - """ - :arg count: (required) - :arg location: - :arg meta: - """ - - count: int - location: Union["LatLonGeoLocation", "GeoHashLocation", Sequence[float], str] - meta: Mapping[str, Any] - - -class GeoDistanceAggregate(AttrDict[Any]): - """ - Result of a `geo_distance` aggregation. The unit for `from` and `to` - is meters by default. - - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - buckets: Sequence["RangeBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "RangeBucket"]: - return self.buckets # type: ignore - - -class GeoHashGridAggregate(AttrDict[Any]): - """ - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - buckets: Sequence["GeoHashGridBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "GeoHashGridBucket"]: - return self.buckets # type: ignore - - -class GeoHashGridBucket(AttrDict[Any]): - """ - :arg key: (required) - :arg doc_count: (required) - """ - - key: str - doc_count: int - - -class GeoHexGridAggregate(AttrDict[Any]): - """ - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - buckets: Sequence["GeoHexGridBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "GeoHexGridBucket"]: - return self.buckets # type: ignore - - -class GeoHexGridBucket(AttrDict[Any]): - """ - :arg key: (required) - :arg doc_count: (required) - """ - - key: str - doc_count: int - - -class GeoLine(AttrDict[Any]): - """ - A GeoJson GeoLine. - - :arg type: (required) Always `"LineString"` - :arg coordinates: (required) Array of `[lon, lat]` coordinates - """ - - type: str - coordinates: Sequence[Sequence[float]] - - -class GeoLineAggregate(AttrDict[Any]): - """ - :arg type: (required) - :arg geometry: (required) - :arg properties: (required) - :arg meta: - """ - - type: str - geometry: "GeoLine" - properties: Any - meta: Mapping[str, Any] - - -class GeoTileGridAggregate(AttrDict[Any]): - """ - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - buckets: Sequence["GeoTileGridBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "GeoTileGridBucket"]: - return self.buckets # type: ignore - - -class GeoTileGridBucket(AttrDict[Any]): - """ - :arg key: (required) - :arg doc_count: (required) - """ - - key: str - doc_count: int - - -class GlobalAggregate(AttrDict[Any]): - """ - :arg doc_count: (required) - :arg meta: - """ - - doc_count: int - meta: Mapping[str, Any] - - -class HdrPercentileRanksAggregate(AttrDict[Any]): - """ - :arg values: (required) - :arg meta: - """ - - values: Union[Mapping[str, Union[str, int, None]], Sequence["ArrayPercentilesItem"]] - meta: Mapping[str, Any] - - -class HdrPercentilesAggregate(AttrDict[Any]): - """ - :arg values: (required) - :arg meta: - """ - - values: Union[Mapping[str, Union[str, int, None]], Sequence["ArrayPercentilesItem"]] - meta: Mapping[str, Any] - - -class HistogramAggregate(AttrDict[Any]): - """ - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - buckets: Sequence["HistogramBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "HistogramBucket"]: - return self.buckets # type: ignore - - -class HistogramBucket(AttrDict[Any]): - """ - :arg key: (required) - :arg doc_count: (required) - :arg key_as_string: - """ - - key: float - doc_count: int - key_as_string: str - - -class Hit(AttrDict[Any]): - """ - :arg index: (required) - :arg id: - :arg score: - :arg explanation: - :arg fields: - :arg highlight: - :arg inner_hits: - :arg matched_queries: - :arg nested: - :arg ignored: - :arg ignored_field_values: - :arg shard: - :arg node: - :arg routing: - :arg source: - :arg rank: - :arg seq_no: - :arg primary_term: - :arg version: - :arg sort: - """ - - index: str - id: str - score: Union[float, None] - explanation: "Explanation" - fields: Mapping[str, Any] - highlight: Mapping[str, Sequence[str]] - inner_hits: Mapping[str, "InnerHitsResult"] - matched_queries: Union[Sequence[str], Mapping[str, float]] - nested: "NestedIdentity" - ignored: Sequence[str] - ignored_field_values: Mapping[ - str, Sequence[Union[int, float, str, bool, None, Any]] - ] - shard: str - node: str - routing: str - source: Any - rank: int - seq_no: int - primary_term: int - version: int - sort: Sequence[Union[int, float, str, bool, None, Any]] - - -class HitsMetadata(AttrDict[Any]): - """ - :arg hits: (required) - :arg total: Total hit count information, present only if - `track_total_hits` wasn't `false` in the search request. - :arg max_score: - """ - - hits: Sequence["Hit"] - total: Union["TotalHits", int] - max_score: Union[float, None] - - -class InferenceAggregate(AttrDict[Any]): - """ - :arg value: - :arg feature_importance: - :arg top_classes: - :arg warning: - :arg meta: - """ - - value: Union[int, float, str, bool, None, Any] - feature_importance: Sequence["InferenceFeatureImportance"] - top_classes: Sequence["InferenceTopClassEntry"] - warning: str - meta: Mapping[str, Any] - - -class InferenceClassImportance(AttrDict[Any]): - """ - :arg class_name: (required) - :arg importance: (required) - """ - - class_name: str - importance: float - - -class InferenceFeatureImportance(AttrDict[Any]): - """ - :arg feature_name: (required) - :arg importance: - :arg classes: - """ - - feature_name: str - importance: float - classes: Sequence["InferenceClassImportance"] - - -class InferenceTopClassEntry(AttrDict[Any]): - """ - :arg class_name: (required) - :arg class_probability: (required) - :arg class_score: (required) - """ - - class_name: Union[int, float, str, bool, None, Any] - class_probability: float - class_score: float - - -class InnerHitsResult(AttrDict[Any]): - """ - :arg hits: (required) - """ - - hits: "HitsMetadata" - - -class IpPrefixAggregate(AttrDict[Any]): - """ - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - buckets: Sequence["IpPrefixBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "IpPrefixBucket"]: - return self.buckets # type: ignore - - -class IpPrefixBucket(AttrDict[Any]): - """ - :arg is_ipv6: (required) - :arg key: (required) - :arg prefix_length: (required) - :arg doc_count: (required) - :arg netmask: - """ - - is_ipv6: bool - key: str - prefix_length: int - doc_count: int - netmask: str - - -class IpRangeAggregate(AttrDict[Any]): - """ - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - buckets: Sequence["IpRangeBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "IpRangeBucket"]: - return self.buckets # type: ignore - - -class IpRangeBucket(AttrDict[Any]): - """ - :arg doc_count: (required) - :arg key: - :arg from: - :arg to: - """ - - doc_count: int - key: str - from_: str - to: str - - -class KnnCollectorResult(AttrDict[Any]): - """ - :arg name: (required) - :arg reason: (required) - :arg time_in_nanos: (required) - :arg time: - :arg children: - """ - - name: str - reason: str - time_in_nanos: Any - time: Any - children: Sequence["KnnCollectorResult"] - - -class KnnQueryProfileBreakdown(AttrDict[Any]): - """ - :arg advance: (required) - :arg advance_count: (required) - :arg build_scorer: (required) - :arg build_scorer_count: (required) - :arg compute_max_score: (required) - :arg compute_max_score_count: (required) - :arg count_weight: (required) - :arg count_weight_count: (required) - :arg create_weight: (required) - :arg create_weight_count: (required) - :arg match: (required) - :arg match_count: (required) - :arg next_doc: (required) - :arg next_doc_count: (required) - :arg score: (required) - :arg score_count: (required) - :arg set_min_competitive_score: (required) - :arg set_min_competitive_score_count: (required) - :arg shallow_advance: (required) - :arg shallow_advance_count: (required) - """ - - advance: int - advance_count: int - build_scorer: int - build_scorer_count: int - compute_max_score: int - compute_max_score_count: int - count_weight: int - count_weight_count: int - create_weight: int - create_weight_count: int - match: int - match_count: int - next_doc: int - next_doc_count: int - score: int - score_count: int - set_min_competitive_score: int - set_min_competitive_score_count: int - shallow_advance: int - shallow_advance_count: int - - -class KnnQueryProfileResult(AttrDict[Any]): - """ - :arg type: (required) - :arg description: (required) - :arg time_in_nanos: (required) - :arg breakdown: (required) - :arg time: - :arg debug: - :arg children: - """ - - type: str - description: str - time_in_nanos: Any - breakdown: "KnnQueryProfileBreakdown" - time: Any - debug: Mapping[str, Any] - children: Sequence["KnnQueryProfileResult"] - - -class LongRareTermsAggregate(AttrDict[Any]): - """ - Result of the `rare_terms` aggregation when the field is some kind of - whole number like a integer, long, or a date. - - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - buckets: Sequence["LongRareTermsBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "LongRareTermsBucket"]: - return self.buckets # type: ignore - - -class LongRareTermsBucket(AttrDict[Any]): - """ - :arg key: (required) - :arg doc_count: (required) - :arg key_as_string: - """ - - key: int - doc_count: int - key_as_string: str - - -class LongTermsAggregate(AttrDict[Any]): - """ - Result of a `terms` aggregation when the field is some kind of whole - number like a integer, long, or a date. - - :arg doc_count_error_upper_bound: - :arg sum_other_doc_count: - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - doc_count_error_upper_bound: int - sum_other_doc_count: int - buckets: Sequence["LongTermsBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "LongTermsBucket"]: - return self.buckets # type: ignore - - -class LongTermsBucket(AttrDict[Any]): - """ - :arg key: (required) - :arg doc_count: (required) - :arg key_as_string: - :arg doc_count_error_upper_bound: - """ - - key: int - doc_count: int - key_as_string: str - doc_count_error_upper_bound: int - - -class MatrixStatsAggregate(AttrDict[Any]): - """ - :arg doc_count: (required) - :arg fields: - :arg meta: - """ - - doc_count: int - fields: Sequence["MatrixStatsFields"] - meta: Mapping[str, Any] - - -class MatrixStatsFields(AttrDict[Any]): - """ - :arg name: (required) - :arg count: (required) - :arg mean: (required) - :arg variance: (required) - :arg skewness: (required) - :arg kurtosis: (required) - :arg covariance: (required) - :arg correlation: (required) - """ - - name: str - count: int - mean: float - variance: float - skewness: float - kurtosis: float - covariance: Mapping[str, float] - correlation: Mapping[str, float] - - -class MaxAggregate(AttrDict[Any]): - """ - :arg value: (required) The metric value. A missing value generally - means that there was no data to aggregate, unless specified - otherwise. - :arg value_as_string: - :arg meta: - """ - - value: Union[float, None] - value_as_string: str - meta: Mapping[str, Any] - - -class MedianAbsoluteDeviationAggregate(AttrDict[Any]): - """ - :arg value: (required) The metric value. A missing value generally - means that there was no data to aggregate, unless specified - otherwise. - :arg value_as_string: - :arg meta: - """ - - value: Union[float, None] - value_as_string: str - meta: Mapping[str, Any] - - -class MinAggregate(AttrDict[Any]): - """ - :arg value: (required) The metric value. A missing value generally - means that there was no data to aggregate, unless specified - otherwise. - :arg value_as_string: - :arg meta: - """ - - value: Union[float, None] - value_as_string: str - meta: Mapping[str, Any] - - -class MissingAggregate(AttrDict[Any]): - """ - :arg doc_count: (required) - :arg meta: - """ - - doc_count: int - meta: Mapping[str, Any] - - -class MultiTermsAggregate(AttrDict[Any]): - """ - :arg doc_count_error_upper_bound: - :arg sum_other_doc_count: - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - doc_count_error_upper_bound: int - sum_other_doc_count: int - buckets: Sequence["MultiTermsBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "MultiTermsBucket"]: - return self.buckets # type: ignore - - -class MultiTermsBucket(AttrDict[Any]): - """ - :arg key: (required) - :arg doc_count: (required) - :arg key_as_string: - :arg doc_count_error_upper_bound: - """ - - key: Sequence[Union[int, float, str, bool, None, Any]] - doc_count: int - key_as_string: str - doc_count_error_upper_bound: int - - -class NestedAggregate(AttrDict[Any]): - """ - :arg doc_count: (required) - :arg meta: - """ - - doc_count: int - meta: Mapping[str, Any] - - -class NestedIdentity(AttrDict[Any]): - """ - :arg field: (required) - :arg offset: (required) - :arg _nested: - """ - - field: str - offset: int - _nested: "NestedIdentity" - - -class ParentAggregate(AttrDict[Any]): - """ - :arg doc_count: (required) - :arg meta: - """ - - doc_count: int - meta: Mapping[str, Any] - - -class PercentilesBucketAggregate(AttrDict[Any]): - """ - :arg values: (required) - :arg meta: - """ - - values: Union[Mapping[str, Union[str, int, None]], Sequence["ArrayPercentilesItem"]] - meta: Mapping[str, Any] - - -class PhraseSuggest(AttrDict[Any]): - """ - :arg options: (required) - :arg length: (required) - :arg offset: (required) - :arg text: (required) - """ - - options: Sequence["PhraseSuggestOption"] - length: int - offset: int - text: str - - -class PhraseSuggestOption(AttrDict[Any]): - """ - :arg text: (required) - :arg score: (required) - :arg highlighted: - :arg collate_match: - """ - - text: str - score: float - highlighted: str - collate_match: bool - - -class Profile(AttrDict[Any]): - """ - :arg shards: (required) - """ - - shards: Sequence["ShardProfile"] - - -class QueryBreakdown(AttrDict[Any]): - """ - :arg advance: (required) - :arg advance_count: (required) - :arg build_scorer: (required) - :arg build_scorer_count: (required) - :arg create_weight: (required) - :arg create_weight_count: (required) - :arg match: (required) - :arg match_count: (required) - :arg shallow_advance: (required) - :arg shallow_advance_count: (required) - :arg next_doc: (required) - :arg next_doc_count: (required) - :arg score: (required) - :arg score_count: (required) - :arg compute_max_score: (required) - :arg compute_max_score_count: (required) - :arg count_weight: (required) - :arg count_weight_count: (required) - :arg set_min_competitive_score: (required) - :arg set_min_competitive_score_count: (required) - """ - - advance: int - advance_count: int - build_scorer: int - build_scorer_count: int - create_weight: int - create_weight_count: int - match: int - match_count: int - shallow_advance: int - shallow_advance_count: int - next_doc: int - next_doc_count: int - score: int - score_count: int - compute_max_score: int - compute_max_score_count: int - count_weight: int - count_weight_count: int - set_min_competitive_score: int - set_min_competitive_score_count: int - - -class QueryProfile(AttrDict[Any]): - """ - :arg breakdown: (required) - :arg description: (required) - :arg time_in_nanos: (required) - :arg type: (required) - :arg children: - """ - - breakdown: "QueryBreakdown" - description: str - time_in_nanos: Any - type: str - children: Sequence["QueryProfile"] - - -class RangeAggregate(AttrDict[Any]): - """ - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - buckets: Sequence["RangeBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "RangeBucket"]: - return self.buckets # type: ignore - - -class RangeBucket(AttrDict[Any]): - """ - :arg doc_count: (required) - :arg from: - :arg to: - :arg from_as_string: - :arg to_as_string: - :arg key: The bucket key. Present if the aggregation is _not_ keyed - """ - - doc_count: int - from_: float - to: float - from_as_string: str - to_as_string: str - key: str - - -class RateAggregate(AttrDict[Any]): - """ - :arg value: (required) - :arg value_as_string: - :arg meta: - """ - - value: float - value_as_string: str - meta: Mapping[str, Any] - - -class Retries(AttrDict[Any]): - """ - :arg bulk: (required) - :arg search: (required) - """ - - bulk: int - search: int - - -class ReverseNestedAggregate(AttrDict[Any]): - """ - :arg doc_count: (required) - :arg meta: - """ - - doc_count: int - meta: Mapping[str, Any] - - -class SamplerAggregate(AttrDict[Any]): - """ - :arg doc_count: (required) - :arg meta: - """ - - doc_count: int - meta: Mapping[str, Any] - - -class ScriptedMetricAggregate(AttrDict[Any]): - """ - :arg value: (required) - :arg meta: - """ - - value: Any - meta: Mapping[str, Any] - - -class SearchProfile(AttrDict[Any]): - """ - :arg collector: (required) - :arg query: (required) - :arg rewrite_time: (required) - """ - - collector: Sequence["Collector"] - query: Sequence["QueryProfile"] - rewrite_time: int - - -class ShardFailure(AttrDict[Any]): - """ - :arg reason: (required) - :arg shard: (required) - :arg index: - :arg node: - :arg status: - """ - - reason: "ErrorCause" - shard: int - index: str - node: str - status: str - - -class ShardProfile(AttrDict[Any]): - """ - :arg aggregations: (required) - :arg cluster: (required) - :arg id: (required) - :arg index: (required) - :arg node_id: (required) - :arg searches: (required) - :arg shard_id: (required) - :arg dfs: - :arg fetch: - """ - - aggregations: Sequence["AggregationProfile"] - cluster: str - id: str - index: str - node_id: str - searches: Sequence["SearchProfile"] - shard_id: int - dfs: "DfsProfile" - fetch: "FetchProfile" - - -class ShardStatistics(AttrDict[Any]): - """ - :arg failed: (required) - :arg successful: (required) Indicates how many shards have - successfully run the search. - :arg total: (required) Indicates how many shards the search will run - on overall. - :arg failures: - :arg skipped: - """ - - failed: int - successful: int - total: int - failures: Sequence["ShardFailure"] - skipped: int - - -class SignificantLongTermsAggregate(AttrDict[Any]): - """ - :arg bg_count: - :arg doc_count: - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - bg_count: int - doc_count: int - buckets: Sequence["SignificantLongTermsBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "SignificantLongTermsBucket"]: - return self.buckets # type: ignore - - -class SignificantLongTermsBucket(AttrDict[Any]): - """ - :arg key: (required) - :arg score: (required) - :arg bg_count: (required) - :arg doc_count: (required) - :arg key_as_string: - """ - - key: int - score: float - bg_count: int - doc_count: int - key_as_string: str - - -class SignificantStringTermsAggregate(AttrDict[Any]): - """ - :arg bg_count: - :arg doc_count: - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - bg_count: int - doc_count: int - buckets: Sequence["SignificantStringTermsBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "SignificantStringTermsBucket"]: - return self.buckets # type: ignore - - -class SignificantStringTermsBucket(AttrDict[Any]): - """ - :arg key: (required) - :arg score: (required) - :arg bg_count: (required) - :arg doc_count: (required) - """ - - key: str - score: float - bg_count: int - doc_count: int - - -class SimpleValueAggregate(AttrDict[Any]): - """ - :arg value: (required) The metric value. A missing value generally - means that there was no data to aggregate, unless specified - otherwise. - :arg value_as_string: - :arg meta: - """ - - value: Union[float, None] - value_as_string: str - meta: Mapping[str, Any] - - -class StandardDeviationBounds(AttrDict[Any]): - """ - :arg upper: (required) - :arg lower: (required) - :arg upper_population: (required) - :arg lower_population: (required) - :arg upper_sampling: (required) - :arg lower_sampling: (required) - """ - - upper: Union[float, None] - lower: Union[float, None] - upper_population: Union[float, None] - lower_population: Union[float, None] - upper_sampling: Union[float, None] - lower_sampling: Union[float, None] - - -class StandardDeviationBoundsAsString(AttrDict[Any]): - """ - :arg upper: (required) - :arg lower: (required) - :arg upper_population: (required) - :arg lower_population: (required) - :arg upper_sampling: (required) - :arg lower_sampling: (required) - """ - - upper: str - lower: str - upper_population: str - lower_population: str - upper_sampling: str - lower_sampling: str - - -class StatsAggregate(AttrDict[Any]): - """ - Statistics aggregation result. `min`, `max` and `avg` are missing if - there were no values to process (`count` is zero). - - :arg count: (required) - :arg min: (required) - :arg max: (required) - :arg avg: (required) - :arg sum: (required) - :arg min_as_string: - :arg max_as_string: - :arg avg_as_string: - :arg sum_as_string: - :arg meta: - """ - - count: int - min: Union[float, None] - max: Union[float, None] - avg: Union[float, None] - sum: float - min_as_string: str - max_as_string: str - avg_as_string: str - sum_as_string: str - meta: Mapping[str, Any] - - -class StatsBucketAggregate(AttrDict[Any]): - """ - :arg count: (required) - :arg min: (required) - :arg max: (required) - :arg avg: (required) - :arg sum: (required) - :arg min_as_string: - :arg max_as_string: - :arg avg_as_string: - :arg sum_as_string: - :arg meta: - """ - - count: int - min: Union[float, None] - max: Union[float, None] - avg: Union[float, None] - sum: float - min_as_string: str - max_as_string: str - avg_as_string: str - sum_as_string: str - meta: Mapping[str, Any] - - -class StringRareTermsAggregate(AttrDict[Any]): - """ - Result of the `rare_terms` aggregation when the field is a string. - - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - buckets: Sequence["StringRareTermsBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "StringRareTermsBucket"]: - return self.buckets # type: ignore - - -class StringRareTermsBucket(AttrDict[Any]): - """ - :arg key: (required) - :arg doc_count: (required) - """ - - key: str - doc_count: int - - -class StringStatsAggregate(AttrDict[Any]): - """ - :arg count: (required) - :arg min_length: (required) - :arg max_length: (required) - :arg avg_length: (required) - :arg entropy: (required) - :arg distribution: - :arg min_length_as_string: - :arg max_length_as_string: - :arg avg_length_as_string: - :arg meta: - """ - - count: int - min_length: Union[int, None] - max_length: Union[int, None] - avg_length: Union[float, None] - entropy: Union[float, None] - distribution: Union[Mapping[str, float], None] - min_length_as_string: str - max_length_as_string: str - avg_length_as_string: str - meta: Mapping[str, Any] - - -class StringTermsAggregate(AttrDict[Any]): - """ - Result of a `terms` aggregation when the field is a string. - - :arg doc_count_error_upper_bound: - :arg sum_other_doc_count: - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - doc_count_error_upper_bound: int - sum_other_doc_count: int - buckets: Sequence["StringTermsBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "StringTermsBucket"]: - return self.buckets # type: ignore - - -class StringTermsBucket(AttrDict[Any]): - """ - :arg key: (required) - :arg doc_count: (required) - :arg doc_count_error_upper_bound: - """ - - key: Union[int, float, str, bool, None, Any] - doc_count: int - doc_count_error_upper_bound: int - - -class SumAggregate(AttrDict[Any]): - """ - Sum aggregation result. `value` is always present and is zero if there - were no values to process. - - :arg value: (required) The metric value. A missing value generally - means that there was no data to aggregate, unless specified - otherwise. - :arg value_as_string: - :arg meta: - """ - - value: Union[float, None] - value_as_string: str - meta: Mapping[str, Any] - - -class TDigestPercentileRanksAggregate(AttrDict[Any]): - """ - :arg values: (required) - :arg meta: - """ - - values: Union[Mapping[str, Union[str, int, None]], Sequence["ArrayPercentilesItem"]] - meta: Mapping[str, Any] - - -class TDigestPercentilesAggregate(AttrDict[Any]): - """ - :arg values: (required) - :arg meta: - """ - - values: Union[Mapping[str, Union[str, int, None]], Sequence["ArrayPercentilesItem"]] - meta: Mapping[str, Any] - - -class TTestAggregate(AttrDict[Any]): - """ - :arg value: (required) - :arg value_as_string: - :arg meta: - """ - - value: Union[float, None] - value_as_string: str - meta: Mapping[str, Any] - - -class TermSuggest(AttrDict[Any]): - """ - :arg options: (required) - :arg length: (required) - :arg offset: (required) - :arg text: (required) - """ - - options: Sequence["TermSuggestOption"] - length: int - offset: int - text: str - - -class TermSuggestOption(AttrDict[Any]): - """ - :arg text: (required) - :arg score: (required) - :arg freq: (required) - :arg highlighted: - :arg collate_match: - """ - - text: str - score: float - freq: int - highlighted: str - collate_match: bool - - -class TimeSeriesAggregate(AttrDict[Any]): - """ - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - buckets: Sequence["TimeSeriesBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "TimeSeriesBucket"]: - return self.buckets # type: ignore - - -class TimeSeriesBucket(AttrDict[Any]): - """ - :arg key: (required) - :arg doc_count: (required) - """ - - key: Mapping[str, Union[int, float, str, bool, None, Any]] - doc_count: int - - -class TopHitsAggregate(AttrDict[Any]): - """ - :arg hits: (required) - :arg meta: - """ - - hits: "HitsMetadata" - meta: Mapping[str, Any] - - -class TopMetrics(AttrDict[Any]): - """ - :arg sort: (required) - :arg metrics: (required) - """ - - sort: Sequence[Union[Union[int, float, str, bool, None, Any], None]] - metrics: Mapping[str, Union[Union[int, float, str, bool, None, Any], None]] - - -class TopMetricsAggregate(AttrDict[Any]): - """ - :arg top: (required) - :arg meta: - """ - - top: Sequence["TopMetrics"] - meta: Mapping[str, Any] - - -class TotalHits(AttrDict[Any]): - """ - :arg relation: (required) - :arg value: (required) - """ - - relation: Literal["eq", "gte"] - value: int - - -class UnmappedRareTermsAggregate(AttrDict[Any]): - """ - Result of a `rare_terms` aggregation when the field is unmapped. - `buckets` is always empty. - - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - buckets: Sequence[Any] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, Any]: - return self.buckets # type: ignore - - -class UnmappedSamplerAggregate(AttrDict[Any]): - """ - :arg doc_count: (required) - :arg meta: - """ - - doc_count: int - meta: Mapping[str, Any] - - -class UnmappedSignificantTermsAggregate(AttrDict[Any]): - """ - Result of the `significant_terms` aggregation on an unmapped field. - `buckets` is always empty. - - :arg bg_count: - :arg doc_count: - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - bg_count: int - doc_count: int - buckets: Sequence[Any] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, Any]: - return self.buckets # type: ignore - - -class UnmappedTermsAggregate(AttrDict[Any]): - """ - Result of a `terms` aggregation when the field is unmapped. `buckets` - is always empty. - - :arg doc_count_error_upper_bound: - :arg sum_other_doc_count: - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - doc_count_error_upper_bound: int - sum_other_doc_count: int - buckets: Sequence[Any] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, Any]: - return self.buckets # type: ignore - - -class ValueCountAggregate(AttrDict[Any]): - """ - Value count aggregation result. `value` is always present. - - :arg value: (required) The metric value. A missing value generally - means that there was no data to aggregate, unless specified - otherwise. - :arg value_as_string: - :arg meta: - """ - - value: Union[float, None] - value_as_string: str - meta: Mapping[str, Any] - - -class VariableWidthHistogramAggregate(AttrDict[Any]): - """ - :arg buckets: (required) the aggregation buckets as a list - :arg meta: - """ - - buckets: Sequence["VariableWidthHistogramBucket"] - meta: Mapping[str, Any] - - @property - def buckets_as_dict(self) -> Mapping[str, "VariableWidthHistogramBucket"]: - return self.buckets # type: ignore - - -class VariableWidthHistogramBucket(AttrDict[Any]): - """ - :arg min: (required) - :arg key: (required) - :arg max: (required) - :arg doc_count: (required) - :arg min_as_string: - :arg key_as_string: - :arg max_as_string: - """ - - min: float - key: float - max: float - doc_count: int - min_as_string: str - key_as_string: str - max_as_string: str - - -class WeightedAvgAggregate(AttrDict[Any]): - """ - Weighted average aggregation result. `value` is missing if the weight - was set to zero. - - :arg value: (required) The metric value. A missing value generally - means that there was no data to aggregate, unless specified - otherwise. - :arg value_as_string: - :arg meta: - """ - - value: Union[float, None] - value_as_string: str - meta: Mapping[str, Any] diff --git a/elasticsearch_dsl/update_by_query.py b/elasticsearch_dsl/update_by_query.py deleted file mode 100644 index fdff22bc..00000000 --- a/elasticsearch_dsl/update_by_query.py +++ /dev/null @@ -1,19 +0,0 @@ -# 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 ._async.update_by_query import AsyncUpdateByQuery # noqa: F401 -from ._sync.update_by_query import UpdateByQuery # noqa: F401 diff --git a/elasticsearch_dsl/update_by_query_base.py b/elasticsearch_dsl/update_by_query_base.py deleted file mode 100644 index e4490ddf..00000000 --- a/elasticsearch_dsl/update_by_query_base.py +++ /dev/null @@ -1,149 +0,0 @@ -# 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, Dict, Type - -from typing_extensions import Self - -from .query import Bool, Q -from .response import UpdateByQueryResponse -from .search_base import ProxyDescriptor, QueryProxy, Request -from .utils import _R, recursive_to_dict - - -class UpdateByQueryBase(Request[_R]): - query = ProxyDescriptor[Self]("query") - - def __init__(self, **kwargs: Any): - """ - Update by query request to elasticsearch. - - :arg using: `Elasticsearch` instance to use - :arg index: limit the search to index - :arg doc_type: only query this type. - - All the parameters supplied (or omitted) at creation type can be later - overridden by methods (`using`, `index` and `doc_type` respectively). - - """ - super().__init__(**kwargs) - self._response_class = UpdateByQueryResponse[_R] - self._script: Dict[str, Any] = {} - self._query_proxy = QueryProxy(self, "query") - - def filter(self, *args: Any, **kwargs: Any) -> Self: - return self.query(Bool(filter=[Q(*args, **kwargs)])) - - def exclude(self, *args: Any, **kwargs: Any) -> Self: - return self.query(Bool(filter=[~Q(*args, **kwargs)])) - - @classmethod - def from_dict(cls, d: Dict[str, Any]) -> Self: - """ - Construct a new `UpdateByQuery` instance from a raw dict containing the search - body. Useful when migrating from raw dictionaries. - - Example:: - - ubq = UpdateByQuery.from_dict({ - "query": { - "bool": { - "must": [...] - } - }, - "script": {...} - }) - ubq = ubq.filter('term', published=True) - """ - u = cls() - u.update_from_dict(d) - return u - - def _clone(self) -> Self: - """ - Return a clone of the current search request. Performs a shallow copy - of all the underlying objects. Used internally by most state modifying - APIs. - """ - ubq = super()._clone() - - ubq._response_class = self._response_class - ubq._script = self._script.copy() - ubq.query._proxied = self.query._proxied - return ubq - - def response_class(self, cls: Type[UpdateByQueryResponse[_R]]) -> Self: - """ - Override the default wrapper used for the response. - """ - ubq = self._clone() - ubq._response_class = cls - return ubq - - def update_from_dict(self, d: Dict[str, Any]) -> Self: - """ - Apply options from a serialized body to the current instance. Modifies - the object in-place. Used mostly by ``from_dict``. - """ - d = d.copy() - if "query" in d: - self.query._proxied = Q(d.pop("query")) - if "script" in d: - self._script = d.pop("script") - self._extra.update(d) - return self - - def script(self, **kwargs: Any) -> Self: - """ - Define update action to take: - https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting-using.html - for more details. - - Note: the API only accepts a single script, so - calling the script multiple times will overwrite. - - Example:: - - ubq = Search() - ubq = ubq.script(source="ctx._source.likes++"") - ubq = ubq.script(source="ctx._source.likes += params.f"", - lang="expression", - params={'f': 3}) - """ - ubq = self._clone() - if ubq._script: - ubq._script = {} - ubq._script.update(kwargs) - return ubq - - def to_dict(self, **kwargs: Any) -> Dict[str, Any]: - """ - Serialize the search into the dictionary that will be sent over as the - request'ubq body. - - All additional keyword arguments will be included into the dictionary. - """ - d = {} - if self.query: - d["query"] = self.query.to_dict() - - if self._script: - d["script"] = self._script - - d.update(recursive_to_dict(self._extra)) - d.update(recursive_to_dict(kwargs)) - return d diff --git a/elasticsearch_dsl/utils.py b/elasticsearch_dsl/utils.py deleted file mode 100644 index 476778f8..00000000 --- a/elasticsearch_dsl/utils.py +++ /dev/null @@ -1,686 +0,0 @@ -# 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 collections.abc -from copy import copy -from typing import ( - TYPE_CHECKING, - Any, - Callable, - ClassVar, - Dict, - Generic, - Iterable, - Iterator, - List, - Mapping, - Optional, - Tuple, - Type, - Union, - cast, -) - -from elastic_transport.client_utils import DEFAULT -from typing_extensions import Self, TypeAlias, TypeVar - -from .exceptions import UnknownDslObject, ValidationException - -if TYPE_CHECKING: - from elastic_transport import ObjectApiResponse - from elasticsearch import AsyncElasticsearch, Elasticsearch - - from .document_base import DocumentOptions - from .field import Field - from .index_base import IndexBase - from .response import Hit # noqa: F401 - from .types import Hit as HitBaseType - -UsingType: TypeAlias = Union[str, "Elasticsearch"] -AsyncUsingType: TypeAlias = Union[str, "AsyncElasticsearch"] -AnyUsingType: TypeAlias = Union[str, "Elasticsearch", "AsyncElasticsearch"] - -_ValT = TypeVar("_ValT") # used by AttrDict -_R = TypeVar("_R", default="Hit") # used by Search and Response classes - -SKIP_VALUES = ("", None) -EXPAND__TO_DOT = True - -DOC_META_FIELDS = frozenset( - ( - "id", - "routing", - ) -) - -META_FIELDS = frozenset( - ( - # Elasticsearch metadata fields, except 'type' - "index", - "using", - "score", - "version", - "seq_no", - "primary_term", - ) -).union(DOC_META_FIELDS) - - -def _wrap(val: Any, obj_wrapper: Optional[Callable[[Any], Any]] = None) -> Any: - if isinstance(val, dict): - return AttrDict(val) if obj_wrapper is None else obj_wrapper(val) - if isinstance(val, list): - return AttrList(val) - return val - - -def _recursive_to_dict(value: Any) -> Any: - if hasattr(value, "to_dict"): - return value.to_dict() - elif isinstance(value, dict) or isinstance(value, AttrDict): - return {k: _recursive_to_dict(v) for k, v in value.items()} - elif isinstance(value, list) or isinstance(value, AttrList): - return [recursive_to_dict(elem) for elem in value] - else: - return value - - -class AttrList(Generic[_ValT]): - def __init__( - self, l: List[_ValT], obj_wrapper: Optional[Callable[[_ValT], Any]] = None - ): - # make iterables into lists - if not isinstance(l, list): - l = list(l) - self._l_ = l - self._obj_wrapper = obj_wrapper - - def __repr__(self) -> str: - return repr(self._l_) - - def __eq__(self, other: Any) -> bool: - if isinstance(other, AttrList): - return other._l_ == self._l_ - # make sure we still equal to a dict with the same data - return bool(other == self._l_) - - def __ne__(self, other: Any) -> bool: - return not self == other - - def __getitem__(self, k: Union[int, slice]) -> Any: - l = self._l_[k] - if isinstance(k, slice): - return AttrList[_ValT](l, obj_wrapper=self._obj_wrapper) # type: ignore[arg-type] - return _wrap(l, self._obj_wrapper) - - def __setitem__(self, k: int, value: _ValT) -> None: - self._l_[k] = value - - def __iter__(self) -> Iterator[Any]: - return map(lambda i: _wrap(i, self._obj_wrapper), self._l_) - - def __len__(self) -> int: - return len(self._l_) - - def __nonzero__(self) -> bool: - return bool(self._l_) - - __bool__ = __nonzero__ - - def __getattr__(self, name: str) -> Any: - return getattr(self._l_, name) - - def __getstate__(self) -> Tuple[List[_ValT], Optional[Callable[[_ValT], Any]]]: - return self._l_, self._obj_wrapper - - def __setstate__( - self, state: Tuple[List[_ValT], Optional[Callable[[_ValT], Any]]] - ) -> None: - self._l_, self._obj_wrapper = state - - def to_list(self) -> List[_ValT]: - return self._l_ - - -class AttrDict(Generic[_ValT]): - """ - Helper class to provide attribute like access (read and write) to - dictionaries. Used to provide a convenient way to access both results and - nested dsl dicts. - """ - - _d_: Dict[str, _ValT] - RESERVED: Dict[str, str] = {"from_": "from"} - - def __init__(self, d: Dict[str, _ValT]): - # assign the inner dict manually to prevent __setattr__ from firing - super().__setattr__("_d_", d) - - def __contains__(self, key: object) -> bool: - return key in self._d_ - - def __nonzero__(self) -> bool: - return bool(self._d_) - - __bool__ = __nonzero__ - - def __dir__(self) -> List[str]: - # introspection for auto-complete in IPython etc - return list(self._d_.keys()) - - def __eq__(self, other: Any) -> bool: - if isinstance(other, AttrDict): - return other._d_ == self._d_ - # make sure we still equal to a dict with the same data - return bool(other == self._d_) - - def __ne__(self, other: Any) -> bool: - return not self == other - - def __repr__(self) -> str: - r = repr(self._d_) - if len(r) > 60: - r = r[:60] + "...}" - return r - - def __getstate__(self) -> Tuple[Dict[str, _ValT]]: - return (self._d_,) - - def __setstate__(self, state: Tuple[Dict[str, _ValT]]) -> None: - super().__setattr__("_d_", state[0]) - - def __getattr__(self, attr_name: str) -> Any: - try: - return self.__getitem__(attr_name) - except KeyError: - raise AttributeError( - f"{self.__class__.__name__!r} object has no attribute {attr_name!r}" - ) - - def __delattr__(self, attr_name: str) -> None: - try: - del self._d_[self.RESERVED.get(attr_name, attr_name)] - except KeyError: - raise AttributeError( - f"{self.__class__.__name__!r} object has no attribute {attr_name!r}" - ) - - def __getitem__(self, key: str) -> Any: - return _wrap(self._d_[self.RESERVED.get(key, key)]) - - def __setitem__(self, key: str, value: _ValT) -> None: - self._d_[self.RESERVED.get(key, key)] = value - - def __delitem__(self, key: str) -> None: - del self._d_[self.RESERVED.get(key, key)] - - def __setattr__(self, name: str, value: _ValT) -> None: - # the __orig__class__ attribute has to be treated as an exception, as - # is it added to an object when it is instantiated with type arguments - if ( - name in self._d_ or not hasattr(self.__class__, name) - ) and name != "__orig_class__": - self._d_[self.RESERVED.get(name, name)] = value - else: - # there is an attribute on the class (could be property, ..) - don't add it as field - super().__setattr__(name, value) - - def __iter__(self) -> Iterator[str]: - return iter(self._d_) - - def to_dict(self, recursive: bool = False) -> Dict[str, _ValT]: - return cast( - Dict[str, _ValT], _recursive_to_dict(self._d_) if recursive else self._d_ - ) - - def keys(self) -> Iterable[str]: - return self._d_.keys() - - def items(self) -> Iterable[Tuple[str, _ValT]]: - return self._d_.items() - - -class DslMeta(type): - """ - Base Metaclass for DslBase subclasses that builds a registry of all classes - for given DslBase subclass (== all the query types for the Query subclass - of DslBase). - - It then uses the information from that registry (as well as `name` and - `shortcut` attributes from the base class) to construct any subclass based - on it's name. - - For typical use see `QueryMeta` and `Query` in `elasticsearch_dsl.query`. - """ - - name: str - _classes: Dict[str, type] - _type_name: str - _types: ClassVar[Dict[str, Type["DslBase"]]] = {} - - def __init__(cls, name: str, bases: Tuple[type, ...], attrs: Dict[str, Any]): - super().__init__(name, bases, attrs) - # skip for DslBase - if not hasattr(cls, "_type_shortcut"): - return - if not cls.name: - # abstract base class, register it's shortcut - cls._types[cls._type_name] = cls._type_shortcut - # and create a registry for subclasses - if not hasattr(cls, "_classes"): - cls._classes = {} - elif cls.name not in cls._classes: - # normal class, register it - cls._classes[cls.name] = cls - - @classmethod - def get_dsl_type(cls, name: str) -> Type["DslBase"]: - try: - return cls._types[name] - except KeyError: - raise UnknownDslObject(f"DSL type {name} does not exist.") - - -class DslBase(metaclass=DslMeta): - """ - Base class for all DSL objects - queries, filters, aggregations etc. Wraps - a dictionary representing the object's json. - - Provides several feature: - - attribute access to the wrapped dictionary (.field instead of ['field']) - - _clone method returning a copy of self - - to_dict method to serialize into dict (to be sent via elasticsearch-py) - - basic logical operators (&, | and ~) using a Bool(Filter|Query) TODO: - move into a class specific for Query/Filter - - respects the definition of the class and (de)serializes it's - attributes based on the `_param_defs` definition (for example turning - all values in the `must` attribute into Query objects) - """ - - _param_defs: ClassVar[Dict[str, Dict[str, Union[str, bool]]]] = {} - - @classmethod - def get_dsl_class( - cls: Type[Self], name: str, default: Optional[str] = None - ) -> Type[Self]: - try: - return cls._classes[name] - except KeyError: - if default is not None: - return cls._classes[default] - raise UnknownDslObject( - f"DSL class `{name}` does not exist in {cls._type_name}." - ) - - def __init__(self, _expand__to_dot: Optional[bool] = None, **params: Any) -> None: - if _expand__to_dot is None: - _expand__to_dot = EXPAND__TO_DOT - self._params: Dict[str, Any] = {} - for pname, pvalue in params.items(): - if pvalue == DEFAULT: - continue - # expand "__" to dots - if "__" in pname and _expand__to_dot: - pname = pname.replace("__", ".") - # convert instrumented fields to string - if type(pvalue).__name__ == "InstrumentedField": - pvalue = str(pvalue) - self._setattr(pname, pvalue) - - def _repr_params(self) -> str: - """Produce a repr of all our parameters to be used in __repr__.""" - return ", ".join( - f"{n.replace('.', '__')}={v!r}" - for (n, v) in sorted(self._params.items()) - # make sure we don't include empty typed params - if "type" not in self._param_defs.get(n, {}) or v - ) - - def __repr__(self) -> str: - return f"{self.__class__.__name__}({self._repr_params()})" - - def __eq__(self, other: Any) -> bool: - return isinstance(other, self.__class__) and other.to_dict() == self.to_dict() - - def __ne__(self, other: Any) -> bool: - return not self == other - - def __setattr__(self, name: str, value: Any) -> None: - if name.startswith("_"): - return super().__setattr__(name, value) - return self._setattr(name, value) - - def _setattr(self, name: str, value: Any) -> None: - # if this attribute has special type assigned to it... - name = AttrDict.RESERVED.get(name, name) - if name in self._param_defs: - pinfo = self._param_defs[name] - - if "type" in pinfo: - # get the shortcut used to construct this type (query.Q, aggs.A, etc) - shortcut = self.__class__.get_dsl_type(str(pinfo["type"])) - - # list of dict(name -> DslBase) - if pinfo.get("multi") and pinfo.get("hash"): - if not isinstance(value, (tuple, list)): - value = (value,) - value = list( - {k: shortcut(v) for (k, v) in obj.items()} for obj in value - ) - elif pinfo.get("multi"): - if not isinstance(value, (tuple, list)): - value = (value,) - value = list(map(shortcut, value)) - - # dict(name -> DslBase), make sure we pickup all the objs - elif pinfo.get("hash"): - value = {k: shortcut(v) for (k, v) in value.items()} - - # single value object, just convert - else: - value = shortcut(value) - self._params[name] = value - - def __getattr__(self, name: str) -> Any: - if name.startswith("_"): - raise AttributeError( - f"{self.__class__.__name__!r} object has no attribute {name!r}" - ) - - value = None - try: - value = self._params[name] - except KeyError: - # compound types should never throw AttributeError and return empty - # container instead - if name in self._param_defs: - pinfo = self._param_defs[name] - if pinfo.get("multi"): - value = self._params.setdefault(name, []) - elif pinfo.get("hash"): - value = self._params.setdefault(name, {}) - if value is None: - raise AttributeError( - f"{self.__class__.__name__!r} object has no attribute {name!r}" - ) - - # wrap nested dicts in AttrDict for convenient access - if isinstance(value, dict): - return AttrDict(value) - return value - - def to_dict(self) -> Dict[str, Any]: - """ - Serialize the DSL object to plain dict - """ - d = {} - for pname, value in self._params.items(): - pinfo = self._param_defs.get(pname) - - # typed param - if pinfo and "type" in pinfo: - # don't serialize empty lists and dicts for typed fields - if value in ({}, []): - continue - - # list of dict(name -> DslBase) - if pinfo.get("multi") and pinfo.get("hash"): - value = list( - {k: v.to_dict() for k, v in obj.items()} for obj in value - ) - - # multi-values are serialized as list of dicts - elif pinfo.get("multi"): - value = list(map(lambda x: x.to_dict(), value)) - - # squash all the hash values into one dict - elif pinfo.get("hash"): - value = {k: v.to_dict() for k, v in value.items()} - - # serialize single values - else: - value = value.to_dict() - - # serialize anything with to_dict method - elif hasattr(value, "to_dict"): - value = value.to_dict() - - d[pname] = value - return {self.name: d} - - def _clone(self) -> Self: - c = self.__class__() - for attr in self._params: - c._params[attr] = copy(self._params[attr]) - return c - - -if TYPE_CHECKING: - HitMetaBase = HitBaseType -else: - HitMetaBase = AttrDict[Any] - - -class HitMeta(HitMetaBase): - inner_hits: Mapping[str, Any] - - def __init__( - self, - document: Dict[str, Any], - exclude: Tuple[str, ...] = ("_source", "_fields"), - ): - d = { - k[1:] if k.startswith("_") else k: v - for (k, v) in document.items() - if k not in exclude - } - if "type" in d: - # make sure we are consistent everywhere in python - d["doc_type"] = d.pop("type") - super().__init__(d) - - -class ObjectBase(AttrDict[Any]): - _doc_type: "DocumentOptions" - _index: "IndexBase" - meta: HitMeta - - def __init__(self, meta: Optional[Dict[str, Any]] = None, **kwargs: Any): - meta = meta or {} - for k in list(kwargs): - if k.startswith("_") and k[1:] in META_FIELDS: - meta[k] = kwargs.pop(k) - - super(AttrDict, self).__setattr__("meta", HitMeta(meta)) - - # process field defaults - if hasattr(self, "_defaults"): - for name in self._defaults: - if name not in kwargs: - value = self._defaults[name] - if callable(value): - value = value() - kwargs[name] = value - - super().__init__(kwargs) - - @classmethod - def __list_fields(cls) -> Iterator[Tuple[str, "Field", bool]]: - """ - Get all the fields defined for our class, if we have an Index, try - looking at the index mappings as well, mark the fields from Index as - optional. - """ - for name in cls._doc_type.mapping: - field = cls._doc_type.mapping[name] - yield name, field, False - - if hasattr(cls.__class__, "_index"): - if not cls._index._mapping: - return - for name in cls._index._mapping: - # don't return fields that are in _doc_type - if name in cls._doc_type.mapping: - continue - field = cls._index._mapping[name] - yield name, field, True - - @classmethod - def __get_field(cls, name: str) -> Optional["Field"]: - try: - return cls._doc_type.mapping[name] - except KeyError: - # fallback to fields on the Index - if hasattr(cls, "_index") and cls._index._mapping: - try: - return cls._index._mapping[name] - except KeyError: - pass - return None - - @classmethod - def from_es(cls, hit: Union[Dict[str, Any], "ObjectApiResponse[Any]"]) -> Self: - meta = hit.copy() - data = meta.pop("_source", {}) - doc = cls(meta=meta) - doc._from_dict(data) - return doc - - def _from_dict(self, data: Dict[str, Any]) -> None: - for k, v in data.items(): - f = self.__get_field(k) - if f and f._coerce: - v = f.deserialize(v) - setattr(self, k, v) - - def __getstate__(self) -> Tuple[Dict[str, Any], Dict[str, Any]]: # type: ignore[override] - return self.to_dict(), self.meta._d_ - - def __setstate__(self, state: Tuple[Dict[str, Any], Dict[str, Any]]) -> None: # type: ignore[override] - data, meta = state - super(AttrDict, self).__setattr__("_d_", {}) - super(AttrDict, self).__setattr__("meta", HitMeta(meta)) - self._from_dict(data) - - def __getattr__(self, name: str) -> Any: - try: - return super().__getattr__(name) - except AttributeError: - f = self.__get_field(name) - if f is not None and hasattr(f, "empty"): - value = f.empty() - if value not in SKIP_VALUES: - setattr(self, name, value) - value = getattr(self, name) - return value - raise - - def __setattr__(self, name: str, value: Any) -> None: - if name in self.__class__._doc_type.mapping: - self._d_[name] = value - else: - super().__setattr__(name, value) - - def to_dict(self, skip_empty: bool = True) -> Dict[str, Any]: - out = {} - for k, v in self._d_.items(): - # if this is a mapped field, - f = self.__get_field(k) - if f and f._coerce: - v = f.serialize(v) - - # if someone assigned AttrList, unwrap it - if isinstance(v, AttrList): - v = v._l_ - - if skip_empty: - # don't serialize empty values - # careful not to include numeric zeros - if v in ([], {}, None): - continue - - out[k] = v - return out - - def clean_fields(self, validate: bool = True) -> None: - errors: Dict[str, List[ValidationException]] = {} - for name, field, optional in self.__list_fields(): - data = self._d_.get(name, None) - if data is None and optional: - continue - try: - # save the cleaned value - data = field.clean(data) - except ValidationException as e: - errors.setdefault(name, []).append(e) - - if name in self._d_ or data not in ([], {}, None): - self._d_[name] = cast(Any, data) - - if validate and errors: - raise ValidationException(errors) - - def clean(self) -> None: - pass - - def full_clean(self) -> None: - self.clean_fields(validate=False) - self.clean() - self.clean_fields(validate=True) - - -def merge( - data: Union[Dict[str, Any], AttrDict[Any]], - new_data: Union[Dict[str, Any], AttrDict[Any]], - raise_on_conflict: bool = False, -) -> None: - if not ( - isinstance(data, (AttrDict, collections.abc.Mapping)) - and isinstance(new_data, (AttrDict, collections.abc.Mapping)) - ): - raise ValueError( - f"You can only merge two dicts! Got {data!r} and {new_data!r} instead." - ) - - for key, value in new_data.items(): - if ( - key in data - and isinstance(data[key], (AttrDict, collections.abc.Mapping)) - and isinstance(value, (AttrDict, collections.abc.Mapping)) - ): - merge(data[key], value, raise_on_conflict) # type: ignore - elif key in data and data[key] != value and raise_on_conflict: - raise ValueError(f"Incompatible data for key {key!r}, cannot be merged.") - else: - data[key] = value - - -def recursive_to_dict(data: Any) -> Any: - """Recursively transform objects that potentially have .to_dict() - into dictionary literals by traversing AttrList, AttrDict, list, - tuple, and Mapping types. - """ - if isinstance(data, AttrList): - data = list(data._l_) - elif hasattr(data, "to_dict"): - data = data.to_dict() - if isinstance(data, (list, tuple)): - return type(data)(recursive_to_dict(inner) for inner in data) - elif isinstance(data, dict): - return {key: recursive_to_dict(val) for key, val in data.items()} - return data diff --git a/elasticsearch_dsl/wrappers.py b/elasticsearch_dsl/wrappers.py deleted file mode 100644 index ecd2e136..00000000 --- a/elasticsearch_dsl/wrappers.py +++ /dev/null @@ -1,119 +0,0 @@ -# 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 operator -from typing import ( - TYPE_CHECKING, - Callable, - ClassVar, - Dict, - Literal, - Mapping, - Optional, - Tuple, - TypeVar, - Union, - cast, -) - -if TYPE_CHECKING: - from _operator import _SupportsComparison - -from typing_extensions import TypeAlias - -from .utils import AttrDict - -ComparisonOperators: TypeAlias = Literal["lt", "lte", "gt", "gte"] -RangeValT = TypeVar("RangeValT", bound="_SupportsComparison") - -__all__ = ["Range"] - - -class Range(AttrDict[RangeValT]): - OPS: ClassVar[ - Mapping[ - ComparisonOperators, - Callable[["_SupportsComparison", "_SupportsComparison"], bool], - ] - ] = { - "lt": operator.lt, - "lte": operator.le, - "gt": operator.gt, - "gte": operator.ge, - } - - def __init__( - self, - d: Optional[Dict[str, RangeValT]] = None, - /, - **kwargs: RangeValT, - ): - if d is not None and (kwargs or not isinstance(d, dict)): - raise ValueError( - "Range accepts a single dictionary or a set of keyword arguments." - ) - - if d is None: - data = kwargs - else: - data = d - - for k in data: - if k not in self.OPS: - raise ValueError(f"Range received an unknown operator {k!r}") - - if "gt" in data and "gte" in data: - raise ValueError("You cannot specify both gt and gte for Range.") - - if "lt" in data and "lte" in data: - raise ValueError("You cannot specify both lt and lte for Range.") - - super().__init__(data) - - def __repr__(self) -> str: - return "Range(%s)" % ", ".join("%s=%r" % op for op in self._d_.items()) - - def __contains__(self, item: object) -> bool: - if isinstance(item, str): - return super().__contains__(item) - - item_supports_comp = any(hasattr(item, f"__{op}__") for op in self.OPS) - if not item_supports_comp: - return False - - for op in self.OPS: - if op in self._d_ and not self.OPS[op]( - cast("_SupportsComparison", item), self._d_[op] - ): - return False - return True - - @property - def upper(self) -> Union[Tuple[RangeValT, bool], Tuple[None, Literal[False]]]: - if "lt" in self._d_: - return self._d_["lt"], False - if "lte" in self._d_: - return self._d_["lte"], True - return None, False - - @property - def lower(self) -> Union[Tuple[RangeValT, bool], Tuple[None, Literal[False]]]: - if "gt" in self._d_: - return self._d_["gt"], False - if "gte" in self._d_: - return self._d_["gte"], True - return None, False diff --git a/noxfile.py b/noxfile.py index b585b422..d0aea0c9 100644 --- a/noxfile.py +++ b/noxfile.py @@ -58,9 +58,7 @@ def test(session): @nox.session(python="3.13") def format(session): - session.install("black~=24.0", "isort", "unasync", "setuptools", ".[develop]") - session.run("python", "utils/run-unasync.py") - session.run("python", "utils/generator.py", env={"PYTHONPATH": "./"}) + session.install("black~=24.0", "isort", "setuptools", ".[develop]") session.run("black", "--target-version=py38", *SOURCE_FILES) session.run("isort", *SOURCE_FILES) session.run("python", "utils/license-headers.py", "fix", *SOURCE_FILES) @@ -70,30 +68,17 @@ def format(session): @nox.session(python="3.13") def lint(session): - session.install("flake8", "black~=24.0", "isort", "unasync", "setuptools") + session.install("flake8", "black~=24.0", "isort", "setuptools") session.run("black", "--check", "--target-version=py38", *SOURCE_FILES) session.run("isort", "--check", *SOURCE_FILES) - session.run("python", "utils/run-unasync.py", "--check") session.run("flake8", "--ignore=E501,E741,W503,E704", *SOURCE_FILES) session.run("python", "utils/license-headers.py", "check", *SOURCE_FILES) @nox.session(python="3.8") def type_check(session): - session.install(".[develop]") - session.run( - "mypy", - "--strict", - "--implicit-reexport", - "--explicit-package-bases", - "elasticsearch_dsl", - "tests", - "examples", - ) - session.run( - "pyright", - "examples", - ) + # type checking is done by the unified client now + pass @nox.session() diff --git a/setup.py b/setup.py index 680eb145..4c392d01 100644 --- a/setup.py +++ b/setup.py @@ -30,7 +30,8 @@ install_requires = [ "python-dateutil", "typing-extensions", - "elasticsearch>=8.0.0,<9.0.0", + # "elasticsearch>=8.0.0,<9.0.0", + "elasticsearch @ https://github.com/elastic/elasticsearch-py/archive/refs/heads/main.zip#egg=elasticsearch", "elastic-transport>=8.0.0,<9.0.0", ]