fix: single-term ~ prefix, multi-word OR grouping; docs: IS NULL & exists()

- Preserve ~ optional-term prefix on single-word FULLTEXT (was escaped)
- Wrap multi-word OR operands in parentheses to prevent precedence issues
  (e.g. 'gaming laptop OR tablet' → (gaming laptop)|tablet)
- Add IS NULL / IS NOT NULL (ismissing) section to README
- Add exists() function section to README
- Add to What's Implemented checklist
- Add 3 new tests (368 total)

Author: nkanu17

README.md

@@ -157,6 +157,8 @@ The layered approach emerged from TDD — writing tests first revealed natural b
 - [x] Full-text search: exact phrase, fuzzy, proximity, OR/union, LIKE patterns, BM25 scoring (see below)
 - [x] GEO field queries with full operator support (see below)
 - [x] Date functions: `YEAR()`, `MONTH()`, `DAY()`, `DATE_FORMAT()`, etc. (see below)
+- [x] `IS NULL` / `IS NOT NULL` via `ismissing()` (requires Redis 7.4+, see below)
+- [x] `exists()` function for field presence checks (see below)
 
 ## What's Not Implemented (Yet...)
 
@@ -219,6 +221,45 @@ SELECT * FROM products WHERE fulltext(title, 'laptop') OR fulltext(description,
 - OR is case-insensitive: `'laptop OR tablet'`, `'laptop or tablet'`, and `'laptop Or tablet'` all work
 - Special characters (`@`, `|`, `-`, `*`, `+`, etc.) in search terms are automatically escaped
 
+### IS NULL / IS NOT NULL (ismissing)
+
+Check for missing (absent) fields using standard SQL `IS NULL` / `IS NOT NULL` syntax. Requires **Redis 7.4+** (RediSearch 2.10+) with `INDEXMISSING` declared on the field.
+
+| SQL | RediSearch Output |
+|-----|-------------------|
+| `WHERE email IS NULL` | `ismissing(@email)` |
+| `WHERE email IS NOT NULL` | `-ismissing(@email)` |
+
+```sql
+-- Find users without an email
+SELECT * FROM users WHERE email IS NULL
+
+-- Find users with an email
+SELECT * FROM users WHERE email IS NOT NULL
+
+-- Combine with other filters
+SELECT * FROM users WHERE category = 'eng' AND email IS NULL
+```
+
+**Note:** The field must be declared with `INDEXMISSING` in the index schema. A warning is emitted at translation time as a reminder.
+
+### exists() — Field Presence Check
+
+Check whether a field has a value using `exists()` in SELECT or HAVING. This uses `FT.AGGREGATE` with `APPLY exists(@field)`.
+
+```sql
+-- Check if fields exist (returns 1 or 0)
+SELECT name, exists(email) AS has_email FROM users
+
+-- Filter to only rows where a field exists
+SELECT name FROM users HAVING exists(email) = 1
+
+-- Combine with other computed fields
+SELECT name, exists(email) AS has_email, exists(phone) AS has_phone FROM users
+```
+
+**Note:** `exists()` is different from `IS NOT NULL` — it works via `FT.AGGREGATE APPLY` and doesn't require `INDEXMISSING` on the field, but returns `1`/`0` rather than filtering rows directly.
+
 ### DATE/DATETIME Handling
 
 Redis does not have a native DATE field type. Dates are stored as **NUMERIC fields** with Unix timestamps.

sql_redis/query_builder.py

@@ -142,12 +142,18 @@ def build_text_condition(
             search_value = f'"{escaped}"'
         elif re.search(r"\s+[Oo][Rr]\s+", value):
             # OR union within text field: split on case-insensitive OR with
-            # flexible whitespace, escape each term, join with |
-            or_terms = [
-                self._escape_fulltext_term(t.strip())
-                for t in re.split(r"\s+[Oo][Rr]\s+", value)
-            ]
-            search_value = f"({'|'.join(or_terms)})"
+            # flexible whitespace, escape each term, join with |.
+            # Multi-word operands (e.g. "gaming laptop OR tablet") are wrapped
+            # in parentheses so each side is an atomic subexpression.
+            or_parts: list[str] = []
+            for part in re.split(r"\s+[Oo][Rr]\s+", value):
+                words = part.strip().split()
+                if len(words) > 1:
+                    escaped = " ".join(self._escape_fulltext_term(w) for w in words)
+                    or_parts.append(f"({escaped})")
+                else:
+                    or_parts.append(self._escape_fulltext_term(words[0]))
+            search_value = f"({'|'.join(or_parts)})"
         elif " " in value:
             # FULLTEXT/MATCH with multi-word: tokenized search with stopword filtering.
             # Each term is escaped to prevent accidental operator injection, but a
@@ -182,8 +188,12 @@ def build_text_condition(
             terms = " ".join(escaped_words)
             search_value = f"({terms})"
         else:
-            # Single-word FULLTEXT — escape to prevent accidental operator injection
-            search_value = self._escape_fulltext_term(value)
+            # Single-word FULLTEXT — escape to prevent accidental operator injection.
+            # Preserve ~ optional-term prefix (same as multi-word branch).
+            if value.startswith("~"):
+                search_value = "~" + self._escape_fulltext_term(value[1:])
+            else:
+                search_value = self._escape_fulltext_term(value)
 
         # Handle multi-field search — use computed search_value with multi-field syntax
         if isinstance(field, list):

tests/test_query_builder.py

@@ -656,3 +656,25 @@ def test_escape_plus_in_fulltext(self):
         builder = QueryBuilder()
         result = builder.build_text_condition("title", "FULLTEXT", "C++")
         assert result == r"@title:C\+\+"
+
+    def test_single_term_optional_prefix_preserved(self):
+        """Single-term FULLTEXT with ~ prefix preserves optional semantics."""
+        builder = QueryBuilder()
+        result = builder.build_text_condition("title", "FULLTEXT", "~gaming")
+        assert result == "@title:~gaming"
+
+    def test_or_multiword_operand_grouped(self):
+        """OR with multi-word operand wraps it in parentheses."""
+        builder = QueryBuilder()
+        result = builder.build_text_condition(
+            "title", "FULLTEXT", "gaming laptop OR tablet"
+        )
+        assert result == "@title:((gaming laptop)|tablet)"
+
+    def test_or_both_multiword_operands_grouped(self):
+        """OR with multi-word operands on both sides wraps each."""
+        builder = QueryBuilder()
+        result = builder.build_text_condition(
+            "title", "FULLTEXT", "gaming laptop OR android tablet"
+        )
+        assert result == "@title:((gaming laptop)|(android tablet))"