Code review fixes

- Rename vars used for recursive calls
- parent_model -> path_prefix
- new_parent_model -> path
- Remove check for "fields" in encrypted_fields

  - encrypted_fields dict will always have "fields" key

- Document queryset limitations

Author: aclark4life

django_mongodb_backend/base.py

@@ -278,8 +278,9 @@ def cursor(self):
 
     def get_database_version(self):
         """Return a tuple of the database's version."""
-        # TODO: Replace with `tuple(self.connection.server_info()["versionArray"])` once
-        # pymongocrypt >= 1.14.2 is required and PYTHON-5429 is resolved.
+        # TODO: Remove this workaround and replace with
+        # `tuple(self.connection.server_info()["versionArray"])` when the minimum
+        # supported version of pymongocrypt is >= 1.14.2 and PYTHON-5429 is resolved.
         # See: https://jira.mongodb.org/browse/PYTHON-5429
         return tuple(self.connection.admin.command("buildInfo")["versionArray"])
 

django_mongodb_backend/features.py

@@ -636,7 +636,7 @@ def _supports_transactions(self):
     def supports_queryable_encryption(self):
         """
         Queryable Encryption requires a MongoDB 7.0 or later replica set or sharded
-        cluster, as well as MonogDB Atlas or Enterprise.
+        cluster, as well as MongoDB Atlas or Enterprise.
         """
         self.connection.ensure_connection()
         build_info = self.connection.connection.admin.command("buildInfo")

django_mongodb_backend/schema.py

@@ -479,7 +479,9 @@ def _create_collection(self, model):
             else:
                 encrypted_fields = encrypted_fields_map.get(db_table)
 
-            if encrypted_fields and encrypted_fields.get("fields"):
+            # if encrypted_fields and encrypted_fields.get("fields"):
+
+            if encrypted_fields:
                 db.create_collection(db_table, encryptedFields=encrypted_fields)
             else:
                 db.create_collection(db_table)
@@ -489,20 +491,20 @@ def _create_collection(self, model):
             db.create_collection(db_table)
 
     def _get_encrypted_fields(
-        self, model, create_data_keys=False, key_alt_name=None, parent_model=None
+        self, model, create_data_keys=False, key_alt_name=None, path_prefix=None
     ):
         """
         Recursively collect encryption schema data for only encrypted fields in a model.
         Returns None if no encrypted fields are found anywhere in the model hierarchy.
 
         key_alt_name is the base path used for keyAltNames.
-        parent_model is the dot-notated path inside the document for schema mapping.
+        path_prefix is the dot-notated path inside the document for schema mapping.
         """
         connection = self.connection
         client = connection.connection
         fields = model._meta.fields
         key_alt_name = key_alt_name or model._meta.db_table
-        parent_model = parent_model or ""
+        path_prefix = path_prefix or ""
 
         options = client._options
         auto_encryption_opts = getattr(options, "auto_encryption_opts", None)
@@ -520,7 +522,7 @@ def _get_encrypted_fields(
 
         for field in fields:
             new_key_alt_name = f"{key_alt_name}.{field.column}"
-            new_parent_model = f"{parent_model}.{field.column}" if parent_model else field.column
+            path = f"{path_prefix}.{field.column}" if path_prefix else field.column
 
             # --- EmbeddedModelField ---
             if isinstance(field, EmbeddedModelField):
@@ -550,7 +552,7 @@ def _get_encrypted_fields(
 
                     field_dict = {
                         "bsonType": "object",
-                        "path": new_parent_model,
+                        "path": path,
                         "keyId": data_key,
                     }
                     if getattr(field, "queries", False):
@@ -563,7 +565,7 @@ def _get_encrypted_fields(
                         field.embedded_model,
                         create_data_keys=create_data_keys,
                         key_alt_name=new_key_alt_name,
-                        parent_model=new_parent_model,
+                        path_prefix=path,
                     )
                     if embedded_result and embedded_result.get("fields"):
                         field_list.extend(embedded_result["fields"])
@@ -595,7 +597,7 @@ def _get_encrypted_fields(
 
                 field_dict = {
                     "bsonType": field.db_type(connection),
-                    "path": new_parent_model,
+                    "path": path,
                     "keyId": data_key,
                 }
                 if getattr(field, "queries", False):

docs/topics/queryable-encryption.rst

@@ -99,3 +99,33 @@ For example, to find a patient by their SSN, you can do the following::
     >>> patient = Patient.objects.get(ssn="123-45-6789")
     >>> 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.
+- **Admin/debug limitations** – You’ll need to integrate client-side decryption
+  for Django admin or tools, otherwise you’ll see ciphertext.
+
+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.