address PR #17 review comments

- Fix FULLTEXT operator naming (MATCH → FULLTEXT) in query_builder and tests
- Resolve score alias once per result set to prevent column name flip-flop
- Add fuzzy_level range validation (1-3) in parser
- Fix import formatting (isort/black) in translator.py and analyzer.py

Author: nkanu17

sql_redis/executor.py

@@ -228,20 +228,20 @@ def execute(self, sql: str, *, params: dict | None = None) -> QueryResult:
             elif with_scores:
                 # WITHSCORES format: [count, key1, score1, [fields1], key2, score2, [fields2], ...]
                 # Stride of 3: key, score, field_list
-                # Resolve alias per-row: FT.SEARCH may omit missing attributes,
-                # so different rows can have different field sets.  We must
-                # check each row individually to avoid overwriting a real field
-                # with the score value.
+                # Resolve alias once from the first row so every row uses the
+                # same column name (consistent output schema).
+                resolved_alias: str | None = None
                 for i in range(1, len(raw_result) - 2, 3):
                     score = raw_result[i + 1]
                     row_data = raw_result[i + 2]
                     row = dict(zip(row_data[::2], row_data[1::2]))
-                    row_score_alias = self._resolve_score_alias(
-                        translated.score_alias,
-                        translated.args,
-                        first_row_fields=set(row.keys()),
-                    )
-                    row[row_score_alias] = score
+                    if resolved_alias is None:
+                        resolved_alias = self._resolve_score_alias(
+                            translated.score_alias,
+                            translated.args,
+                            first_row_fields=set(row.keys()),
+                        )
+                    row[resolved_alias] = score
                     rows.append(row)
             else:
                 # Standard format: [count, key1, [fields1], key2, [fields2], ...]
@@ -345,17 +345,20 @@ async def execute(self, sql: str, *, params: dict | None = None) -> QueryResult:
                     rows.append(row)
             elif with_scores:
                 # WITHSCORES format: [count, key1, score1, [fields1], ...]
-                # Resolve alias per-row to avoid field collision on later rows.
+                # Resolve alias once from the first row so every row uses the
+                # same column name (consistent output schema).
+                resolved_alias: str | None = None
                 for i in range(1, len(raw_result) - 2, 3):
                     score = raw_result[i + 1]
                     row_data = raw_result[i + 2]
                     row = dict(zip(row_data[::2], row_data[1::2]))
-                    row_score_alias = self._resolve_score_alias(
-                        translated.score_alias,
-                        translated.args,
-                        first_row_fields=set(row.keys()),
-                    )
-                    row[row_score_alias] = score
+                    if resolved_alias is None:
+                        resolved_alias = self._resolve_score_alias(
+                            translated.score_alias,
+                            translated.args,
+                            first_row_fields=set(row.keys()),
+                        )
+                    row[resolved_alias] = score
                     rows.append(row)
             else:
                 # Standard format: [count, key1, [fields1], key2, [fields2], ...]

sql_redis/parser.py

@@ -1074,6 +1074,11 @@ def _add_function_condition(
                             f"FUZZY level argument must be an integer (got {level_val})"
                         )
                     fuzzy_level = int(level_val)
+                    if fuzzy_level not in (1, 2, 3):
+                        raise ValueError(
+                            f"FUZZY level must be 1, 2, or 3 (got {fuzzy_level}). "
+                            "RediSearch supports a maximum Levenshtein distance of 3."
+                        )
 
             if field_name is None:
                 raise ValueError(

sql_redis/query_builder.py

@@ -180,7 +180,7 @@ def build_text_condition(
                         or_parts.append(self._escape_fulltext_term(token))
             search_value = f"({'|'.join(or_parts)})"
         elif " " in value:
-            # FULLTEXT/MATCH with multi-word: tokenized search with stopword filtering.
+            # FULLTEXT with multi-word: tokenized search with stopword filtering.
             # Each term is escaped to prevent accidental operator injection, but a
             # leading ~ (optional-term modifier) is preserved as an intentional
             # RediSearch operator.

tests/test_query_builder.py

@@ -324,7 +324,7 @@ def test_simple_text_query(self):
         """Build simple text search query."""
         builder = QueryBuilder()
         result = builder.build_query_string(
-            text_conditions=[("title", "MATCH", "laptop")],
+            text_conditions=[("title", "FULLTEXT", "laptop")],
             field_types={"title": "TEXT"},
         )
 
@@ -334,7 +334,7 @@ def test_combined_query(self):
         """Build combined text + numeric + tag query."""
         builder = QueryBuilder()
         result = builder.build_query_string(
-            text_conditions=[("title", "MATCH", "laptop")],
+            text_conditions=[("title", "FULLTEXT", "laptop")],
             numeric_conditions=[("price", "<", 1000)],
             tag_conditions=[("category", "=", "electronics")],
             field_types={"title": "TEXT", "price": "NUMERIC", "category": "TAG"},