Skip to content

Commit 896eae5

Browse files
committed
docs(v2): address Copilot review on EQL reference (PR #38)
- indexes.mdx: cast query-shape example params to their EQL domain types, consistent with the typed-operand rule - numbers/dates-and-times/text: the fail-loud note now scopes to operators — ORDER BY on a variant without an ordering term doesn't raise, it silently returns a meaningless order (links Sorting)
1 parent 123a544 commit 896eae5

4 files changed

Lines changed: 6 additions & 6 deletions

File tree

content/docs/reference/eql/dates-and-times.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ A value for an `_ord` column carries the shared envelope keys (`v`, `i`, `c` —
8585
| `ORDER BY` ||||
8686
| `IS NULL` / `IS NOT NULL` ||||
8787

88-
Blocked cells raise an `operator … is not supported` exception — they never silently return wrong rows. Operands must be typed (`$1::eql_v3.timestamp_ord`), or PostgreSQL resolves the native `jsonb` operator instead of the encrypted one. Both rules are covered in [Core concepts](/reference/eql/core-concepts).
88+
Blocked *operator* cells raise an `operator … is not supported` exception — they never silently return wrong rows. `ORDER BY` is the one blocked cell that doesn't raise: it isn't an operator, so sorting a variant without an ordering term runs — but the order is meaningless (see [Sorting](/reference/eql/sorting)). Operands must be typed (`$1::eql_v3.timestamp_ord`), or PostgreSQL resolves the native `jsonb` operator instead of the encrypted one. Both rules are covered in [Core concepts](/reference/eql/core-concepts).
8989

9090
## Functions
9191

content/docs/reference/eql/indexes.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ WHERE email = '{"hm":"abc"}'::jsonb;
7777
### Equality
7878

7979
```sql
80-
SELECT * FROM users WHERE email = $1;
80+
SELECT * FROM users WHERE email = $1::eql_v3.text_eq;
8181
-- Index Scan using users_email_eq
8282
-- Index Cond: (eql_v3.eq_term(email) = eql_v3.eq_term($1))
8383
```
@@ -87,14 +87,14 @@ SELECT * FROM users WHERE email = $1;
8787
The `<`, `<=`, `>`, `>=` operators inline to comparisons on `eql_v3.ord_term`, so natural-form range predicates match the btree:
8888

8989
```sql
90-
SELECT * FROM users WHERE created_at < $1;
90+
SELECT * FROM users WHERE created_at < $1::eql_v3.timestamp_ord;
9191
```
9292

9393
`ORDER BY` needs care. The planner inlines operators in *predicates* but does not rewrite *sort keys*: `ORDER BY created_at` uses the index for the `WHERE` clause but still adds a `Sort` node, which scales linearly with the rows passing the filter. To stream rows out of the btree already ordered, write the sort key in extractor form:
9494

9595
```sql
9696
SELECT * FROM users
97-
WHERE created_at < $1
97+
WHERE created_at < $1::eql_v3.timestamp_ord
9898
ORDER BY eql_v3.ord_term(created_at) DESC
9999
LIMIT 10;
100100
```

content/docs/reference/eql/numbers.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,7 @@ A value for an `_ord` column carries the shared envelope keys (`v`, `i`, `c` —
9090
| `ORDER BY` ||||
9191
| `IS NULL` / `IS NOT NULL` ||||
9292

93-
Blocked cells raise an `operator … is not supported` exception — they never silently return wrong rows. Operands must be typed (`$1::eql_v3.int8_ord`), or PostgreSQL resolves the native `jsonb` operator instead of the encrypted one. Both rules are covered in [Core concepts](/reference/eql/core-concepts).
93+
Blocked *operator* cells raise an `operator … is not supported` exception — they never silently return wrong rows. `ORDER BY` is the one blocked cell that doesn't raise: it isn't an operator, so sorting a variant without an ordering term runs — but the order is meaningless (see [Sorting](/reference/eql/sorting)). Operands must be typed (`$1::eql_v3.int8_ord`), or PostgreSQL resolves the native `jsonb` operator instead of the encrypted one. Both rules are covered in [Core concepts](/reference/eql/core-concepts).
9494

9595
## Functions
9696

content/docs/reference/eql/text.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,7 +84,7 @@ The narrower variants carry only their own term: a `text_eq` payload carries `hm
8484
| `ORDER BY` ||||||
8585
| `IS NULL` / `IS NOT NULL` ||||||
8686

87-
Blocked cells raise an `operator … is not supported` exception — they never silently return wrong rows. Operands must be typed (`$1::eql_v3.text_eq`), or PostgreSQL resolves the native `jsonb` operator instead of the encrypted one. Both rules are covered in [Core concepts](/reference/eql/core-concepts).
87+
Blocked *operator* cells raise an `operator … is not supported` exception — they never silently return wrong rows. `ORDER BY` is the one blocked cell that doesn't raise: it isn't an operator, so sorting a variant without an ordering term runs — but the order is meaningless (see [Sorting](/reference/eql/sorting)). Operands must be typed (`$1::eql_v3.text_eq`), or PostgreSQL resolves the native `jsonb` operator instead of the encrypted one. Both rules are covered in [Core concepts](/reference/eql/core-concepts).
8888

8989
## Functions
9090

0 commit comments

Comments
 (0)