diff --git a/docs/source/embedded-models.rst b/docs/source/embedded-models.rst new file mode 100644 index 00000000..389a2b22 --- /dev/null +++ b/docs/source/embedded-models.rst @@ -0,0 +1,52 @@ +Embedded Models +=============== + +Use :class:`~django_mongdob.fields.EmbeddedModelField` to structure your data +using `embedded documents +`_. + +The Basics +---------- + +Let's consider this example:: + + from django_mongodb.fields import EmbeddedModelField + + class Customer(models.Model): + name = models.CharField(...) + address = EmbeddedModelField('Address') + ... + + class Address(models.Model): + ... + city = models.CharField(...) + + +The API is very natural and is similar to that of Django's relation fields:: + + >>> Customer(name='Bob', address=Address(city='New York', ...), ...).save() + >>> bob = Customer.objects.get(...) + >>> bob.address + + >>> bob.address.city + 'New York' + +Represented in BSON, Bob's structure looks like this: + +.. code-block:: js + + { + "_id": ObjectId(...), + "name": "Bob", + "address": { + ... + "city": "New York" + }, + ... + } + + +Querying ``EmbeddedModelField`` +------------------------------- + +... diff --git a/docs/source/fields.rst b/docs/source/fields.rst index 0bb0feb3..98249839 100644 --- a/docs/source/fields.rst +++ b/docs/source/fields.rst @@ -5,6 +5,39 @@ Model field reference Some MongoDB-specific fields are available in ``django_mongodb.fields``. +``EmbeddedModelField`` +---------------------- + +.. class:: EmbeddedModelField(embedded_model, **kwargs) + +Stores a model of type ``embedded_model``. + + .. attribute:: embedded_model + + This is a required argument. + + Specifies the model class to embed. + + 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.fields import EmbeddedModelField + + + class ChessBoard(models.Model): + board = EmbeddedModelField( + ArrayField( + models.CharField(max_length=10, blank=True), + size=8, + ), + size=8, + ) + ``ObjectIdField`` ----------------- diff --git a/docs/source/index.rst b/docs/source/index.rst index 8df60944..80dcce02 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -8,6 +8,7 @@ django-mongodb 5.0.x documentation fields querysets forms + embedded-models Indices and tables ==================