Docstring and minor changes.

Author: WaVEV

django_mongodb_backend/compiler.py

@@ -116,6 +116,18 @@ def _prepare_search_expressions_for_pipeline(self, expression, search_idx, repla
                 replacements[sub_expr] = self._get_replace_expr(sub_expr, searches, alias)
 
     def _prepare_search_query_for_aggregation_pipeline(self, order_by):
+        """
+        Prepare expressions for the search pipeline.
+
+        Handle the computation of search functions used by various
+        expressions. Separate and create intermediate columns, and replace
+        nodes to simulate a search operation.
+
+        MongoDB's $search or $searchVector are stages. To apply operations over them,
+        compute the $search or $vectorSearch first, then apply additional operations in a subsequent
+        stage by replacing the aggregate expressions with new document field prefixed
+        by `__search_expr.search#`.
+        """
         replacements = {}
         annotation_group_idx = itertools.count(start=1)
         for expr in self.query.annotation_select.values():
@@ -237,6 +249,15 @@ def _build_aggregation_pipeline(self, ids, group):
         return pipeline
 
     def _compound_searches_queries(self, search_replacements):
+        """
+        Builds a query pipeline from a mapping of search expressions to result columns.
+
+        Currently, only a single `$search` or `$vectorSearch` expression is supported.
+        Combining multiple search expressions is not yet allowed and will raise a ValueError.
+
+        This method will eventually support hybrid search by allowing the combination of
+        `$search` and `$vectorSearch` operations.
+        """
         if not search_replacements:
             return []
         if len(search_replacements) > 1:
@@ -250,7 +271,7 @@ def _compound_searches_queries(self, search_replacements):
                     "If you need to combine them, consider restructuring your query logic or "
                     "running them as separate queries."
                 )
-            if not has_search:
+            if has_vector_search:
                 raise ValueError(
                     "Cannot combine two `$vectorSearch` operator. "
                     "If you need to combine them, consider restructuring your query logic or "
@@ -312,8 +333,7 @@ def pre_sql_setup(self, with_col_aliases=False):
         }
         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)
