ESORM

https://esorm.readthedocs.io/en/latest/
Admin
ESORM is a Python ElasticSearch Object Relational Mapper (ORM) based on Pydantic that provides async...
Tokens:32,625
Snippets:278
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install ESORM

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Install the ESORM package using pip. This command installs the library and its dependencies.

```bash
pip install pyesorm

```

--------------------------------

### Setup Mappings from Models

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Automatically create indices and mappings in Elasticsearch based on defined ESORM model classes. Ensure all model classes are imported first, as they are registered globally.

```python
from esorm import setup_mappings


# Create indices and mappings
async def prepare_es():
    import models  # Import your models
    # Here models argument is not needed, but you can pass it to prevent unused import warning
    await setup_mappings(models)
```

--------------------------------

### Connect with Advanced Options

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Connect to Elasticsearch with additional options like waiting for readiness and enabling sniffing on start and connection failure. These options are passed directly to the underlying AsyncElasticsearch constructor.

```python
from esorm import connect


async def es_init():
    await connect('localhost:9200', wait=True, sniff_on_start=True, sniff_on_connection_fail=True)
```

--------------------------------

### Implement FastAPI Pagination and Sorting with ESORM

Source: https://esorm.readthedocs.io/en/latest/advanced_usage.html

Shows how to add pagination and sorting capabilities to FastAPI endpoints using ESORM's dependencies. This setup allows for dynamic control over data retrieval, including setting default page size and defining sortable fields.

```python
from typing import List
from esorm import ESModelTimestamp, Pagination, Sort
from fastapi import FastAPI, Depends

from esorm.fastapi import make_dep_sort, make_dep_pagination


class User(ESModelTimestamp):
    """ The User model """
    first_name: str
    last_name: str


app = FastAPI()

@app.get("/all_users")
async def all_users(
    # This will create a _page, and a _page_size query parameter for the endpoint
    pagination: Pagination = Depends(make_dep_pagination(default_page=1, default_page_size=10)),
    # This will create a _sort enum query parameter for the endpoint, so it is selectable in swagger UI
    sort: Sort = Depends(make_dep_sort(
        first_name_last_name_asc=  # This is the name of the 1st sort option
        # Definition of the sort options
        [
            {'first_name': {"order": "asc"}},
            {'last_name': {"order": "asc"}},
        ],
        last_name_first_name_asc=  # This is the name of the 2nd sort option
        # Definition of the sort options
        [
            {'last_name': {"order": "asc"}},
            {'first_name': {"order": "asc"}},
        ]
    )),
) -> List[User]:
    """ Get all users """
    return await sort(pagination(User)).all()

```

--------------------------------

### Retrieve Selected Fields Using _source

Source: https://esorm.readthedocs.io/en/latest/advanced_usage.html

Specify the fields to retrieve using the _source argument in search and get methods. Ensure default values are provided for all fields in the model.

```python
import esorm

class Model(esorm.ESModel):
    f_int: int = 0
    f_str: str = 'a'


async def test_source():
    doc = Model(f_int=1, f_str='b')
    doc_id = await doc.save()

    doc = await Model.get(doc_id)
    assert doc.f_str == 'b'
    assert doc.f_int == 1

    doc = await Model.search_one_by_fields(dict(_id=doc_id), _source=['f_str'])
    assert doc.f_str == 'b'
    assert doc.f_int == 0

    doc = await Model.search_one_by_fields(dict(_id=doc_id), _source=['f_int'])
    assert doc.f_str == 'a'
    assert doc.f_int == 1

    doc = await Model.get(doc_id, _source=['f_str'])
    assert doc.f_str == 'b'
    assert doc.f_int == 0

    doc = await Model.get(doc_id, _source=['f_int'])
    assert doc.f_str == 'a'
    assert doc.f_int == 1
```

--------------------------------

### Prefix Query

Source: https://esorm.readthedocs.io/en/latest/_modules/esorm/query.html

Defines a prefix query to find documents where a field starts with a specified prefix.

```APIDOC
## Prefix Query

### Description
Defines a prefix query to find documents where a field starts with a specified prefix.

### Structure
```python
class ESPrefix(TypedDict, total=False):
    value: str
    boost: float
    rewrite: str

class FieldPrefix(TypedDict):
    prefix: Dict[str, ESPrefix]
```

### Example Usage (Conceptual)
```json
{
  "prefix": {
    "field_name": {
      "value": "prefix_value"
    }
  }
}
```
```

--------------------------------

### async connect()

Source: https://esorm.readthedocs.io/en/latest/_modules/esorm/esorm.html

Establishes a connection to the ElasticSearch cluster and initializes the global client proxy.

```APIDOC
## connect(hosts, *args, wait=False, **kwargs)

### Description
Connects to an ElasticSearch instance and sets the global client proxy. Optionally waits for the cluster to be ready.

### Parameters
#### Arguments
- **hosts** (Union[str, List, Mapping]) - Required - ElasticSearch hosts to connect to.
- **args** (list) - Optional - Additional positional arguments for AsyncElasticsearch.
- **wait** (bool) - Optional - If True, blocks until the ElasticSearch cluster is reachable.
- **kwargs** (dict) - Optional - Additional keyword arguments for AsyncElasticsearch.

### Response
- **client** (AsyncElasticsearch) - The initialized ElasticSearch client instance.
```

--------------------------------

### Get Elasticsearch Version

Source: https://esorm.readthedocs.io/en/latest/esorm.html

Retrieves the version string of the connected Elasticsearch cluster.

