support "is null" "is not null"

SQL-Quick-Reference.md

@@ -92,6 +92,11 @@ SELECT * FROM events WHERE _ts > '2025-01-01';
 SELECT * FROM events WHERE status IN ('active', 'completed');
 SELECT COUNT(*) FROM events;
 
+-- NULL checking operations
+SELECT * FROM events WHERE status IS NULL;
+SELECT * FROM events WHERE status IS NOT NULL;
+SELECT * FROM events WHERE user_id IS NOT NULL AND status = 'active';
+
 -- System columns (available on all tables)
 SELECT _ts, _key, _source, * FROM events;
 
@@ -131,6 +136,33 @@ Every topic includes these system columns:
 
 **Note:** The `_ts` column supports automatic parsing of timestamp strings in WHERE clauses. Formats supported: `'2025-01-01'`, `'2025-01-01T15:30:00Z'`, `'2025-01-01 15:30:00'`, etc.
 
+## NULL Value Handling
+
+### NULL Checking Operations
+```sql
+-- Check for NULL values
+SELECT * FROM events WHERE description IS NULL;
+
+-- Check for non-NULL values  
+SELECT * FROM events WHERE user_id IS NOT NULL;
+
+-- Combine with other conditions
+SELECT * FROM events 
+WHERE user_id IS NOT NULL 
+  AND status = 'active' 
+  AND _ts >= '2025-01-01';
+
+-- Filter out records with missing data
+SELECT * FROM events WHERE user_id IS NOT NULL AND description IS NOT NULL;
+```
+
+### NULL Value Semantics
+- **Empty strings** are treated as valid values (not NULL)
+- **Missing fields** in records are considered NULL
+- **Boolean, numeric, and timestamp values** are never NULL once present
+- **Bytes values** are treated as non-NULL even if empty
+- NULL values are excluded from aggregate functions like `COUNT(column_name)`
+
 ## Troubleshooting
 
 ### Check Status
@@ -150,6 +182,7 @@ SELECT MIN(timestamp), MAX(timestamp) FROM table_name;
 2. **Auth failed**: Verify credentials in users file
 3. **Timeouts**: Increase `-idle-timeout` setting
 4. **Slow queries**: Add WHERE clauses and LIMIT
+5. **NULL filtering**: Use `IS NULL` / `IS NOT NULL` instead of `= NULL` / `!= NULL`
 
 ### Debug Mode
 ```bash
@@ -181,6 +214,11 @@ weed db -v=2 ...
    SELECT _source, _ts FROM events LIMIT 100;
    ```
 
+5. **Filter NULL values for cleaner results**:
+   ```sql
+   SELECT * FROM events WHERE user_id IS NOT NULL LIMIT 100;
+   ```
+
 ## Limitations
 
 **Not Supported:**