edits

Author: timgraham

django_mongodb_backend/fields/embedded_model_array.py

@@ -86,14 +86,17 @@ def as_mql(self, compiler, connection):
 
 class _EmbeddedModelArrayOutputField(ArrayField):
     """
-    Represents the output of an EmbeddedModelArrayField when traversed in a query path.
+    Represent the output of an EmbeddedModelArrayField when traversed in a
+    query path.
 
-    This field is not meant to be used directly in model definitions. It exists solely to
-    support query output resolution; when an EmbeddedModelArrayField is accessed in a query,
-    the result should behave like an array of the embedded model's target type.
+    This field is not meant to be used in model definitions. It exists solely
+    to support query output resolution. When an EmbeddedModelArrayField is
+    accessed in a query, the result should behave like an array of the embedded
+    model's target type.
 
-    While it mimics ArrayField's lookups behavior, the way those lookups are resolved
-    follows the semantics of EmbeddedModelArrayField rather than native array behavior.
+    While it mimics ArrayField's lookup behavior, the way those lookups are
+    resolved follows the semantics of EmbeddedModelArrayField rather than
+    ArrayField.
     """
 
     ALLOWED_LOOKUPS = {
@@ -115,19 +118,20 @@ def process_rhs(self, compiler, connection):
         value = self.rhs
         if not self.get_db_prep_lookup_value_is_iterable:
             value = [value]
-        # Value must be serialized based on the query target.
-        # If querying a subfield inside the array (i.e., a nested KeyTransform), use the output
-        # field of the subfield. Otherwise, use the base field of the array itself.
+        # Value must be serialized based on the query target. If querying a
+        # subfield inside the array (i.e., a nested KeyTransform), use the
+        # output field of the subfield. Otherwise, use the base field of the
+        # array itself.
         get_db_prep_value = self.lhs._lhs.output_field.get_db_prep_value
         return None, [
             v if hasattr(v, "as_mql") else get_db_prep_value(v, connection, prepared=True)
             for v in value
         ]
 
     def as_mql(self, compiler, connection):
-        # Querying a subfield within the array elements (via nested KeyTransform).
-        # Replicates MongoDB's implicit ANY-match by mapping over the array and applying
-        # `$in` on the subfield.
+        # Querying a subfield within the array elements (via nested
+        # KeyTransform). Replicate MongoDB's implicit ANY-match by mapping over
+        # the array and applying $in on the subfield.
         lhs_mql = process_lhs(self, compiler, connection)
         inner_lhs_mql = lhs_mql["$ifNull"][0]["$map"]["in"]
         values = process_rhs(self, compiler, connection)
@@ -183,7 +187,7 @@ def __init__(self, key_name, array_field, *args, **kwargs):
         self.key_name = key_name
         # The iteration items begins from the base_field, a virtual column with
         # base field output type is created.
-        column_target = array_field.embedded_model._meta.get_field(key_name).clone()
+        column_target = array_field.base_field.embedded_model._meta.get_field(key_name).clone()
         column_name = f"$item.{key_name}"
         column_target.db_column = column_name
         column_target.set_attributes_from_name(column_name)
@@ -199,17 +203,18 @@ def get_lookup(self, name):
 
     def get_transform(self, name):
         """
-        Validate that `name` is either a field of an embedded model or a
-        lookup on an embedded model's field.
+        Validate that `name` is either a field of an embedded model or am
+        allowed lookup on an embedded model's field.
         """
-        # Once the sub lhs is a transform, all the filter are applied over it.
-        # Otherwise get transform from EMF.
+        # Once the sub-lhs is a transform, all the filters are applied over it.
+        # Otherwise get the transform from EMF.
         if transform := self._lhs.get_transform(name):
             if isinstance(transform, KeyTransformFactory):
                 raise ValueError("Cannot perform multiple levels of array traversal in a query.")
             self._sub_transform = transform
             return self
         output_field = self._lhs.output_field
+        # The lookup must be allowed AND a valid lookup for the field.
         allowed_lookups = self.output_field.ALLOWED_LOOKUPS.intersection(
             set(output_field.get_lookups())
         )

docs/source/ref/models/fields.rst

@@ -91,7 +91,7 @@ We will use the following example model::
         def __str__(self):
             return self.name
 
-.. fieldlookup:: arrayfield.contains
+.. fieldlookup:: mongo-arrayfield.contains
 
 ``contains``
 ^^^^^^^^^^^^
@@ -134,7 +134,7 @@ passed. It uses the ``$setIntersection`` operator. For example:
     >>> Post.objects.filter(tags__contained_by=["thoughts", "django", "tutorial"])
     <QuerySet [<Post: First post>, <Post: Second post>, <Post: Third post>]>
 
-.. fieldlookup:: arrayfield.overlap
+.. fieldlookup:: mongo-arrayfield.overlap
 
 ``overlap``
 ~~~~~~~~~~~
@@ -154,7 +154,7 @@ uses the ``$setIntersection`` operator. For example:
     >>> Post.objects.filter(tags__overlap=["thoughts", "tutorial"])
     <QuerySet [<Post: First post>, <Post: Second post>, <Post: Third post>]>
 
-.. fieldlookup:: arrayfield.len
+.. fieldlookup:: mongo-arrayfield.len
 
 ``len``
 ^^^^^^^
@@ -170,7 +170,7 @@ available for :class:`~django.db.models.IntegerField`. For example:
     >>> Post.objects.filter(tags__len=1)
     <QuerySet [<Post: Second post>]>
 
-.. fieldlookup:: arrayfield.index
+.. fieldlookup:: mongo-arrayfield.index
 
 Index transforms
 ^^^^^^^^^^^^^^^^
@@ -196,7 +196,7 @@ array. The lookups available after the transform are those from the
 
 These indexes use 0-based indexing.
 
-.. fieldlookup:: arrayfield.slice
+.. fieldlookup:: mongo-arrayfield.slice
 
 Slice transforms
 ^^^^^^^^^^^^^^^^
@@ -299,155 +299,6 @@ These indexes use 0-based indexing.
     As described above for :class:`EmbeddedModelField`,
     :djadmin:`makemigrations` does not yet detect changes to embedded models.
 
-Querying ``EmbeddedModelArrayField``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-There are a number of custom lookups and a transform for
-:class:`EmbeddedModelArrayField`, similar to those available
-for :class:`ArrayField`.
-We will use the following example model::
-
-    from django.db import models
-    from django_mongodb_backend.fields import EmbeddedModelArrayField
-
-
-    class Tag(EmbeddedModel):
-        label = models.CharField(max_length=100)
-
-    class Post(models.Model):
-        name = models.CharField(max_length=200)
-        tags = EmbeddedModelArrayField(Tag)
-
-        def __str__(self):
-            return self.name
-
-Embedded field lookup
-^^^^^^^^^^^^^^^^^^^^^
-
-Embedded field lookup for :class:`EmbeddedModelArrayField` allow querying
-fields of the embedded model. This is done by composing the two involved paths:
-the path to the ``EmbeddedModelArrayField`` and the path within the nested
-embedded model.
-This composition enables generating the appropriate query for the lookups.
-
-.. fieldlookup:: embeddedmodelarrayfield.in
-
-``in``
-^^^^^^
-
-Returns objects where any of the embedded documents in the field match any of
-the values passed. For example:
-
-.. code-block:: pycon
-
-    >>> Post.objects.create(
-    ...     name="First post", tags=[Tag(label="thoughts"), Tag(label="django")]
-    ... )
-    >>> Post.objects.create(name="Second post", tags=[Tag(label="thoughts")])
-    >>> Post.objects.create(
-    ...     name="Third post", tags=[Tag(label="tutorial"), Tag(label="django")]
-    ... )
-
-    >>> Post.objects.filter(tags__label__in=["thoughts"])
-    <QuerySet [<Post: First post>, <Post: Second post>]>
-
-    >>> Post.objects.filter(tags__label__in=["tutorial", "thoughts"])
-    <QuerySet [<Post: First post>, <Post: Second post>, <Post: Third post>]>
-
-.. fieldlookup:: embeddedmodelarrayfield.len
-
-``len``
-^^^^^^^
-
-Returns the length of the embedded model array. The lookups available afterward
-are those available for :class:`~django.db.models.IntegerField`. For example:
-
-.. code-block:: pycon
-
-    >>> Post.objects.create(
-    ...     name="First post", tags=[Tag(label="thoughts"), Tag(label="django")]
-    ... )
-    >>> Post.objects.create(name="Second post", tags=[Tag(label="thoughts")])
-
-    >>> Post.objects.filter(tags__len=1)
-    <QuerySet [<Post: Second post>]>
-
-.. fieldlookup:: embeddedmodelarrayfield.exact
-
-``exact``
-^^^^^^^^^
-
-Returns objects where **any** embedded model in the array exactly matches the
-given value. This acts like an existence filter on matching embedded documents.
-
-.. code-block:: pycon
-
-    >>> Post.objects.create(
-    ...     name="First post", tags=[Tag(label="thoughts"), Tag(label="django")]
-    ... )
-    >>> Post.objects.create(name="Second post", tags=[Tag(label="tutorial")])
-
-    >>> Post.objects.filter(tags__label__exact="tutorial")
-    <QuerySet [<Post: Second post>]>
-
-.. fieldlookup:: embeddedmodelarrayfield.iexact
-
-``iexact``
-^^^^^^^^^^
-
-Returns objects where **any** embedded model in the array has a field that
-matches the given value **case-insensitively**. This works like ``exact`` but
-ignores letter casing.
-
-.. code-block:: pycon
-
-
-    >>> Post.objects.create(
-    ...     name="First post", tags=[Tag(label="Thoughts"), Tag(label="Django")]
-    ... )
-    >>> Post.objects.create(name="Second post", tags=[Tag(label="tutorial")])
-
-    >>> Post.objects.filter(tags__label__iexact="django")
-    <QuerySet [<Post: First post>]>
-
-    >>> Post.objects.filter(tags__label__iexact="TUTORIAL")
-    <QuerySet [<Post: Second post>]>
-
-.. fieldlookup:: embeddedmodelarrayfield.gt
-.. fieldlookup:: embeddedmodelarrayfield.gte
-.. fieldlookup:: embeddedmodelarrayfield.lt
-.. fieldlookup:: embeddedmodelarrayfield.lte
-
-``Greater Than, Greater Than or Equal, Less Than, Less Than or Equal``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-These lookups return objects where **any** embedded document contains a value
-that satisfies the corresponding comparison. These are typically used on
-numeric or comparable fields within the embedded model.
-
-Examples:
-
-.. code-block:: pycon
-
-    Post.objects.create(
-        name="First post", tags=[Tag(label="django", rating=5), Tag(label="rest", rating=3)]
-    )
-    Post.objects.create(
-        name="Second post", tags=[Tag(label="python", rating=2)]
-    )
-
-    Post.objects.filter(tags__rating__gt=3)
-    <QuerySet [<Post: First post>]>
-
-    Post.objects.filter(tags__rating__gte=3)
-    <QuerySet [<Post: First post>, <Post: Second post>]>
-
-    Post.objects.filter(tags__rating__lt=3)
-    <QuerySet []>
-
-    Post.objects.filter(tags__rating__lte=3)
-    <QuerySet [<Post: First post>, <Post: Second post>]>
-
 ``ObjectIdAutoField``
 ---------------------
 

docs/source/topics/embedded-models.rst

@@ -115,3 +115,69 @@ Represented in BSON, the post's structure looks like this:
       name: 'Hello world!',
       tags: [ { name: 'welcome' }, { name: 'test' } ]
     }