```APIDOC
## get_es_version()

### Description
Fetches the version information from the connected Elasticsearch cluster.

### Response
- **Returns** (str) - The version string of the Elasticsearch cluster.
```

--------------------------------

### Get ElasticSearch Version

Source: https://esorm.readthedocs.io/en/latest/_modules/esorm/esorm.html

Retrieves the version number of the connected ElasticSearch instance. Assumes a client has already been connected.

```python
async def get_es_version() -> str:
    """
    Get ElasticSearch version

    :return: ElasticSearch version
    """
    info = await es.info()
    return info['version']['number']
```

--------------------------------

### Define Wildcard and Prefix Query Structures

Source: https://esorm.readthedocs.io/en/latest/_modules/esorm/query.html

Use ESWildcard, FieldWildcard, ESPrefix, and FieldPrefix for pattern and prefix matching.

```python
class ESWildcard(TypedDict, total=False):
    """
    Represents a wildcard query for pattern matching in Elasticsearch.
    """
    value: str
    """ The pattern to search for. e.g., "te?t" or "test*" """
    boost: float
    """ Optional boosting value for the query """
    rewrite: str
    """ Optional, method used to rewrite the query (e.g., "constant_score", "scoring_boolean") """
    case_insensitive: bool
    """ Optional, whether the query is case insensitive. """



class FieldWildcard(TypedDict):
    """
    Represents a wildcard query for pattern matching in Elasticsearch.
    """
    wildcard: Dict[str, ESWildcard]
    """ Wildcard query structure """



class ESPrefix(TypedDict, total=False):
    """
    Represents a prefix query for prefix matching in Elasticsearch.
    """
    value: str
    """ The prefix to search for. """
    boost: float
    """ Optional boosting value for the query """
    rewrite: str
    """ Optional, method used to rewrite the query (e.g., "constant_score", "scoring_boolean") """



class FieldPrefix(TypedDict):
    """
    Represents a prefix query for prefix matching in Elasticsearch.
    """
    prefix: Dict[str, ESPrefix]
    """ Prefix query structure """
```

--------------------------------

### Get User Document by ID

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Retrieve a document from Elasticsearch by its ID using an ESORM model. The retrieved document will have its attributes populated.

```python
from esorm import ESModel


# Here the model have automatically generated id
class User(ESModel):
    name: str
    age: int


async def get_user(user_id: str):
    user = await User.get(user_id)
    print(user.name)
```

--------------------------------

### Bulk Create Users with Immediate Refresh

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Performs bulk creation of user documents and forces an immediate refresh of the index. Useful for testing or when immediate visibility of changes is critical.

```python
from typing import List
from esorm import ESModel, ESBulk


# Here the model have automatically generated id
class User(ESModel):
    name: str
    age: int


async def bulk_create_users_immediate():
    async with ESBulk(refresh=True) as bulk:  # Force immediate refresh
        for i in range(10):
            user = User(name=f'User {i}', age=i)
            await bulk.save(user)
```

--------------------------------

### Connect and Wait for Node Readiness

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Connect to Elasticsearch and wait for the node to become ready before proceeding. This is recommended for ensuring stability.

```python
from esorm import connect


async def es_init():
    await connect('localhost:9200', wait=True)
```

--------------------------------

### Get Current UTC Time

Source: https://esorm.readthedocs.io/en/latest/_modules/esorm/utils.html

Retrieves the current time in Coordinated Universal Time (UTC). Ensures timezone-aware datetime objects are used.

```python
def utcnow():
    """
    Get current UTC time

    :return: Current UTC time
    """
    return datetime.datetime.now(datetime.timezone.utc)
```

--------------------------------

### Connect to Elasticsearch

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Connect to a single Elasticsearch instance using a connection string. Ensure the 'esorm' library is imported.

```python
from esorm import connect


async def es_init():
    await connect('localhost:9200')
```

--------------------------------

### Connect to ElasticSearch

Source: https://esorm.readthedocs.io/en/latest/_modules/esorm/esorm.html

Establishes a connection to ElasticSearch. Optionally waits for the client to be ready. Requires `AsyncElasticsearch` and `asyncio`.

```python
async def connect(hosts: Union[str, Union[List[Union[str, Mapping[str, Union[str, int]], NodeConfig]], None]],
                  *args, wait=False, **kwargs) -> Optional[AsyncElasticsearch]:
    """
    Connect to ElasticSearch

    :param hosts: ElasticSearch hosts to connect, either a list a mapping, or a single string
    :param args: Other AsyncElasticsearch arguments
    :param wait: Wait for AsyncElasticsearch to be ready
    :param kwargs: Other AsyncElasticsearch keyword arguments
    :return: AsyncElasticsearch client instance
    """
    cast(_ESProxy, es).set_client(AsyncElasticsearch(hosts=hosts, *args, **kwargs))

    try:
        logger.info(f"Connecting to ElasticSearch ({hosts})…")
        if wait:
            # Wait for ES to start, this will block until ES is ready to prevent routers start early
            while True:
                status = await es.ping()
                if not status:
                    logger.info("Waiting for ElasticSearch to be ready…")
                    await asyncio.sleep(2.0)
                else:
                    break

        return es

    except asyncio.CancelledError:
        return None
```

--------------------------------

### Integrate ESORM with FastAPI for User Management

Source: https://esorm.readthedocs.io/en/latest/advanced_usage.html

Demonstrates how to use ESORM models with FastAPI for creating and retrieving user data. This includes defining a User model inheriting from ESModelTimestamp and creating API endpoints for user creation and searching.

