Clean ups.

Author: WaVEV

django_mongodb_backend/compiler.py

@@ -128,6 +128,9 @@ def _prepare_search_query_for_aggregation_pipeline(self, order_by):
         self._prepare_search_expressions_for_pipeline(
             self.having, annotation_group_idx, replacements
         )
+        self._prepare_search_expressions_for_pipeline(
+            self.get_where(), annotation_group_idx, replacements
+        )
         return replacements
 
     def _prepare_annotations_for_aggregation_pipeline(self, order_by):
@@ -206,9 +209,6 @@ def _get_group_id_expressions(self, order_by):
             ids = self.get_project_fields(tuple(columns), force_expression=True)
         return ids, replacements
 
-    def _build_search_pipeline(self, search_queries):
-        pass
-
     def _build_aggregation_pipeline(self, ids, group):
         """Build the aggregation pipeline for grouping."""
         pipeline = []
@@ -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
                             }
                         }
@@ -291,6 +312,9 @@ def pre_sql_setup(self, with_col_aliases=False):
             for target, expr in self.query.annotation_select.items()
         }
         self.order_by_objs = [expr.replace_expressions(all_replacements) for expr, _ in order_by]
+        if (where := self.get_where()) and search_replacements:
+            where = where.replace_expressions(search_replacements)
+            self.set_where(where)
         return extra_select, order_by, group_by
 
     def execute_sql(
@@ -692,6 +716,9 @@ def _get_ordering(self):
     def get_where(self):
         return getattr(self, "where", self.query.where)
 
+    def set_where(self, value):
+        self.where = value
+
     def explain_query(self):
         # Validate format (none supported) and options.
         options = self.connection.ops.explain_query_prefix(

django_mongodb_backend/expressions/search.py

@@ -1,6 +1,9 @@
 from django.db import NotSupportedError
-from django.db.models import Expression, FloatField
+from django.db.models import CharField, Expression, FloatField, TextField
 from django.db.models.expressions import F, Value
+from django.db.models.lookups import Lookup
+
+from ..query_utils import process_lhs, process_rhs
 
 
 def cast_as_value(value):
@@ -68,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):
@@ -86,22 +89,23 @@ def __str__(self):
         cls = self.identity[0]
         kwargs = dict(self.identity[1:])
         arg_str = ", ".join(f"{k}={v!r}" for k, v in kwargs.items())
-        return f"{cls.__name__}({arg_str})"
+        return f"<{cls.__name__}({arg_str})>"
 
     def __repr__(self):
         return str(self)
 
     def as_sql(self, compiler, connection):
         return "", []
 
-    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)
@@ -139,9 +143,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):
@@ -190,10 +192,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):
@@ -236,9 +235,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):
@@ -260,11 +257,28 @@ def search_operator(self, compiler, connection):
             "path": self.path.as_mql(compiler, connection, as_path=True),
         }
         if self.score is not None:
-            params["score"] = self.score.definitions
+            params["score"] = self.score.as_mql(compiler, connection)
         return {"exists": params}
 
 
 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)
@@ -294,7 +308,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:
@@ -307,10 +321,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):
@@ -360,9 +371,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):
@@ -408,9 +417,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):
@@ -464,10 +471,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):
@@ -516,9 +520,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):
@@ -571,11 +573,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):
@@ -600,7 +598,7 @@ def search_operator(self, compiler, connection):
             "query": self.query.value,
         }
         if self.score:
-            params["score"] = self.score.query.as_mql(compiler, connection)
+            params["score"] = self.score.as_mql(compiler, connection)
         if self.allow_analyzed_field is not None:
             params["allowAnalyzedField"] = self.allow_analyzed_field.value
         return {"wildcard": params}
@@ -622,9 +620,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):
@@ -671,9 +667,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):
@@ -716,9 +710,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):
@@ -771,9 +763,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__(
@@ -856,10 +846,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):
@@ -914,10 +900,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__(
@@ -1005,7 +988,31 @@ class SearchScoreOption(Expression):
     """Class to mutate scoring on a search operation"""
 
     def __init__(self, definitions=None):
-        self.definitions = definitions
+        self._definitions = definitions
+
+    def as_mql(self, compiler, connection):
+        return self._definitions
+
+
+class SearchTextLookup(Lookup):
+    lookup_name = "search"
+
+    def __init__(self, lhs, rhs):
+        super().__init__(lhs, rhs)
+        self.lhs = SearchText(self.lhs, self.rhs)
+        self.rhs = Value(0)
+
+    def __str__(self):
+        return f"SearchText({self.lhs}, {self.rhs})"
+
+    def __repr__(self):
+        return f"SearchText({self.lhs}, {self.rhs})"
 
     def as_mql(self, compiler, connection):
-        return self.definitions
+        lhs_mql = process_lhs(self, compiler, connection)
+        value = process_rhs(self, compiler, connection)
+        return {"$gte": [lhs_mql, value]}
+
+
+CharField.register_lookup(SearchTextLookup)
+TextField.register_lookup(SearchTextLookup)

django_mongodb_backend/query_utils.py

@@ -4,7 +4,7 @@
 
 
 def is_direct_value(node):
-    return not hasattr(node, "as_sql") and not hasattr(node, "as_mql")
+    return not hasattr(node, "as_sql")
 
 
 def process_lhs(node, compiler, connection):