+            self.set_where(where.replace_expressions(search_replacements))
         return extra_select, order_by, group_by
 
     def execute_sql(

django_mongodb_backend/expressions/__init__.py

@@ -0,0 +1,39 @@
+from .search import (
+    CombinedSearchExpression,
+    CompoundExpression,
+    SearchAutocomplete,
+    SearchEquals,
+    SearchExists,
+    SearchGeoShape,
+    SearchGeoWithin,
+    SearchIn,
+    SearchMoreLikeThis,
+    SearchPhrase,
+    SearchQueryString,
+    SearchRange,
+    SearchRegex,
+    SearchScoreOption,
+    SearchText,
+    SearchVector,
+    SearchWildcard,
+)
+
+__all__ = [
+    "CombinedSearchExpression",
+    "CompoundExpression",
+    "SearchAutocomplete",
+    "SearchEquals",
+    "SearchExists",
+    "SearchGeoShape",
+    "SearchGeoWithin",
+    "SearchIn",
+    "SearchMoreLikeThis",
+    "SearchPhrase",
+    "SearchQueryString",
+    "SearchRange",
+    "SearchRegex",
+    "SearchScoreOption",
+    "SearchText",
+    "SearchVector",
+    "SearchWildcard",
+]

django_mongodb_backend/expressions/builtins.py

@@ -71,7 +71,9 @@ def col(self, compiler, connection, as_path=False):  # noqa: ARG001
     # Add the column's collection's alias for columns in joined collections.
     has_alias = self.alias and self.alias != compiler.collection_name
     prefix = f"{self.alias}." if has_alias else ""
-    return f"{prefix}{self.target.column}" if as_path else f"${prefix}{self.target.column}"
+    if not as_path:
+        prefix = f"${prefix}"
+    return f"{prefix}{self.target.column}"
 
 
 def col_pairs(self, compiler, connection):

tests/queries_/test_search.py

@@ -10,7 +10,7 @@
 from django.test import TransactionTestCase, skipUnlessDBFeature
 from pymongo.operations import SearchIndexModel
 
-from django_mongodb_backend.expressions.search import (
+from django_mongodb_backend.expressions import (
     CompoundExpression,
     SearchAutocomplete,
     SearchEquals,
@@ -84,7 +84,7 @@ def drop_index():
 
 
 @skipUnlessDBFeature("supports_atlas_search")
-class SearchEqualsTest(SearchUtilsMixin):
+class SearchEqualsTests(SearchUtilsMixin):
     @classmethod
     def setUpClass(cls):
         super().setUpClass()
@@ -100,7 +100,6 @@ def setUpClass(cls):
         )
 
     def setUp(self):
-        super().setUp()
         self.article = Article.objects.create(headline="cross", number=1, body="body")
         Article.objects.create(headline="other thing", number=2, body="body")
 
@@ -110,7 +109,6 @@ def test_search_equals(self):
 
     def test_boost_score(self):
         boost_score = SearchScoreOption({"boost": {"value": 3}})
-
         qs = Article.objects.annotate(
             score=SearchEquals(path="headline", value="cross", score=boost_score)
         )
@@ -148,7 +146,7 @@ def test_function_score(self):
 
 
 @skipUnlessDBFeature("supports_atlas_search")
-class SearchAutocompleteTest(SearchUtilsMixin):
+class SearchAutocompleteTests(SearchUtilsMixin):
     @classmethod
     def setUpClass(cls):
         super().setUpClass()
@@ -186,7 +184,6 @@ def setUpClass(cls):
         )
 
     def setUp(self):
-        super().setUp()
         self.article = Article.objects.create(
             headline="crossing and something",
             number=2,
@@ -229,7 +226,7 @@ def test_constant_score(self):
 
 
 @skipUnlessDBFeature("supports_atlas_search")
-class SearchExistsTest(SearchUtilsMixin):
+class SearchExistsTests(SearchUtilsMixin):
     @classmethod
     def setUpClass(cls):
         super().setUpClass()
@@ -240,7 +237,6 @@ def setUpClass(cls):
         )
 
     def setUp(self):
-        super().setUp()
         self.article = Article.objects.create(headline="ignored", number=3, body="something")
 
     def test_search_exists(self):
@@ -256,7 +252,7 @@ def test_constant_score(self):
 
 
 @skipUnlessDBFeature("supports_atlas_search")
-class SearchInTest(SearchUtilsMixin):
+class SearchInTests(SearchUtilsMixin):
     @classmethod
     def setUpClass(cls):
         super().setUpClass()
@@ -267,7 +263,6 @@ def setUpClass(cls):
         )
 
     def setUp(self):
-        super().setUp()
         self.article = Article.objects.create(headline="cross", number=1, body="a")
         Article.objects.create(headline="road", number=2, body="b")
 
@@ -286,7 +281,7 @@ def test_constant_score(self):
 
 
 @skipUnlessDBFeature("supports_atlas_search")
-class SearchPhraseTest(SearchUtilsMixin):
+class SearchPhraseTests(SearchUtilsMixin):
     @classmethod
     def setUpClass(cls):
         super().setUpClass()
@@ -297,7 +292,6 @@ def setUpClass(cls):
         )
 
     def setUp(self):
-        super().setUp()
         self.article = Article.objects.create(
             headline="irrelevant", number=1, body="the quick brown fox"
         )
@@ -318,7 +312,7 @@ def test_constant_score(self):
 
 
 @skipUnlessDBFeature("supports_atlas_search")
-class SearchRangeTest(SearchUtilsMixin):
+class SearchRangeTests(SearchUtilsMixin):
     @classmethod
     def setUpClass(cls):
         super().setUpClass()
@@ -330,7 +324,6 @@ def setUpClass(cls):
         Article.objects.create(headline="x", number=5, body="z")
 
     def setUp(self):
-        super().setUp()
         self.number20 = Article.objects.create(headline="y", number=20, body="z")
 
     def test_search_range(self):
@@ -348,7 +341,7 @@ def test_constant_score(self):
 
 
 @skipUnlessDBFeature("supports_atlas_search")
-class SearchRegexTest(SearchUtilsMixin):
+class SearchRegexTests(SearchUtilsMixin):
     @classmethod
     def setUpClass(cls):
         super().setUpClass()