```python
from typing import List, Optional
from esorm import ESModelTimestamp
from fastapi import FastAPI


class User(ESModelTimestamp):
    """ The User model """
    first_name: str
    last_name: str


app = FastAPI()


@app.post("/users")
async def create_user(first_name: str, last_name: str) -> User:
    """ Create a new user """
    user = User(first_name=first_name, last_name=last_name)
    await user.save()
    return user


@app.get("/users")
async def users(first_name: Optional[str] = None, last_name: Optional[str] = None) -> List[User]:
    """ Search users """
    return await User.search_by_fields(first_name=first_name, last_name=last_name)

```

--------------------------------

### Bulk Create Users

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Performs bulk creation of multiple user documents. This is significantly faster than individual save operations for large datasets.

```python
from typing import List
from esorm import ESModel, ESBulk


# Here the model have automatically generated id
class User(ESModel):
    name: str
    age: int


async def bulk_create_users():
    async with ESBulk() as bulk:
        # Creating or modifiying models
        for i in range(10):
            user = User(name=f'User {i}', age=i)
            await bulk.save(user)
```

--------------------------------

### ESORM Utilities Module

Source: https://esorm.readthedocs.io/en/latest/esorm.html

Lists utility functions for common tasks like case conversion and time handling.

```APIDOC
## ESORM Utilities Module

### Description
Offers helper functions for various utility tasks within the ESORM library.

### Functions
- `camel_case()`: Converts strings to camelCase.
- `snake_case()`: Converts strings to snake_case.
- `utcnow()`: Returns the current UTC time.
```

--------------------------------

### esorm.utils Module

Source: https://esorm.readthedocs.io/en/latest/_sources/esorm.rst.txt

Details the members, undocumented members, and inheritance of the esorm.utils submodule.

```APIDOC
## esorm.utils Module

### Description
Details the members, undocumented members, and inheritance of the esorm.utils submodule.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Define Exists Query Structures

Source: https://esorm.readthedocs.io/en/latest/_modules/esorm/query.html

Use ESExists and FieldExists to verify the presence of a field in documents.

```python
class ESExists(TypedDict):
    """
    Represents an exists query to check if a field exists.
    """
    field: str
    """ The field to check. """



class FieldExists(TypedDict):
    """
    Represents an exists query to check if a field exists in Elasticsearch.
    """
    exists: ESExists
    """ Exists query structure """
```

--------------------------------

### esorm.bulk Module

Source: https://esorm.readthedocs.io/en/latest/_sources/esorm.rst.txt

Details the members, undocumented members, and inheritance of the esorm.bulk submodule.

```APIDOC
## esorm.bulk Module

### Description
Details the members, undocumented members, and inheritance of the esorm.bulk submodule.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Define Term and Terms Query Structures

Source: https://esorm.readthedocs.io/en/latest/_modules/esorm/query.html

Use ESTerm, FieldTerm, and FieldTerms for exact value matching queries.

```python
class ESTerm(TypedDict, total=False):
    """
    Represents the parameters for a term query in Elasticsearch.
    """
    value: Union[str, int, float]
    """ The value to search for. """
    boost: Union[int, float]
    """ Optional boosting value for the query. """



class FieldTerm(TypedDict):
    """
    Represents a term query for exact value matching in Elasticsearch.
    """
    term: Dict[str, ESTerm]
    """ Term query structure """



class FieldTerms(TypedDict):
    """
    Represents a terms query for exact value matching in Elasticsearch.
    """
    terms: Dict[str, List[Union[str, int, float]]]
    """ Terms query structure """
```

--------------------------------

### Connect to Elasticsearch

Source: https://esorm.readthedocs.io/en/latest/esorm.html

Establishes an asynchronous connection to an Elasticsearch cluster.

```APIDOC
## connect(hosts, *args, wait=False, **kwargs)

### Description
Connects to an Elasticsearch instance using the provided host configurations.

### Parameters
#### Arguments
- **hosts** (Union[str, List[Union[str, Mapping[str, Union[str, int]], NodeConfig]], None]) - Required - Elasticsearch hosts to connect to.
- **args** (Any) - Optional - Additional AsyncElasticsearch arguments.
- **wait** (bool) - Optional - Whether to wait for the client to be ready.
- **kwargs** (Any) - Optional - Additional AsyncElasticsearch keyword arguments.

### Response
- **Returns** (Optional[AsyncElasticsearch]) - An instance of the AsyncElasticsearch client.
```

--------------------------------

### Module Structure

Source: https://esorm.readthedocs.io/en/latest/genindex.html

Overview of the ESORM module structure.

```APIDOC
## ESORM Modules

- **esorm.aggs**: Contains aggregation related classes and functions.
- **esorm.error**: Contains error handling classes.
- **esorm.esorm**: Main ESORM module.
- **esorm.logger**: Logging utilities.
- **esorm.query**: Contains query construction classes and functions.
- **esorm.response**: Contains classes for handling search responses.
- **esorm.utils**: Utility functions.
```

--------------------------------

### Immediate Refresh for Critical Visibility

Source: https://esorm.readthedocs.io/en/latest/_sources/changelog.rst.txt

Use `refresh=True` for operations where immediate visibility of changes is critical, such as in testing scenarios. Be aware this can impact performance under heavy load.

```python
# Example not provided in source, but implied by description
```

--------------------------------

### Handle conflicts in bulk operations

Source: https://esorm.readthedocs.io/en/latest/advanced_usage.html

Shows how to manage concurrency conflicts within an ESBulk context manager.

