@venizia/ignis-docs 0.2.1-0 → 0.2.1-1

package/content/references/base/filter-system/json-filtering.md

@@ -6,39 +6,9 @@ difficulty: intermediate
 
 # JSON/JSONB Filtering
 
-Query nested fields within JSON/JSONB columns using dot notation. This is a PostgreSQL-specific feature.
+Query nested fields within JSON/JSONB columns using dot notation. PostgreSQL-specific.
 
-
-## Basic JSON Path Syntax
-
-JSON paths are expressed as dot-notation keys in the `where` clause. A key is recognized as a JSON path if it contains a `.` or `[`.
-
-```typescript
-// Column: metadata jsonb
-// Data: { "user": { "id": 123, "role": "admin" }, "tags": ["urgent"] }
-
-// Simple nested field
-{ where: { 'metadata.user.id': 123 } }
-// SQL: CASE WHEN ("metadata" #>> '{user,id}') ~ '^-?[0-9]+(\.[0-9]+)?$'
-//      THEN ("metadata" #>> '{user,id}')::numeric ELSE NULL END = 123
-
-// String field (no numeric casting)
-{ where: { 'metadata.user.role': 'admin' } }
-// SQL: "metadata" #>> '{user,role}' = 'admin'
-
-// Array index access
-{ where: { 'metadata.tags[0]': 'urgent' } }
-// SQL: "metadata" #>> '{tags,0}' = 'urgent'
-
-// Kebab-case keys
-{ where: { 'metadata.user-id': 'abc123' } }
-// SQL: "metadata" #>> '{user-id}' = 'abc123'
-```
-
-
-## Supported Path Formats
-
-| Format | Example | SQL Path |
+| Format | Example | SQL path |
 |--------|---------|----------|
 | Simple field | `metadata.name` | `{name}` |
 | Nested field | `metadata.user.email` | `{user,email}` |
@@ -46,204 +16,95 @@ JSON paths are expressed as dot-notation keys in the `where` clause. A key is re
 | Nested with array | `metadata.items[2].name` | `{items,2,name}` |
 | Kebab-case | `metadata.user-id` | `{user-id}` |
 
+> [!NOTE]
+> A key is recognized as a JSON path if it contains a `.` or `[`. The column named by the first path segment must be a `json`/`jsonb` column, or the query throws.
 
-## JSON with Operators
 
-All standard operators work with JSON paths:
+## Basic Usage
 
 ```typescript
-// Numeric comparison (automatic safe casting)
-{ where: { 'metadata.score': { gt: 80 } } }
-// SQL: CASE WHEN ("metadata" #>> '{score}') ~ '^-?[0-9]+(\.[0-9]+)?$'
-//      THEN ("metadata" #>> '{score}')::numeric ELSE NULL END > 80
+// Column: metadata jsonb
+// Data: { "user": { "id": 123, "role": "admin" } }
 
-// Range comparison
-{ where: { 'metadata.priority': { gte: 1, lte: 5 } } }
+{ where: { 'metadata.user.role': 'admin' } }
+// SQL: "metadata" #>> '{user,role}' = 'admin'
+```
 
-// Between
-{ where: { 'metadata.score': { between: [70, 90] } } }
+All standard operators work with a JSON path key:
 
-// Pattern matching (text comparison, no numeric casting)
+```typescript
+{ where: { 'metadata.score': { gt: 80 } } }
 { where: { 'metadata.level': { ilike: '%high%' } } }
-// SQL: "metadata" #>> '{level}' ILIKE '%high%'
-
-// IN operator (text comparison)
 { where: { 'metadata.status': { in: ['pending', 'review'] } } }
-
-// Regex
 { where: { 'metadata.code': { regexp: '^[A-Z]+$' } } }
-// SQL: "metadata" #>> '{code}' ~ '^[A-Z]+$'
-
-// Not equal
-{ where: { 'metadata.type': { ne: 'draft' } } }
-// SQL: "metadata" #>> '{type}' != 'draft'
 ```
 
