Session objects handles the actual queueing of database operations. The primary methods on a session are query, save, and flush.

The session also responsible for ordering operations and knowing when operations need to be flushed, although it does not currently do anything intelligent for ordering.

class ommongo.session.Session(database, tz_aware=False, timezone=None, safe=False, cache_size=0, auto_ensure=True)

Create a session connecting to database.

  • database – the database to connect to. Should be an instance of pymongo.database.Database
  • safe – Whether the “safe” option should be used on mongo writes, blocking to make sure there are no errors.
  • auto_ensure – Whether to implicitly call ensure_indexes on all write operations.
  • db: the underlying pymongo database object
  • queue: the queue of unflushed database commands (currently useless since there aren’t any operations which defer flushing)
  • cache_size: The size of the identity map to keep. When objects are pulled from the DB they are checked against this map and if present, the existing object is used. Defaults to 0, use None to only clear at session end.
add(item, safe=None)

Add an item into the queue of things to be inserted. Does not flush.


Clear all objects from the collections associated with the objects in *cls. use with caution!


Clear the queue of database operations without executing any of the pending operations


Serialize a document, remove its _id, and deserialize as a new object

classmethod connect(database, timezone=None, cache_size=0, auto_ensure=True, replica_set=None, *args, **kwds)

connect is a thin wrapper around __init__ which creates the database connection that the session will use.

  • database – the database name to use. Should be an instance of basestring
  • safe – The value for the “safe” parameter of the Session init function
  • auto_ensure – Whether to implicitly call ensure_indexes on all write operations.
  • replica_set – The replica-set to use (as a string). If specified, pymongo.mongo_replica_set_client.MongoReplicaSetClient is used instead of pymongo.mongo_client.MongoClient
  • args – arguments for pymongo.mongo_client.MongoClient
  • kwds – keyword arguments for pymongo.mongo_client.MongoClient
dereference(ref, allow_none=False)

End the session. Flush all pending operations and ending the pymongo request

end_trans(exc_type=None, exc_val=None, exc_tb=None)
execute_query(query, session)

Get the results of query. This method does flush in a transaction, so any objects retrieved which are not in the cache which would be updated when the transaction finishes will be stale


Perform all database operations currently in the queue


Get the index information for the collection associated with cls. Index information is returned in the same format as pymongo.

insert(item, safe=None)

[DEPRECATED] Please use save() instead. This actually calls the underlying save function, so the name is confusing.

Insert an item into the work queue and flushes.

query(type, exclude_subclasses=False)
Begin a query on the database’s collection for type. If type
is an instance of basesting, the query will be in raw query mode which will not check field values or transform returned results into python objects.

See also

Query class


Load a new copy of a document from the database. does not replace the old one

remove(obj, safe=None)

Remove a particular object from the database. If the object has no mongo ID set, the method just returns. If this is a partial document without the mongo ID field retrieved a FieldNotRetrieved will be raised

  • obj – the object to save
  • safe – whether to wait for the operation to complete. Defaults to the session’s safe value.

Begin a remove query on the database’s collection for type.

See also

RemoveQuery class

save(item, safe=None)

Saves an item into the work queue and flushes.

update(item, id_expression=None, upsert=False, update_ops={}, safe=None, **kwargs)

Update an item in the database. Uses the on_update keyword to each field to decide which operations to do, or.

  • item – An instance of a Document subclass
  • id_expression – A query expression that uniquely picks out the item which should be updated. If id_expression is not passed, update uses item.mongo_id.
  • upsert – Whether the update operation should be an upsert. If the item may not be in the database yet this should be True
  • update_ops – By default the operation used to update a field is specified with the on_update argument to its constructor. To override that value, use this dictionary, with QueryField objects as the keys and the mongo operation to use as the values.
  • kwargs – The kwargs are merged into update_ops dict to decide which fields to update the operation for. These can only be for the top-level document since the keys are just strings.


This operation is experimental and not fully tested, although it does have code coverage.