```python
from esorm import ESModel, ESBulk, error


class User(ESModel):
    first_name: str
    last_name: str


async def test_bulk():
    # Load the user
    user_load1 = await User.get(id = 1)
    # Load again
    user_load2 = await User.get(id = 1)
    # Here both have the same _seq_no and _primary_term
    try:
        async with ESBulk(wait_for=True) as bulk:
            user_load1.first_name = "John"
            await bulk.save(user_load1)
            user_load2.first_name = "Jane"
            await bulk.save(user_load2)  #
    except error.BulkError as e:
        # You can get the failed operations from e.failed_operations
        print("Bulk error:", e.failed_operations)
```

--------------------------------

### Describe ESORM Fields Using Docstrings

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Provide descriptions for ESORM model fields using docstrings immediately after the field definition. This is an alternative to using Pydantic's `TextField` for documentation purposes.

```python
from esorm import ESModel
from esorm.fields import TextField


class User(ESModel):
    name: str = 'John Doe'
    """ The name of the user """
    age: int = 18
    """ The age of the user """

    # This is the usual Pydantic way, but I think docstrings are more intuitive and readable
    address: str = TextField(description="The address of the user")
```

--------------------------------

### Paginate Search Results with Callback

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Decorate a model with `Pagination` to handle pagination. A callback function can process the total number of documents found.

```python
from esorm.model import ESModel, Pagination


class User(ESModel):
    id: int  # This will be used as the document _id in the index
    name: str
    age: int


def get_users(page = 1, page_size = 10):

    def pagination_callback(total: int):
        # You may set a header value or something else here
        print(f'Total users: {total}')

    # 1st create the decorator itself
    pagination = Pagination(page=page, page_size=page_size)

    # Then decorate your model
    res = pagination(User).search_by_fields(age=18)

    # Here the result has maximum 10 items
    return res

```

--------------------------------

### esorm.fastapi Module

Source: https://esorm.readthedocs.io/en/latest/_sources/esorm.rst.txt

Details the members, undocumented members, and inheritance of the esorm.fastapi submodule.

```APIDOC
## esorm.fastapi Module

### Description
Details the members, undocumented members, and inheritance of the esorm.fastapi submodule.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Utility Functions

Source: https://esorm.readthedocs.io/en/latest/_modules/esorm/utils.html

A collection of utility functions for string manipulation and time retrieval.

```APIDOC
## snake_case

### Description
Converts a camelCase string to snake_case.

### Parameters
- **camel_str** (str) - Required - The string to convert to snake case.

### Response
- **return** (str) - Converted string.

---

## camel_case

### Description
Converts a snake_case string to camelCase.

### Parameters
- **snake_str** (str) - Required - The string to convert to camel case.
- **capitalize_first** (bool) - Optional - Capitalize the first letter.

### Response
- **return** (str) - Converted string.

---

## utcnow

### Description
Retrieves the current UTC time.

### Response
- **return** (datetime) - Current UTC time.
```

--------------------------------

### Handle race conditions with ESORM

Source: https://esorm.readthedocs.io/en/latest/advanced_usage.html

Demonstrates catching ConflictError when multiple instances of the same document are updated or deleted.

```python
from esorm import ESModel


class User(ESModel):
    first_name: str
    last_name: str


async def test_race_condition():
    """ Update the user """
    from elasticsearch import ConflictError

    # Load the user
    user_load1 = await User.get(id = 1)
    # Load again
    user_load2 = await User.get(id = 1)
    # Here both have the same _seq_no and _primary_term

    try:
        # Update the 1st loaded user
        user_load1.first_name = "John"
        await user_load1.save()
        # Update the 2nd loaded user
        user_load2.first_name = "Jane"
        await user_load2.save()   # This will raise a ConflictError
    except ConflictError:
        print("Conflict error")

    # Load the user
    user_load1 = await User.get(id = 1)
    # Load again
    user_load2 = await User.get(id = 1)
    # Here both have the same _seq_no and _primary_term

    # Delete operation
    try:
        user_load1.first_name = "John"
        await user_load1.save()
        await user_load2.delete()  # This will raise a ConflictError
    except ConflictError:
        print("Conflict error")
```

--------------------------------

### Define Match and Match Phrase Query Structures

Source: https://esorm.readthedocs.io/en/latest/_modules/esorm/query.html

Use ESMatch, FieldMatch, ESMatchPhrase, and FieldMatchPhrase for text-based search queries.

```python
class ESMatch(TypedDict, total=False):
    """
    Represents the parameters for a match query in Elasticsearch.
    """
    query: Union[str, int, float]
    """ The value to search for. """
    operator: str
    """ The operator to use for the query. """
    boost: Union[int, float]
    """ Optional boosting value for the query. """
    analyzer: str
    """ Optional analyzer to use for the query. """
    fuzziness: Union[int, str]
    """ Optional fuzziness value for the query. """
    prefix_length: int
    """ Optional prefix length for the query. """
    max_expansions: int
    """ Optional maximum number of expansions for the query. """
    zero_terms_query: str
    """ Optional zero terms query for the query. """



class FieldMatch(TypedDict):
    """
    Represents a match query for matching based on the provided text in Elasticsearch.
    """
    match: Dict[str, ESMatch]
    """ Match query structure """



class ESMatchPhrase(TypedDict, total=False):
    """
    Represents the parameters for a match_phrase query in Elasticsearch.
    """
    query: str
    """ The value to search for. """
    analyzer: str
    """ Optional analyzer to use for the query. """
    boost: Union[int, float]
    """ Optional boosting value for the query. """
    slop: int
    """ Optional slop value for the query. """



