Skip to content

Commit 9de3535

Browse files
authored
Merge pull request #1548 from cipherstash/claude/project-thread-7am8g0
fix(eql): drop ignored query_json cast and correct eql-bindings wire docs
2 parents ef1ef1b + d25dc49 commit 9de3535

6 files changed

Lines changed: 23 additions & 14 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@cipherstash/eql': patch
3+
---
4+
5+
Drop the `CREATE CAST (public.eql_v3_json_search AS eql_v3.query_json)` that PostgreSQL always ignored (it warned "cast will be ignored because the source data type is a domain" on every install). `doc::eql_v3.query_json` was never converting; call `eql_v3.to_ste_vec_query(col)` instead. Also corrects the `eql-bindings` wire-format docs: `op` backs `_ord` / `_ord_ope` (and `text_ord` / `text_search` carry `hm` + `op`), `ob` only `_ord_ore`.

‎packages/eql/crates/eql-bindings/src/v3/mod.rs‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -23,22 +23,24 @@
2323
//! For the generated flat-scalar families, every payload has the shared envelope
2424
//! keys (required by every scalar domain CHECK, mirroring `ENVELOPE_KEYS` in
2525
//! `eql-domains`): `v`, `i`, `c`. Then the domain's required term keys — `hm`
26-
//! for `_eq`, `ob` for `_ord`/`_ord_ore`, `op` for `_ord_ope`, `bf` for
27-
//! `_match`, none for
28-
//! storage-only. `Option` does not appear in the generated scalar structs: the
26+
//! for `_eq`, `op` for `_ord`/`_ord_ope`, `ob` for `_ord_ore`, `bf` for
27+
//! `_match` (and, alongside the ordering term, for the `_search` domains),
28+
//! none for storage-only. `Option` does not appear in the generated scalar structs: the
2929
//! capability **is** the type identity. Hold a [`integer::IntegerEq`] and `hm` is
3030
//! present, guaranteed by the Rust type and (SQL-side) by the domain CHECK. A
3131
//! missing term key is a deserialization error — the Rust analogue of the CHECK
3232
//! constraint.
3333
//!
34-
//! One exception to "`ob` for `_ord`": `text`'s ordered domains carry **both**
35-
//! `hm` and the ordering term (`text_ord`/`text_ord_ore`/`text_search` carry
36-
//! `hm` + `ob`; `text_ord_ope` carries `hm` + `op`), where the non-text
34+
//! One exception to "the ordering term alone": `text`'s ordered domains carry **both**
35+
//! `hm` and the ordering term (`text_ord`/`text_ord_ope` carry `hm` + `op`;
36+
//! `text_ord_ore` carries `hm` + `ob`; `text_search` carries `hm` + `op` +
37+
//! `bf`; `text_search_ore` carries `hm` + `ob` + `bf`), where the non-text
3738
//! ordered domains carry the ordering term alone. Text routes `=`/`<>`
3839
//! through `hm` rather than the ordering term because lexicographic ORE/OPE
3940
//! over text is not equality-lossless, so equality needs the HMAC. The
4041
//! generated struct doc surfaces this structurally — its required-keys line
41-
//! lists `hm` `ob` (or `hm` `op`) rather than just the ordering key.
42+
//! lists `hm` `op` (or `hm` `ob`, plus `bf` for the `_search` domains) rather than
43+
//! just the ordering key.
4244
//!
4345
//! The generated flat-scalar types are also **strict**: every scalar struct is
4446
//! `#[serde(deny_unknown_fields)]`, so a payload carrying keys outside the

‎packages/eql/docs/reference/json-support.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -214,7 +214,7 @@ separate equality-indexed scalar column when server-side grouping is required.
214214
- **`eql_v3.jsonb_document_contains(a public.eql_v3_json_search, b public.eql_v3_json_search) RETURNS boolean`** — true if every selector in `b` is present in `a` (selector-subset containment); backs the `@>` operator.
215215
- **`eql_v3.jsonb_contains(a jsonb, b jsonb)` / `eql_v3.jsonb_contained_by(a jsonb, b jsonb)`** — function-form containment entrypoints for platforms that cannot type an operator call (Supabase PostgREST RPC, for example); same result as `@>` / `<@` (a parity test pins this).
216216
- **`eql_v3.jsonb_array(val jsonb) RETURNS jsonb[]`** — function-form array accessor for the same platforms.
217-
- **`eql_v3.to_ste_vec_query(val public.eql_v3_json_search) RETURNS eql_v3.query_json`** — the GIN-indexable query shape `@>` inlines to.
217+
- **`eql_v3.to_ste_vec_query(val public.eql_v3_json_search) RETURNS eql_v3.query_json`** — the GIN-indexable query shape `@>` inlines to. This is the only document-to-needle conversion: `doc::eql_v3.query_json` is **not** equivalent (PostgreSQL ignores casts from a domain, so it is a plain coercion that fails the `query_json` CHECK for a stored document, whose `sv` entries carry ciphertext).
218218
- **`eql_v3.meta_data(val jsonb)`** — envelope accessor: returns `{i, v, h}` (the key header `h` included so an extracted entry can be decrypted). **`eql_v3.ciphertext(val jsonb)`** — returns the `c` field; on the ste_vec surface `c` is raw AEAD output, decryptable only together with the entry's `s` and the document `h`. **`eql_v3.selector(val jsonb)` / `(entry public.eql_v3_json_entry)`** — selector accessor.
219219

