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)