fix: TEXT field = operator now uses exact phrase matching

- Changed = operator on TEXT fields to always wrap values in quotes
  (@field:"value") for exact phrase semantics, preserving stopwords
- Fixes 'bank of america' bug where stopwords like 'of' were stripped
- Added _escape_text_value() to escape quotes/backslashes in values
- Negation now derived from operator (consistent with TAG builder)
- FULLTEXT operator retains tokenized search with stopword filtering
- Fixed import formatting to match project black/isort style
- Updated docstrings and tests to use FULLTEXT (actual parser operator)
- All 333 tests passing (299 unit + 34 integration)

Author: nkanu17

sql_redis/query_builder.py

@@ -51,6 +51,17 @@ class QueryBuilder:
     # Characters that need escaping in TAG values
     TAG_SPECIAL_CHARS = r".,<>{}[]\"':;!@#$%^&*()-+=~"
 
+    @staticmethod
+    def _escape_text_value(value: str) -> str:
+        """Escape characters that are special inside RediSearch double-quoted phrases.
+
+        Backslashes and double quotes must be escaped so they don't break
+        the query syntax or alter its meaning.
+        """
+        # Escape backslashes first (so we don't double-escape the quote escapes),
+        # then escape double quotes.
+        return value.replace("\\", "\\\\").replace('"', '\\"')
+
     def build_text_condition(
         self,
         field: str | list[str],
@@ -62,14 +73,16 @@ def build_text_condition(
 
         Args:
             field: Field name or list of field names for multi-field search.
-            operator: One of =, MATCH, LIKE, FUZZY.
+            operator: One of =, !=, FULLTEXT, LIKE, FUZZY.
             value: The search term or pattern.
             negated: If True, prefix with - for negation.
 
         Returns:
-            RediSearch query syntax like @field:term or @field:"phrase".
+            RediSearch query syntax like @field:"exact phrase" or @field:(term1 term2).
         """
-        prefix = "-" if negated else ""
+        # Derive negation from both the flag and the operator itself,
+        # consistent with how build_tag_condition handles != via operator.
+        prefix = "-" if negated or operator == "!=" else ""
 
         # Handle multi-field search
         if isinstance(field, list):
@@ -83,8 +96,14 @@ def build_text_condition(
         elif operator == "FUZZY":
             # Wrap with % for fuzzy matching
             search_value = f"%{value}%"
+        elif operator in ("=", "!="):
+            # Exact phrase match — always wrap in quotes, preserve stopwords.
+            # This ensures "bank of america" stays as-is rather than
+            # being tokenized or having stopwords stripped.
+            escaped = self._escape_text_value(value)
+            search_value = f'"{escaped}"'
         elif " " in value:
-            # Phrase search - filter stopwords and wrap in quotes
+            # MATCH with multi-word: tokenized search with stopword filtering
             words = value.split()
             removed_stopwords = [
                 w for w in words if w.lower() in REDIS_DEFAULT_STOPWORDS
@@ -95,16 +114,17 @@ def build_text_condition(
 
             if removed_stopwords:
                 warnings.warn(
-                    f"Stopwords {removed_stopwords} were removed from phrase search '{value}'. "
+                    f"Stopwords {removed_stopwords} were removed from text search '{value}'. "
                     "By default, Redis does not index stopwords. "
-                    "To include stopwords in your index, create it with STOPWORDS 0.",
+                    "To include stopwords in your index, create it with STOPWORDS 0. "
+                    "Use = operator for exact phrase matching that preserves stopwords.",
                     UserWarning,
                     stacklevel=2,
                 )
 
-            # Use filtered phrase, or original if all words were stopwords
-            phrase = " ".join(filtered_words) if filtered_words else value
-            search_value = f'"{phrase}"'
+            # Use filtered words in parentheses (AND semantics), or original if all were stopwords
+            terms = " ".join(filtered_words) if filtered_words else value
+            search_value = f"({terms})"
         else:
             search_value = value
 

tests/test_parameter_substitution.py

@@ -211,9 +211,13 @@ def test_empty_string_value(self, param_executor: Executor, param_test_index: st
         Note: Redis Search doesn't handle empty string literals well in TEXT fields.
         This is a Redis limitation, not a parameter substitution bug.
         """
-        # Empty strings cause Redis syntax errors in TEXT field queries
+        # Empty strings cause Redis errors in TEXT field queries
         # This is expected behavior - Redis Search requires non-empty search terms
-        with pytest.raises(redis.exceptions.ResponseError, match="Syntax error"):
+        # With exact phrase syntax (@field:""), Redis may return "Syntax error"
+        # or "INDEXEMPTY" guidance depending on the Redis version
+        with pytest.raises(
+            redis.exceptions.ResponseError, match="Syntax error|INDEXEMPTY"
+        ):
             param_executor.execute(
                 f"SELECT * FROM {param_test_index} WHERE name = :name",
                 params={"name": ""},

tests/test_query_builder.py

@@ -8,27 +8,58 @@
 class TestQueryBuilderTextFields:
     """Tests for building TEXT field query syntax."""
 
-    def test_text_single_term(self):
-        """TEXT field with single term: @field:term."""
+    def test_text_single_term_exact(self):
+        """TEXT field with = wraps in quotes for exact phrase: @field:"term"."""
         builder = QueryBuilder()
         result = builder.build_text_condition("title", "=", "laptop")
 
-        assert result == "@title:laptop"
+        assert result == '@title:"laptop"'
 
     def test_text_exact_phrase(self):
-        """TEXT field with phrase: @field:"exact phrase"."""
+        """TEXT field with = preserves multi-word phrase: @field:"exact phrase"."""
         builder = QueryBuilder()
         result = builder.build_text_condition("title", "=", "gaming laptop")
 
         assert result == '@title:"gaming laptop"'
 
-    def test_text_match_term(self):
-        """TEXT field with MATCH: @field:term."""
+    def test_text_exact_phrase_preserves_stopwords(self):
+        """TEXT field with = preserves stopwords in exact phrase matching."""
+        builder = QueryBuilder()
+        result = builder.build_text_condition("name", "=", "bank of america")
+
+        # Stopwords like "of" must NOT be stripped for exact phrase matching
+        assert result == '@name:"bank of america"'
+
+    def test_text_exact_phrase_escapes_quotes(self):
+        """TEXT field with = escapes double quotes inside the value."""
         builder = QueryBuilder()
-        result = builder.build_text_condition("title", "MATCH", "laptop")
+        result = builder.build_text_condition("title", "=", 'say "hello"')
+
+        assert result == r'@title:"say \"hello\""'
+
+    def test_text_exact_phrase_escapes_backslashes(self):
+        """TEXT field with = escapes backslashes inside the value."""
+        builder = QueryBuilder()
+        result = builder.build_text_condition("path", "=", r"c:\users\docs")
+
+        assert result == r'@path:"c:\\users\\docs"'
+
+    def test_text_fulltext_term(self):
+        """TEXT field with FULLTEXT (tokenized search): @field:term."""
+        builder = QueryBuilder()
+        result = builder.build_text_condition("title", "FULLTEXT", "laptop")
 
         assert result == "@title:laptop"
 
+    def test_text_fulltext_multi_word(self):
+        """TEXT field with FULLTEXT and multi-word: @field:(term1 term2)."""
+        builder = QueryBuilder()
+        result = builder.build_text_condition(
+            "description", "FULLTEXT", "gaming laptop"
+        )
+
+        assert result == "@description:(gaming laptop)"
+
     def test_text_prefix_search(self):
         """TEXT field with prefix: @field:prefix*."""
         builder = QueryBuilder()

tests/test_translator.py

@@ -136,7 +136,7 @@ def test_select_with_text_filter(self, translator: Translator, basic_index: str)
         )
 
         assert result.command == "FT.SEARCH"
-        assert result.query_string == "@title:hello"
+        assert result.query_string == '@title:"hello"'
 
     def test_select_with_numeric_filter(self, translator: Translator, basic_index: str):
         """SELECT with NUMERIC field condition."""
@@ -202,7 +202,7 @@ def test_and_conditions(self, translator: Translator, basic_index: str):
             f"SELECT * FROM {basic_index} WHERE title = 'hello' AND price > 50"
         )
 
-        assert "@title:hello" in result.query_string
+        assert '@title:"hello"' in result.query_string
         assert "@price:[(50 +inf]" in result.query_string
 
     def test_or_conditions(self, translator: Translator, basic_index: str):