Update docs

Author: aclark4life

docs/howto/queryable-encryption.rst

@@ -41,8 +41,8 @@ encrypted database in your :setting:`django:DATABASES` setting.
 
 This database will be used to store encrypted fields in your models. The
 following example shows how to configure an encrypted database using the
-:class:`pymongo.encryption_options.AutoEncryptionOpts` from the
-:mod:`pymongo.encryption_options` module.
+:class:`AutoEncryptionOpts <pymongo.encryption_options.AutoEncryptionOpts>` from the
+:mod:`encryption_options <pymongo.encryption_options>` module.
 
 This example uses a local KMS provider and a key vault namespace for storing
 encryption keys.
@@ -188,6 +188,7 @@ Example of KMS configuration with AWS KMS:
         def kms_provider(self, model, **hints):
             return "aws"
 
+.. _qe-configuring-encrypted-fields-map:
 
 Configuring the ``encrypted_fields_map``
 ========================================

docs/ref/django-admin.rst

@@ -22,9 +22,35 @@ Available commands
 .. django-admin:: showencryptedfieldsmap
 
     This command shows the mapping of encrypted fields to attributes including
-    data type, data keys and query types. It can be used to set the
-    ``encrypted_fields_map`` in ``AutoEncryptionOpts``.
+    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>`.
 
     .. 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
+
+    The output will look like::
+
+        {
+            "myapp.mymodel": {
+                "encrypted_field_1": {
+                    "bsonType": "string",
+                    "keyId": "UUID('...')",
+                    "queries": ["equality", "range"]
+                },
+                "encrypted_field_2": {
+                    "bsonType": "int",
+                    "keyId": "UUID('...')",
+                    "queries": ["equality"]
+                }
+            },
+            ...
+        }

docs/ref/models/encrypted-fields.rst

@@ -88,29 +88,32 @@ Queryable Encryption.
 
     .. versionadded:: 5.2.3
 
-    A mixin that can be used to create custom encrypted fields that support
-    MongoDB's Queryable Encryption.
+    A mixin that can be used to create custom encrypted fields with Queryable
+    Encryption.
 
-    To create a custom encrypted field, inherit from ``EncryptedFieldMixin`` and
-    the desired Django field class.
-
-
-    For example, to create a custom encrypted field that supports ``equality``
-    queries, you can define it as follows:
+    To create an encrypted field, inherit from ``EncryptedFieldMixin`` and
+    your custom field class:
 
     .. code-block:: python
 
         from django.db import models
         from django_mongodb_backend.fields import EncryptedFieldMixin
-        from .models import MyField
+        from myapp.fields import MyField
 
 
         class MyEncryptedField(EncryptedFieldMixin, MyField):
             pass
 
 
+    You can then use your custom encrypted field in a model, specifying the
+    desired query types:
+
+    .. code-block:: python
+
         class MyModel(models.Model):
             my_encrypted_field = MyEncryptedField(
                 queries={"queryType": "equality"},
-                # Other field options...
+            )
+            my_encrypted_field_too = MyEncryptedField(
+                queries={"queryType": "range"},
             )

docs/ref/utils.rst

@@ -48,3 +48,41 @@ following parts can be considered stable.
 
     But for maximum flexibility, construct :setting:`DATABASES` manually as
     described in :ref:`configuring-databases-setting`.
+
+.. versionadded:: 5.2.3
+
+``model_has_encrypted_fields()``
+=================================
+
+.. function:: model_has_encrypted_fields(model)
+
+    Returns ``True`` if the given Django model has any fields that use
+    encrypted models.
+
+    Example usage in a database router::
+
+        from django_mongodb_backend.utils import model_has_encrypted_fields
+
+        class EncryptedRouter:
+            def db_for_read(self, model, **hints):
+                if model_has_encrypted_fields(model):
+                    return "encrypted"
+                return "default"
+
+            def db_for_write(self, model, **hints):
+                if model_has_encrypted_fields(model):
+                    return "encrypted"
+                return "default"
+
+            def allow_migrate(self, db, app_label, model_name=None, **hints):
+                if hints.get("model"):
+                    if model_has_encrypted_fields(hints["model"]):
+                        return db == "encrypted"
+                    else:
+                        return db == "default"
+                return None
+
+            def kms_provider(self, model):
+                if model_has_encrypted_fields(model):
+                    return "local"
+            return None

docs/topics/known-issues.rst

@@ -26,6 +26,8 @@ Model fields
   - :class:`~django.db.models.CompositePrimaryKey`
   - :class:`~django.db.models.GeneratedField`
 
+.. _known-issues-limitations-querying:
+
 Querying
 ========
 

docs/topics/queryable-encryption.rst

@@ -21,6 +21,9 @@ queries on certain encrypted fields. To use encrypted fields in your models,
 import the necessary field types from ``django_mongodb_backend.models`` and
 define your models as usual.
 
+Here's the `Python Queryable Encryption Tutorial`_ example implemented in
+Django:
+
 .. code-block:: python
 
     # myapp/models.py
@@ -94,8 +97,10 @@ query type in the model field definition. For example, if you want to query the
         billing = EncryptedEmbeddedModelField("Billing")
         bill_amount = models.DecimalField(max_digits=10, decimal_places=2)
 
-Query types
-~~~~~~~~~~~
+.. _qe-available-query-types:
+
+Available query types
+~~~~~~~~~~~~~~~~~~~~~
 
 The ``queries`` option should be a dictionary that specifies the type of queries
 that can be performed on the field. The :ref:`available query types
@@ -116,30 +121,12 @@ For example, to find a patient by their SSN, you can do the following::
     >>> patient.name
     'Bob'
 
-
 QuerySet limitations
 ~~~~~~~~~~~~~~~~~~~~
 
-When using Django QuerySets with MongoDB Queryable Encryption, it’s important to
-understand that many typical ORM features are restricted because the database
-only sees encrypted ciphertext, not plaintext. This means that only certain
-query types are supported, and a lot of filtering, sorting, and aggregating must
-be done client-side after decryption. Key limitations include:
-
-- **Equality only filtering** – You can filter encrypted fields using exact
-  matches, but operators like contains, startswith, regex, or unsupported range
-  lookups will not work.
-- **No server-side sorting** – .order_by() on encrypted fields won’t produce
-  meaningful results; sorting needs to happen after decryption in Python.
-- **No server-side aggregation** – Functions like annotate() or aggregate()
-  won’t operate on encrypted fields; you must aggregate locally after fetching
-  data.
-- **Index constraints** – Queries are only possible on encrypted fields that
-  have a configured queryable encryption index and keys available on the client.
-- **No joins on encrypted fields** – Filtering across relationships using
-  encrypted foreign keys is unsupported because matching must happen
-  client-side.
-
-In short, when working with Queryable Encryption, design your queries to use
-exact matches only on encrypted fields, and plan to handle any sorting or
-aggregation after results are decrypted in your application code.
+In addition to :ref:`Django MongoDB Backend's QuerySet limitations
+<known-issues-limitations-querying>`,
+
+.. TODO
+
+.. _Python Queryable Encryption Tutorial: https://github.com/mongodb/docs/tree/main/content/manual/manual/source/includes/qe-tutorials/python