objectid – Tools for working with MongoDB ObjectIds

Tools for working with MongoDB ObjectIds.

class pymongo.objectid.ObjectId([oid=None])

Initialize a new ObjectId.

If oid is None, create a new (unique) ObjectId. If oid is an instance of (basestring, ObjectId) validate it and use that. Otherwise, a TypeError is raised. If oid is invalid, InvalidId is raised.

  • oid (optional): a valid ObjectId (12 byte binary or 24 character hex string)

New in version 1.2.1: The oid parameter can be a unicode instance (that contains only hexadecimal digits).

See general MongoDB documentation



Get a hex encoded version of ObjectId o.

The following property always holds:

>>> o = ObjectId()
>>> o == ObjectId(str(o))

This representation is useful for urls or other places where o.binary is inappropriate.

12-byte binary representation of this ObjectId.
classmethod from_datetime(generation_time)

Create a dummy ObjectId instance with a specific generation time.

This method is useful for doing range queries on a field containing ObjectId instances.


It is not safe to insert a document containing an ObjectId generated using this method. This method deliberately eliminates the uniqueness guarantee that ObjectIds generally provide. ObjectIds generated with this method should be used exclusively in queries.

generation_time will be converted to a UTC timestamp naively. Pass either a naive datetime instance containing UTC, or an aware instance that has been converted to UTC.

An example using this helper to get documents where "_id" was generated before January 1, 2010 would be:

>>> gen_time = datetime.datetime(2010, 1, 1)
>>> dummy_id = ObjectId.from_datetime(gen_time)
>>> result = collection.find({"_id": {"$lt": dummy_id}})
  • generation_time: datetime to be used as the generation time for the resulting ObjectId.

New in version 1.6.


A datetime.datetime instance representing the time of generation for this ObjectId.

The datetime.datetime is always naive and represents the generation time in UTC. It is precise to the second.

New in version 1.2.

Previous topic

binary – Tools for representing binary data to be stored in MongoDB

Next topic

bson – Tools for working with BSON in Python

This Page