+> [!NOTE]
+> If the path does not exist in a row's JSON, `#>>` returns `NULL` - the row is safely excluded, never an error.
 
-## Safe Numeric Casting
 
-When a numeric comparison operator (`gt`, `gte`, `lt`, `lte`, `between`, `notBetween`) is used with a JSON path, IGNIS wraps the extraction in a safe CASE expression. This prevents database errors when JSON fields contain mixed types:
+## Numeric Casting
 
-```typescript
-// Data in database:
-// Row 1: { "score": 85 }      <- number
-// Row 2: { "score": "high" }  <- string
-// Row 3: { "score": null }    <- null
+A JSON `#>>` extraction is text, so a numeric comparison needs a cast or Postgres raises `operator does not exist`. IGNIS wraps the extraction in a safe `CASE` expression, decided per operator:
 
-// Query with numeric operator
+```typescript
 { where: { 'metadata.score': { gt: 50 } } }
-
-// Generated SQL:
-// CASE WHEN ("metadata" #>> '{score}') ~ '^-?[0-9]+(\.[0-9]+)?$'
-//   THEN ("metadata" #>> '{score}')::numeric
-//   ELSE NULL
-// END > 50
-
-// Result:
-// Row 1: 85 > 50 -> matched
-// Row 2: "high" -> NULL -> not matched
-// Row 3: null -> NULL -> not matched
+// SQL: CASE WHEN ("metadata" #>> '{score}') ~ '^-?[0-9]+(\.[0-9]+)?$'
+//      THEN ("metadata" #>> '{score}')::numeric ELSE NULL END > 50
 ```
 
-| JSON Value | Numeric Operation Result |
-|------------|-------------------------|
-| `{ "score": 85 }` | Compares as `85` |
-| `{ "score": "85" }` | Compares as `85` (string passes regex) |
-| `{ "score": "high" }` | Treated as `NULL` (no match) |
-| `{ "score": null }` | Treated as `NULL` (no match) |
+| Operators | Casts to numeric when... |
+|-----------|---------------------------|
+| `gt`, `gte`, `lt`, `lte` | the operand is a `number` |
+| `between`, `notBetween` | both bounds are numbers |
+| `eq`, `ne`, `neq` | the operand is a `number` |
+| `in`, `inq`, `nin` | every array element is a `number` |
+| `like`, `ilike`, `nlike`, `nilike`, `regexp`, `iregexp` | never - always text |
+| direct value (no operator object) | the value is `typeof number` |
 
-Non-numeric operators (`eq`, `ne`, `like`, `ilike`, `in`, etc.) use text comparison via `#>>` without numeric casting.
+> [!NOTE]
+> A numeric-looking string still passes the cast (`"85"` -> `85`); a non-numeric string or `null` falls through to `NULL` and never matches.
 
-The cast is decided **per operator**, not once for the whole operator object -- a mixed object casts only the operators that need it:
+The cast applies per operator, not once for the whole object - a mixed object casts only the operators that need it:
 
 ```typescript
-// Mixed operator object: gte casts, like does not
 { where: { 'metadata.score': { gte: 1, like: '%a%' } } }
-// SQL: CASE WHEN ("metadata" #>> '{score}') ~ '^-?[0-9]+(\.[0-9]+)?$'
-//      THEN ("metadata" #>> '{score}')::numeric ELSE NULL END >= 1
-//   AND "metadata" #>> '{score}' LIKE '%a%'
+// gte casts to numeric; like stays text - both read the same #>> extraction
 ```
 
 `not` recurses into whatever it wraps, so a numeric operator nested under `not` still gets cast:
 
 ```typescript
-// not wrapping an operator - the nested gt still gets the numeric cast
 { where: { 'metadata.score': { not: { gt: 50 } } } }
 // SQL: NOT (CASE WHEN ("metadata" #>> '{score}') ~ '^-?[0-9]+(\.[0-9]+)?$'
 //           THEN ("metadata" #>> '{score}')::numeric ELSE NULL END > 50)
 ```
 
 
