Edits.

Author: WaVEV

django_mongodb_backend/compiler.py

@@ -241,7 +241,28 @@ def _compound_searches_queries(self, search_replacements):
         if not search_replacements:
             return []
         if len(search_replacements) > 1:
-            raise ValueError("Cannot perform more than one search operation.")
+            has_search = any(not isinstance(search, SearchVector) for search in search_replacements)
+            has_vector_search = any(
+                isinstance(search, SearchVector) for search in search_replacements
+            )
+            if has_search and has_vector_search:
+                raise ValueError(
+                    "Cannot combine a `$vectorSearch` with a `$search` operator. "
+                    "If you need to combine them, consider restructuring your query logic or "
+                    "running them as separate queries."
+                )
+            if not has_search:
+                raise ValueError(
+                    "Cannot combine two `$vectorSearch` operator. "
+                    "If you need to combine them, consider restructuring your query logic or "
+                    "running them as separate queries."
+                )
+            raise ValueError(
+                "Only one $search operation is allowed per query. "
+                f"Received {len(search_replacements)} search expressions. "
+                "To combine multiple search expressions, use either a CompoundExpression for "
+                "fine-grained control or CombinedSearchExpression for simple logical combinations."
+            )
         pipeline = []
         for search, result_col in search_replacements.items():
             score_function = (
@@ -252,7 +273,7 @@ def _compound_searches_queries(self, search_replacements):
                     search.as_mql(self, self.connection),
                     {
                         "$addFields": {
-                            result_col.as_mql(self, self.connection).removeprefix("$"): {
+                            result_col.as_mql(self, self.connection, as_path=True): {
                                 "$meta": score_function
                             }
                         }

django_mongodb_backend/expressions/search.py

@@ -71,7 +71,7 @@ def __or__(self, other):
         return self._combine(other, Operator(Operator.OR))
 
     def __ror__(self, other):
-        return self._combine(self, Operator(Operator.OR), other)
+        return self._combine(other, Operator(Operator.OR))
 
 
 class SearchExpression(SearchCombinable, Expression):
@@ -101,10 +101,14 @@ def get_source_expressions(self):
         return []
 
     def _get_indexed_fields(self, mappings):
-        for field, definition in mappings.get("fields", {}).items():
-            yield field
-            for path in self._get_indexed_fields(definition):
-                yield f"{field}.{path}"
+        if isinstance(mappings, list):
+            for definition in mappings:
+                yield from self._get_indexed_fields(definition)
+        else:
+            for field, definition in mappings.get("fields", {}).items():
+                yield field
+                for path in self._get_indexed_fields(definition):
+                    yield f"{field}.{path}"
 
     def _get_query_index(self, fields, compiler):
         fields = set(fields)
@@ -142,9 +146,7 @@ class SearchAutocomplete(SearchExpression):
             any-order token matching.
         score: Optional expression to adjust score relevance (e.g., `{"boost": {"value": 5}}`).
 
-    Notes:
-        * Requires an Atlas Search index with `autocomplete` mappings.
-        * The operator is injected under the `$search` stage in the aggregation pipeline.
+    Reference: https://www.mongodb.com/docs/atlas/atlas-search/autocomplete/
     """
 
     def __init__(self, path, query, fuzzy=None, token_order=None, score=None):
@@ -193,10 +195,7 @@ class SearchEquals(SearchExpression):
         value: The exact value to match against.
         score: Optional expression to modify the relevance score.
 
-    Notes:
-        * The field must be indexed with a supported type for `equals`.
-        * Supports numeric, string, boolean, and date values.
-        * Score boosting can be applied using the `score` parameter.
+    Reference: https://www.mongodb.com/docs/atlas/atlas-search/equals/
     """
 
     def __init__(self, path, value, score=None):
@@ -239,9 +238,7 @@ class SearchExists(SearchExpression):
         path: The document path to check (as string or expression).
         score: Optional expression to modify the relevance score.
 
-    Notes:
-        * The target field must be mapped in the Atlas Search index.
-        * This does not test for null—only for presence.
+    Reference: https://www.mongodb.com/docs/atlas/atlas-search/exists/
     """
 
     def __init__(self, path, score=None):
@@ -268,6 +265,23 @@ def search_operator(self, compiler, connection):
 
 
 class SearchIn(SearchExpression):
+    """
+    Atlas Search expression that matches documents where the field value is in a given list.
+
+    This expression uses the **in** operator to match documents whose field
+    contains a value from the provided array of values.
+
+    Example:
+        SearchIn("status", ["pending", "approved", "rejected"])
+
+    Args:
+        path: The document path to match against (as string or expression).
+        value: A list of values to check for membership.
+        score: Optional expression to adjust the relevance score.
+
+    Reference: https://www.mongodb.com/docs/atlas/atlas-search/in/
+    """
+
     def __init__(self, path, value, score=None):
         self.path = cast_as_field(path)
         self.value = cast_as_value(value)
@@ -297,7 +311,7 @@ class SearchPhrase(SearchExpression):
     """
     Atlas Search expression that matches a phrase in the specified field.
 
-    This expression uses the **phrase** operator to search for exact or near-exact
+    This expression uses the **phrase** operator to search for exact or near exact
     sequences of terms. It supports optional slop (word distance) and synonym sets.
 
     Example:
@@ -310,10 +324,7 @@ class SearchPhrase(SearchExpression):
         synonyms: Optional name of a synonym mapping defined in the Atlas index.
         score: Optional expression to modify the relevance score.
 
-    Notes:
-        * The field must be mapped as `"type": "string"` with appropriate analyzers.
-        * Slop allows flexibility in word positioning, like `"quick brown fox"`
-            matching `"quick fox"` if `slop=1`.
+    Reference: https://www.mongodb.com/docs/atlas/atlas-search/phrase/
     """
 
     def __init__(self, path, query, slop=None, synonyms=None, score=None):
@@ -363,9 +374,7 @@ class SearchQueryString(SearchExpression):
         query: The Lucene-style query string.
         score: Optional expression to modify the relevance score.
 
-    Notes:
-        * The query string syntax must conform to Atlas Search rules.
-        * This operator is powerful but can be harder to validate or sanitize.
+    Reference: https://www.mongodb.com/docs/atlas/atlas-search/queryString/
     """
 
     def __init__(self, path, query, score=None):
@@ -411,9 +420,7 @@ class SearchRange(SearchExpression):
         gte: Optional inclusive lower bound (`>=`).
         score: Optional expression to modify the relevance score.
 
-    Notes:
-        * At least one of `lt`, `lte`, `gt`, or `gte` must be provided.
-        * The field must be mapped in the Atlas Search index as a comparable type.
+    Reference: https://www.mongodb.com/docs/atlas/atlas-search/range/
     """
 
     def __init__(self, path, lt=None, lte=None, gt=None, gte=None, score=None):
@@ -467,10 +474,7 @@ class SearchRegex(SearchExpression):
         allow_analyzed_field: Whether to allow matching against analyzed fields (default is False).
         score: Optional expression to modify the relevance score.
 
-    Notes:
-        * Regular expressions must follow JavaScript regex syntax.
-        * By default, the field must be mapped as `"analyzer": "keyword"`
-            unless `allow_analyzed_field=True`.
+    Reference: https://www.mongodb.com/docs/atlas/atlas-search/regex/
     """
 
     def __init__(self, path, query, allow_analyzed_field=None, score=None):
@@ -519,9 +523,7 @@ class SearchText(SearchExpression):
         synonyms: Optional name of a synonym mapping defined in the Atlas index.
         score: Optional expression to adjust relevance scoring.
 
-    Notes:
-        * The target field must be indexed for full-text search in Atlas.
-        * Fuzzy matching helps match terms with minor typos or variations.
+    Reference: https://www.mongodb.com/docs/atlas/atlas-search/text/
     """
 
     def __init__(self, path, query, fuzzy=None, match_criteria=None, synonyms=None, score=None):
@@ -574,11 +576,7 @@ class SearchWildcard(SearchExpression):
         allow_analyzed_field: Whether to allow matching against analyzed fields (default is False).
         score: Optional expression to modify the relevance score.
 
-    Notes:
-        * Wildcard patterns follow standard syntax, where `*` matches any sequence of characters
-            and `?` matches a single character.
-        * By default, the field should be keyword or unanalyzed
-            unless `allow_analyzed_field=True`.
+    Reference: https://www.mongodb.com/docs/atlas/atlas-search/wildcard/
     """
 
     def __init__(self, path, query, allow_analyzed_field=None, score=None):
@@ -625,9 +623,7 @@ class SearchGeoShape(SearchExpression):
         geometry: The GeoJSON geometry to compare against.
         score: Optional expression to modify the relevance score.
 
-    Notes:
-        * The field must be indexed as a geo shape type in Atlas Search.
-        * Geometry must conform to GeoJSON specification.
+    Reference: https://www.mongodb.com/docs/atlas/atlas-search/geoShape/
     """
 
     def __init__(self, path, relation, geometry, score=None):
@@ -674,9 +670,7 @@ class SearchGeoWithin(SearchExpression):
         geo_object: The GeoJSON geometry defining the boundary.
         score: Optional expression to adjust the relevance score.
 
-    Notes:
-        * The geo field must be indexed appropriately in the Atlas Search index.
-        * The geometry must follow GeoJSON format.
+    Reference: https://www.mongodb.com/docs/atlas/atlas-search/geoWithin/
     """
 
     def __init__(self, path, kind, geo_object, score=None):
@@ -719,9 +713,7 @@ class SearchMoreLikeThis(SearchExpression):
         documents: A list of example documents or expressions to find similar documents.
         score: Optional expression to modify the relevance scoring.
 
-    Notes:
-        * The documents should be representative examples to base similarity on.
-        * Supports various field types depending on the Atlas Search configuration.
+    Reference: https://www.mongodb.com/docs/atlas/atlas-search/morelikethis/
     """
 
     def __init__(self, documents, score=None):
@@ -774,9 +766,7 @@ class CompoundExpression(SearchExpression):
         score: Optional expression to adjust scoring.
         minimum_should_match: Minimum number of `should` clauses that must match.
 
-    Notes:
-        * This is the most flexible way to build complex Atlas Search queries.
-        * Supports nesting of expressions to any depth.
+    Reference: https://www.mongodb.com/docs/atlas/atlas-search/compound/
     """
 
     def __init__(
@@ -859,10 +849,6 @@ class CombinedSearchExpression(SearchExpression):
         lhs: The left-hand search expression.
         operator: The boolean operator as a string (e.g., "and", "or", "not").
         rhs: The right-hand search expression.
-
-    Notes:
-        * The operator must be supported by MongoDB Atlas Search boolean logic.
-        * This class enables building complex nested search queries.
     """
 
     def __init__(self, lhs, operator, rhs):
@@ -917,10 +903,7 @@ class SearchVector(SearchExpression):
         exact: Optional flag to enforce exact matching.
         filter: Optional filter expression to narrow candidate documents.
 
-    Notes:
-        * The vector field must be indexed as a vector type in Atlas Search.
-        * Parameters like `num_candidates` and `exact` control search
-            performance and accuracy trade-offs.
+    Reference: https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-stage/
     """
 
     def __init__(

tests/queries_/test_search.py

@@ -3,6 +3,7 @@
 from time import monotonic, sleep
 
 from django.db import connection
+from django.db.models import Q
 from django.db.utils import DatabaseError
 from django.test import TransactionTestCase, skipUnlessDBFeature
 from pymongo.operations import SearchIndexModel
@@ -463,7 +464,7 @@ def setUp(self):
                 "mappings": {
                     "dynamic": False,
                     "fields": {
-                        "headline": {"type": "token"},
+                        "headline": [{"type": "token"}, {"type": "string"}],
                         "body": {"type": "string"},
                         "number": {"type": "number"},
                     },
@@ -498,7 +499,7 @@ def tearDown(self):
         self._tear_down(Article)
         super().tearDown()
 
-    def test_compound_expression(self):
+    def test_expression(self):
         must_expr = SearchEquals(path="headline", value="space exploration")
         must_not_expr = SearchPhrase(path="body", query="icy moons")
         should_expr = SearchPhrase(path="body", query="exoplanets")
@@ -513,7 +514,7 @@ def test_compound_expression(self):
         qs = Article.objects.annotate(score=compound).order_by("score")
         self.wait_for_assertion(lambda: self.assertCountEqual(qs.all(), [self.exoplanet]))
 
-    def test_compound_operations(self):
+    def test_operations(self):
         expr = SearchEquals(path="headline", value="space exploration") & ~SearchEquals(
             path="number", value=3
         )
@@ -522,6 +523,65 @@ def test_compound_operations(self):
             lambda: self.assertCountEqual(qs.all(), [self.mars_mission, self.exoplanet])
         )
 
+    def test_multiple_search(self):
+        msg = (
+            "Only one $search operation is allowed per query. Received 2 search expressions. "
+            "To combine multiple search expressions, use either a CompoundExpression for "
+            "fine-grained control or CombinedSearchExpression for simple logical combinations."
+        )
+        with self.assertRaisesMessage(ValueError, msg):
+            Article.objects.annotate(
+                score1=SearchEquals(path="headline", value="space exploration"),
+                score2=~SearchEquals(path="number", value=3),
+            ).order_by("score1", "score2").first()
+
+        with self.assertRaisesMessage(ValueError, msg):
+            Article.objects.filter(
+                Q(headline__search="space exploration"), Q(headline__search="space exploration 2")
+            ).first()
+
+    def test_multiple_type_search(self):
+        msg = (
+            "Cannot combine a `$vectorSearch` with a `$search` operator. "
+            "If you need to combine them, consider "
+            "restructuring your query logic or running them as separate queries."
+        )
+        with self.assertRaisesMessage(ValueError, msg):
+            Article.objects.annotate(
+                score1=SearchEquals(path="headline", value="space exploration"),
+                score2=SearchVector(
+                    path="headline",
+                    query_vector=[1, 2, 3],
+                    num_candidates=5,
+                    limit=2,
+                ),
+            ).order_by("score1", "score2").first()
+
+    def test_multiple_vector_search(self):
+        msg = (
+            "Cannot combine two `$vectorSearch` operator. If you need to combine them, "
+            "consider restructuring your query logic or running them as separate queries."
+        )
+        with self.assertRaisesMessage(ValueError, msg):
+            Article.objects.annotate(
+                score1=SearchVector(
+                    path="headline",
+                    query_vector=[1, 2, 3],
+                    num_candidates=5,
+                    limit=2,
+                ),
+                score2=SearchVector(
+                    path="headline",
+                    query_vector=[1, 2, 4],
+                    num_candidates=5,
+                    limit=2,
+                ),
+            ).order_by("score1", "score2").first()
+
+    def test_search_and_filter(self):
+        qs = Article.objects.filter(headline__search="space exploration", number__gt=2)
+        self.wait_for_assertion(lambda: self.assertCountEqual(qs.all(), [self.icy_moons]))
+
 
 @skipUnlessDBFeature("supports_atlas_search")
 class SearchVectorTest(SearchUtilsMixin):