class FieldMatchPhrase(TypedDict):
    """
    Represents a match_phrase query for exact phrase matching in Elasticsearch.
    """
    match_phrase: Dict[str, ESMatchPhrase]
    """ Match phrase query structure """
```

--------------------------------

### Date Histogram Aggregation Parameters

Source: https://esorm.readthedocs.io/en/latest/changelog.html

Configure date histogram aggregations with various parameters like calendar_interval, fixed_interval, format, and time_zone for precise time-based bucketing.

```python
ESDateHistogramParams(calendar_interval='1d', format='yyyy-MM-dd', time_zone='UTC')
```

--------------------------------

### Connect to Multiple Elasticsearch Hosts

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Connect to a cluster of Elasticsearch instances by providing a list of host connection strings. This is useful for high availability.

```python
from esorm import connect


async def es_init():
    await connect(['localhost:9200', 'localhost:9200'])
```

--------------------------------

### Error Handling

Source: https://esorm.readthedocs.io/en/latest/reference.html

List of custom exceptions used within the ESORM library.

```APIDOC
## esorm.error module

### Description
Defines specific error classes for handling Elasticsearch and bulk operation failures.

### Exceptions
- **BulkError**: Raised during bulk operation failures.
- **BulkOperationError**: Specific error for a single bulk operation.
- **ConflictError**: Raised on version conflicts.
- **IndexDoesNotFoundError**: Raised when an index is missing.
- **InvalidModelError**: Raised when a model definition is invalid.
- **InvalidResponseError**: Raised when the Elasticsearch response cannot be parsed.
- **NotFoundError**: Generic error for missing resources.
```

--------------------------------

### esorm.query Module

Source: https://esorm.readthedocs.io/en/latest/_sources/esorm.rst.txt

Details the members, undocumented members, and inheritance of the esorm.query submodule.

```APIDOC
## esorm.query Module

### Description
Details the members, undocumented members, and inheritance of the esorm.query submodule.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### esorm.esorm Module

Source: https://esorm.readthedocs.io/en/latest/_sources/esorm.rst.txt

Details the members, undocumented members, and inheritance of the esorm.esorm submodule.

```APIDOC
## esorm.esorm Module

### Description
Details the members, undocumented members, and inheritance of the esorm.esorm submodule.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### esorm.response Module

Source: https://esorm.readthedocs.io/en/latest/_sources/esorm.rst.txt

Details the members, undocumented members, and inheritance of the esorm.response submodule.

```APIDOC
## esorm.response Module

### Description
Details the members, undocumented members, and inheritance of the esorm.response submodule.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Combine keyword shortcut with custom subfields

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Mix the keyword shortcut with custom field definitions, noting that custom configurations for 'keyword' take precedence.

```python
class Product(ESModel):
    # Both keyword and custom fields
    title: str = TextField(..., keyword=True, fields={
        'suggest': {'type': 'completion'},
        'ngram': {'type': 'text', 'analyzer': 'ngram'}
    })
    # Results in: {
    #     'keyword': {'type': 'keyword'},  # Added automatically
    #     'suggest': {'type': 'completion'},
    #     'ngram': {'type': 'text', 'analyzer': 'ngram'}
    # }

    # Custom keyword configuration takes precedence
    name: str = TextField(..., keyword=True, fields={
        'keyword': {'type': 'keyword', 'ignore_above': 512}  # Custom config preserved
    })
```

--------------------------------

### Query Construction

Source: https://esorm.readthedocs.io/en/latest/reference.html

Overview of the query module components used for building Elasticsearch queries.

```APIDOC
## esorm.query module

### Description
Contains classes for building various Elasticsearch queries including boolean, term, match, range, and geo-spatial queries.

### Components
- **Query Types**: ESBool, ESExists, ESFilter, ESFuzzy, ESGeoDistance, ESKnnQuery, ESMatch, ESMatchAll, ESMatchNone, ESMatchPhrase, ESMultiMatch, ESMust, ESMustNot, ESPrefix, ESRange, ESShould, ESTerm, ESWildcard.
- **Field Helpers**: FieldBool, FieldESMatchNone, FieldExists, FieldFuzzy, FieldGeoDistance, FieldKnn, FieldMatch, FieldMatchAll, FieldMatchPhrase, FieldPrefix, FieldRange, FieldTerm, FieldTerms, FieldWildcard.
```

--------------------------------

### General Search for Users

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Searches for documents matching a specified query. Results can be returned as a list of model instances or a dictionary keyed by document ID using `res_dict=True`.

```python
from esorm import ESModel


# Here the model have automatically generated id
class User(ESModel):
    name: str
    age: int


async def search_users():
    # Search for users at least 18 years old
    users = await User.search(
        query={
            'bool': {
                'must': [{
                    'range': {
                        'age': {
                            'gte': 18
                        }
                    }
                }]
            }
        }
    )
    for user in users:
        print(user.name)
```

--------------------------------

### esorm.watcher Module

Source: https://esorm.readthedocs.io/en/latest/_sources/esorm.rst.txt

Details the members, undocumented members, and inheritance of the esorm.watcher submodule.

```APIDOC
## esorm.watcher Module

### Description
Details the members, undocumented members, and inheritance of the esorm.watcher submodule.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Utility Functions

Source: https://esorm.readthedocs.io/en/latest/genindex.html

Utility functions available in ESORM.

```APIDOC
## Utility Functions

