Connect to the database specified by the ‘db’ argument.
Connection settings may be provided here as well if the database is not running on the default port on localhost. If authentication is needed, provide username and password arguments as well.
Multiple databases are supported by using aliases. Provide a separate alias to connect to a different instance of mongod.
Changed in version 0.6: - added multiple database support.
Add a connection.
| Parameters: |
|
|---|
The base class used for defining the structure and properties of collections of documents stored in MongoDB. Inherit from this class, and add fields as class attributes to define a document’s structure. Individual documents may then be created by making instances of the Document subclass.
By default, the MongoDB collection used to store documents created using a Document subclass will be the name of the subclass converted to lowercase. A different collection may be specified by providing collection to the meta dictionary in the class definition.
A Document subclass may be itself subclassed, to create a specialised version of the document that will be stored in the same collection. To facilitate this behaviour, _cls and _types fields are added to documents (hidden though the MongoEngine interface though). To disable this behaviour and remove the dependence on the presence of _cls and _types, set allow_inheritance to False in the meta dictionary.
A Document may use a Capped Collection by specifying max_documents and max_size in the meta dictionary. max_documents is the maximum number of documents that is allowed to be stored in the collection, and max_size is the maximum size of the collection in bytes. If max_size is not specified and max_documents is, max_size defaults to 10000000 bytes (10MB).
Indexes may be created by specifying indexes in the meta dictionary. The value should be a list of field names or tuples of field names. Index direction may be specified by prefixing the field names with a + or - sign.
Automatic index creation can be disabled by specifying attr:auto_create_index in the meta dictionary. If this is set to False then indexes will not be created by MongoEngine. This is useful in production systems where index creation is performed as part of a deployment system.
By default, _types will be added to the start of every index (that doesn’t contain a list) if allow_inheritance is True. This can be disabled by either setting types to False on the specific index or by setting index_types to False on the meta dictionary for the document.
Recursively saves any references / generic references on an objects
Delete the Document from the database. This will only take effect if the document has been previously saved.
| Parameters: | safe – check if the operation succeeded before returning |
|---|
Drops the entire collection associated with this Document type from the database.
alias of TopLevelDocumentMetaclass
This method registers the delete rules to apply when removing this object.
Reloads all attributes from the database.
New in version 0.1.2.
Changed in version 0.6: Now chainable
Save the Document to the database. If the document already exists, it will be updated, otherwise it will be created.
If safe=True and the operation is unsuccessful, an OperationError will be raised.
| Parameters: |
|
|---|
Changed in version 0.5: In existing documents it only saves changed fields using set / unset. Saves are cascaded and any DBRef objects that have changes are saved as well.
Changed in version 0.6: Cascade saves are optional = defaults to True, if you want fine grain control then you can turn off using document meta[‘cascade’] = False Also you can pass different kwargs to the cascade save using cascade_kwargs which overwrites the existing kwargs with custom values
Handles dereferencing of DBRef objects to a maximum depth in order to cut down the number queries to mongodb.
New in version 0.5.
Returns an instance of DBRef useful in __raw__ queries.
A Document that isn’t stored in its own collection. EmbeddedDocuments should be used as fields on Documents through the EmbeddedDocumentField field type.
A EmbeddedDocument subclass may be itself subclassed, to create a specialised version of the embedded document that will be stored in the same collection. To facilitate this behaviour, _cls and _types fields are added to documents (hidden though the MongoEngine interface though). To disable this behaviour and remove the dependence on the presence of _cls and _types, set allow_inheritance to False in the meta dictionary.
alias of DocumentMetaclass
A Dynamic Document class allowing flexible, expandable and uncontrolled schemas. As a Document subclass, acts in the same way as an ordinary document but has expando style properties. Any data passed or set against the DynamicDocument that is not a field is automatically converted into a DynamicField and data can be attributed to that field.
Note
There is one caveat on Dynamic Documents: fields cannot start with _
alias of TopLevelDocumentMetaclass
A Dynamic Embedded Document class allowing flexible, expandable and uncontrolled schemas. See DynamicDocument for more information about dynamic documents.
alias of DocumentMetaclass
A document returned from a map/reduce query.
| Parameters: |
|
|---|
New in version 0.3.
Lazy-load the object referenced by self.key. self.key should be the primary_key.
Validation exception.
May represent an error validating a field or a document containing fields with validation errors.
| Variables: | errors – A dictionary of errors for fields within this document or list, or None if the error is for an individual field. |
|---|
Returns a dictionary of all errors within a document
Keys are field names or list indices and values are the validation error messages, or a nested dictionary of errors for an embedded document or list.
A set of results returned from a query. Wraps a MongoDB cursor, providing Document objects as the results.
Filter the selected documents by calling the QuerySet with a query.
| Parameters: |
|
|---|
Returns all documents.
Include all fields. Reset all previously calls of .only() and .exclude().
post = BlogPost.objects(...).exclude("comments").only("title").all_fields()
New in version 0.5.
Instead of returning Document instances, return raw values from pymongo.
| Parameters: | coerce_type – Field types (if applicable) would be use to coerce types. |
|---|
Average over the values of the specified field.
| Parameters: | field – the field to average over; use dot-notation to refer to embedded document fields |
|---|
Changed in version 0.5: - updated to map_reduce as db.eval doesnt work with sharding.
Count the selected elements in the query.
Create new object. Returns the saved object instance.
New in version 0.4.
Delete the documents matched by the query.
| Parameters: | safe – check if the operation succeeded before returning |
|---|
Return a list of distinct values for a given field.
| Parameters: | field – the field to select distinct values from |
|---|
New in version 0.4.
Changed in version 0.5: - Fixed handling references
Changed in version 0.6: - Improved db_field refrence handling
Ensure that the given indexes are in place.
| Parameters: | key_or_list – a single index key or a list of index keys (to construct a multi-field index); keys may be prefixed with a + or a - to determine the index ordering |
|---|
Opposite to .only(), exclude some document’s fields.
post = BlogPost.objects(...).exclude("comments")
| Parameters: | fields – fields to exclude |
|---|
New in version 0.5.
Execute a Javascript function on the server. A list of fields may be provided, which will be translated to their correct names and supplied as the arguments to the function. A few extra variables are added to the function’s scope: collection, which is the name of the collection in use; query, which is an object representing the current query; and options, which is an object containing any options specified as keyword arguments.
As fields in MongoEngine may use different names in the database (set using the db_field keyword argument to a Field constructor), a mechanism exists for replacing MongoEngine field names with the database field names in Javascript code. When accessing a field, use square-bracket notation, and prefix the MongoEngine field name with a tilde (~).
| Parameters: |
|
|---|
Return an explain plan record for the QuerySet‘s cursor.
| Parameters: | format – format the plan before returning it |
|---|
Manipulate how you load this document’s fields. Used by .only() and .exclude() to manipulate which fields to retrieve. Fields also allows for a greater level of control for example:
Retrieving a Subrange of Array Elements:
You can use the $slice operator to retrieve a subrange of elements in an array
post = BlogPost.objects(...).fields(slice__comments=5) // first 5 comments
| Parameters: | kwargs – A dictionary identifying what to include |
|---|
New in version 0.5.
An alias of __call__()
Retrieve the first object matching the query.
Retrieve the the matching object raising MultipleObjectsReturned or DocumentName.MultipleObjectsReturned exception if multiple results and DoesNotExist or DocumentName.DoesNotExist if no results are found.
New in version 0.3.
Retrieve unique object or create, if it doesn’t exist. Returns a tuple of (object, created), where object is the retrieved or created object and created is a boolean specifying whether a new object was created. Raises MultipleObjectsReturned or DocumentName.MultipleObjectsReturned if multiple results are found. A new document will be created if the document doesn’t exists; a dictionary of default values for the new document may be provided as a keyword argument called defaults.
Note
This requires two separate operations and therefore a race condition exists. Because there are no transactions in mongoDB other approaches should be investigated, to ensure you don’t accidently duplicate data when using this method.
| Parameters: |
|
|---|
Changed in version 0.6: - added auto_save
New in version 0.3.
Added ‘hint’ support, telling Mongo the proper index to use for the query.
Judicious use of hints can greatly improve query performance. When doing a query on multiple fields (at least one of which is indexed) pass the indexed field as a hint to the query.
Hinting will not do anything if the corresponding index does not exist. The last hint applied to this cursor takes precedence over all others.
New in version 0.5.
Retrieve a set of documents by their ids.
| Parameters: | object_ids – a list or tuple of ObjectIds |
|---|---|
| Return type: | dict of ObjectIds as keys and collection-specific Document subclasses as values. |
New in version 0.3.
bulk insert documents
If safe=True and the operation is unsuccessful, an OperationError will be raised.
| Parameters: |
|
|---|
By default returns document instances, set load_bulk to False to return just ObjectIds
New in version 0.5.
Returns a dictionary of all items present in a field across the whole queried set of documents, and their corresponding frequency. This is useful for generating tag clouds, or searching documents.
Note
Can only do direct simple mappings and cannot map across ReferenceField or GenericReferenceField for more complex counting a manual map reduce call would is required.
If the field is a ListField, the items within each list will be counted individually.
| Parameters: |
|
|---|
Changed in version 0.5: defaults to map_reduce and can handle embedded document lookups
Limit the number of returned documents to n. This may also be achieved using array-slicing syntax (e.g. User.objects[:5]).
| Parameters: | n – the maximum number of objects to return |
|---|
Perform a map/reduce query using the current query spec and ordering. While map_reduce respects QuerySet chaining, it must be the last call made, as it does not return a maleable QuerySet.
See the test_map_reduce() and test_map_advanced() tests in tests.queryset.QuerySetTest for usage examples.
| Parameters: |
|
|---|
Returns an iterator yielding MapReduceDocument.
Note
Map/Reduce changed in server version >= 1.7.4. The PyMongo map_reduce() helper requires PyMongo version >= 1.11.
Changed in version 0.5: - removed keep_temp keyword argument, which was only relevant for MongoDB server versions older than 1.7.4
New in version 0.3.
Load only a subset of this document’s fields.
post = BlogPost.objects(...).only("title", "author.name")
| Parameters: | fields – fields to include |
|---|
New in version 0.3.
Changed in version 0.5: - Added subfield support
Order the QuerySet by the keys. The order may be specified by prepending each of the keys by a + or a -. Ascending order is assumed.
| Parameters: | keys – fields to order the query results by; keys may be prefixed with + or - to determine the ordering direction |
|---|
Rewind the cursor to its unevaluated state.
New in version 0.3.
Instead of returning Document instances, return either a specific value or a tuple of values in order.
This effects all results and can be unset by calling scalar without arguments. Calls only automatically.
| Parameters: | fields – One or more fields to return instead of a Document. |
|---|
Handles dereferencing of DBRef objects to a maximum depth in order to cut down the number queries to mongodb.
New in version 0.5.
Skip n documents before returning the results. This may also be achieved using array-slicing syntax (e.g. User.objects[5:]).
| Parameters: | n – the number of objects to skip before returning results |
|---|
Enable or disable the slave_okay when querying.
| Parameters: | enabled – whether or not the slave_okay is enabled |
|---|
Enable or disable snapshot mode when querying.
| Parameters: | enabled – whether or not snapshot mode is enabled |
|---|
..versionchanged:: 0.5 - made chainable
Sum over the values of the specified field.
| Parameters: | field – the field to sum over; use dot-notation to refer to embedded document fields |
|---|
Changed in version 0.5: - updated to map_reduce as db.eval doesnt work with sharding.
Enable or disable the default mongod timeout when querying.
| Parameters: | enabled – whether or not the timeout is used |
|---|
..versionchanged:: 0.5 - made chainable
Perform an atomic update on the fields matched by the query. When safe_update is used, the number of affected documents is returned.
| Parameters: |
|
|---|
New in version 0.2.
Perform an atomic update on first field matched by the query. When safe_update is used, the number of affected documents is returned.
| Parameters: |
|
|---|
New in version 0.2.
An alias for scalar
Filter QuerySet results with a $where clause (a Javascript expression). Performs automatic field name substitution like mongoengine.queryset.Queryset.exec_js().
Note
When using this mode of query, the database will call your function, or evaluate your predicate clause, for each object in the collection.
New in version 0.5.
Retrieve the object matching the id provided. Uses object_id only and raises InvalidQueryError if a filter has been applied.
| Parameters: | object_id – the value for the id of the document to look up |
|---|
Changed in version 0.6: Raises InvalidQueryError if filter has been set
Decorator that allows you to define custom QuerySet managers on Document classes. The manager must be a function that accepts a Document class as its first argument, and a QuerySet as its second argument. The method function should return a QuerySet, probably the same one that was passed in, but modified in some way.
A binary data field.
A boolean field type.
New in version 0.1.2.
ComplexDateTimeField handles microseconds exactly instead of rounding like DateTimeField does.
Derives from a StringField so you can do gte and lte filtering by using lexicographical comparison when filtering / sorting strings.
The stored string has the following format:
YYYY,MM,DD,HH,MM,SS,NNNNNN
Where NNNNNN is the number of microseconds of the represented datetime. The , as the separator can be easily modified by passing the separator keyword when initializing the field.
New in version 0.5.
A datetime field.
A fixed-point decimal number field.
New in version 0.3.
A dictionary field that wraps a standard Python dictionary. This is similar to an embedded document, but the structure is not defined.
Note
Required means it cannot be empty - as the default for ListFields is []
New in version 0.3.
Changed in version 0.5: - Can now handle complex / varying types of data
A truly dynamic field type capable of handling different and varying types of data.
Used by DynamicDocument to handle dynamic data
A field that validates input as an E-Mail-Address.
New in version 0.4.
An embedded document field - with a declared document_type. Only valid values are subclasses of EmbeddedDocument.
A GridFS storage field.
New in version 0.4.
Changed in version 0.5: added optional size param for read
Changed in version 0.6: added db_alias for multidb support
An floating point number field.
A generic embedded document field - allows any EmbeddedDocument to be stored.
Only valid values are subclasses of EmbeddedDocument.
Note
You can use the choices param to limit the acceptable EmbeddedDocument types
A reference to any Document subclass that will be automatically dereferenced on access (lazily).
Note
New in version 0.3.
A list storing a latitude and longitude.
New in version 0.4.
A Image File storage field.
New in version 0.6.
An 32-bit integer field.
A list field that wraps a standard field, allowing multiple instances of the field to be used as a list in the database.
If using with ReferenceFields see: One to Many with ListFields
Note
Required means it cannot be empty - as the default for ListFields is []
A field that maps a name to a specified field type. Similar to a DictField, except the ‘value’ of each item must match the specified field type.
New in version 0.5.
An field wrapper around MongoDB’s ObjectIds.
A reference to a document that will be automatically dereferenced on access (lazily).
Use the reverse_delete_rule to handle what should happen if the document the field is referencing is deleted. EmbeddedDocuments, DictFields and MapFields do not support reverse_delete_rules and an InvalidDocumentError will be raised if trying to set on one of these Document / Field types.
The options are:
DO_NOTHING - don’t do anything (default).
NULLIFY - Updates the reference to null.
CASCADE - Deletes the documents associated with the reference.
DENY - Prevent the deletion of the reference object.
- PULL - Pull the reference from a ListField
of references
Alternative syntax for registering delete rules (useful when implementing bi-directional delete rules)
class Bar(Document):
content = StringField()
foo = ReferenceField('Foo')
Bar.register_delete_rule(Foo, 'bar', NULLIFY)
Note
reverse_delete_rules do not trigger pre / post delete signals to be triggered.
Changed in version 0.5: added reverse_delete_rule
Provides a sequental counter (see http://www.mongodb.org/display/DOCS/Object+IDs#ObjectIDs-SequenceNumbers)
Note
Although traditional databases often use increasing sequence numbers for primary keys. In MongoDB, the preferred approach is to use Object IDs instead. The concept is that in a very large cluster of machines, it is easier to create an object ID than have global, uniformly increasing sequence numbers.
New in version 0.5.
A ListField that sorts the contents of its list before writing to the database in order to ensure that a sorted list is always retrieved.
Warning
There is a potential race condition when handling lists. If you set / save the whole list then other processes trying to save the whole list as well could overwrite changes. The safest way to append to a list is to perform a push operation.
New in version 0.4.
Changed in version 0.6: - added reverse keyword
A unicode string field.
A field that validates input as an URL.
New in version 0.3.
A UUID field.
New in version 0.6.