Module motor_odm.query

class motor_odm.query.Query(*args: Any, **kwargs: Any)

Bases: dict, typing.Generic

A MongoDB query.

Queries behave like ordinary dictionaries (in fact they inherit from dict). However they offer some additional convenience related to MongoDB queries. Most notably they can be constructed conveniently from keyword arguments. See the documentation on q() for details.

This class also offers some factory methods for special queries such as using a JSON Schema.

add_expression(field: str, value: Any, op: str = None) → None

Adds a single expression to this query.

An expression is a constraint for a single field. This method modifies the query to add a constraint for the specified field to be equal to value. If op is specified it is used instead of the default $eq operator.

Raises

KeyError – If field has already a value for op that is not equal to value.

comment(comment: str) → motor_odm.query.Query

Adds a comment to this query.

classmethod expr(expression: dict) → motor_odm.query.Query

Constructs an $expr query.

extend(**kwargs: DictStrAny) → None

Adds fields to this query.

This method adds the same keys and values that you would get using the q() function with only keyword arguments. See the documentation on that method for details.

classmethod schema(schema: DictStrAny) → Query

Constructs a $jsonSchema query.

classmethod text(search: str, language: str = None, case_sensitive: bool = None, diacritic_sensitive: bool = None) → motor_odm.query.Query

Constructs a $text query using the specified arguments.

classmethod where(where: Union[str, bson.code.Code]) → motor_odm.query.Query

Constructs a $where query.

motor_odm.query.q(*args: Any, **kwargs: Any) → motor_odm.query.Query

Creates a MongoDB query from the specified arguments.

The query can be used to filter documents in Motor-ODM or even directly in Motor or PyMongo. This function is the preferred way of constructing queries. You can use special keyword arguments to construct more complex queries.

One of the most common cases is a query by ID. Specify the ID as the only positional argument:

>>> q(123)
{'_id': 123}

If you pass None as the single id value, a query will be constructed that matches nothing. >>> q(None) {‘X’: {‘$in’: []}}

You can also create a query that matches an ID in a list of IDs by specifying multiple positional arguments, each of which will be treated as a possible ID. In this case None values will simply be ignored. >>> q(123, None, “ABC”) {‘_id’: {‘$in’: [123, ‘ABC’]}}

Instead of querying the ID of a document you most likely need to filter documents based on their fields. You can do this by providing the respective keyword arguments. You can combine positional and keyword arguments if you need to. In the simples case we want to create a query that filters on the value of one or more fields:

>>> q(name="John", age=20)
{'name': 'John', 'age': 20}

You can also use MongoDB query operators to create more complex queries:

>>> q(age__gt=20, age__lt=100)
{'age': {'$gt': 20, '$lt': 100}}

Lastly you can combine queries with &, | and ^. The ^ operator means nor in this case.

>>> (q(age=20) & q(name="John")) | q(age=21)
{'$or': [{'$and': [{'age': 20}, {'name': 'John'}]}, {'age': 21}]}