### snake_case()
- **Description**: Converts a string to snake_case.
- **Module**: `esorm.utils`

### utcnow()
- **Description**: Returns the current UTC time.
- **Module**: `esorm.utils`
```

--------------------------------

### Connection Management

Source: https://esorm.readthedocs.io/en/latest/reference.html

Functions for establishing connections and retrieving Elasticsearch version information.

```APIDOC
## esorm.esorm module

### Description
Provides core functionality for connecting to the Elasticsearch cluster and checking the version.

### Methods
- **connect()**: Establishes a connection to the Elasticsearch instance.
- **get_es_version()**: Retrieves the version of the connected Elasticsearch instance.
```

--------------------------------

### Perform Vector Search with kNN

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Execute k-nearest neighbors (kNN) search on a vector field. Requires a field name, query vector, k value, and optionally num_candidates.

```python
# Vector search using kNN
results = await Document.search({
    "knn": {
        "field": "embedding",
        "query_vector": [0.1, 0.2, ...],  # your query vector
        "k": 10,  # number of neighbors to return
        "num_candidates": 100  # number of candidates to consider
    }
})

```

--------------------------------

### esorm.model Module

Source: https://esorm.readthedocs.io/en/latest/_sources/esorm.rst.txt

Details the members, undocumented members, and inheritance of the esorm.model submodule.

```APIDOC
## esorm.model Module

### Description
Details the members, undocumented members, and inheritance of the esorm.model submodule.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### ESORM Field Types and Definitions

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Overview of how to define model fields using ESORM's field types and specialized field definition functions.

```APIDOC
## Field Definitions

### Description
ESORM allows mapping Python model attributes to Elasticsearch field types using the `esorm.fields` module. Fields can be defined using simple type annotations or specialized classes for advanced configuration.

### Supported Field Types
- `keyword`, `text`, `binary`, `byte`, `short`, `integer` (or `int32`), `long` (or `int64`), `unsigned_long` (or `uint64`), `float16` (or `half_float`), `float32` (or `float`), `double`, `boolean`, `geo_point`, `dense_vector`.

### Example
```python
from esorm import ESModel
from esorm.fields import TextField, NumericField, DenseVectorField

class Product(ESModel):
    id: str
    name: str = TextField(..., min_length=3, max_length=100)
    price: float = NumericField(..., gt=0)
    embedding: dense_vector = DenseVectorField(..., dims=384, similarity="cosine")
```
```

--------------------------------

### esorm Module

Source: https://esorm.readthedocs.io/en/latest/_sources/esorm.rst.txt

This section details the members, undocumented members, and inheritance of the main esorm module.

```APIDOC
## esorm Module

### Description
Details the members, undocumented members, and inheritance of the main esorm module.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Define fields with specialized configuration

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Use specialized field classes like TextField or NumericField for granular control over indexing parameters.

```python
from esorm.fields import Field, TextField, NumericField, DenseVectorField

class Product(ESModel):
    id: str
    name: str = TextField(..., min_length=3, max_length=100)
    price: float = NumericField(..., gt=0)
    is_available: bool = Field(True)
    location: geo_point
    embedding: dense_vector = DenseVectorField(..., dims=384, similarity="cosine")
```

--------------------------------

### Create Elasticsearch Index Template

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Create an index template in Elasticsearch using ESORM. This allows defining default settings and mappings for indices that match a specific pattern.

```python
from esorm import model as esorm_model


# Create index template
async def prepare_es():
    await esorm_model.create_index_template('default_template',
                                            prefix_name='esorm_',
                                            shards=3,
                                            auto_expand_replicas='1-5')
```

--------------------------------

### Aggregate User Count by Country

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Count the number of users in each country using a 'terms' aggregation. The results are iterated through buckets.

```python
async def aggregate_terms():
    # Get number of users by country
    aggs_def = {
        'countries': {
            'terms': {
                'field': 'country'
            }
        }
    }
    aggs = await User.aggregate(aggs_def)
    for bucket in aggs['countries']['buckets']:
        print(bucket['key'], bucket['doc_count'])

```

--------------------------------

### esorm.error Module

Source: https://esorm.readthedocs.io/en/latest/_sources/esorm.rst.txt

Details the members, undocumented members, and inheritance of the esorm.error submodule.

```APIDOC
## esorm.error Module

### Description
Details the members, undocumented members, and inheritance of the esorm.error submodule.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### esorm.logger Module

Source: https://esorm.readthedocs.io/en/latest/_sources/esorm.rst.txt

Details the members, undocumented members, and inheritance of the esorm.logger submodule.

```APIDOC
## esorm.logger Module

### Description
Details the members, undocumented members, and inheritance of the esorm.logger submodule.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### ESORM Utility Functions

Source: https://esorm.readthedocs.io/en/latest/genindex.html

Details on utility functions within the ESORM library.

```APIDOC
## ESORM Utility Functions

### get_es_version()
Function in module `esorm.esorm`.
```

--------------------------------

### ESORM Core Module

Source: https://esorm.readthedocs.io/en/latest/esorm.html

Details the core functions for connecting to Elasticsearch and retrieving its version.

```APIDOC
## ESORM Core Module

### Description
Provides essential functions for interacting with Elasticsearch, including connection management and version retrieval.

### Functions
- `connect()`: Establishes a connection to Elasticsearch.
- `get_es_version()`: Retrieves the version of the connected Elasticsearch instance.
```

--------------------------------

### Cardinality Aggregation Parameters

Source: https://esorm.readthedocs.io/en/latest/_modules/esorm/aggs.html

Parameters for the cardinality aggregation.

```APIDOC
## Cardinality Aggregation Parameters

