Strip stopwords from exact phrase queries (= operator)

RediSearch does not index stopwords, so exact phrase queries like
"diagnosing and treating" fail with a syntax error. The = operator
now strips default stopwords before wrapping in double quotes, matching
how the indexer assigns consecutive positions. A warning is emitted
when stopwords are removed.

Also removes outdated 'Use = operator for exact phrase matching that
preserves stopwords' hint from FULLTEXT stopword warning.

Author: nkanu17

sql_redis/query_builder.py

@@ -143,8 +143,37 @@ def build_text_condition(
             pct = "%" * level
             search_value = f"{pct}{escaped}{pct}"
         elif operator in ("=", "!="):
-            # Exact phrase match — always wrap in quotes, preserve stopwords.
-            escaped = self._escape_text_value(value)
+            # Exact phrase match — wrap in double quotes.
+            # Strip default stopwords because RediSearch does not index them;
+            # keeping them in the quoted phrase causes a query-time error
+            # (e.g. "diagnosing and treating" fails on "and").
+            # Since the indexer assigns consecutive positions after dropping
+            # stopwords, the stripped phrase matches correctly.
+            words = value.split()
+            removed = [w for w in words if w.lower() in REDIS_DEFAULT_STOPWORDS]
+            filtered = [w for w in words if w.lower() not in REDIS_DEFAULT_STOPWORDS]
+
+            if removed:
+                phrase_words = filtered if filtered else words
+                if filtered:
+                    sw_msg = f"Stopwords {removed} were removed from"
+                else:
+                    sw_msg = (
+                        f"All tokens in '{value}' are stopwords and may not "
+                        "be indexed in"
+                    )
+                warnings.warn(
+                    f"{sw_msg} exact phrase '{value}'. "
+                    "By default, Redis does not index stopwords. "
+                    "To include stopwords in your index, create it "
+                    "with STOPWORDS 0.",
+                    UserWarning,
+                    stacklevel=2,
+                )
+            else:
+                phrase_words = words
+
+            escaped = self._escape_text_value(" ".join(phrase_words))
             search_value = f'"{escaped}"'
         elif re.search(r"\s+OR\s+", value):
             # OR union within text field: split on uppercase-only OR with
@@ -200,8 +229,8 @@ def build_text_condition(
                 warnings.warn(
                     f"{sw_action} text search '{value}'. "
                     "By default, Redis does not index stopwords. "
-                    "To include stopwords in your index, create it with STOPWORDS 0. "
-                    "Use = operator for exact phrase matching that preserves stopwords.",
+                    "To include stopwords in your index, create it "
+                    "with STOPWORDS 0.",
                     UserWarning,
                     stacklevel=2,
                 )

tests/test_query_builder.py

@@ -22,13 +22,31 @@ def test_text_exact_phrase(self):
 
         assert result == '@title:"gaming laptop"'
 
-    def test_text_exact_phrase_preserves_stopwords(self):
-        """TEXT field with = preserves stopwords in exact phrase matching."""
+    def test_text_exact_phrase_strips_stopwords(self):
+        """TEXT field with = strips stopwords and warns (RediSearch doesn't index them)."""
         builder = QueryBuilder()
-        result = builder.build_text_condition("name", "=", "bank of america")
+        import warnings
 
-        # Stopwords like "of" must NOT be stripped for exact phrase matching
-        assert result == '@name:"bank of america"'
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            result = builder.build_text_condition("name", "=", "bank of america")
+
+        # "of" is a stopword — stripped so the phrase matches indexed positions
+        assert result == '@name:"bank america"'
+        assert len(w) == 1
+        assert "Stopwords ['of']" in str(w[0].message)
+
+    def test_text_exact_phrase_no_stopwords_no_warning(self):
+        """TEXT field with = on phrase without stopwords produces no warning."""
+        builder = QueryBuilder()
+        import warnings
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            result = builder.build_text_condition("name", "=", "bank america")
+
+        assert result == '@name:"bank america"'
+        assert len(w) == 0
 
     def test_text_exact_phrase_escapes_quotes(self):
         """TEXT field with = escapes double quotes inside the value."""