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

cardinality: ESAggCardinalityParams

Cardinality aggregation (count distinct values)

date_histogram: ESDateHistogramParams

Date histogram aggregation

date_range: ESAggDateRangeParams

Date range aggregation

extended_stats: ESAggExtendedStatsParams

Extended stats aggregation (includes variance, std deviation)

histogram: ESAggHistogramParams

Histogram aggregation

max: ESAggFieldParams

Maximum aggregation

min: ESAggFieldParams

Minimum aggregation

percentiles: ESAggPercentilesParams

Percentiles aggregation

range: ESAggRangeParams

Range aggregation

stats: ESAggStatsParams

Stats aggregation (count, min, max, avg, sum)

sum: ESAggFieldParams

Sum aggregation

terms: ESAggTermParams

Terms aggregation

value_count: ESAggValueCountParams

Value count 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.ESAggCardinalityParams(*args, **kwargs)

Bases: dict

Represents the parameters for a cardinality aggregation in Elasticsearch.

field: str

The field to aggregate on.

missing: Union[str, int, float]

Value to use for documents missing the aggregation field.

precision_threshold: int

Precision threshold for the cardinality calculation (default: 3000).

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

Bases: dict

Represents the response for a cardinality aggregation.

value: int

The approximate count of distinct values.

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

Bases: dict

Represents a single bucket in a date range aggregation.

doc_count: int

The number of documents in this bucket.

from_: str

The start date of the range (inclusive).

from_as_string: str

The start date as formatted string.

key: str

The key of the bucket.

to: str

The end date of the range (exclusive).

to_as_string: str

The end date as formatted string.

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

Bases: dict

Represents the parameters for a date range aggregation in Elasticsearch.

field: str

The field to aggregate on.

format: str

Date format for parsing range values.

keyed: bool

Whether to return buckets as a hash instead of an array.

ranges: List[Dict[str, str]]

Array of date range buckets (e.g., [{“to”: “2020-01-01”}, {“from”: “2020-01-01”}]).

time_zone: str

Time zone for date calculations.

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

Bases: dict

Represents the response for a date range aggregation.

buckets: List[ESAggDateRangeBucketResponse]

A list of buckets in the date range aggregation.

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.ESAggExtendedStatsParams(*args, **kwargs)

Bases: dict

Represents the parameters for an extended stats aggregation in Elasticsearch.

field: str

The field to aggregate on.

missing: float

Value to use for documents missing the aggregation field.

sigma: float

Number of standard deviations for bounds (default: 2.0).

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

Bases: dict

Represents the response for an extended stats aggregation.

avg: float

Average value.

count: int

Number of values.

max: float

Maximum value.

min: float

Minimum value.

std_deviation: float

Standard deviation.

std_deviation_bounds: Dict[str, float]

Upper and lower bounds based on std deviation.

std_deviation_population: float

Population standard deviation.

std_deviation_sampling: float

Sampling standard deviation.

sum: float

Sum of all values.

sum_of_squares: float

Sum of squares.

variance: float

Variance of the values.

variance_population: float

Population variance.

variance_sampling: float

Sampling variance.

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.ESAggPercentilesParams(*args, **kwargs)

Bases: dict

Represents the parameters for a percentiles aggregation in Elasticsearch.

field: str

The field to aggregate on.

hdr: Dict[str, int]

HDR histogram configuration.

keyed: bool

Whether to return percentiles as a hash instead of an array.

missing: float

Value to use for documents missing the aggregation field.

percents: List[float]

Array of percentiles to compute (e.g., [25, 50, 75, 95, 99]).

tdigest: Dict[str, Union[int, float]]

T-Digest algorithm configuration.

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

Bases: dict

Represents the response for a percentiles aggregation.

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

Bases: dict

Represents a single bucket in a range aggregation.

doc_count: int

The number of documents in this bucket.

from_: float

The start of the range (inclusive).

key: str

The key of the bucket.

to: float

The end of the range (exclusive).

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

Bases: dict

Represents the parameters for a range aggregation in Elasticsearch.

field: str

The field to aggregate on.

keyed: bool

Whether to return buckets as a hash instead of an array.

ranges: List[Dict[str, float]]

Array of range buckets (e.g., [{“to”: 50}, {“from”: 50, “to”: 100}, {“from”: 100}]).

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

Bases: dict

Represents the response for a range aggregation.

buckets: List[ESAggRangeBucketResponse]

A list of buckets in the range aggregation.

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

Bases: dict

Represents the parameters for a stats aggregation in Elasticsearch.

field: str

The field to aggregate on.

missing: float

Value to use for documents missing the aggregation field.

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

Bases: dict

Represents the response for a stats aggregation.

avg: float

Average value.

count: int

Number of values.

max: float

Maximum value.

min: float

Minimum value.

sum: float

Sum of all values.

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.ESAggValueCountParams(*args, **kwargs)

Bases: dict

Represents the parameters for a value count aggregation in Elasticsearch.

field: str

The field to count values for.

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, ESAggCardinalityResponse, ESAggPercentilesResponse, ESAggStatsResponse, ESAggExtendedStatsResponse, ESAggRangeResponse, ESAggDateRangeResponse]]

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

Bases: dict

Represents the parameters for a date histogram aggregation in Elasticsearch.

calendar_interval: str

Calendar-aware interval (e.g., “1M”, “1d”, “month”, “day”).

extended_bounds: ESAggExtendedBounds

The extended bounds of the histogram.

field: str

The field to aggregate on.

fixed_interval: str

Fixed interval in time units (e.g., “30s”, “1h”, “3h”).

format: str

Date format for bucket keys (e.g., “yyyy-MM-dd”).

keyed: bool

Whether to return buckets as a hash instead of an array.

min_doc_count: int

The minimum number of documents in a bucket.

missing: str

Value to use for documents missing the aggregation field.

offset: str

Offset to shift bucket boundaries (e.g., “+6h”, “-1d”).

order: Dict[str, str]

Order of the buckets (e.g., {“_key”: “asc”}).

time_zone: str

Time zone for bucketing (e.g., “+01:00”, “America/Los_Angeles”).

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, ESAggCardinalityResponse, ESAggPercentilesResponse, ESAggStatsResponse, ESAggExtendedStatsResponse, ESAggRangeResponse, ESAggDateRangeResponse]]

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