Skip to content

# odmantic.query

Bases: `Dict[str, Any]`

Base object used to build queries.

All comparison and logical operators returns `QueryExpression` objects.

The `|` and `&` operators are supported for respectively the or and the and logical operators.

Warning

When using those operators make sure to correctly bracket the expressions to avoid python operator precedence issues.

Source code in `odmantic/query.py`

     9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32

    class QueryExpression(Dict[str, Any]):
        """Base object used to build queries.

        All comparison and logical operators returns `QueryExpression` objects.

        The `|` and `&` operators are supported for respectively the
        [or][odmantic.query.or_] and the [and][odmantic.query.and_] logical operators.

        Warning:
            When using those operators make sure to correctly bracket the expressions
            to avoid python operator precedence issues.
        """

        def __repr__(self) -> str:
            parent_repr = super().__repr__()
            if parent_repr == "{}":
                parent_repr = ""
            return f"QueryExpression({parent_repr})"

        def __or__(self, other: "QueryExpression") -> "QueryExpression":  # type: ignore
            return or_(self, other)

        def __and__(self, other: "QueryExpression") -> "QueryExpression":
            return and_(self, other)

## Logical Operators

Logical AND operation between multiple `QueryExpression` objects.

Source code in `odmantic/query.py`

    38
    39
    40

    def and_(*elements: QueryDictBool) -> QueryExpression:
        """Logical **AND** operation between multiple `QueryExpression` objects."""
        return QueryExpression({"$and": elements})

Logical OR operation between multiple `QueryExpression` objects.

Source code in `odmantic/query.py`

    43
    44
    45

    def or_(*elements: QueryDictBool) -> QueryExpression:
        """Logical **OR** operation between multiple `QueryExpression` objects."""
        return QueryExpression({"$or": elements})

Logical NOR operation between multiple `QueryExpression` objects.

Source code in `odmantic/query.py`

    48
    49
    50

    def nor_(*elements: QueryDictBool) -> QueryExpression:
        """Logical **NOR** operation between multiple `QueryExpression` objects."""
        return QueryExpression({"$nor": elements})

## Comparison Operators

Equality comparison operator.

Source code in `odmantic/query.py`

    69
    70
    71

    def eq(field: FieldProxyAny, value: Any) -> QueryExpression:
        """Equality comparison operator."""
        return _cmp_expression(field, "$eq", value)

Inequality comparison operator (includes documents not containing the field).

Source code in `odmantic/query.py`

    74
    75
    76

    def ne(field: FieldProxyAny, value: Any) -> QueryExpression:
        """Inequality comparison operator (includes documents not containing the field)."""
        return _cmp_expression(field, "$ne", value)

Greater than (strict) comparison operator (i.e. >).

Source code in `odmantic/query.py`

    79
    80
    81

    def gt(field: FieldProxyAny, value: Any) -> QueryExpression:
        """Greater than (strict) comparison operator (i.e. >)."""
        return _cmp_expression(field, "$gt", value)

Greater than or equal comparison operator (i.e. >=).

Source code in `odmantic/query.py`

    84
    85
    86

    def gte(field: FieldProxyAny, value: Any) -> QueryExpression:
        """Greater than or equal comparison operator (i.e. >=)."""
        return _cmp_expression(field, "$gte", value)

Less than (strict) comparison operator (i.e. <).

Source code in `odmantic/query.py`

    89
    90
    91

    def lt(field: FieldProxyAny, value: Any) -> QueryExpression:
        """Less than (strict) comparison operator (i.e. <)."""
        return _cmp_expression(field, "$lt", value)

Less than or equal comparison operator (i.e. <=).

Source code in `odmantic/query.py`

    94
    95
    96

    def lte(field: FieldProxyAny, value: Any) -> QueryExpression:
        """Less than or equal comparison operator (i.e. <=)."""
        return _cmp_expression(field, "$lte", value)

Select instances where `field` is contained in `sequence`.

Source code in `odmantic/query.py`

     99
    100
    101

    def in_(field: FieldProxyAny, sequence: Iterable) -> QueryExpression:
        """Select instances where `field` is contained in `sequence`."""
        return _cmp_expression(field, "$in", list(sequence))

Select instances where `field` is not contained in `sequence`.

Source code in `odmantic/query.py`

    104
    105
    106

    def not_in(field: FieldProxyAny, sequence: Iterable) -> QueryExpression:
        """Select instances where `field` is **not** contained in `sequence`."""
        return _cmp_expression(field, "$nin", list(sequence))

Select instances where `field` matches the `pattern` regular expression.

Source code in `odmantic/query.py`

    109
    110
    111
    112
    113
    114
    115
    116
    117

    def match(field: FieldProxyAny, pattern: Union[Pattern, str]) -> QueryExpression:
        """Select instances where `field` matches the `pattern` regular expression."""
        # FIXME might create incompatibilities
        # https://docs.mongodb.com/manual/reference/operator/query/regex/#regex-and-not
        if isinstance(pattern, str):
            r = re.compile(pattern)
        else:
            r = pattern
        return QueryExpression({+field: r})

## Sort helpers

Bases: `Dict[str, Literal[-1, 1]]`

Base object used to build sort queries.

Source code in `odmantic/query.py`

    120
    121
    122
    123
    124
    125
    126
    127

    class SortExpression(Dict[str, Literal[-1, 1]]):
        """Base object used to build sort queries."""

        def __repr__(self) -> str:
            parent_repr = super().__repr__()
            if parent_repr == "{}":
                parent_repr = ""
            return f"SortExpression({parent_repr})"

Sort by ascending `field`.

Source code in `odmantic/query.py`

    136
    137
    138

    def asc(field: FieldProxyAny) -> SortExpression:
        """Sort by ascending `field`."""
        return _build_sort_expression(field, 1)

Sort by descending `field`.

Source code in `odmantic/query.py`

    141
    142
    143

    def desc(field: FieldProxyAny) -> SortExpression:
        """Sort by descending `field`."""
        return _build_sort_expression(field, -1)