Module contents

Submodules

esorm.aggs module

ElasticSearch aggregation type definitions for ESORM

class esorm.aggs.ESAgg(*args, **kwargs)

Bases: dict

Holds all types of aggregations supported

avg: ESAggFieldParams

Average aggregation

histogram: ESAggHistogramParams

Histogram aggregation

max: ESAggFieldParams

Maximum aggregation

min: ESAggFieldParams

Minimum aggregation

sum: ESAggFieldParams

Sum aggregation

terms: ESAggTermParams

Terms aggregation

class esorm.aggs.ESAggBucketResponse(*args, **kwargs)

Bases: dict

Represents a single bucket in a bucket aggregation.

doc_count: int

The number of documents in this bucket.

key: str

The key of the bucket.

class esorm.aggs.ESAggExtendedBounds(*args, **kwargs)

Bases: dict

Represents the parameters for extended bounds in Elasticsearch.

max: int

The maximum value.

min: int

The minimum value.

class esorm.aggs.ESAggFieldParams(*args, **kwargs)

Bases: dict

Represents field parameter in Elasticsearch.

field: str

The field to aggregate on.

class esorm.aggs.ESAggHistogramBucketresponse(*args, **kwargs)

Bases: dict

Represents a bucket in a histogram aggregation.

doc_count: int

The number of documents in this bucket.

key: float

Numeric key corresponding to the bucket’s range.

class esorm.aggs.ESAggHistogramParams(*args, **kwargs)

Bases: dict

Represents the parameters for a histogram aggregation in Elasticsearch.

extended_bounds: ESAggExtendedBounds

The extended bounds of the histogram.

field: str

The field to aggregate on.

interval: int

The interval of the histogram.

min_doc_count: int

The minimum number of documents in a bucket.

class esorm.aggs.ESAggHistogramResponse(*args, **kwargs)

Bases: dict

Represents the response for a histogram aggregation.

buckets: List[ESAggHistogramBucketresponse]

A list of buckets in the histogram aggregation.

class esorm.aggs.ESAggTermParams(*args, **kwargs)

Bases: dict

Represents the parameters for a terms aggregation in Elasticsearch.

field: str

The field to aggregate on.

order: Dict[str, str]

The order of the buckets.

size: int

The number of buckets to return.

class esorm.aggs.ESAggTermsResponse(*args, **kwargs)

Bases: dict

Represents the response for a terms aggregation.

buckets: List[ESAggBucketResponse]

A list of buckets in the terms aggregation.

class esorm.aggs.ESAggValueResponse(*args, **kwargs)

Bases: dict

Represents the response for an average, min, or max aggregation.

value: float

The average, min, or max value.

esorm.aggs.ESAggs

ElasticSearch aggregations type definition

alias of Dict[str, ESAgg]

esorm.aggs.ESAggsResponse

ElasticSearch aggregations response type definition

alias of Dict[str, Union[ESAggValueResponse, ESAggTermsResponse, ESAggHistogramResponse]]

esorm.bulk module

esorm.error module

This module contains all the exceptions that can be raised by ESORM.

exception esorm.error.BulkError(failed_operations)

Bases: Exception

Exception for handling bulk operation errors.

failed_operations: List[BulkOperationError]

class esorm.error.BulkOperationError(*args, **kwargs)

Bases: dict

A dictionary type to represent an error in a bulk operation response from Elasticsearch.

model: ESModel

reason: str

status: int

type: str

exception esorm.error.ConflictError

Bases: Exception

Raised when a conflict occurs.

You can manually raise this to retry operation with retry_on_conflict decorator.

exception esorm.error.IndexDoesNotFoundError

Bases: Exception

Raised when an index does not exist.

exception esorm.error.InvalidModelError

Bases: Exception

Raised when a model is invalid.

exception esorm.error.InvalidResponseError

Bases: Exception

Raised when the response from Elasticsearch is invalid.

exception esorm.error.NotFoundError

Bases: Exception

Raised when a model is not found.

esorm.esorm module

ElasticSearch ORM main module

async esorm.esorm.connect(hosts, *args, wait=False, **kwargs)

Connect to ElasticSearch

Parameters:

