Feat/RAAE-1377/add-is-null-is-not-null-support (#13)

* feat: add IS NULL / IS NOT NULL support via RediSearch ismissing()

Translate SQL IS NULL and IS NOT NULL to RediSearch ismissing(@field)
and -ismissing(@field) respectively. Requires Redis 7.4+ with the
INDEXMISSING attribute declared on the target field.

Changes:
- parser: handle sqlglot exp.Is nodes, emit IS_NULL / IS_NOT_NULL operators
- query_builder: add build_missing_condition() for ismissing() syntax
- translator: short-circuit IS_NULL/IS_NOT_NULL before field-type dispatch
- translator: make DIALECT 2 the default for all FT.SEARCH and FT.AGGREGATE
- executor: catch and re-raise ResponseError with clear version guidance
  when ismissing() fails (both sync and async paths)
- translator: emit UserWarning on IS NULL/IS NOT NULL noting Redis 7.4+
  and INDEXMISSING requirements

Tests:
- 18 integration tests against Redis 8 (TAG, TEXT, NUMERIC field types,
  combined conditions, edge cases, raw command verification)
- Unit tests for parser, query_builder, and translator
- Warning and error message verification tests

* chore: linter

* fix: changes based on pr review
- Changed to "ismissing(@" in both sync and async executor
- Changed to negated=not negated to support double negation
- Parameter test Now asserts on _substitute_params() output deterministically + verifies at least one value executes
- Renamed to test_is_not_null_on_indexmissing_field_returns_present_docs with accurate docstring
- AsyncExecutor catches broad Exception, Changed to catch redis.ResponseError directly (confirmed it's the same class in both sync/async)

* fix: changes based on pr review
- Changed to "ismissing(@" in both sync and async executor
- Changed to negated=not negated to support double negation
- Parameter test Now asserts on _substitute_params() output deterministically + verifies at least one value executes
- Renamed to test_is_not_null_on_indexmissing_field_returns_present_docs with accurate docstring
- AsyncExecutor catches broad Exception, Changed to catch redis.ResponseError directly (confirmed it's the same class in both sync/async)

* fix: pr comments

Executor error re-wrap narrowed (sync + async) — now only augments the error when the server message contains known signatures ("Unknown function", "No such function", "Syntax error", "INDEXMISSING"). Unrelated errors (auth, OOM, unknown index) pass through untouched.

Parser exp.Is else branch — raises ValueError for unsupported IS variants (e.g., IS TRUE, IS DISTINCT FROM) instead of silently dropping the condition.

Author: nkanu17

sql_redis/executor.py

@@ -140,7 +140,26 @@ def execute(self, sql: str, *, params: dict | None = None) -> QueryResult:
                     cmd[i] = vector_param
 
         # Execute command
-        raw_result = self._client.execute_command(*cmd)
+        try:
+            raw_result = self._client.execute_command(*cmd)
+        except redis.ResponseError as e:
+            error_msg = str(e)
+            _ismissing_signatures = (
+                "Unknown function",
+                "No such function",
+                "Syntax error",
+                "INDEXMISSING",
+            )
+            if "ismissing(@" in translated.query_string and any(
+                sig in error_msg for sig in _ismissing_signatures
+            ):
+                raise redis.ResponseError(
+                    f"{error_msg}. This error may be caused by use of the "
+                    "ismissing() function. ismissing() requires Redis 7.4+ "
+                    "(RediSearch 2.10+) and the field must have INDEXMISSING "
+                    "declared in the schema."
+                ) from e
+            raise
 
         # Parse result based on command type
         count = raw_result[0] if raw_result else 0
@@ -207,7 +226,26 @@ async def execute(self, sql: str, *, params: dict | None = None) -> QueryResult:
                     cmd[i] = vector_param
 
         # Execute command asynchronously
-        raw_result = await self._client.execute_command(*cmd)
+        try:
+            raw_result = await self._client.execute_command(*cmd)
+        except redis.ResponseError as e:
+            error_msg = str(e)
+            _ismissing_signatures = (
+                "Unknown function",
+                "No such function",
+                "Syntax error",
+                "INDEXMISSING",
+            )
+            if "ismissing(@" in translated.query_string and any(
+                sig in error_msg for sig in _ismissing_signatures
+            ):
+                raise redis.ResponseError(
+                    f"{error_msg}. This error may be caused by use of the "
+                    "ismissing() function. ismissing() requires Redis 7.4+ "
+                    "(RediSearch 2.10+) and the field must have INDEXMISSING "
+                    "declared in the schema."
+                ) from e
+            raise
 
         # Parse result based on command type
         count = raw_result[0] if raw_result else 0

sql_redis/parser.py

@@ -641,7 +641,29 @@ def _process_where_clause(
             self._process_where_clause(expression.this, result, negated)
             self._process_where_clause(expression.expression, result, negated)
         elif isinstance(expression, exp.Not):
-            self._process_where_clause(expression.this, result, negated=True)
+            self._process_where_clause(expression.this, result, negated=not negated)
+        elif isinstance(expression, exp.Paren):
+            self._process_where_clause(expression.this, result, negated=negated)
+        elif isinstance(expression, exp.Is):
+            # IS NULL: exp.Is(this=Column, expression=Null())
+            # IS NOT NULL arrives here with negated=True via the exp.Not handler above
+            if isinstance(expression.this, exp.Column) and isinstance(
+                expression.expression, exp.Null
+            ):
+                operator = "IS_NOT_NULL" if negated else "IS_NULL"
+                result.conditions.append(
+                    Condition(
+                        field=expression.this.name,
+                        operator=operator,
+                        value=None,
+                        negated=False,
+                    )
+                )
+            else:
+                raise ValueError(
+                    "Unsupported IS expression in WHERE clause; only "
+                    "`column IS NULL` and `column IS NOT NULL` are supported."
+                )
         elif isinstance(expression, exp.Anonymous):
             # Custom function like MATCH(field, value)
             self._add_function_condition(expression, result, negated)

sql_redis/query_builder.py

@@ -332,3 +332,17 @@ def build_query_string(
                 parts.append(self.build_tag_condition(field, operator, value))
 
         return self.combine_conditions(parts, "AND")
+
+    def build_missing_condition(self, field: str, *, is_missing: bool) -> str:
+        """Build ismissing() query fragment for IS NULL / IS NOT NULL.
+
+        Args:
+            field: Field name (without @ prefix).
+            is_missing: True for IS NULL (ismissing), False for IS NOT NULL (-ismissing).
+
+        Returns:
+            Query fragment like "ismissing(@field)" or "-ismissing(@field)".
+        """
+        if is_missing:
+            return f"ismissing(@{field})"
+        return f"-ismissing(@{field})"

sql_redis/translator.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import warnings
 from dataclasses import dataclass, field
 
 from sql_redis.analyzer import AnalyzedQuery, Analyzer
@@ -170,6 +171,18 @@ def _build_query_string(self, analyzed: AnalyzedQuery) -> str:
 
     def _build_condition(self, condition: Condition, field_type: str | None) -> str:
         """Build a single condition string based on field type."""
+        # Short-circuit for IS NULL / IS NOT NULL → ismissing()
+        if condition.operator in ("IS_NULL", "IS_NOT_NULL"):
+            warnings.warn(
+                f"IS NULL / IS NOT NULL on field '{condition.field}' requires "
+                "Redis 7.4+ (RediSearch 2.10+) with INDEXMISSING declared on "
+                "the field. Older versions will return a server error.",
+                stacklevel=4,
+            )
+            return self._query_builder.build_missing_condition(
+                condition.field, is_missing=(condition.operator == "IS_NULL")
+            )
+
         # Determine if this is a negation (either explicit or via != operator)
         operator = condition.operator
         is_negated = condition.negated or operator == "!="
@@ -257,8 +270,6 @@ def _build_search(
         # Handle vector search parameters
         if analyzed.vector_search:
             args.extend(["PARAMS", "2", "vector", "$vector"])
-            args.append("DIALECT")
-            args.append("2")
             params["vector"] = None  # Placeholder for vector bytes
 
         # GEOFILTER clause for geo_distance conditions (only < and <= operators)
@@ -288,6 +299,9 @@ def _build_search(
             offset = parsed.offset or 0
             args.extend(["LIMIT", str(offset), str(parsed.limit)])
 
+        # DIALECT 2 — unconditionally appended as the last arguments
+        args.extend(["DIALECT", "2"])
+
         return TranslatedQuery(
             command="FT.SEARCH",
             index=parsed.index,
@@ -496,6 +510,9 @@ def _build_aggregate(
             offset = parsed.offset or 0
             args.extend(["LIMIT", str(offset), str(parsed.limit)])
 
+        # DIALECT 2 — unconditionally appended as the last arguments
+        args.extend(["DIALECT", "2"])
+
         return TranslatedQuery(
             command="FT.AGGREGATE",
             index=parsed.index,