edits

Author: timgraham

.github/workflows/test-python-atlas.yml

@@ -5,7 +5,7 @@ on:
       paths:
       - '**.py'
       - '!setup.py'
-      - '.github/workflows/test-python.yml'
+      - '.github/workflows/test-python-atlas.yml'
   workflow_dispatch:
 
 concurrency:

django_mongodb_backend/checks.py

@@ -6,7 +6,12 @@
 
 
 def check_indexes(app_configs, databases=None, **kwargs):  # noqa: ARG001
-    # Validate vector search indexes for models.
+    """
+    Call Index.check() on all model indexes.
+
+    This function will be obsolete when Django calls Index.check() after
+    https://code.djangoproject.com/ticket/36273.
+    """
     errors = []
     if app_configs is None:
         models = apps.get_models()
@@ -24,4 +29,4 @@ def check_indexes(app_configs, databases=None, **kwargs):  # noqa: ARG001
 
 
 def register_checks():
-    register(Tags.models)(check_indexes)
+    register(check_indexes, Tags.models)

django_mongodb_backend/features.py

@@ -615,10 +615,13 @@ def is_mongodb_6_3(self):
 
     @cached_property
     def supports_atlas_search(self):
+        """Does the server support Atlas search queries and search indexes?"""
         try:
-            # Check search indexes support (raises if unsupported).
+            # An existing collection must be used on MongoDB 6, otherwise
+            # the operation will not error.
             self.connection.get_collection("django_migrations").list_search_indexes()
         except OperationFailure:
+            # Error: $listSearchIndexes stage is only allowed on MongoDB Atlas
             return False
         else:
             return True

django_mongodb_backend/indexes.py

@@ -125,9 +125,11 @@ def check(self, model, connection):
             )
         return errors
 
-    # Maps Django internal type to atlas search index type.
-    # Reference: https://www.mongodb.com/docs/atlas/atlas-search/define-field-mappings/#data-types
     def search_index_data_types(self, field, db_type):
+        """
+        Map a model field's internal type to search index type.
+        Reference: https://www.mongodb.com/docs/atlas/atlas-search/define-field-mappings/#data-types
+        """
         if field.get_internal_type() == "UUIDField":
             return "uuid"
         if field.get_internal_type() in ("ObjectIdAutoField", "ObjectIdField"):

docs/source/conf.py

@@ -44,6 +44,7 @@
     "mongodb": ("https://www.mongodb.com/docs/languages/python/django-mongodb/v5.1/", None),
     "pymongo": ("https://pymongo.readthedocs.io/en/stable/", None),
     "python": ("https://docs.python.org/3/", None),
+    "atlas": ("https://www.mongodb.com/docs/atlas/", None),
 }
 
 root_doc = "contents"

docs/source/ref/models/indexes.rst

@@ -11,17 +11,27 @@ Some MongoDB-specific indexes are available in
 ``SearchIndex``
 ===============
 
-.. class:: SearchIndex(*expressions, **kwargs)
+.. class:: SearchIndex(fields=(), name=None)
 
-...
+Creates a basic :doc:`search index <atlas:atlas-search/index-definitions>` on
+the given field(s).
 
+If ``name`` isn't provided, one will be generated automatically. If you need
+to reference the name in your search query and don't provide your own name,
+you can lookup the generated one using: ``Model._meta.indexes[0].name``
+(substiting a different index as needed if your model has multiple indexes).
 
 ``VectorSearchIndex``
 =====================
 
-.. class:: VectorSearchIndex(*expressions, similarities="cosine", **kwargs)
+.. class:: VectorSearchIndex(fields=(), similarities="cosine", name=None)
+
+A subclass of :class:`SearchIndex` that creates a :doc:`vector search index
+<atlas:atlas-vector-search/vector-search-type>` on the given field(s).
 
 Available values for ``similarities`` are ``"euclidean"``, ``"cosine"``, and
-``"dotProduct"``.
+``"dotProduct"``. You can provide either a string value, in which case that
+value will be applied to all fields, or a list or tuple of values of the same
+length as list/tuple of fields with a similarity value for each field.
 
-...
+<document restrictions on arrayfield, etc.>

tests/indexes_/test_checks.py

@@ -14,8 +14,8 @@
 @skipIfDBFeature("supports_atlas_search")
 @isolate_apps("indexes_", attr_name="apps")
 @override_system_checks([check_indexes])
-class InvalidSearchIndexesTests(TestCase):
-    def test_requires_atlas_search_support(self):
+class UnsupportedSearchIndexesTests(TestCase):
+    def test_search_requires_atlas_search_support(self):
         class Article(models.Model):
             title = models.CharField(max_length=10)
 
@@ -38,12 +38,7 @@ class Meta:
             ],
         )
 
-
-@skipIfDBFeature("supports_atlas_search")
-@isolate_apps("indexes_", attr_name="apps")
-@override_system_checks([check_indexes])
-class UnsupportedSearchIndexesTests(TestCase):
-    def test_requires_atlas_search_support(self):
+    def test_vector_search_requires_atlas_search_support(self):
         class Article(models.Model):
             title = models.CharField(max_length=10)
 
@@ -151,8 +146,8 @@ class Meta:
                     "Field 'vector_data' is defined more than once. Vector and filter "
                     "fields must use distinct field names.",
                     id="django_mongodb_backend.indexes.VectorSearchIndex.E004",
-                    hint="If you need different configurations for the same field,"
-                    " create separate indexes.",
+                    hint="If you need different configurations for the same field, "
+                    "create separate indexes.",
                     obj=Article._meta.indexes[0],
                 ),
             ],