• hosts (Union[str, List[Union[str, Mapping[str, Union[str, int]], NodeConfig]], None]) – ElasticSearch hosts to connect, either a list a mapping, or a single string

• args – Other AsyncElasticsearch arguments

• wait – Wait for AsyncElasticsearch to be ready

• kwargs – Other AsyncElasticsearch keyword arguments

Return type:

Optional[AsyncElasticsearch]

Returns:

AsyncElasticsearch client instance

async esorm.esorm.get_es_version()

Get ElasticSearch version

Return type:

str

Returns:

ElasticSearch version

esorm.fastapi module

esorm.fields module

esorm.logger module

esorm.model module

esorm.query module

Elasticsearch query type definitions for ESORM

class esorm.query.ESBool(*args, **kwargs)

Bases: dict

Bool query structure

boost: float

Boosting value for the query

filter: List[Union[FieldRange, FieldTerm, FieldTerms, FieldMatch, FieldMatchPhrase, FieldExists, FieldWildcard, FieldPrefix, FieldFuzzy, FieldGeoDistance, FieldMatchAll, FieldESMatchNone, FieldBool]]

Filter queries

minimum_should_match: Union[int, str]

Minimum number of should queries to match

must: List[Union[FieldRange, FieldTerm, FieldTerms, FieldMatch, FieldMatchPhrase, FieldExists, FieldWildcard, FieldPrefix, FieldFuzzy, FieldGeoDistance, FieldMatchAll, FieldESMatchNone, FieldBool, FieldKnn]]

Must queries

must_not: List[Union[FieldRange, FieldTerm, FieldTerms, FieldMatch, FieldMatchPhrase, FieldExists, FieldWildcard, FieldPrefix, FieldFuzzy, FieldGeoDistance, FieldMatchAll, FieldESMatchNone, FieldBool]]

Must not queries

should: List[Union[FieldRange, FieldTerm, FieldTerms, FieldMatch, FieldMatchPhrase, FieldExists, FieldWildcard, FieldPrefix, FieldFuzzy, FieldGeoDistance, FieldMatchAll, FieldESMatchNone, FieldBool, FieldKnn]]

Should queries

class esorm.query.ESExists(*args, **kwargs)

Bases: dict

Represents an exists query to check if a field exists.

field: str

The field to check.

esorm.query.ESFilter

Represents filter queries in Elasticsearch

alias of List[Union[FieldRange, FieldTerm, FieldTerms, FieldMatch, FieldMatchPhrase, FieldExists, FieldWildcard, FieldPrefix, FieldFuzzy, FieldGeoDistance, FieldMatchAll, FieldESMatchNone, FieldBool]]

class esorm.query.ESFuzzy(*args, **kwargs)

Bases: dict

Represents a fuzzy query for approximate matching in Elasticsearch.

boost: float

Optional boosting value for the query

fuzziness: Union[int, str]

Fuzziness value for the query

max_expansions: int

Maximum number of expansions for the query

prefix_length: int

Prefix length for the query

transpositions: bool

Whether to allow transpositions for the query

value: str

The value to search for.

class esorm.query.ESGeoDistance(*args, **kwargs)

Bases: dict

Represents a geo_distance query for distance-based geospatial queries in Elasticsearch.

distance: Union[str, float]

The distance to search for.

distance_type: str

The distance type to use for the query.

location: Union[Dict[str, float], str]

The location to search from.

location_field: str

The field containing the location to search from.

validation_method: str

The validation method to use for the query.

class esorm.query.ESKnnQuery(*args, **kwargs)

Bases: dict

Represents the parameters for a knn query in Elasticsearch.

field: str

The field to search on.

filter: Union[Dict[str, Any], List[Dict[str, Any]], None]

Optional filter to apply to the search.

k: int

The number of neighbors to return.

num_candidates: Optional[int]

The number of candidates to consider.

query_vector: List[float]

The query vector.

class esorm.query.ESMatch(*args, **kwargs)

Bases: dict

Represents the parameters for a match query in Elasticsearch.

analyzer: str

Optional analyzer to use for the query.

boost: Union[int, float]

Optional boosting value for the query.

fuzziness: Union[int, str]

