docs: EQL 2.3 — query coverage + reference-page fixes#22
Open
coderdan wants to merge 4 commits into
Open
Conversation
queries.mdx covered only equality, match, and range/order. Add the rest of what encrypted columns support: - JSONB — expand the thin path/containment stub into containment, field access (`->`), field equality and ordering, and path queries; cross-link the full operator reference in proxy/searchable-json. - GROUP BY / DISTINCT — group and deduplicate encrypted columns by HMAC term; group a JSON field via eql_v2.eq_term(col -> '<selector>'). - Joins — equality joins on encrypted columns, satisfied by a hash join through the hash operator class. Stacked on the EQL 2.3 recipe-fix branch (docs/eql-2.3-index-query-recipes).
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
The Functions section listed fabricated names — `encrypted_eq`, `encrypted_get_hmac_256`, `add_column`, `add_search_config` — none of which exist in EQL. Replace the hand-maintained list with the real function groups (`config_add_*`; the `hmac_256` / `bloom_filter` / `ore_block_u64_8_256` extractors; the operators) and a pointer to the generated /stack/reference/eql/ API reference, which can't drift. Also: fix three broken cross-reference anchors into searchable-encryption.mdx; correct "B-tree for exact" (equality uses a hash functional index in 2.3); add the JSONB operators to the Operators section and the rewritten index/query pages to Related.
coderdan
changed the title
cipher-cell.mdx still described the v2.2 payload. Realign it with the v2.3 on-the-wire schema (eql-payload-v2.3.schema.json): - Add the `k` discriminator field (`ct` / `sv`) — previously undocumented. - Remove `b3` (Blake3) — dropped everywhere in 2.3; STE-vector element equality now uses `hm`. - Collapse `ocf` / `ocv` into the single `oc` (CLLW ORE) field; width is carried on the ciphertext via a leading domain-tag byte. - Re-scope `a` (array marker) — it is an STE-vector element field, not a top-level field. - Correct the `sv` element shape: an STE-vector element is not a full CipherCell — it carries `s` + `c` + optional `a` + exactly one of `hm` / `oc`. - Fix three broken searchable-encryption anchors; fix the `eql_v2.encrypted` -> `eql_v2_encrypted` type name.
coderdan
changed the title
The "sorting encrypted columns" callout claimed sorting is unavailable on "managed databases (Supabase, RDS)" and referenced an `--exclude-operator-family` install flag. AWS RDS does allow custom operator classes — the real limitation is operator-class support, which most providers permit (Supabase being the exception). Reword to match the indexes/queries docs and drop the non-existent install flag.
calvinbrewer
approved these changes
May 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Draft — stacked on #21; hold until
eql-2.3.0final. Base isdocs/eql-2.3-index-query-recipes(PR #21) so the diff shows only this PR's additions; GitHub retargets it tomainonce #21 merges.Why
The encryption query docs and the EQL reference pages had drifted from EQL 2.3:
queries.mdxcovered only equality/match/range,eql-guide.mdx's Functions section listed names that don't exist,cipher-cell.mdxdescribed the v2.2 payload, anddrizzle.mdxmis-stated where sorting is available.Changes
queries.mdx@>), field access (->), field equality & ordering, and path queries.eql_v2.eq_term(col -> '<selector>').eql-guide.mdxencrypted_eq,encrypted_get_hmac_256,add_column, …) with the real groups + a pointer to the generated/stack/reference/eql/reference. Fixed three broken anchors; corrected "B-tree for exact".cipher-cell.mdxeql-payload-v2.3.schema.json): added thekdiscriminator, removedb3, collapsedocf/ocv→oc, re-scopedaas an STE-vector-element field, corrected thesvelement shape, fixed three broken anchors.drizzle.mdx--exclude-operator-familyflag.Verify before merge
eql_v2.jsonb_array(col) @> eql_v2.jsonb_array($1)(consistent with docs(encryption): align index & query recipes with EQL 2.3 #21). EQL 2.3 also has a typedstevec_query@>path; confirm which is the public recipe.WHERE metadata -> 'role' = $1::eql_v2.ste_vec_entryandORDER BY eql_v2.ore_cllw(metadata -> 'created_at'). Confirm the cast.unique(HMAC) index config; confirm.client.encryptQueryfor JSONB,encryptionOps.jsonbPathExists,.innerJoin()— confirm against the current@cipherstash/stackAPI.eql_v2.config_add_table/_column/_index/_cast— confirm that is the intended public config API.eql-payload-v2.3.schema.json; confirm nothing outside that schema changed (envelope / integrity-hash details).