Merge pull request #2794 from bagerard/add_text_score_to_search_text

add ability to turn off text_score computation on search_text call

Author: bagerard

docs/changelog.rst

@@ -19,6 +19,8 @@ Development
     as it was useless and making it look like it was returning a different class although it was the same.
     Thus, it must be called like `with no_dereference(User):` and no longer `with no_dereference(User) as ...:`
 - Added __raw__ to :meth:`~mongoengine.Queryset.order_by()` to allow to provide raw pymongo 'sort' argument and get around some of the limitations #2783
+- Add `text_score` argument on :meth:`~mongoengine.Document.search_text()` to allow text_score computation to be turned off
+    as it interfer with natural returned documents order #2759
 
 Changes in 0.27.0
 =================

mongoengine/base/document.py

@@ -322,7 +322,7 @@ def get_text_score(self):
 
         if "_text_score" not in self._data:
             raise InvalidDocumentError(
-                "This document is not originally built from a text query"
+                "This document is not originally built from a text query (or text_score was not set on search_text() call)"
             )
 
         return self._data["_text_score"]

mongoengine/queryset/base.py

@@ -71,6 +71,7 @@ def __init__(self, document, collection):
         self._none = False
         self._as_pymongo = False
         self._search_text = None
+        self._search_text_score = None
 
         self.__dereference = False
         self.__auto_dereference = True
@@ -229,7 +230,7 @@ def filter(self, *q_objs, **query):
         """An alias of :meth:`~mongoengine.queryset.QuerySet.__call__`"""
         return self.__call__(*q_objs, **query)
 
-    def search_text(self, text, language=None):
+    def search_text(self, text, language=None, text_score=True):
         """
         Start a text search, using text indexes.
         Require: MongoDB server version 2.6+.
@@ -239,6 +240,8 @@ def search_text(self, text, language=None):
             If not specified, the search uses the default language of the index.
             For supported languages, see
             `Text Search Languages <https://docs.mongodb.org/manual/reference/text-search-languages/#text-search-languages>`.
+        :param text_score:  True to have it return the text_score (available through get_text_score()), False to disable that
+            Note that unless you order the results, leaving text_score=True may provide randomness in the returned documents
         """
         queryset = self.clone()
         if queryset._search_text:
@@ -252,6 +255,7 @@ def search_text(self, text, language=None):
         queryset._mongo_query = None
         queryset._cursor_obj = None
         queryset._search_text = text
+        queryset._search_text_score = text_score
 
         return queryset
 
@@ -833,6 +837,7 @@ def _clone_into(self, new_qs):
             "_hint",
             "_collation",
             "_search_text",
+            "_search_text_score",
             "_max_time_ms",
             "_comment",
             "_batch_size",
@@ -1673,7 +1678,8 @@ def _cursor_args(self):
             if fields_name not in cursor_args:
                 cursor_args[fields_name] = {}
 
-            cursor_args[fields_name]["_text_score"] = {"$meta": "textScore"}
+            if self._search_text_score:
+                cursor_args[fields_name]["_text_score"] = {"$meta": "textScore"}
 
         return cursor_args
 

tests/queryset/test_queryset.py

@@ -3692,7 +3692,7 @@ class News(Document):
                 "t2", language="french"
             )
 
-    def test_text_indexes(self):
+    def test_search_text(self):
         class News(Document):
             title = StringField()
             content = StringField()
@@ -3751,14 +3751,16 @@ class News(Document):
         assert "dilma" in new.content
         assert "planejamento" in new.title
 
-        query = News.objects.search_text("candidata")
+        query = News.objects.search_text("candidata", text_score=True)
         assert query._search_text == "candidata"
         new = query.first()
 
         assert isinstance(new.get_text_score(), float)
 
         # count
-        query = News.objects.search_text("brasil").order_by("$text_score")
+        query = News.objects.search_text("brasil", text_score=True).order_by(
+            "$text_score"
+        )
         assert query._search_text == "brasil"
 
         assert query.count() == 3
@@ -3778,6 +3780,13 @@ class News(Document):
         item = News.objects.search_text("brasil").order_by("$text_score").first()
         assert item.get_text_score() == max_text_score
 
+        # Verify query reproducibility when text_score is disabled
+        # Following wouldn't work for text_score=True  #2759
+        for i in range(10):
+            qs1 = News.objects.search_text("brasil", text_score=False)
+            qs2 = News.objects.search_text("brasil", text_score=False)
+            assert list(qs1) == list(qs2)
+
     def test_distinct_handles_references_to_alias(self):
         register_connection("testdb", "mongoenginetest2")