Optional fuzziness value for the query.

max_expansions: int

Optional maximum number of expansions for the query.

operator: str

The operator to use for the query.

prefix_length: int

Optional prefix length for the query.

query: Union[str, int, float]

The value to search for.

zero_terms_query: str

Optional zero terms query for the query.

class esorm.query.ESMatchAll(*args, **kwargs)

Bases: dict

Represents a match_all query for matching all documents in Elasticsearch.

boost: float

Optional boosting value for the query

class esorm.query.ESMatchNone(*args, **kwargs)

Bases: dict

Represents a match_none query for matching no documents in Elasticsearch.

class esorm.query.ESMatchPhrase(*args, **kwargs)

Bases: dict

Represents the parameters for a match_phrase query in Elasticsearch.

analyzer: str

Optional analyzer to use for the query.

boost: Union[int, float]

Optional boosting value for the query.

query: str

The value to search for.

slop: int

Optional slop value for the query.

esorm.query.ESMust

Represents must queries in Elasticsearch

alias of List[Union[FieldRange, FieldTerm, FieldTerms, FieldMatch, FieldMatchPhrase, FieldExists, FieldWildcard, FieldPrefix, FieldFuzzy, FieldGeoDistance, FieldMatchAll, FieldESMatchNone, FieldBool, FieldKnn]]

esorm.query.ESMustNot

Represents must_not queries in Elasticsearch

alias of List[Union[FieldRange, FieldTerm, FieldTerms, FieldMatch, FieldMatchPhrase, FieldExists, FieldWildcard, FieldPrefix, FieldFuzzy, FieldGeoDistance, FieldMatchAll, FieldESMatchNone, FieldBool]]

class esorm.query.ESPrefix(*args, **kwargs)

Bases: dict

Represents a prefix query for prefix matching in Elasticsearch.

boost: float

Optional boosting value for the query

rewrite: str

Optional, method used to rewrite the query (e.g., “constant_score”, “scoring_boolean”)

value: str

The prefix to search for.

class esorm.query.ESQuery(*args, **kwargs)

Bases: dict

Elasticsearch query structure

aggs: Dict[str, ESAgg]

Aggregations query structure

bool: ESBool

Bool query structure

exists: ESExists

Exists query structure

fuzzy: Dict[str, ESFuzzy]

Fuzzy query structure

geo_distance: Dict[str, ESGeoDistance]

Geo distance query structure

knn: ESKnnQuery

KNN query structure

match: Dict[str, ESMatch]

Match query structure

match_all: ESMatchAll

Match all query structure

match_none: ESMatchNone

Match none query structure

match_phrase: Dict[str, ESMatchPhrase]

Match phrase query structure

prefix: Dict[str, ESPrefix]

Prefix query structure

term: Dict[str, ESTerm]

Term query structure

wildcard: Dict[str, ESWildcard]

Wildcard query structure

class esorm.query.ESRange(*args, **kwargs)

Bases: dict

Range query structure

gt: Union[int, float, str]

Greater than

gte: Union[int, float, str]

Greater than or equal

lt: Union[int, float, str]

Less than

lte: Union[int, float, str]

Less than or equal

esorm.query.ESShould

Represents should queries in Elasticsearch

alias of List[Union[FieldRange, FieldTerm, FieldTerms, FieldMatch, FieldMatchPhrase, FieldExists, FieldWildcard, FieldPrefix, FieldFuzzy, FieldGeoDistance, FieldMatchAll, FieldESMatchNone, FieldBool, FieldKnn]]

class esorm.query.ESTerm(*args, **kwargs)

Bases: dict

Represents the parameters for a term query in Elasticsearch.

boost: Union[int, float]

Optional boosting value for the query.

value: Union[str, int, float]

The value to search for.

class esorm.query.ESWildcard(*args, **kwargs)

Bases: dict

Represents a wildcard query for pattern matching in Elasticsearch.

boost: float

Optional boosting value for the query

case_insensitive: bool

Optional, whether the query is case insensitive.

rewrite: str

Optional, method used to rewrite the query (e.g., “constant_score”, “scoring_boolean”)

value: str

The pattern to search for. e.g., “te?t” or “test*”

