fiftyone.core.odm.document¶
Base classes for documents that back dataset contents.
Classes:
Base class for documents that are written to the database in their own collections. |
|
|
Base class for documents that are stored in a MongoDB collection. |
|
Base class for dynamic documents that are stored in a MongoDB collection. |
Mixin for all |
|
Mixin for documents that can be serialized in BSON or JSON format. |
-
class
fiftyone.core.odm.document.
SerializableDocument
¶ Bases:
object
Mixin for documents that can be serialized in BSON or JSON format.
Methods:
clear_field
(field_name)Clears the field from the document.
copy
()Returns a deep copy of the document.
fancy_repr
([class_name, select_fields, …])Generates a customizable string representation of the document.
from_dict
(d[, extended])Loads the document from a BSON/JSON dictionary.
from_json
(s)Loads the document from a JSON string.
get_field
(field_name)Gets the field of the document.
has_field
(field_name)Determines whether the document has a field of the given name.
set_field
(field_name, value[, create])Sets the value of a field of the document.
to_dict
([extended])Serializes this document to a BSON/JSON dictionary.
to_json
([pretty_print])Serializes the document to a JSON string.
-
fancy_repr
(class_name=None, select_fields=None, exclude_fields=None, **kwargs)¶ Generates a customizable string representation of the document.
- Parameters
class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation
- Returns
a string representation of the document
-
has_field
(field_name)¶ Determines whether the document has a field of the given name.
- Parameters
field_name – the field name
- Returns
True/False
-
get_field
(field_name)¶ Gets the field of the document.
- Parameters
field_name – the field name
- Returns
the field value
- Raises
AttributeError – if the field does not exist
-
set_field
(field_name, value, create=False)¶ Sets the value of a field of the document.
- Parameters
field_name – the field name
value – the field value
create (False) – whether to create the field if it does not exist
- Raises
ValueError – if
field_name
is not an allowed field name or does not exist andcreate == False
-
clear_field
(field_name)¶ Clears the field from the document.
- Parameters
field_name – the field name
- Raises
ValueError – if the field does not exist
-
copy
()¶ Returns a deep copy of the document.
- Returns
-
to_dict
(extended=False)¶ Serializes this document to a BSON/JSON dictionary.
- Parameters
extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
- Returns
a dict
-
classmethod
from_dict
(d, extended=False)¶ Loads the document from a BSON/JSON dictionary.
- Parameters
d – a dictionary
extended (False) – whether the input dictionary may contain serialized extended JSON constructs
- Returns
-
to_json
(pretty_print=False)¶ Serializes the document to a JSON string.
- Parameters
pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
- Returns
a JSON string
-
classmethod
from_json
(s)¶ Loads the document from a JSON string.
- Returns
-
-
class
fiftyone.core.odm.document.
MongoEngineBaseDocument
¶ Bases:
fiftyone.core.odm.document.SerializableDocument
Mixin for all
mongoengine:mongoengine.base.BaseDocument
subclasses that implements theSerializableDocument
interface.Methods:
clear_field
(field_name)Clears the field from the document.
copy
()Returns a deep copy of the document.
fancy_repr
([class_name, select_fields, …])Generates a customizable string representation of the document.
field_to_mongo
(field_name)field_to_python
(field_name, value)from_dict
(d[, extended])Loads the document from a BSON/JSON dictionary.
from_json
(s)Loads the document from a JSON string.
get_field
(field_name)Gets the field of the document.
has_field
(field_name)Determines whether the document has a field of the given name.
set_field
(field_name, value[, create])Sets the value of a field of the document.
to_dict
([extended])Serializes this document to a BSON/JSON dictionary.
to_json
([pretty_print])Serializes the document to a JSON string.
-
has_field
(field_name)¶ Determines whether the document has a field of the given name.
- Parameters
field_name – the field name
- Returns
True/False
-
get_field
(field_name)¶ Gets the field of the document.
- Parameters
field_name – the field name
- Returns
the field value
- Raises
AttributeError – if the field does not exist
-
set_field
(field_name, value, create=False)¶ Sets the value of a field of the document.
- Parameters
field_name – the field name
value – the field value
create (False) – whether to create the field if it does not exist
- Raises
ValueError – if
field_name
is not an allowed field name or does not exist andcreate == False
-
clear_field
(field_name)¶ Clears the field from the document.
- Parameters
field_name – the field name
- Raises
ValueError – if the field does not exist
-
field_to_mongo
(field_name)¶
-
field_to_python
(field_name, value)¶
-
to_dict
(extended=False)¶ Serializes this document to a BSON/JSON dictionary.
- Parameters
extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
- Returns
a dict
-
classmethod
from_dict
(d, extended=False)¶ Loads the document from a BSON/JSON dictionary.
- Parameters
d – a dictionary
extended (False) – whether the input dictionary may contain serialized extended JSON constructs
- Returns
-
copy
()¶ Returns a deep copy of the document.
- Returns
-
fancy_repr
(class_name=None, select_fields=None, exclude_fields=None, **kwargs)¶ Generates a customizable string representation of the document.
- Parameters
class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation
- Returns
a string representation of the document
-
classmethod
from_json
(s)¶ Loads the document from a JSON string.
- Returns
-
to_json
(pretty_print=False)¶ Serializes the document to a JSON string.
- Parameters
pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
- Returns
a JSON string
-
-
class
fiftyone.core.odm.document.
BaseDocument
¶ Bases:
fiftyone.core.odm.document.MongoEngineBaseDocument
Base class for documents that are written to the database in their own collections.
The ID of a document is automatically populated when it is added to the database, and the ID of a document is
None
if it has not been added to the database.-
id
¶ the ID of the document, or
None
if it has not been added to the database
Methods:
clear_field
(field_name)Clears the field from the document.
copy
()Returns a deep copy of the document.
fancy_repr
([class_name, select_fields, …])Generates a customizable string representation of the document.
field_to_mongo
(field_name)field_to_python
(field_name, value)from_dict
(d[, extended])Loads the document from a BSON/JSON dictionary.
from_json
(s)Loads the document from a JSON string.
get_field
(field_name)Gets the field of the document.
has_field
(field_name)Determines whether the document has a field of the given name.
set_field
(field_name, value[, create])Sets the value of a field of the document.
to_dict
([extended])Serializes this document to a BSON/JSON dictionary.
to_json
([pretty_print])Serializes the document to a JSON string.
Attributes:
Whether the document has been inserted into the database.
-
property
in_db
¶ Whether the document has been inserted into the database.
-
clear_field
(field_name)¶ Clears the field from the document.
- Parameters
field_name – the field name
- Raises
ValueError – if the field does not exist
-
copy
()¶ Returns a deep copy of the document.
- Returns
-
fancy_repr
(class_name=None, select_fields=None, exclude_fields=None, **kwargs)¶ Generates a customizable string representation of the document.
- Parameters
class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation
- Returns
a string representation of the document
-
field_to_mongo
(field_name)¶
-
field_to_python
(field_name, value)¶
-
classmethod
from_dict
(d, extended=False)¶ Loads the document from a BSON/JSON dictionary.
- Parameters
d – a dictionary
extended (False) – whether the input dictionary may contain serialized extended JSON constructs
- Returns
-
classmethod
from_json
(s)¶ Loads the document from a JSON string.
- Returns
-
get_field
(field_name)¶ Gets the field of the document.
- Parameters
field_name – the field name
- Returns
the field value
- Raises
AttributeError – if the field does not exist
-
has_field
(field_name)¶ Determines whether the document has a field of the given name.
- Parameters
field_name – the field name
- Returns
True/False
-
set_field
(field_name, value, create=False)¶ Sets the value of a field of the document.
- Parameters
field_name – the field name
value – the field value
create (False) – whether to create the field if it does not exist
- Raises
ValueError – if
field_name
is not an allowed field name or does not exist andcreate == False
-
to_dict
(extended=False)¶ Serializes this document to a BSON/JSON dictionary.
- Parameters
extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
- Returns
a dict
-
to_json
(pretty_print=False)¶ Serializes the document to a JSON string.
- Parameters
pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
- Returns
a JSON string
-
-
class
fiftyone.core.odm.document.
DynamicDocument
(*args, **values)¶ Bases:
fiftyone.core.odm.document.BaseDocument
,mongoengine.document.DynamicDocument
Base class for dynamic documents that are stored in a MongoDB collection. Dynamic documents can have arbitrary fields added to them. The ID of a document is automatically populated when it is added to the database, and the ID of a document is
None
if it has not been added to the database. .. attribute:: idthe ID of the document, or
None
if it has not been added to the databaseAttributes:
Whether the document has been inserted into the database.
Get the primary key.
Methods:
cascade_save
(**kwargs)Recursively save any references and generic references on the document.
clean
()Hook for doing document level data cleaning before validation is run.
clear_field
(field_name)Clears the field from the document.
Compares the indexes defined in MongoEngine with the ones existing in the database.
copy
()Returns a deep copy of the document.
create_index
(keys[, background])Creates the given indexes if required.
delete
([signal_kwargs])Delete the
Document
from the database.Drops the entire collection associated with this
Document
type from the database.ensure_index
(key_or_list[, background])Ensure that the given indexes are in place.
Checks the document meta data and ensures all the indexes exist.
fancy_repr
([class_name, select_fields, …])Generates a customizable string representation of the document.
field_to_mongo
(field_name)field_to_python
(field_name, value)from_dict
(d[, extended])Loads the document from a BSON/JSON dictionary.
from_json
(s)Loads the document from a JSON string.
get_field
(field_name)Gets the field of the document.
Get text score from text query
has_field
(field_name)Determines whether the document has a field of the given name.
Lists all of the indexes that should be created for given collection.
modify
([query])Perform an atomic update of the document in the database and reload the document object using updated version.
register_delete_rule
(document_cls, …)This method registers the delete rules to apply when removing this object.
reload
(*fields, **kwargs)Reloads all attributes from the database.
save
([force_insert, validate, clean, …])Save the
Document
to the database.select_related
([max_depth])Handles dereferencing of
DBRef
objects to a maximum depth in order to cut down the number queries to mongodb.set_field
(field_name, value[, create])Sets the value of a field of the document.
switch_collection
(collection_name[, …])Temporarily switch the collection for a document instance.
switch_db
(db_alias[, keep_created])Temporarily switch the database for a document instance.
to_dbref
()Returns an instance of
DBRef
useful in __raw__ queries.to_dict
([extended])Serializes this document to a BSON/JSON dictionary.
to_json
([pretty_print])Serializes the document to a JSON string.
to_mongo
(*args, **kwargs)Return as SON data ready for use with MongoDB.
update
(**kwargs)Performs an update on the
Document
A convenience wrapper toupdate()
.validate
([clean])Ensure that all fields’ values are valid and that required fields are present.
Classes:
alias of
mongoengine.base.metaclasses.TopLevelDocumentMetaclass
-
STRICT
= False¶
-
cascade_save
(**kwargs)¶ Recursively save any references and generic references on the document.
-
clean
()¶ Hook for doing document level data cleaning before validation is run.
Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.
-
clear_field
(field_name)¶ Clears the field from the document.
- Parameters
field_name – the field name
- Raises
ValueError – if the field does not exist
-
classmethod
compare_indexes
()¶ Compares the indexes defined in MongoEngine with the ones existing in the database. Returns any missing/extra indexes.
-
copy
()¶ Returns a deep copy of the document.
- Returns
-
classmethod
create_index
(keys, background=False, **kwargs)¶ Creates the given indexes if required.
- Parameters
keys – 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
background – Allows index creation in the background
-
delete
(signal_kwargs=None, **write_concern)¶ Delete the
Document
from the database. This will only take effect if the document has been previously saved.- Parameters
signal_kwargs – (optional) kwargs dictionary to be passed to the signal calls.
write_concern – Extra keyword arguments are passed down which will be used as options for the resultant
getLastError
command. For example,save(..., w: 2, fsync: True)
will wait until at least two servers have recorded the write and will force an fsync on the primary server.
Changed in version 0.10.7: Add signal_kwargs argument
-
classmethod
drop_collection
()¶ Drops the entire collection associated with this
Document
type from the database.Raises
OperationError
if the document has no collection set (i.g. if it is abstract)Changed in version 0.10.7:
OperationError
exception raised if no collection available
-
classmethod
ensure_index
(key_or_list, background=False, **kwargs)¶ Ensure that the given indexes are in place. Deprecated in favour of create_index.
- 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
background – Allows index creation in the background
-
classmethod
ensure_indexes
()¶ Checks the document meta data and ensures all the indexes exist.
Global defaults can be set in the meta - see guide/defining-documents
Note
You can disable automatic index creation by setting auto_create_index to False in the documents meta data
-
fancy_repr
(class_name=None, select_fields=None, exclude_fields=None, **kwargs)¶ Generates a customizable string representation of the document.
- Parameters
class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation
- Returns
a string representation of the document
-
field_to_mongo
(field_name)¶
-
field_to_python
(field_name, value)¶
-
classmethod
from_dict
(d, extended=False)¶ Loads the document from a BSON/JSON dictionary.
- Parameters
d – a dictionary
extended (False) – whether the input dictionary may contain serialized extended JSON constructs
- Returns
-
classmethod
from_json
(s)¶ Loads the document from a JSON string.
- Returns
-
get_field
(field_name)¶ Gets the field of the document.
- Parameters
field_name – the field name
- Returns
the field value
- Raises
AttributeError – if the field does not exist
-
get_text_score
()¶ Get text score from text query
-
has_field
(field_name)¶ Determines whether the document has a field of the given name.
- Parameters
field_name – the field name
- Returns
True/False
-
property
in_db
¶ Whether the document has been inserted into the database.
-
classmethod
list_indexes
()¶ Lists all of the indexes that should be created for given collection. It includes all the indexes from super- and sub-classes.
-
modify
(query=None, **update)¶ Perform an atomic update of the document in the database and reload the document object using updated version.
Returns True if the document has been updated or False if the document in the database doesn’t match the query.
Note
All unsaved changes that have been made to the document are rejected if the method returns True.
- Parameters
query – the update will be performed only if the document in the database matches the query
update – Django-style update keyword arguments
-
my_metaclass
¶ alias of
mongoengine.base.metaclasses.TopLevelDocumentMetaclass
Methods:get_auto_id_names
(new_class)Find a name for the automatic ID field for the given new class.
mro
Return a type’s method resolution order.
-
property
pk
¶ Get the primary key.
-
classmethod
register_delete_rule
(document_cls, field_name, rule)¶ This method registers the delete rules to apply when removing this object.
-
reload
(*fields, **kwargs)¶ Reloads all attributes from the database.
- Parameters
fields – (optional) args list of fields to reload
max_depth – (optional) depth of dereferencing to follow
New in version 0.1.2.
Changed in version 0.6: Now chainable
Changed in version 0.9: Can provide specific fields to reload
-
save
(force_insert=False, validate=True, clean=True, write_concern=None, cascade=None, cascade_kwargs=None, _refs=None, save_condition=None, signal_kwargs=None, **kwargs)¶ Save the
Document
to the database. If the document already exists, it will be updated, otherwise it will be created. Returns the saved object instance.- Parameters
force_insert – only try to create a new document, don’t allow updates of existing documents.
validate – validates the document; set to
False
to skip.clean – call the document clean method, requires validate to be True.
write_concern – Extra keyword arguments are passed down to
save()
ORinsert()
which will be used as options for the resultantgetLastError
command. For example,save(..., write_concern={w: 2, fsync: True}, ...)
will wait until at least two servers have recorded the write and will force an fsync on the primary server.cascade – Sets the flag for cascading saves. You can set a default by setting “cascade” in the document __meta__
cascade_kwargs – (optional) kwargs dictionary to be passed throw to cascading saves. Implies
cascade=True
._refs – A list of processed references used in cascading saves
save_condition – only perform save if matching record in db satisfies condition(s) (e.g. version number). Raises
OperationError
if the conditions are not satisfiedsignal_kwargs – (optional) kwargs dictionary to be passed to the signal calls.
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: Added cascading saves
Changed in version 0.8: Cascade saves are optional and default to False. If you want fine grain control then you can turn off using document meta[‘cascade’] = True. Also you can pass different kwargs to the cascade save using cascade_kwargs which overwrites the existing kwargs with custom values.
Changed in version 0.8.5: Optional save_condition that only overwrites existing documents if the condition is satisfied in the current db record.
Changed in version 0.10:
OperationError
exception raised if save_condition fails.Changed in version 0.10.1: :class: save_condition failure now raises a SaveConditionError
Changed in version 0.10.7: Add signal_kwargs argument
Handles dereferencing of
DBRef
objects to a maximum depth in order to cut down the number queries to mongodb.New in version 0.5.
-
set_field
(field_name, value, create=False)¶ Sets the value of a field of the document.
- Parameters
field_name – the field name
value – the field value
create (False) – whether to create the field if it does not exist
- Raises
ValueError – if
field_name
is not an allowed field name or does not exist andcreate == False
-
switch_collection
(collection_name, keep_created=True)¶ Temporarily switch the collection for a document instance.
Only really useful for archiving off data and calling save():
user = User.objects.get(id=user_id) user.switch_collection('old-users') user.save()
- Parameters
collection_name (str) – The database alias to use for saving the document
keep_created (bool) – keep self._created value after switching collection, else is reset to True
See also
Use
switch_db
if you need to read from another database
-
switch_db
(db_alias, keep_created=True)¶ Temporarily switch the database for a document instance.
Only really useful for archiving off data and calling save():
user = User.objects.get(id=user_id) user.switch_db('archive-db') user.save()
- Parameters
db_alias (str) – The database alias to use for saving the document
keep_created (bool) – keep self._created value after switching db, else is reset to True
See also
Use
switch_collection
if you need to read from another collection
-
to_dict
(extended=False)¶ Serializes this document to a BSON/JSON dictionary.
- Parameters
extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
- Returns
a dict
-
to_json
(pretty_print=False)¶ Serializes the document to a JSON string.
- Parameters
pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
- Returns
a JSON string
-
to_mongo
(*args, **kwargs)¶ Return as SON data ready for use with MongoDB.
-
update
(**kwargs)¶ Performs an update on the
Document
A convenience wrapper toupdate()
.Raises
OperationError
if called on an object that has not yet been saved.
-
validate
(clean=True)¶ Ensure that all fields’ values are valid and that required fields are present.
Raises
ValidationError
if any of the fields’ values are found to be invalid.
-
-
class
fiftyone.core.odm.document.
Document
(*args, **values)¶ Bases:
fiftyone.core.odm.document.BaseDocument
,mongoengine.document.Document
Base class for documents that are stored in a MongoDB collection.
The ID of a document is automatically populated when it is added to the database, and the ID of a document is
None
if it has not been added to the database.-
id
¶ the ID of the document, or
None
if it has not been added to the database
Attributes:
Whether the document has been inserted into the database.
Get the primary key.
Methods:
cascade_save
(**kwargs)Recursively save any references and generic references on the document.
clean
()Hook for doing document level data cleaning before validation is run.
clear_field
(field_name)Clears the field from the document.
Compares the indexes defined in MongoEngine with the ones existing in the database.
copy
()Returns a deep copy of the document.
create_index
(keys[, background])Creates the given indexes if required.
delete
([signal_kwargs])Delete the
Document
from the database.Drops the entire collection associated with this
Document
type from the database.ensure_index
(key_or_list[, background])Ensure that the given indexes are in place.
Checks the document meta data and ensures all the indexes exist.
fancy_repr
([class_name, select_fields, …])Generates a customizable string representation of the document.
field_to_mongo
(field_name)field_to_python
(field_name, value)from_dict
(d[, extended])Loads the document from a BSON/JSON dictionary.
from_json
(s)Loads the document from a JSON string.
get_field
(field_name)Gets the field of the document.
Get text score from text query
has_field
(field_name)Determines whether the document has a field of the given name.
Lists all of the indexes that should be created for given collection.
modify
([query])Perform an atomic update of the document in the database and reload the document object using updated version.
register_delete_rule
(document_cls, …)This method registers the delete rules to apply when removing this object.
reload
(*fields, **kwargs)Reloads all attributes from the database.
save
([validate, clean])Save the
Document
to the database.select_related
([max_depth])Handles dereferencing of
DBRef
objects to a maximum depth in order to cut down the number queries to mongodb.set_field
(field_name, value[, create])Sets the value of a field of the document.
switch_collection
(collection_name[, …])Temporarily switch the collection for a document instance.
switch_db
(db_alias[, keep_created])Temporarily switch the database for a document instance.
to_dbref
()Returns an instance of
DBRef
useful in __raw__ queries.to_dict
([extended])Serializes this document to a BSON/JSON dictionary.
to_json
([pretty_print])Serializes the document to a JSON string.
to_mongo
(*args, **kwargs)Return as SON data ready for use with MongoDB.
update
(**kwargs)Performs an update on the
Document
A convenience wrapper toupdate()
.validate
([clean])Ensure that all fields’ values are valid and that required fields are present.
Classes:
alias of
mongoengine.base.metaclasses.TopLevelDocumentMetaclass
-
save
(validate=True, clean=True, **kwargs)¶ Save the
Document
to the database.If the document already exists, it will be updated, otherwise it will be created.
- Parameters
validate (True) – validates the document
clean (True) – call the document’s clean method; requires
validate
to be True
- Returns
self
-
STRICT
= False¶
-
cascade_save
(**kwargs)¶ Recursively save any references and generic references on the document.
-
clean
()¶ Hook for doing document level data cleaning before validation is run.
Any ValidationError raised by this method will not be associated with a particular field; it will have a special-case association with the field defined by NON_FIELD_ERRORS.
-
clear_field
(field_name)¶ Clears the field from the document.
- Parameters
field_name – the field name
- Raises
ValueError – if the field does not exist
-
classmethod
compare_indexes
()¶ Compares the indexes defined in MongoEngine with the ones existing in the database. Returns any missing/extra indexes.
-
copy
()¶ Returns a deep copy of the document.
- Returns
-
classmethod
create_index
(keys, background=False, **kwargs)¶ Creates the given indexes if required.
- Parameters
keys – 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
background – Allows index creation in the background
-
delete
(signal_kwargs=None, **write_concern)¶ Delete the
Document
from the database. This will only take effect if the document has been previously saved.- Parameters
signal_kwargs – (optional) kwargs dictionary to be passed to the signal calls.
write_concern – Extra keyword arguments are passed down which will be used as options for the resultant
getLastError
command. For example,save(..., w: 2, fsync: True)
will wait until at least two servers have recorded the write and will force an fsync on the primary server.
Changed in version 0.10.7: Add signal_kwargs argument
-
classmethod
drop_collection
()¶ Drops the entire collection associated with this
Document
type from the database.Raises
OperationError
if the document has no collection set (i.g. if it is abstract)Changed in version 0.10.7:
OperationError
exception raised if no collection available
-
classmethod
ensure_index
(key_or_list, background=False, **kwargs)¶ Ensure that the given indexes are in place. Deprecated in favour of create_index.
- 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
background – Allows index creation in the background
-
classmethod
ensure_indexes
()¶ Checks the document meta data and ensures all the indexes exist.
Global defaults can be set in the meta - see guide/defining-documents
Note
You can disable automatic index creation by setting auto_create_index to False in the documents meta data
-
fancy_repr
(class_name=None, select_fields=None, exclude_fields=None, **kwargs)¶ Generates a customizable string representation of the document.
- Parameters
class_name (None) – optional class name to use
select_fields (None) – iterable of field names to restrict to
exclude_fields (None) – iterable of field names to exclude
**kwargs – additional key-value pairs to include in the string representation
- Returns
a string representation of the document
-
field_to_mongo
(field_name)¶
-
field_to_python
(field_name, value)¶
-
classmethod
from_dict
(d, extended=False)¶ Loads the document from a BSON/JSON dictionary.
- Parameters
d – a dictionary
extended (False) – whether the input dictionary may contain serialized extended JSON constructs
- Returns
-
classmethod
from_json
(s)¶ Loads the document from a JSON string.
- Returns
-
get_field
(field_name)¶ Gets the field of the document.
- Parameters
field_name – the field name
- Returns
the field value
- Raises
AttributeError – if the field does not exist
-
get_text_score
()¶ Get text score from text query
-
has_field
(field_name)¶ Determines whether the document has a field of the given name.
- Parameters
field_name – the field name
- Returns
True/False
-
property
in_db
¶ Whether the document has been inserted into the database.
-
classmethod
list_indexes
()¶ Lists all of the indexes that should be created for given collection. It includes all the indexes from super- and sub-classes.
-
modify
(query=None, **update)¶ Perform an atomic update of the document in the database and reload the document object using updated version.
Returns True if the document has been updated or False if the document in the database doesn’t match the query.
Note
All unsaved changes that have been made to the document are rejected if the method returns True.
- Parameters
query – the update will be performed only if the document in the database matches the query
update – Django-style update keyword arguments
-
my_metaclass
¶ alias of
mongoengine.base.metaclasses.TopLevelDocumentMetaclass
Methods:get_auto_id_names
(new_class)Find a name for the automatic ID field for the given new class.
mro
Return a type’s method resolution order.
-
property
pk
¶ Get the primary key.
-
classmethod
register_delete_rule
(document_cls, field_name, rule)¶ This method registers the delete rules to apply when removing this object.
-
reload
(*fields, **kwargs)¶ Reloads all attributes from the database.
- Parameters
fields – (optional) args list of fields to reload
max_depth – (optional) depth of dereferencing to follow
New in version 0.1.2.
Changed in version 0.6: Now chainable
Changed in version 0.9: Can provide specific fields to reload
Handles dereferencing of
DBRef
objects to a maximum depth in order to cut down the number queries to mongodb.New in version 0.5.
-
set_field
(field_name, value, create=False)¶ Sets the value of a field of the document.
- Parameters
field_name – the field name
value – the field value
create (False) – whether to create the field if it does not exist
- Raises
ValueError – if
field_name
is not an allowed field name or does not exist andcreate == False
-
switch_collection
(collection_name, keep_created=True)¶ Temporarily switch the collection for a document instance.
Only really useful for archiving off data and calling save():
user = User.objects.get(id=user_id) user.switch_collection('old-users') user.save()
- Parameters
collection_name (str) – The database alias to use for saving the document
keep_created (bool) – keep self._created value after switching collection, else is reset to True
See also
Use
switch_db
if you need to read from another database
-
switch_db
(db_alias, keep_created=True)¶ Temporarily switch the database for a document instance.
Only really useful for archiving off data and calling save():
user = User.objects.get(id=user_id) user.switch_db('archive-db') user.save()
- Parameters
db_alias (str) – The database alias to use for saving the document
keep_created (bool) – keep self._created value after switching db, else is reset to True
See also
Use
switch_collection
if you need to read from another collection
-
to_dict
(extended=False)¶ Serializes this document to a BSON/JSON dictionary.
- Parameters
extended (False) – whether to serialize extended JSON constructs such as ObjectIDs, Binary, etc. into JSON format
- Returns
a dict
-
to_json
(pretty_print=False)¶ Serializes the document to a JSON string.
- Parameters
pretty_print (False) – whether to render the JSON in human readable format with newlines and indentations
- Returns
a JSON string
-
to_mongo
(*args, **kwargs)¶ Return as SON data ready for use with MongoDB.
-
update
(**kwargs)¶ Performs an update on the
Document
A convenience wrapper toupdate()
.Raises
OperationError
if called on an object that has not yet been saved.
-
validate
(clean=True)¶ Ensure that all fields’ values are valid and that required fields are present.
Raises
ValidationError
if any of the fields’ values are found to be invalid.
-