### Description
Represents the parameters for a cardinality aggregation in Elasticsearch.

### Parameters
#### Request Body
- **field** (str) - Optional - The field to aggregate on.
- **precision_threshold** (int) - Optional - Precision threshold for the cardinality calculation (default: 3000).
- **missing** (Union[str, int, float]) - Optional - Value to use for documents missing the aggregation field.
```

--------------------------------

### esorm.fields Module

Source: https://esorm.readthedocs.io/en/latest/_sources/esorm.rst.txt

Details the members, undocumented members, and inheritance of the esorm.fields submodule.

```APIDOC
## esorm.fields Module

### Description
Details the members, undocumented members, and inheritance of the esorm.fields submodule.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### ESORM Query Parameters

Source: https://esorm.readthedocs.io/en/latest/genindex.html

Details on query-related parameters and classes within the ESORM library.

```APIDOC
## ESORM Query Parameters

### FieldBool
Class in `esorm.query`.

### FieldESMatchNone
Class in `esorm.query`.

### FieldExists
Class in `esorm.query`.

### FieldFuzzy
Class in `esorm.query`.

### FieldGeoDistance
Class in `esorm.query`.

### FieldKnn
Class in `esorm.query`.

### FieldMatch
Class in `esorm.query`.

### FieldMatchAll
Class in `esorm.query`.

### FieldMatchPhrase
Class in `esorm.query`.

### FieldPrefix
Class in `esorm.query`.

### FieldRange
Class in `esorm.query`.

### FieldTerm
Class in `esorm.query`.

### FieldTerms
Class in `esorm.query`.

### FieldWildcard
Class in `esorm.query`.

### ESExists
Class in `esorm.query`.

### ESKnnQuery
Class in `esorm.query`.

### ESMultiMatch
Attribute: `fields`

### ESBool
Attribute: `filter`

### ESRange
Attributes: `gt`, `gte`, `lt`, `lte`

### ESFuzzy
Attribute: `fuzziness`

### ESGeoDistance
Attributes: `location`, `location_field`

### ESQuery
Attributes: `fuzzy`, `geo_distance`, `knn`
```

--------------------------------

### esorm.aggs Module

Source: https://esorm.readthedocs.io/en/latest/_sources/esorm.rst.txt

Details the members, undocumented members, and inheritance of the esorm.aggs submodule.

```APIDOC
## esorm.aggs Module

### Description
Details the members, undocumented members, and inheritance of the esorm.aggs submodule.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

--------------------------------

### Define Range Query Structures

Source: https://esorm.readthedocs.io/en/latest/_modules/esorm/query.html

Use ESRange and FieldRange to define range-based queries with optional boundary constraints.

```python
class ESRange(TypedDict, total=False):
    """
    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 """



class FieldRange(TypedDict):
    """
    Range qyery field
    """
    range: Dict[str, ESRange]
    """ Range query structure """
```

--------------------------------

### Create User Document

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Create a new document in Elasticsearch using an ESORM model. The document will have an automatically generated ID. The `save()` method returns the ID of the created document.

```python
from esorm import ESModel


# Here the model have automatically generated id
class User(ESModel):
    name: str
    age: int


async def create_user():
    # Create a new user
    user = User(name='John Doe', age=25)
    # Save the user to ElasticSearch
    new_user_id = await user.save()
    print(new_user_id)
```

--------------------------------

### Ping Elasticsearch Client

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Retrieve the global proxy client instance and use it to ping the Elasticsearch cluster. This confirms the connection is active.

```python
from esorm import es


async def es_init():
    await es.ping()
```

--------------------------------

### Configure ESORM Model Settings with ESConfig

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Customize ESORM model behavior by defining an inner `ESConfig` class. This allows setting the index name, ID field, default sort order, and Elasticsearch index settings.

```python
from typing import Optional, List, Dict, Any
from esorm import ESModel


class User(ESModel):
    class ESConfig:
        """ ESModel Config """
        # The index name
        index: Optional[str] = None
        # The name of the 'id' field
        id_field: Optional[str] = None
        # Default sort
        default_sort: Optional[List[Dict[str, Dict[str, str]]]] = None
        # ElasticSearch index settings (https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html)
        settings: Optional[Dict[str, Any]] = None
        # Maximum recursion depth of lazy properties
        lazy_property_max_recursion_depth: int = 1
```

--------------------------------

### Retry model methods on conflict

Source: https://esorm.readthedocs.io/en/latest/advanced_usage.html

Demonstrates using retry_on_conflict on a model method, which automatically reloads the model instance before retrying.

```python
import asyncio
from esorm import ESModel, retry_on_conflict


class User(ESModel):
    first_name: str
    last_name: str
    logins: int = 0

    @retry_on_conflict(3, reload_on_conflict=True)  # reload_on_conflict is True by default
    async def login(self):
        self.logins += 1
        await self.save()

async def test_retry_on_conflict(user: User):
    user_1 = await User.get(user._id)
    user_2 = await User.get(user._id)
    user_3 = await User.get(user._id)
    # This won't raise a ConflictError, becaue the model reloads and retries the method on conflict
    await asyncio.gather(
        user_1.login(),
        user_2.login(),
        user_3.login(),
    )
```

--------------------------------

### Use ESModelTimestamp for Automatic Timestamps

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Inherit from `ESModelTimestamp` to automatically include `created_at` and `updated_at` fields in your model. These fields are managed by ESORM to store creation and last update times.

```python
from esorm import ESModelTimestamp