class esorm.query.FieldBool(*args, **kwargs)

Bases: dict

Represents a bool query for combining other queries in Elasticsearch.

bool: ESBool

Bool query structure

class esorm.query.FieldESMatchNone(*args, **kwargs)

Bases: dict

Represents a match_none query for matching no documents in Elasticsearch.

match_none: ESMatchNone

Match none query structure

class esorm.query.FieldExists(*args, **kwargs)

Bases: dict

Represents an exists query to check if a field exists in Elasticsearch.

exists: ESExists

Exists query structure

class esorm.query.FieldFuzzy(*args, **kwargs)

Bases: dict

Represents a fuzzy query for approximate matching in Elasticsearch.

fuzzy: Dict[str, ESFuzzy]

Fuzzy query structure

class esorm.query.FieldGeoDistance(*args, **kwargs)

Bases: dict

Represents a geo_distance query for distance-based geospatial queries in Elasticsearch.

geo_distance: Dict[str, ESGeoDistance]

Geo distance query structure

class esorm.query.FieldKnn(*args, **kwargs)

Bases: dict

Represents a knn query for vector similarity search in Elasticsearch.

knn: ESKnnQuery

KNN query structure

class esorm.query.FieldMatch(*args, **kwargs)

Bases: dict

Represents a match query for matching based on the provided text in Elasticsearch.

match: Dict[str, ESMatch]

Match query structure

class esorm.query.FieldMatchAll(*args, **kwargs)

Bases: dict

Represents a match_all query for matching all documents in Elasticsearch.

match_all: ESMatchAll

Match all query structure

class esorm.query.FieldMatchPhrase(*args, **kwargs)

Bases: dict

Represents a match_phrase query for exact phrase matching in Elasticsearch.

match_phrase: Dict[str, ESMatchPhrase]

Match phrase query structure

class esorm.query.FieldPrefix(*args, **kwargs)

Bases: dict

Represents a prefix query for prefix matching in Elasticsearch.

prefix: Dict[str, ESPrefix]

Prefix query structure

class esorm.query.FieldRange(*args, **kwargs)

Bases: dict

Range qyery field

range: Dict[str, ESRange]

Range query structure

class esorm.query.FieldTerm(*args, **kwargs)

Bases: dict

Represents a term query for exact value matching in Elasticsearch.

term: Dict[str, ESTerm]

Term query structure

class esorm.query.FieldTerms(*args, **kwargs)

Bases: dict

Represents a terms query for exact value matching in Elasticsearch.

terms: Dict[str, List[Union[str, int, float]]]

Terms query structure

class esorm.query.FieldWildcard(*args, **kwargs)

Bases: dict

Represents a wildcard query for pattern matching in Elasticsearch.

wildcard: Dict[str, ESWildcard]

Wildcard query structure

esorm.response module

This module contains type definitions for the response from Elasticsearch.

class esorm.response.ESResponse(*args, **kwargs)

Bases: dict

Represents the overall structure of an Elasticsearch response.

aggregations: Dict[str, Union[ESAggValueResponse, ESAggTermsResponse, ESAggHistogramResponse]]

The aggregations section of the response.

hits: Hits

The hits section of the response.

timed_out: bool

Whether the query timed out.

took: int

The time in milliseconds it took to execute the query.

class esorm.response.Hit(*args, **kwargs)

Bases: dict

Represents a single hit (result) from Elasticsearch.

class esorm.response.Hits(*args, **kwargs)

Bases: dict

Represents the hits section of the Elasticsearch response.

hits: List[Hit]

List of hits.

max_score: Optional[float]

The maximum score of the hits.

total: Dict[str, int]

The total number of hits.

esorm.utils module

Utility functions

esorm.utils.camel_case(snake_str, capitalize_first=False)

Convert to camel case

Parameters:

• snake_str (str) – The string to convert to camel case

• capitalize_first (bool) – Capitalize the first letter

Returns:

Converted string

esorm.utils.snake_case(camel_str)

Convert to snake case

Parameters:

camel_str (str) – The string to convert to snake case

Returns:

Converted string

esorm.utils.utcnow()

Get current UTC time

Returns:

Current UTC time

esorm.watcher module