+
+Querying ``EmbeddedModelArrayField``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can query into an embedded model array using the same double underscore
+syntax as relational fields. For example, to find posts that have a label with
+name "test"::
+
+    >>> Post.objects.filter(tags__name="test")
+
+There are a limited set of lookups you can chain after an embedded field:
+
+* :lookup:`exact`, :lookup:`iexact`
+* :lookup:`in`
+* :lookup:`gt`, :lookup:`gte`, :lookup:`lt`, :lookup:`lte`
+
+For example, to find posts that have tags with name "test", "TEST", "tEsT",
+etc::
+
+>>> Post.objects.filter(tags__name__iexact="test")
+
+.. fieldlookup:: embeddedmodelarrayfield.len
+
+``len`` transform
+^^^^^^^^^^^^^^^^^
+
+You can also use the ``len`` transform to filter on the length of the array.
+The lookups available afterward are those available for
+:class:`~django.db.models.IntegerField`. For example, to match posts with one
+tag::
+
+    >>> Post.objects.filter(tags__len=1)
+
+or at least one tag::
+
+    >>> Post.objects.filter(tags__len__gte=1)
+
+Index and slice transforms
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Like :class:`~django_mongodb_backend.fields.ArrayField`, you can use
+:lookup:`index <mongo-arrayfield.index>` and :lookup:`slice
+<mongo-arrayfield.slice>` transforms to filter on particular items in an array.
+
+For example, to find posts where the first tag is named "test"::
+
+>>> Post.objects.filter(tags__0__name="test")
+
+Or to find posts where the one of the first two tags is named "test"::
+
+>>> Post.objects.filter(tags__0_1__name="test")
+
+These indexes use 0-based indexing.
+
+Nested ``EmbeddedModelArrayField``\s
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If your models use nested ``EmbeddedModelArrayField``\s, you can't use double
+underscores to query into the the second level.
+
+For example, if the ``Tag`` model had an ``EmbeddedModelArrayField`` called
+``colors``:
+
+    >>> Post.objects.filter(tags__colors__name="blue")
+    ...
+    ValueError: Cannot perform multiple levels of array traversal in a query.