Query Objects

class mongoalchemy.query.Query(type, session)

A query object has all of the methods necessary to programmatically generate a mongo query as well as methods to retrieve results of the query or do an update based on it.

In general a query object should be created via Session.query, not directly.

Parameters:
  • type – A subclass of class:mongoalchemy.document.Document
  • db – The Session which this query is associated with.
query

The mongo query object which would be executed if this Query object were used

raw_output()

Turns on raw output, meaning that the MongoAlchemy ORM layer is skipped and the results from pymongo are returned. Useful if you want to use the query functionality without getting python objects back

limit(limit)

Sets the limit on the number of documents returned

Parameters:limit – the number of documents to return
skip(skip)

Sets the number of documents to skip in the result

Parameters:skip – the number of documents to skip
clone()

Creates a clone of the current query and all settings. Further updates to the cloned object or the original object will not affect each other

one()

Execute the query and return one result. If more than one result is returned, raises a BadResultException

first()

Execute the query and return the first result. Unlike one, if there are multiple documents it simply returns the first one. If there are no documents, first returns None

hint_asc(qfield)

Applies a hint for the query that it should use a (qfield, ASCENDING) index when performing the query.

Parameters:qfield – the instance of mongoalchemy.QueryField to use as the key.
hint_desc(qfield)

Applies a hint for the query that it should use a (qfield, DESCENDING) index when performing the query.

Parameters:qfield – the instance of mongoalchemy.QueryField to use as the key.
explain()

Executes an explain operation on the database for the current query and returns the raw explain object returned.

all()

Return all of the results of a query in a list

distinct(key)

Execute this query and return all of the unique values of key.

Parameters:key – the instance of mongoalchemy.QueryField to use as the distinct key.
filter(*query_expressions)

Apply the given query expressions to this query object

Example: s.query(SomeObj).filter(SomeObj.age > 10, SomeObj.blood_type == 'O')

Parameters:query_expressions – Instances of mongoalchemy.query_expression.QueryExpression

See also

QueryExpression class

filter_by(**filters)

Filter for the names in filters being equal to the associated values. Cannot be used for sub-objects since keys must be strings

count(with_limit_and_skip=False)

Execute a count on the number of results this query would return.

Parameters:with_limit_and_skip – Include .limit() and .skip() arguments in the count?
fields(*fields)

Only return the specified fields from the object. Accessing a field that was not specified in fields will result in a :class:mongoalchemy.document.FieldNotRetrieved exception being raised

Parameters:fields – Instances of :class:mongoalchemy.query.QueryField specifying which fields to return
ascending(qfield)

Sort the result based on qfield in ascending order. These calls can be chained to sort by multiple fields.

Parameters:qfield – Instance of :class:mongoalchemy.query.QueryField specifying which field to sort by.
descending(qfield)

Sort the result based on qfield in ascending order. These calls can be chained to sort by multiple fields.

Parameters:qfield – Instance of :class:mongoalchemy.query.QueryField specifying which field to sort by.
sort(*sort_tuples)

pymongo-style sorting. Accepts a list of tuples.

Parameters:sort_tuples – varargs of sort tuples.
not_(*query_expressions)

Add a $not expression to the query, negating the query expressions given.

Examples: query.not_(SomeDocClass.age <= 18) becomes {'age' : { '$not' : { '$gt' : 18 } }}

Parameters:query_expressions – Instances of mongoalchemy.query_expression.QueryExpression
or_(first_qe, *qes)

Add a $not expression to the query, negating the query expressions given. The | operator on query expressions does the same thing

Examples: query.or_(SomeDocClass.age == 18, SomeDocClass.age == 17) becomes {'$or' : [{ 'age' : 18 }, { 'age' : 17 }]}

Parameters:query_expressions – Instances of mongoalchemy.query_expression.QueryExpression
in_(qfield, *values)

Check to see that the value of qfield is one of values

Parameters:
nin(qfield, *values)

Check to see that the value of qfield is not one of values

Parameters:
find_and_modify(new=False, remove=False)

The mongo “find and modify” command. Behaves like an update expression in that “execute” must be called to do the update and return the results.

Parameters:
  • new – Whether to return the new object or old (default: False)
  • remove – Whether to remove the object before returning it
set(*args, **kwargs)

Refer to: set()

unset(qfield)

Refer to: unset()

inc(*args, **kwargs)

Refer to: inc()

append(qfield, value)

Refer to: append()

extend(qfield, *value)

Refer to: extend()

remove(qfield, value)

Refer to: remove()

remove_all(qfield, *value)

Refer to: remove_all()

add_to_set(qfield, value)

Refer to: add_to_set()

pop_first(qfield)

Refer to: pop_first()

pop_last(qfield)

Refer to: pop_last()

class mongoalchemy.query.QueryResult(session, cursor, type, raw_output=False, fields=None)
next()
rewind()
clone()

Previous topic

Expression Language — Querying and Updating

Next topic

Mongo Query Expression Language

This Page