-## Numeric Value Equality
-
-When a JSON path is compared to a number using direct equality (not an operator object), numeric casting is also applied:
-
-```typescript
-{ where: { 'metadata.user.id': 123 } }
-// Uses numeric CASE expression since value is typeof number
-```
-
-When compared to a string, it uses text comparison:
-
-```typescript
-{ where: { 'metadata.user.role': 'admin' } }
-// Uses "metadata" #>> '{user,role}' text comparison
-```
-
-
-## JSON Path Ordering
-
-Order results by JSON fields:
+## Ordering
 
 ```typescript
 { order: ['metadata.priority DESC'] }
 // SQL: ORDER BY "metadata" #> '{priority}' DESC
-
-// Multiple JSON fields
-{ order: ['metadata.priority DESC', 'metadata.score ASC'] }
 ```
 
 > [!NOTE]
-> JSON ordering uses `#>` (returns JSONB, preserves native types) unlike where clauses which use `#>>` (returns text). This means JSONB sort order applies.
-
-**Sort Order for JSONB Types:**
-
-| JSONB Type | Sort Order |
-|------------|------------|
-| `null` | First (lowest) |
-| `boolean` | `false` < `true` |
-| `number` | Numeric order |
-| `string` | Lexicographic |
-| `array` | Element-wise |
-| `object` | Key-value |
+> Ordering uses `#>` (returns JSONB, preserves native type ordering); `where` uses `#>>` (returns text) instead.
 
 
-## Path Validation & Security
+## Path Validation
 
-Path components are validated against the pattern `/^[a-zA-Z_][a-zA-Z0-9_-]*$|^\d+$/` to prevent SQL injection:
+Every path component must match `/^[a-zA-Z_][a-zA-Z0-9_-]*$|^\d+$/` - a letter/underscore start followed by letters, digits, underscore or hyphen, or a bare digit run for an array index.
 
 ```typescript
-// Valid paths
-'metadata.fieldName'
-'metadata.nested.deep.value'
-'data.items[0]'
-'config.user_id'
-'data.meta-data'  // kebab-case allowed
-
-// Invalid (throws error)
-'metadata.field;DROP TABLE'
-'data.123invalid'         // starts with digit (not array index context)
-'config.(SELECT * FROM users)'
-```
-
-**Error Messages:**
-```
-// Non-JSON column
-Error: Column 'name' is not JSON/JSONB type | dataType: 'text'
-
-// Invalid path
-Error: Invalid JSON path component: 'field;DROP'
+'metadata.fieldName'        // valid
+'data.meta-data'            // valid - kebab-case allowed
+'data.123invalid'           // invalid - starts with a digit outside array-index context
+'metadata.field;DROP TABLE' // invalid - throws
 ```
 
-The column referenced by the first path segment (before the first `.` or `[`) must be a `json` or `jsonb` column type. Using a JSON path on a non-JSON column throws an error.
-
-
-## Performance Tips
-
-1. **Index Your JSON Paths:**
-```sql
-CREATE INDEX idx_metadata_priority ON "Product" (("metadata" ->> 'priority'));
-CREATE INDEX idx_metadata_gin ON "Product" USING GIN ("metadata");
-```
-
-2. **Use Appropriate Types in JSON:**
-```json
-// Good - numeric operators will work correctly
-{ "priority": 3, "enabled": true }
-
-// Bad - numeric operators will need string-to-number casting
-{ "priority": "3", "enabled": "true" }
-```
-
-3. **Keep Paths Shallow:**
-```typescript
-// Easier to work with and index
-'metadata.priority'
-
-// Harder to optimize
-'data.level1.level2.level3.level4.value'
-```
-
-
-## Null-Safe JSON Paths
-
-```typescript
-// If JSON field doesn't exist, #>> returns NULL
-// This is safe - no errors, just no matches
-{ where: { 'metadata.nonexistent.field': 'value' } }
-// SQL: "metadata" #>> '{nonexistent,field}' = 'value'
-// Result: No rows (NULL != 'value')
-```
+> [!NOTE]
+> A path on a non-JSON column also throws: `Column 'name' is not a JSON column`.
 
 
 ## See also
