doc query limitations + docs polish + todos

Author: timgraham

django_mongodb_backend/features.py

@@ -636,8 +636,12 @@ def _supports_transactions(self):
     @cached_property
     def supports_queryable_encryption(self):
         """
-        Queryable Encryption requires a MongoDB 8.0 or later replica set or sharded
-        cluster, as well as MongoDB Atlas or Enterprise.
+        For testing purposes, Queryable Encryption requires a MongoDB 8.0 or
+        later replica set or sharded cluster, as well as MongoDB Atlas or
+        Enterprise. This flag must not guard any non-test functionality since
+        it would prevent MongoDB 7.0 from being used, which also supports
+        Queryable Encryption. The models in tests/encryption_ aren't compatible
+        with MongoDB 7.0 because {"queryType": "range"} being "rangePreview".
         """
         self.connection.ensure_connection()
         build_info = self.connection.connection.admin.command("buildInfo")

docs/howto/queryable-encryption.rst

@@ -14,7 +14,7 @@ Encryption in your Django project.
 .. admonition:: MongoDB requirements
 
     Queryable Encryption can be used with MongoDB replica sets or sharded
-    clusters running version 8.0 or later. Standalone instances are not
+    clusters running version 7.0 or later. Standalone instances are not
     supported. The :ref:`manual:qe-compatibility-reference` table summarizes
     which MongoDB server products support Queryable Encryption.
 

docs/ref/django-admin.rst

@@ -21,18 +21,12 @@ Available commands
 
 .. django-admin:: showencryptedfieldsmap
 
-    This command shows the mapping of encrypted fields to attributes including
-    data type, data keys and query types. Its output can be used to set the
-    :ref:`encrypted_fields_map <qe-configuring-encrypted-fields-map>` argument
-    in :class:`AutoEncryptionOpts
-    <pymongo.encryption_options.AutoEncryptionOpts>`.
+    This command generates output for includision in
+    :class:`~pymongo.encryption_options.AutoEncryptionOpts`\'s
+    ``encrypted_fields_map`` argument.
+
+    See :ref:`qe-configuring-encrypted-fields-map`.
 
     .. django-admin-option:: --database DATABASE
 
         Specifies the database to use. Defaults to ``default``.
-
-    To show the encrypted fields map for a database named ``encrypted``, run:
-
-    .. code-block:: console
-
-        $ python manage.py showencryptedfieldsmap --database encrypted

docs/ref/settings.rst

@@ -2,8 +2,6 @@
 Settings
 ========
 
-.. _queryable-encryption-settings:
-
 Queryable Encryption
 ====================
 

docs/topics/queryable-encryption.rst

@@ -5,8 +5,8 @@ Queryable Encryption
 .. versionadded:: 5.2.3
 
 Once you have successfully set up MongoDB Queryable Encryption as described in
-:doc:`the installation guide </howto/queryable-encryption>`, you can start
-using encrypted fields in your Django models.
+:doc:`/howto/queryable-encryption`, you can start using encrypted fields in
+your Django models.
 
 Encrypted fields
 ================
@@ -59,6 +59,8 @@ Here are models based on the `Python Queryable Encryption Tutorial`_::
 Migrations
 ----------
 
+# TODO: this is coupled to the howto
+
 Once you have defined your models, create migrations with:
 
 .. code-block:: console
@@ -76,9 +78,14 @@ model data. The fields will automatically handle encryption and decryption,
 ensuring that :ref:`sensitive data is stored securely in the database
 <manual:qe-features-encryption-at-rest>`.
 
+# TODO: once encrypted models are migrated, encrypted fields cannot be added or
+modified.
+
 Routers
 -------
 
+# TODO: this is redundant with the howto.
+
 The example above requires a :ref:`database router
 <qe-configuring-database-routers-setting>` to direct operations on models with
 encrypted fields to the appropriate database. It also requires the use of a
