DOCSP-50489: EmbeddedModelArrayField support (#37)

* DOCSP-50489: EmbeddedModelArrayField support

* edit limitations

* edits

* RR feedback

* AC feedback

(cherry picked from commit 8a0692b)

Author: norareidy

source/includes/model-data/models.py

@@ -79,4 +79,29 @@ class Meta:
 
     def __str__(self):
         return self.title
-# end-embedded-field
+# end-embedded-field
+
+# start-embedded-array-field
+from django.db import models
+from django_mongodb_backend.models import EmbeddedModel
+from django_mongodb_backend.fields import EmbeddedModelArrayField
+
+class Actor(EmbeddedModel):
+    first_name = models.CharField(max_length=100)
+    last_name = models.CharField(max_length=100)
+    role = models.CharField(max_length=100)
+
+class Movie(models.Model):
+    title = models.CharField(max_length=200)
+    plot = models.TextField(blank=True)
+    runtime = models.IntegerField(default=0)
+    released = models.DateTimeField("release date", null=True, blank=True)
+    cast = EmbeddedModelArrayField(Actor, null=True, blank=True)
+
+    class Meta:
+        db_table = "movies"
+        managed = False
+    
+    def __str__(self):
+        return self.title
+# end-embedded-array-field

source/limitations-upcoming.txt

@@ -108,11 +108,8 @@ in the following table. To view a full list of supported types, see the
      - Planned GA Support
 
    * - ``Array``
-     - *Partially Supported*. You can use the ``ArrayField`` field type with the
-       following limitations:
-
-       - ``ArrayField`` polymorphism is not supported.
-       -  Nested ``EmbeddedModelField`` values within an ``ArrayField`` are not supported.
+     - *Partially Supported*. You can use the ``ArrayField`` field type, but
+       ``ArrayField`` polymorphism is not supported.
 
      - ✓
 

source/model-data/models.txt

@@ -168,9 +168,10 @@ The following table describes supported BSON field types and their
          in this guide.
 
    * - ``Object``
-     - ``EmbeddedModelField``
-     - | Stores embedded documents. To learn more about using this field
-         with {+django-odm+}, see the :ref:`django-models-embedded` section in this guide.
+     - ``EmbeddedModelField`` or ``EmbeddedModelArrayField``
+     - | Stores one or multiple embedded documents. To learn more about using these fields
+         with {+django-odm+}, see the :ref:`django-models-embedded` and :ref:`django-models-embedded-array`
+         sections.
 
    * - ``ObjectId``
      - ``ObjectIdField``
@@ -452,6 +453,36 @@ and modifies the ``Movie`` model to include the ``EmbeddedModelField``:
    To learn how to query data stored in an ``EmbeddedModelField``, see
    :ref:`django-query-embedded` in the Specify a Query guide.
 
+.. _django-models-embedded-array:
+
+Use an EmbeddedModelArrayField
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can use an ``EmbeddedModelArrayField`` to represent a MongoDB document
+field that stores an array of documents in a one-to-many relationship. Each
+document in the array corresponds to a {+django-odm+} ``EmbeddedModelField`` value. To create an ``EmbeddedModelArrayField``,
+use the ``EmbeddedModelArrayField()`` class constructor and pass the following arguments:
+
+- ``embedded_model``: Specifies the model stored in each array item.
+
+- ``max_size``: *(Optional)* Specifies the maximum size of the array.
+
+Example
+```````
+
+This example adds an ``EmbeddedModelArrayField`` value to the model created in
+the :ref:`Define a Model example <django-models-define-ex>` in this
+guide. This ``cast`` field stores an array of embedded ``Actor`` models.
+The following code defines the ``Actor`` model and modifies the ``Movie`` model
+to include the ``EmbeddedModelArrayField``:
+
+.. literalinclude:: /includes/model-data/models.py
+   :start-after: start-embedded-array-field
+   :end-before: end-embedded-array-field
+   :language: python
+   :copyable:
+   :emphasize-lines: 5, 15
+
 Additional Information
 ----------------------