class User(ESModelTimestamp):
    name: str
    age: int
```

--------------------------------

### Bulk Delete Users with Wait

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Performs bulk deletion of multiple user documents and waits for the scheduled refresh to complete, ensuring consistency.

```python
from typing import List
from esorm import ESModel, ESBulk


# Here the model have automatically generated id
class User(ESModel):
    name: str
    age: int


async def bulk_delete_users(users: List[User]):
    async with ESBulk(wait_for=True) as bulk:  # Wait for scheduled refresh
        # Deleting models
        for user in users:
            await bulk.delete(user)
```

--------------------------------

### Save Document with Immediate Refresh

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Save a document to Elasticsearch and force an immediate refresh, making the changes visible to search operations right away. This can impact performance under heavy load.

```python
# Immediate refresh - changes immediately visible to search
await user.save(refresh=True)
```

--------------------------------

### ESORM Aggregation Parameters

Source: https://esorm.readthedocs.io/en/latest/genindex.html

Details on aggregation-related parameters and classes within the ESORM library.

```APIDOC
## ESORM Aggregation Parameters

### ESAggCardinalityParams
Attribute: `field`

### ESAggDateRangeParams
Attributes: `field`, `keyed`, `format`

### ESAggExtendedStatsParams
Attribute: `field`

### ESAggFieldParams
Attribute: `field`

### ESAggHistogramParams
Attribute: `field`, `interval`

### ESAggPercentilesParams
Attribute: `field`, `keyed`, `hdr`

### ESAggRangeParams
Attribute: `field`, `keyed`

### ESAggStatsParams
Attribute: `field`

### ESAggTermParams
Attribute: `field`

### ESAggValueCountParams
Attribute: `field`

### ESDateHistogramParams
Attributes: `field`, `fixed_interval`, `keyed`, `format`

### ESAgg
Attribute: `histogram`

### ESAggBucketResponse
Attribute: `key`

### ESAggDateRangeBucketResponse
Attributes: `from_`, `from_as_string`, `key`

### ESAggHistogramBucketresponse
Attribute: `key`

### ESAggRangeBucketResponse
Attributes: `from_`, `key`
```

--------------------------------

### Import necessary types for ESORM aggregations

Source: https://esorm.readthedocs.io/en/latest/_modules/esorm/aggs.html

Imports TypedDict, Dict, List, and Union for defining complex types. TypeAlias from typing_extensions is also imported for creating type aliases.

```python
from typing import TypedDict, Dict, List, Union
from typing_extensions import TypeAlias
```

--------------------------------

### Define List of Primitive Fields in ESORM Model

Source: https://esorm.readthedocs.io/en/latest/introduction.html

Use Python's typing.List to define fields that are lists of primitive types like strings or integers.

```python
from typing import List
from esorm import ESModel


class User(ESModel):
    emails: List[str]
    favorite_ids: List[int]
    ...
```

--------------------------------

### ESORM Custom Exceptions

Source: https://esorm.readthedocs.io/en/latest/_modules/esorm/error.html

This section details the custom exceptions provided by the ESORM library for error handling.

```APIDOC
## ESORM Error Exceptions

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

### NotFoundError

Raised when a model is not found.

### IndexDoesNotFoundError

Raised when an index does not exist.

### InvalidResponseError

Raised when the response from Elasticsearch is invalid.

### InvalidModelError

Raised when a model is invalid.

### ConflictError

Raised when a conflict occurs. You can manually raise this to retry operation with `retry_on_conflict` decorator.

### BulkOperationError

A dictionary type to represent an error in a bulk operation response from Elasticsearch.
- **status** (int) - The status code of the error
- **type** (str) - Type of the error
- **reason** (str) - A human-readable reason for the error
- **model** (ESModel) - The model object

### BulkError

Exception for handling bulk operation errors.
- **failed_operations** (List[BulkOperationError]) - A list of errors that occurred during the bulk operation.
```

--------------------------------

### Subfield Configuration

Source: https://esorm.readthedocs.io/en/latest/introduction.html

How to define subfields for exact matching, multiple analyzers, or custom indexing requirements.

```APIDOC
## Subfields

### Description
Subfields allow indexing the same data in multiple ways. You can use the `keyword=True` shortcut for exact matching or the `fields` parameter for custom subfield definitions.

### Custom Subfields Example
```python
class Product(ESModel):
    description: str = TextField(..., fields={
        'english': {'type': 'text', 'analyzer': 'english'},
        'spanish': {'type': 'text', 'analyzer': 'spanish'}
    })
```
```

--------------------------------

### Percentiles Aggregation Parameters

Source: https://esorm.readthedocs.io/en/latest/_modules/esorm/aggs.html

Parameters for the percentiles aggregation.

```APIDOC
## Percentiles Aggregation Parameters

### Description
Represents the parameters for a percentiles aggregation in Elasticsearch.

### Parameters
#### Request Body
- **field** (str) - Optional - The field to aggregate on.
- **percents** (List[float]) - Optional - Array of percentiles to compute (e.g., [25, 50, 75, 95, 99]).
- **keyed** (bool) - Optional - Whether to return percentiles as a hash instead of an array.
- **tdigest** (Dict[str, Union[int, float]]) - Optional - T-Digest algorithm configuration.
- **hdr** (Dict[str, int]) - Optional - HDR histogram configuration.
- **missing** (float) - Optional - Value to use for documents missing the aggregation field.
```
Tokens:
Raw