INTPYTHON-729 Allow creating search indexes with field mappings and analyzers

Co-authored-by: Tim Graham <[email protected]>

Author: Jibola

django_mongodb_backend/indexes.py

@@ -109,9 +109,38 @@ class SearchIndex(Index):
     suffix = "six"
     _error_id_prefix = "django_mongodb_backend.indexes.SearchIndex"
 
-    def __init__(self, *, fields=(), name=None):
+    def __init__(
+        self, *, fields=(), field_mappings=None, name=None, analyzer=None, search_analyzer=None
+    ):
+        if field_mappings and not isinstance(field_mappings, dict):
+            raise ValueError(
+                "field_mappings must be a dictionary mapping field names to their "
+                "Atlas Search index options."
+            )
+        if analyzer is not None and not isinstance(analyzer, str):
+            raise ValueError(f"analyzer must be a string; got: {type(analyzer)}.")
+        if search_analyzer is not None and not isinstance(search_analyzer, str):
+            raise ValueError(f"search_analyzer must be a string; got: {type(search_analyzer)}.")
+        self.field_mappings = field_mappings
+        self.analyzer = analyzer
+        self.search_analyzer = search_analyzer
+        if field_mappings:
+            if fields:
+                raise ValueError("Cannot provide fields and field_mappings.")
+            fields = [*self.field_mappings.keys()]
         super().__init__(fields=fields, name=name)
 
+    def deconstruct(self):
+        path, args, kwargs = super().deconstruct()
+        if self.field_mappings:
+            kwargs["field_mappings"] = self.field_mappings
+            del kwargs["fields"]
+        if self.analyzer:
+            kwargs["analyzer"] = self.analyzer
+        if self.search_analyzer:
+            kwargs["search_analyzer"] = self.search_analyzer
+        return path, args, kwargs
+
     def check(self, model, connection):
         errors = []
         if not connection.features.supports_atlas_search:
@@ -152,12 +181,21 @@ def get_pymongo_index_model(
             return None
         fields = {}
         for field_name, _ in self.fields_orders:
-            field = model._meta.get_field(field_name)
-            type_ = self.search_index_data_types(field.db_type(schema_editor.connection))
             field_path = column_prefix + model._meta.get_field(field_name).column
-            fields[field_path] = {"type": type_}
+            if self.field_mappings:
+                fields[field_path] = self.field_mappings[field_name]
+            else:
+                field = model._meta.get_field(field_name)
+                type_ = self.search_index_data_types(field.db_type(schema_editor.connection))
+                fields[field_path] = {"type": type_}
+        extra = {}
+        if self.analyzer:
+            extra["analyzer"] = self.analyzer
+        if self.search_analyzer:
+            extra["searchAnalyzer"] = self.search_analyzer
         return SearchIndexModel(
-            definition={"mappings": {"dynamic": False, "fields": fields}}, name=self.name
+            definition={"mappings": {"dynamic": False, "fields": fields}, **extra},
+            name=self.name,
         )
 
 

django_mongodb_backend/introspection.py

@@ -44,8 +44,12 @@ def _get_search_index_info(self, table_name):
                 type_ = VectorSearchIndex.suffix
                 options = details
             else:
-                options = details["latestDefinition"]["mappings"]
-                columns = list(options.get("fields", {}).keys())
+                options = {
+                    "analyzer": details["latestDefinition"].get("analyzer"),
+                    "searchAnalyzer": details["latestDefinition"].get("searchAnalyzer"),
+                    "mappings": details["latestDefinition"]["mappings"],
+                }
+                columns = list(options["mappings"].get("fields", {}).keys())
                 type_ = SearchIndex.suffix
             constraints[details["name"]] = {
                 "check": False,

docs/ref/models/indexes.rst

@@ -26,7 +26,7 @@ minutes, depending on the size of the collection.
 ``SearchIndex``
 ---------------
 
-.. class:: SearchIndex(fields=(), name=None)
+.. class:: SearchIndex(fields=(), field_mappings=None, name=None, analyzer=None, search_analyzer=None)
 
     Creates a basic :doc:`search index <atlas:atlas-search/index-definitions>`
     on the given field(s).
@@ -35,12 +35,29 @@ minutes, depending on the size of the collection.
     supported. See the :ref:`Atlas documentation <atlas:bson-data-chart>` for a
     complete list of unsupported data types.
 
+    Use ``field_mappings`` (instead of ``fields``) to create an advanced search
+    index. ``field_mappings`` is a dictionary that maps field names to index
+    options. It corresponds to ``definition["mappings"]["fields"]`` in the
+    :ref:`atlas:fts-static-mapping-examples`.
+
     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``
     (substituting the name of your model as well as a different list index if
     your model has multiple indexes).
 
+    Use ``analyzer`` and ``search_analyzer`` to configure the indexing and
+    searching :doc:`analyzer <atlas:atlas-search/analyzers>`, respectively, for
+    the search index definition. If these options aren't provided, the server
+    defaults to ``lucene.standard``. It corresponds to
+    ``definition["analyzer"]`` and ``definition["searchAnalyzer"]`` in the
+    :ref:`atlas:fts-static-mapping-examples`.
+
+    .. versionchanged:: 5.2.2
+
+        The ``field_mappings``, ``analyzer``, and ``search_analyzer`` arguments
+        were added.
+
 ``VectorSearchIndex``
 ---------------------
 

docs/releases/5.2.x.rst

@@ -10,7 +10,8 @@ Django MongoDB Backend 5.2.x
 New features
 ------------
 
-- ...
+- The new ``field_mappings``, ``analyzer``, and ``search_analyzer`` arguments
+  of :class:`.SearchIndex` allow creating advanced indexes.
 
 Bug fixes
 ---------