220220
### Path query functions

‎packages/eql/src/v3/json/types.sql‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -249,6 +249,13 @@ $$;
249249
--! GIN index expression:
250250
--! `GIN (eql_v3.to_ste_vec_query(col)::jsonb jsonb_path_ops)`.
251251
--!
252+
--! @note There is deliberately no `CREATE CAST` from `public.eql_v3_json_search`
253+
--! to `eql_v3.query_json`. PostgreSQL ignores a cast whose source type is a
254+
--! domain (it warns "cast will be ignored because the source data type is a
255+
--! domain"), so `doc::eql_v3.query_json` would never call
256+
--! `to_ste_vec_query`; it is a plain binary coercion that then fails the
257+
--! `query_json` CHECK. Call `eql_v3.to_ste_vec_query(col)` explicitly.
258+
--!
252259
--! @param e public.eql_v3_json_search Source encrypted payload
253260
--! @return eql_v3.query_json Query-shaped needle, sv elements normalised.
254261
--! @see eql_v3.query_json
@@ -291,7 +298,3 @@ AS $$
291298
)
292299
)::eql_v3.query_json
293300
$$;
294-
295-
CREATE CAST (public.eql_v3_json_search AS eql_v3.query_json)
296-
WITH FUNCTION eql_v3.to_ste_vec_query(public.eql_v3_json_search)
297-
AS ASSIGNMENT;

‎packages/eql/tasks/test/splinter.sh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,7 @@ function_search_path_mutable eql_v3 @> function Containment (@>) operator wrappe
101101
function_search_path_mutable eql_v3 <@ function Contained-by (<@) operator wrapper on the eql_v3 encrypted-JSONB surface: same rationale as eql_v3.@>. Three overloads.
102102
function_search_path_mutable eql_v3 selector function STE-vec entry selector extractor: typed (public.eql_v3_jsonb_entry) overload, inlinable so `eql_v3.selector(col -> 'sel')` folds into the calling query. Structural domain-arg skip. The (jsonb) overload is plpgsql with a pinned search_path and does not surface.
103103
function_search_path_mutable eql_v3 ope_term function STE-vec ordered-term extractor for public.eql_v3_jsonb_entry: inlinable so `eql_v3.ope_term(col -> 'sel')` folds into the calling range query and matches the functional btree index built on the same expression. SET search_path would disable SQL function inlining. The deprecated eq_term(json_entry) compatibility alias is pinned and does not surface.
104-
function_search_path_mutable eql_v3 to_ste_vec_query function Encrypted-JSONB query-document constructor (CAST WITH FUNCTION for eql_v3.query_jsonb): inlinable SQL over a public.eql_v3_json domain arg, structural domain-arg skip. Builds the ste_vec query value the @>/<@ wrappers compare against; must inline to fold into the calling query.
104+
function_search_path_mutable eql_v3 to_ste_vec_query function Encrypted-JSONB containment-needle constructor, called explicitly (there is no CAST to eql_v3.query_json; PostgreSQL ignores casts from a domain): inlinable SQL over a public.eql_v3_json_search / eql_v3.query_json arg, structural domain-arg skip. Builds the ste_vec query value the @>/<@ wrappers compare against; must inline to fold into the calling query and to match the functional GIN index on eql_v3.to_ste_vec_query(col)::jsonb.
105105
function_search_path_mutable eql_v3 jsonb_document_contains function Typed encrypted-JSONB document containment engine backing the public.eql_v3_json_search @>/<@ operators: the inlinable SQL (public.eql_v3_json_search) overload folds to native jsonb containment over eql_v3.to_ste_vec_query(a/b)::jsonb, so the planner can match the functional GIN index on eql_v3.to_ste_vec_query(col)::jsonb. Structural domain-arg skip leaves this overload unpinned; the raw jsonb[] plpgsql overload has a fixed search_path and does not surface.
106106
function_search_path_mutable eql_v3 ste_vec_contains function Deprecated compatibility alias for the typed eql_v3.jsonb_document_contains overload. It must remain inlinable so existing function-form queries retain the same functional-GIN-index matching as before the rename. The public.eql_v3_json_search domain arguments leave this overload intentionally unpinned; the raw jsonb[] alias is pinned by tasks/pin_search_path_v3.sql and does not surface.
107107
function_search_path_mutable eql_v3 jsonb_array function ste_vec deterministic-field array extractor on the eql_v3 encrypted-JSONB surface: public inlinable SQL (raw jsonb arg) behind the documented functional GIN index expression eql_v3.jsonb_array(col). Takes bare jsonb, so it carries the documented `eql-inline-critical` COMMENT marker that pin_search_path_v3.sql honours rather than the structural skip.

‎packages/eql/tests/sqlx/snapshots/eql_v3_public_surface.txt‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,6 @@ aggregate eql_v3.min(public.eql_v3_text_search_ore)
5959
aggregate eql_v3.min(public.eql_v3_timestamp_ord)
6060
aggregate eql_v3.min(public.eql_v3_timestamp_ord_ope)
6161
aggregate eql_v3.min(public.eql_v3_timestamp_ord_ore)
62-
cast public.eql_v3_json_search -> eql_v3.query_json
6362
function eql_v3.->(e public.eql_v3_json_search, selector integer)
6463
function eql_v3.->(e public.eql_v3_json_search, selector text)
6564
function eql_v3.->>(e public.eql_v3_json_search, selector integer)

0 commit comments

Comments
 (0)