@@ -364,7 +357,6 @@ def setUpClass(cls):
         )
 
     def setUp(self):
-        super().setUp()
         self.article = Article.objects.create(headline="hello world", number=1, body="abc")
         Article.objects.create(headline="hola mundo", number=2, body="abc")
 
@@ -387,7 +379,7 @@ def test_constant_score(self):
 
 
 @skipUnlessDBFeature("supports_atlas_search")
-class SearchTextTest(SearchUtilsMixin):
+class SearchTextTests(SearchUtilsMixin):
     @classmethod
     def setUpClass(cls):
         super().setUpClass()
@@ -398,7 +390,6 @@ def setUpClass(cls):
         )
 
     def setUp(self):
-        super().setUp()
         self.article = Article.objects.create(
             headline="ignored", number=1, body="The lazy dog sleeps"
         )
@@ -437,7 +428,7 @@ def test_constant_score(self):
 
 
 @skipUnlessDBFeature("supports_atlas_search")
-class SearchWildcardTest(SearchUtilsMixin):
+class SearchWildcardTests(SearchUtilsMixin):
     @classmethod
     def setUpClass(cls):
         super().setUpClass()
@@ -453,7 +444,6 @@ def setUpClass(cls):
         )
 
     def setUp(self):
-        super().setUp()
         self.article = Article.objects.create(headline="dark-knight", number=1, body="")
         Article.objects.create(headline="batman", number=2, body="")
 
@@ -472,7 +462,7 @@ def test_constant_score(self):
 
 
 @skipUnlessDBFeature("supports_atlas_search")
-class SearchGeoShapeTest(SearchUtilsMixin):
+class SearchGeoShapeTests(SearchUtilsMixin):
     @classmethod
     def setUpClass(cls):
         super().setUpClass()
@@ -488,7 +478,6 @@ def setUpClass(cls):
         )
 
     def setUp(self):
-        super().setUp()
         self.article = Article.objects.create(
             headline="any", number=1, body="", location={"type": "Point", "coordinates": [40, 5]}
         )
@@ -523,7 +512,7 @@ def test_constant_score(self):
 
 
 @skipUnlessDBFeature("supports_atlas_search")
-class SearchGeoWithinTest(SearchUtilsMixin):
+class SearchGeoWithinTests(SearchUtilsMixin):
     @classmethod
     def setUpClass(cls):
         super().setUpClass()
@@ -534,7 +523,6 @@ def setUpClass(cls):
         )
 
     def setUp(self):
-        super().setUp()
         self.article = Article.objects.create(
             headline="geo", number=2, body="", location={"type": "Point", "coordinates": [40, 5]}
         )
@@ -577,7 +565,7 @@ def test_constant_score(self):
 
 @skipUnlessDBFeature("supports_atlas_search")
 @unittest.expectedFailure
-class SearchMoreLikeThisTest(SearchUtilsMixin):
+class SearchMoreLikeThisTests(SearchUtilsMixin):
     @classmethod
     def setUpClass(cls):
         super().setUpClass()
@@ -620,7 +608,7 @@ def test_search_more_like_this(self):
 
 
 @skipUnlessDBFeature("supports_atlas_search")
-class CompoundSearchTest(SearchUtilsMixin):
+class CompoundSearchTests(SearchUtilsMixin):
     @classmethod
     def setUpClass(cls):
         super().setUpClass()
@@ -640,7 +628,6 @@ def setUpClass(cls):
         )
 
     def setUp(self):
-        super().setUp()
         self.mars_mission = Article.objects.create(
             number=1,
             headline="space exploration",
@@ -785,7 +772,7 @@ def test_search_and_filter(self):
 
 
 @skipUnlessDBFeature("supports_atlas_search")
-class SearchVectorTest(SearchUtilsMixin):
+class SearchVectorTests(SearchUtilsMixin):
     @classmethod
     def setUpClass(cls):
         super().setUpClass()
@@ -807,7 +794,6 @@ def setUpClass(cls):
         )
 
     def setUp(self):
-        super().setUp()
         self.mars = Article.objects.create(
             headline="Mars landing",
             number=1,