.. module:: django_mongodb_backend.fields
Some MongoDB-specific fields are available in django_mongodb_backend.fields.
A field for storing lists of data. Most field types can be used, and you
pass another field instance as the :attr:`base_field
<ArrayField.base_field>`. You may also specify a :attr:`max_size
<ArrayField.max_size>`. ArrayField can be nested to store
multi-dimensional arrays.
If you give the field a :attr:`~django.db.models.Field.default`, ensure
it's a callable such as list (for an empty default) or a callable that
returns a list (such as a function). Incorrectly using default=[]
creates a mutable default that is shared between all instances of
ArrayField.
.. attribute:: base_field
This is a required argument.
Specifies the underlying data type and behavior for the array. It
should be an instance of a subclass of
:class:`~django.db.models.Field`. For example, it could be an
:class:`~django.db.models.IntegerField` or a
:class:`~django.db.models.CharField`. Most field types are permitted,
with the exception of those handling relational data
(:class:`~django.db.models.ForeignKey`,
:class:`~django.db.models.OneToOneField` and
:class:`~django.db.models.ManyToManyField`) and file fields (
:class:`~django.db.models.FileField` and
:class:`~django.db.models.ImageField`). :class:`EmbeddedModelField` is
also not (yet) supported.
It is possible to nest array fields - you can specify an instance of
``ArrayField`` as the ``base_field``. For example::
from django.db import models
from django_mongodb_backend.fields import ArrayField
class ChessBoard(models.Model):
board = ArrayField(
ArrayField(
models.CharField(max_length=10, blank=True),
max_size=8,
),
max_size=8,
)
Transformation of values between the database and the model, validation
of data and configuration, and serialization are all delegated to the
underlying base field.
.. attribute:: max_size
This is an optional argument.
If passed, the array will have a maximum size as specified, validated
by forms and model validation, but not enforced by the database.
There are a number of custom lookups and transforms for :class:`ArrayField`. We will use the following example model:
from django.db import models
from django_mongodb_backend.fields import ArrayField
class Post(models.Model):
name = models.CharField(max_length=200)
tags = ArrayField(models.CharField(max_length=200), blank=True)
def __str__(self):
return self.name
.. fieldlookup:: arrayfield.contains
The :lookup:`contains` lookup is overridden on :class:`ArrayField`. The
returned objects will be those where the values passed are a subset of the
data. It uses the $setIntersection operator. For example:
>>> Post.objects.create(name="First post", tags=["thoughts", "django"])
>>> Post.objects.create(name="Second post", tags=["thoughts"])
>>> Post.objects.create(name="Third post", tags=["tutorial", "django"])
>>> Post.objects.filter(tags__contains=["thoughts"])
<QuerySet [<Post: First post>, <Post: Second post>]>
>>> Post.objects.filter(tags__contains=["django"])
<QuerySet [<Post: First post>, <Post: Third post>]>
>>> Post.objects.filter(tags__contains=["django", "thoughts"])
<QuerySet [<Post: First post>]>This is the inverse of the :lookup:`contains <arrayfield.contains>` lookup -
the objects returned will be those where the data is a subset of the values
passed. It uses the $setIntersection operator. For example:
>>> Post.objects.create(name="First post", tags=["thoughts", "django"])
>>> Post.objects.create(name="Second post", tags=["thoughts"])
>>> Post.objects.create(name="Third post", tags=["tutorial", "django"])
>>> Post.objects.filter(tags__contained_by=["thoughts", "django"])
<QuerySet [<Post: First post>, <Post: Second post>]>
>>> Post.objects.filter(tags__contained_by=["thoughts", "django", "tutorial"])
<QuerySet [<Post: First post>, <Post: Second post>, <Post: Third post>]>.. fieldlookup:: arrayfield.overlap
Returns objects where the data shares any results with the values passed. It
uses the $setIntersection operator. For example:
>>> Post.objects.create(name="First post", tags=["thoughts", "django"])
>>> Post.objects.create(name="Second post", tags=["thoughts", "tutorial"])
>>> Post.objects.create(name="Third post", tags=["tutorial", "django"])
>>> Post.objects.filter(tags__overlap=["thoughts"])
<QuerySet [<Post: First post>, <Post: Second post>]>
>>> Post.objects.filter(tags__overlap=["thoughts", "tutorial"])
<QuerySet [<Post: First post>, <Post: Second post>, <Post: Third post>]>.. fieldlookup:: arrayfield.len
Returns the length of the array. The lookups available afterward are those available for :class:`~django.db.models.IntegerField`. For example:
>>> Post.objects.create(name="First post", tags=["thoughts", "django"])
>>> Post.objects.create(name="Second post", tags=["thoughts"])
>>> Post.objects.filter(tags__len=1)
<QuerySet [<Post: Second post>]>.. fieldlookup:: arrayfield.index
Index transforms index into the array. Any non-negative integer can be used. There are no errors if it exceeds the :attr:`max_size <ArrayField.max_size>` of the array. The lookups available after the transform are those from the :attr:`base_field <ArrayField.base_field>`. For example:
>>> Post.objects.create(name="First post", tags=["thoughts", "django"])
>>> Post.objects.create(name="Second post", tags=["thoughts"])
>>> Post.objects.filter(tags__0="thoughts")
<QuerySet [<Post: First post>, <Post: Second post>]>
>>> Post.objects.filter(tags__1__iexact="Django")
<QuerySet [<Post: First post>]>
>>> Post.objects.filter(tags__276="javascript")
<QuerySet []>These indexes use 0-based indexing.
.. fieldlookup:: arrayfield.slice
Slice transforms take a slice of the array. Any two non-negative integers can be used, separated by a single underscore. The lookups available after the transform do not change. For example:
>>> Post.objects.create(name="First post", tags=["thoughts", "django"])
>>> Post.objects.create(name="Second post", tags=["thoughts"])
>>> Post.objects.create(name="Third post", tags=["django", "python", "thoughts"])
>>> Post.objects.filter(tags__0_1=["thoughts"])
<QuerySet [<Post: First post>, <Post: Second post>]>
>>> Post.objects.filter(tags__0_2__contains=["thoughts"])
<QuerySet [<Post: First post>, <Post: Second post>]>These indexes use 0-based indexing.
Stores a model of type embedded_model.
.. attribute:: embedded_model
This is a required argument.
Specifies the model class to embed. It must be a subclass of
:class:`django_mongodb_backend.models.EmbeddedModel`.
It can be either a concrete model class or a :ref:`lazy reference
<lazy-relationships>` to a model class.
The embedded model cannot have relational fields
(:class:`~django.db.models.ForeignKey`,
:class:`~django.db.models.OneToOneField` and
:class:`~django.db.models.ManyToManyField`).
It is possible to nest embedded models. For example::
from django.db import models
from django_mongodb_backend.fields import EmbeddedModelField
from django_mongodb_backend.models import EmbeddedModel
class Address(EmbeddedModel):
...
class Author(EmbeddedModel):
address = EmbeddedModelField(Address)
class Book(models.Model):
author = EmbeddedModelField(Author)
See :doc:`/topics/embedded-models` for more details and examples.
Migrations support is limited
:djadmin:`makemigrations` does not yet detect changes to embedded models.
After you create a model with an EmbeddedModelField or add an
EmbeddedModelField to an existing model, no further updates to the
embedded model will be made. Using the models above as an example, if you
created these models and then added an indexed field to Address,
the index created in the nested Book embed is not created.
This field is typically the default primary key field for all models stored in MongoDB. See :ref:`specifying the-default-pk-field`.
Stores an :class:`~bson.objectid.ObjectId`.