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
- MATCH operator retains tokenized search with stopword filtering
- Updated tests for new behavior
- All 331 tests passing (297 unit + 34 integration)

Author: nkanu17

sql_redis/query_builder.py

@@ -62,12 +62,12 @@ 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 =, !=, MATCH, 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 ""
 
@@ -83,8 +83,13 @@ 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.
+            search_value = f'"{value}"'
         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 +100,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,11 @@ 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):
             param_executor.execute(
                 f"SELECT * FROM {param_test_index} WHERE name = :name",
                 params={"name": ""},

tests/test_query_builder.py

@@ -8,27 +8,42 @@
 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_exact_phrase_preserves_stopwords(self):
+        """TEXT field with = preserves stopwords (Jay's 'bank of america' fix)."""
+        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_match_term(self):
         """TEXT field with MATCH: @field:term."""
         builder = QueryBuilder()
         result = builder.build_text_condition("title", "MATCH", "laptop")
 
         assert result == "@title:laptop"
 
+    def test_text_match_multi_word(self):
+        """TEXT field with MATCH and multi-word: @field:(term1 term2)."""
+        builder = QueryBuilder()
+        result = builder.build_text_condition("description", "MATCH", "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):