@@ -256,6 +117,6 @@ CREATE INDEX idx_metadata_gin ON "Product" USING GIN ("metadata");
 
 **Files:**
 
-- [`packages/core/src/connectors/postgres/repositories/dialect/filter.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/dialect/filter.ts) - `FilterBuilder`, `buildJsonWhereCondition`/`buildJsonOperatorConditions`/`buildJsonOrderBy`
-- [`packages/core/src/connectors/postgres/repositories/dialect/internal/json-utils.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/dialect/internal/json-utils.ts) - `isJsonPath`, `parseJsonPath`, path validation regex
-- [`packages/core/src/base/repositories/common/operators.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/repositories/common/operators.ts) - `QueryOperators` constants
+- [`packages/core-server/src/connectors/relational/repositories/dialect/filter.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/relational/repositories/dialect/filter.ts) - `FilterBuilder`, `buildJsonWhereCondition`/`buildJsonOperatorConditions`/`buildJsonOrderBy`
+- [`packages/core-server/src/connectors/relational/repositories/dialect/internal/json-utils.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/relational/repositories/dialect/internal/json-utils.ts) - `isJsonPath`, `parseJsonPath`, path validation regex
+- [`packages/filter/src/common/operators.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/filter/src/common/operators.ts) - `QueryOperators` constants

package/content/references/base/filter-system/list-operators.md

@@ -6,72 +6,42 @@ difficulty: intermediate
 
 # List Operators
 
-Operators for matching values against arrays.
+Matches a field against a set of candidate values.
 
+| Operator | SQL | Meaning |
+|----------|-----|---------|
+| `in` | `IN` | Value is one of the array |
+| `inq` | `IN` | Alias for `in` |
+| `nin` | `NOT IN` | Value is none of the array |
 
-## in / inq - In Array
-
-Matches records where field value is in the provided array. `in` and `inq` are aliases and behave identically.
+## in / inq
 
 ```typescript
 { where: { status: { in: ['active', 'pending', 'review'] } } }
-{ where: { status: { inq: ['active', 'pending', 'review'] } } }  // Alias
-
 // SQL: WHERE "status" IN ('active', 'pending', 'review')
-
-// Numeric IDs
-{ where: { categoryId: { in: [1, 2, 3, 4, 5] } } }
-// SQL: WHERE "category_id" IN (1, 2, 3, 4, 5)
 ```
 
+**Notice:** `in` and `inq` are the same operator under two names.
+
+**Edge cases:**
+- `{ in: [] }` (empty array) matches no rows (`WHERE false`).
+- `{ in: 'value' }` (non-array operand) falls back to `=`.
+- `{ in: null }` falls back to `= NULL` (not `IS NULL`) and matches no rows; use `is`/`eq` for null checks.
 
-## nin - Not In Array
+## nin
 
 ```typescript
 { where: { status: { nin: ['deleted', 'archived', 'banned'] } } }
 // SQL: WHERE "status" NOT IN ('deleted', 'archived', 'banned')
 ```
 
+**Notice:** `NOT IN` excludes rows where the column is `NULL`.
 