@@ -96,16 +103,15 @@ Querying encrypted fields
 
 In order to query encrypted fields, you must define the queryable encryption
 query type in the model field definition. For example, if you want to query the
-``ssn`` field for equality, you can define it as follows::
+``ssn`` field for equality, you can add the ``queries`` argument::
 
     class PatientRecord(EmbeddedModel):
         ssn = EncryptedCharField(max_length=11, queries={"queryType": "equality"})
-        billing = EncryptedEmbeddedModelField("Billing")
-        bill_amount = models.DecimalField(max_digits=10, decimal_places=2)
 
-Then you can perform a query like this:
+Then you can perform a equality query just like you would on a non-encrypted
+field:
 
-.. code-block:: console
+.. code-block:: pycon
 
     >>> patient = Patient.objects.get(patient_record__ssn="123-45-6789")
     >>> patient.name
@@ -116,13 +122,13 @@ Then you can perform a query like this:
 Available query types
 ~~~~~~~~~~~~~~~~~~~~~
 
-The ``queries`` option should be a dictionary that specifies the type of queries
-that can be performed on the field. Of the :ref:`available query types
-<manual:qe-fundamentals-encrypt-query>` Django MongoDB Backend currently
-supports:
+The ``queries`` option should be a dictionary that specifies the type of
+queries that can be performed on the field, as well as any query options. The
+:ref:`available query types <manual:qe-fundamentals-encrypt-query>` depend on
+your version of MongoDB.
 
-- ``equality``
-- ``range``
+For example, in MongoDB 8.0, the supported types are ``equality`` and
+``range``.
 
 .. admonition:: Query types vs. Django lookups
 
@@ -131,10 +137,41 @@ supports:
     perform comparisons on encrypted fields, while Django's range lookups are
     used for filtering based on a range of values.
 
-QuerySet limitations
-~~~~~~~~~~~~~~~~~~~~
+``QuerySet`` limitations
+~~~~~~~~~~~~~~~~~~~~~~~~
 
 In addition to :ref:`Django MongoDB Backend's QuerySet limitations
-<known-issues-limitations-querying>`,
-
-.. TODO
+<known-issues-limitations-querying>`, some ``QuerySet`` methods aren't
+supported on encrypted fields. Each unsupported method is followed by a sample
+error message from the database. Depending on the exact query, error messages
+may vary.
+
+- :meth:`~django.db.models.query.QuerySet.order_by`: Cannot add an encrypted
+  field as a prefix of another encrypted field.
+- :meth:`~django.db.models.query.QuerySet.alias`,
+  :meth:`~django.db.models.query.QuerySet.annotate`,
+  :meth:`~django.db.models.query.QuerySet.distinct`: Cannot group on field
+  '_id.value' which is encrypted with the random algorithm or whose encryption
+  properties are not known until runtime.
+- :meth:`~django.db.models.query.QuerySet.dates`,
+  :meth:`~django.db.models.query.QuerySet.datetimes`: If the value type is a
+  date, the type of the index must also be date (and vice versa).
+- :meth:`~django.db.models.query.QuerySet.in_bulk`: Encrypted fields can't have
+  unique constraints.
+
+# TODO: add details about joined queries after
+https://github.com/mongodb/django-mongodb-backend/pull/443 is finalized.
+
+There are also several ``QuerySet`` methods that aren't permitted on any models
+(regardless of whether or not they have encrypted fields) that use a database
+connection with Automatic Encryption. Each unsupported method is followed by a
+sample error message from the database.
+
+- :meth:`~django.db.models.query.QuerySet.update`: Multi-document updates are
+  not allowed with Queryable Encryption.
+- :meth:`~django.db.models.query.QuerySet.aggregate`,
+  :meth:`~django.db.models.query.QuerySet.count`: Aggregation stage
+  $internalFacetTeeConsumer is not allowed or supported with automatic
+  encryption.
+- :meth:`~django.db.models.query.QuerySet.union`: Aggregation stage $unionWith
+  is not allowed or supported with automatic encryption.