-## Edge Cases
-
-| Scenario | Behavior |
-|----------|----------|
-| `{ in: [] }` (empty array) | Returns no rows (`WHERE false`) |
-| `{ nin: [] }` (empty array) | Returns all rows (`WHERE true`) |
-| `{ in: 'value' }` (non-array) | Treated as `{ eq: 'value' }` |
-| `{ nin: 'value' }` (non-array) | Treated as `{ ne: 'value' }` |
-
-> [!WARNING]
-> `NOT IN` excludes rows where the column is `NULL`. If your column can be `NULL`, use `OR` to include them:
-> ```typescript
-> where: {
->   or: [
->     { status: { nin: ['deleted'] } },
->     { status: { is: null } }
->   ]
-> }
-> ```
-
-
-## Performance Tip
-
-```typescript
-import { userRepository } from '@/repositories';
-
-// For very large arrays (1000+ items), consider chunking
-const allIds: number[] = [ /* 5000 ids */ ];
-
-const chunkSize = 500;
-const results = [];
-for (let i = 0; i < allIds.length; i += chunkSize) {
-  const chunk = allIds.slice(i, i + chunkSize);
-  const chunkResults = await userRepository.find({
-    filter: { where: { id: { in: chunk } } }
-  });
-  results.push(...chunkResults);
-}
-```
+**Edge cases:**
+- Include NULL rows with an explicit `or` branch: `{ or: [{ status: { nin: [...] } }, { status: { is: null } }] }`.
+- `{ nin: [] }` (empty array) matches all rows (`WHERE true`).
+- `{ nin: 'value' }` (non-array operand) falls back to `!=`.
+- `{ nin: null }` falls back to `!= NULL` (not `IS NOT NULL`) and matches no rows.
 
 ## See also
 
@@ -81,6 +51,6 @@ for (let i = 0; i < allIds.length; i += chunkSize) {
 
 **Files:**
 
-- [`packages/core/src/connectors/postgres/repositories/dialect/query.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/dialect/query.ts) - `PostgresQueryOperators.FNS`, per-operator SQL builders
-- [`packages/core/src/connectors/postgres/repositories/dialect/filter.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/dialect/filter.ts) - `FilterBuilder`, translates `TFilter` to Drizzle/SQL
-- [`packages/core/src/base/repositories/common/operators.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/repositories/common/operators.ts) - `QueryOperators` constants
+- [`packages/core-server/src/connectors/postgres/repositories/dialect/query.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/repositories/dialect/query.ts) - `PostgresQueryOperators.FNS`, per-operator SQL builders
+- [`packages/core-server/src/connectors/relational/repositories/dialect/filter.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/relational/repositories/dialect/filter.ts) - `FilterBuilder`, translates `TFilter` to Drizzle/SQL
+- [`packages/filter/src/common/operators.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/filter/src/common/operators.ts) - `QueryOperators` constants

package/content/references/base/filter-system/logical-operators.md

@@ -8,26 +8,27 @@ difficulty: intermediate
 
 Combine multiple conditions with AND and OR logic.
 
+| Form | Where shape | SQL |
+|------|-------------|-----|
+| Implicit AND | multiple keys in one object | `AND` between each key |
+| Explicit AND | `{ and: [...] }` | `AND` between grouped clauses |
+| OR | `{ or: [...] }` | `OR` between grouped clauses |
+| NOT | `{ field: { not: ... } }` | `NOT (...)` around the negated condition |
+
 
 ## Implicit AND
 
-Multiple conditions in the same object are combined with AND:
+Multiple conditions in the same object combine with AND.
 
 ```typescript
-{
-  where: {
-    status: 'active',
-    role: 'admin',
-    verified: true,
-  }
-}
+{ where: { status: 'active', role: 'admin', verified: true } }
 // SQL: WHERE "status" = 'active' AND "role" = 'admin' AND "verified" = true
 ```
 
 
 ## Explicit AND
 
-Use `and` array for explicit AND conditions:
+Use an `and` array to group conditions explicitly.
 
 ```typescript
 {
@@ -35,19 +36,16 @@ Use `and` array for explicit AND conditions:
     and: [
       { status: 'active' },
       { role: { in: ['admin', 'moderator'] } },
-      { createdAt: { gte: new Date('2024-01-01') } },
     ]
   }
 }
-// SQL: WHERE ("status" = 'active')
-//        AND ("role" IN ('admin', 'moderator'))
-//        AND ("created_at" >= '2024-01-01')
+// SQL: WHERE ("status" = 'active') AND ("role" IN ('admin', 'moderator'))
 ```
 
 
-## OR Operator
+## OR
 
-Use `or` array for OR conditions:
+Use an `or` array to match any of several conditions.
 
 ```typescript
 {
@@ -55,152 +53,96 @@ Use `or` array for OR conditions:
     or: [
       { status: 'active' },
       { isPublished: true },
-      { featured: true },
     ]
   }
 }
-// SQL: WHERE ("status" = 'active')
-//         OR ("is_published" = true)
-//         OR ("featured" = true)
+// SQL: WHERE ("status" = 'active') OR ("is_published" = true)
 ```
 
 
-## Nested AND/OR
+## NOT
 
-Combine AND and OR for complex logic:
+`not` negates whatever it wraps: a bare value negates `eq`, a nested operator object negates that operator.
 
 ```typescript
-// (status = 'active' AND verified = true) OR (role = 'admin')
-{
-  where: {
-    or: [
-      {
-        and: [
-          { status: 'active' },
-          { verified: true },
-        ]
-      },
-      { role: 'admin' },
-    ]
-  }
-}
+{ where: { status: { not: 'archived' } } }
+// SQL: WHERE NOT ("status" = 'archived')
 
-// status = 'active' AND (role = 'admin' OR role = 'moderator')
-{
-  where: {
-    status: 'active',
-    or: [
-      { role: 'admin' },
-      { role: 'moderator' },
-    ]
-  }
-}
-// Equivalent to:
-{
-  where: {
-    status: 'active',
-    role: { in: ['admin', 'moderator'] },
-  }
-}
+{ where: { views: { not: { gt: 100 } } } }
+// SQL: WHERE NOT ("views" > 100)
 ```
 
+> [!NOTE]
+> `not` is supported on the PostgreSQL connector. The dedicated negation operators below are often clearer for a single condition.
 
-## Empty Groups
 
-An empty `and`/`or` array is not a no-op -- each empty case resolves to what the operator means with zero conditions:
+## Dedicated Negation Operators
 
-```typescript
-// Empty AND is vacuously TRUE - dropped from the query entirely
-{ where: { and: [] } }
-// SQL: (no condition added)
+| Operator | Example | SQL |
+|----------|---------|-----|
+| `ne` / `neq` | `{ status: { ne: 'deleted' } }` | `!=` |
+| `nin` | `{ status: { nin: ['deleted', 'banned'] } }` | `NOT IN` |
+| `nlike` | `{ email: { nlike: '%@test.com' } }` | `NOT LIKE` |
+| `nilike` | `{ email: { nilike: '%@test.com' } }` | `NOT ILIKE` |
+| `isn` / `ne: null` | `{ verifiedAt: { isn: null } }` | `IS NOT NULL` |
+| `notBetween` | `{ score: { notBetween: [40, 60] } }` | `NOT BETWEEN` |
 
-// Empty OR is vacuously FALSE - compiles to a condition that matches nothing
-{ where: { or: [] } }
-// SQL: WHERE false
-```
-
-This matters when the array is built from a caller-supplied list, e.g. `{ or: permittedOrgIds.map(id => ({ orgId: id })) }`: an empty permission list must return zero rows, not every row, so `or: []` matching nothing is the safe default.
+> [!NOTE]
+> `ne`/`neq`/`nin` follow SQL three-valued logic - a row whose field is `NULL` never matches them (`NULL <> value` is UNKNOWN, not TRUE). Use `exists`/`notExists` or an explicit `{ field: null }` branch to include NULL rows.
 
 
-## NOT Logic
+## Nested AND/OR
 
-IGNIS has a general-purpose `not` operator that negates whatever condition it wraps - a bare value negates `eq`, and a nested operator object negates that operator. It is supported on the PostgreSQL connector:
+Combine AND and OR for multi-level logic.
 
 ```typescript
-// NOT equal (bare value negates eq)
-{ where: { status: { not: 'archived' } } }
-// SQL: WHERE NOT ("status" = 'archived')
-
-// Negate a nested operator condition
-{ where: { views: { not: { gt: 100 } } } }
-// SQL: WHERE NOT ("views" > 100)
+// (status = 'active' AND verified = true) OR (role = 'admin')
+{
+  where: {
+    or: [
+      { and: [{ status: 'active' }, { verified: true }] },
+      { role: 'admin' },
+    ]
+  }
+}
 ```
 
-The dedicated negation operators remain available and are often clearer for a single condition:
+A top-level key alongside `or` ANDs with it - these two filters are equivalent:
 
 ```typescript
-// NOT equal
-{ where: { status: { ne: 'deleted' } } }
-{ where: { status: { neq: 'deleted' } } }
+// status = 'active' AND (role = 'admin' OR role = 'moderator')
+{ where: { status: 'active', or: [{ role: 'admin' }, { role: 'moderator' }] } }
 
-// NOT IN
-{ where: { status: { nin: ['deleted', 'banned'] } } }
+// Same result, using in instead
+{ where: { status: 'active', role: { in: ['admin', 'moderator'] } } }
+```
 
-// NOT LIKE
-{ where: { email: { nlike: '%@test.com' } } }
 
-// NOT ILIKE
-{ where: { email: { nilike: '%@test.com' } } }
+## Empty Groups
 
-// IS NOT NULL
-{ where: { verifiedAt: { isn: null } } }
-{ where: { verifiedAt: { ne: null } } }
+An empty `and`/`or` array is not a no-op - each resolves to what the operator means with zero conditions.
 
-// NOT BETWEEN
-{ where: { score: { notBetween: [40, 60] } } }
+```typescript
+{ where: { and: [] } }
+// Vacuously TRUE - dropped from the query entirely, no condition added
+
+{ where: { or: [] } }
+// SQL: WHERE false - vacuously FALSE, matches nothing
 ```
 
 > [!NOTE]
-> `ne`/`neq`/`nin` follow SQL three-valued logic - a row whose field is `NULL` never matches them (`NULL <> value` is UNKNOWN, not TRUE). Use `exists`/`notExists` or an explicit `{ field: null }` branch when you need NULL rows in the result.
-
-
-## Complex Example
+> This matters for a caller-built list, e.g. `{ or: permittedOrgIds.map(id => ({ orgId: id })) }`: an empty permission list must return zero rows, so `or: []` matching nothing is the safe default.
 
-```typescript
-// Find active products that are either:
-// - Featured with high rating, OR
-// - On sale with good stock
-{
-  where: {
-    status: 'active',
-    deletedAt: { is: null },
-    or: [
-      {
-        and: [
-          { featured: true },
-          { rating: { gte: 4.5 } }
-        ]
-      },
-      {
-        and: [
-          { onSale: true },
-          { stock: { gte: 10 } }
-        ]
-      }
-    ]
-  }
-}
-```
 
 ## See also
 
 - [Filter System Overview](./) - the `filter` shape and the full `where` operator table
-- [Null Operators](./null-operators) - `isn`, one of the dedicated negation operators referenced above
+- [Null Operators](./null-operators) - `isn`, one of the dedicated negation operators above
 - [Comparison Operators](./comparison-operators) - `ne`/`neq`, the other dedicated negation operators
 - [Quick Reference](./quick-reference) - every operator, one line each
 
 **Files:**
 
-- [`packages/core/src/connectors/postgres/repositories/dialect/filter.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/dialect/filter.ts) - `FilterBuilder`, `buildLogicalGroupCondition`/`buildNotCondition`
-- [`packages/core/src/connectors/postgres/repositories/dialect/query.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/dialect/query.ts) - `PostgresQueryOperators.FNS`, per-operator SQL builders
-- [`packages/core/src/base/repositories/common/operators.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/repositories/common/operators.ts) - `QueryOperators` constants
+- [`packages/core-server/src/connectors/relational/repositories/dialect/filter.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/relational/repositories/dialect/filter.ts) - `FilterBuilder`, `buildLogicalGroupCondition`/`buildNotCondition`
+- [`packages/core-server/src/connectors/postgres/repositories/dialect/query.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/repositories/dialect/query.ts) - `PostgresQueryOperators.FNS`, per-operator SQL builders
+- [`packages/filter/src/common/operators.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/filter/src/common/operators.ts) - `QueryOperators` constants