docs(encryption): align index & query recipes with EQL 2.3#21
Closed
coderdan wants to merge 3 commits into
Closed
Conversation
Pre-2.3 docs assumed a bare `WHERE col = $1` would not engage a functional index, so they taught two models: operator-class B-tree indexes for self-hosted, hand-wrapped `eql_v2.hmac_256(...)` queries for Supabase. EQL 2.3's functional-index inlining makes functional indexes the single recipe for both deployments, and bare-form queries engage them automatically. indexes.mdx — rewrite around functional indexes: one recipe per query type (equality `USING hash (eql_v2.hmac_256)`, match `USING gin (eql_v2.bloom_filter)`, JSONB `USING gin (eql_v2.jsonb_array)`, range `USING btree (eql_v2.ore_block_u64_8_256)`); range is the lone self-hosted-only case (its ORE-term operator class needs superuser); drop the obsolete "Supabase query forms" wrong/right section and the removed-in-2.3 OPE references. queries.mdx — collapse the self-hosted/Supabase equality split into a single bare-form query; fix ORDER BY to the functional `eql_v2.ore_block_u64_8_256(col)` form; replace the dead `cs_ste_vec_v2(...)` function name. searchable-encryption.mdx — same ORDER BY and `cs_ste_vec_v2` fixes.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…elf-hosted only The range index needs a custom operator class on the ORE term type. That is not a self-hosted-vs-managed split: any provider that allows operator-class creation supports it — self-hosted PostgreSQL and AWS RDS included. Supabase is the notable exception, not "all managed databases". Reword the range-index availability across indexes.mdx, queries.mdx, and searchable-encryption.mdx — "most providers" rather than "self-hosted only", and drop the over-specific "requires superuser" claim.
7 tasks
calvinbrewer
approved these changes
May 20, 2026
2 tasks
Contributor
Author
|
Superseded by #44. The new |
coderdan
added a commit
that referenced
this pull request
Jul 5, 2026
Some customers still run EQL v2.2 (v2.3 is being withdrawn). The new
/reference/eql section documents EQL v3 only, so this adds a durable,
nested EQL v2 reference sourced from the v2.2 docs, surviving the
CIP-3335 deletion of the legacy /stack tree:
content/docs/reference/eql/v2/
index.mdx — EQL v2 overview (from reference/eql-guide.mdx)
indexes.mdx — index recipes, incl. the Supabase query forms
queries.mdx — equality / match / range query patterns
payload.mdx — the CipherCell v2.2 payload (b3, ocf/ocv)
Content is the v2.2 legacy docs, NOT the EQL 2.3 rewrites from #21/#22
(which no longer ship). Two grounded doc-bug fixes are carried in: the
eql-guide's fabricated index-extraction function names are corrected to
the real eql_v2.hmac_256 / bloom_filter / ore_block_u64_8_256 (verified
against the index recipes), and a stale cs_ste_vec_v2 name is aligned to
eql_v2.ste_vec.
Each page carries v2 facets (type: reference, components: [eql],
verifiedAgainst eql 2.2) and a version banner routing new projects to the
v3 reference. Wired into the EQL nav under a "Previous versions" separator.
Supersedes #21 and #22 for the v2 branch.
Claude-Session: https://claude.ai/code/session_01CqDNqLSEEkCi7xAJFq7HJA
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 — hold until
eql-2.3.0final ships. Cross-checked against EQL 2.3 (eql-2.3.0-pre.4+ in-flight fixes).Why
The encryption docs were written against pre-2.3 EQL, where a bare
WHERE col = $1did not engage a functional index. They taught two models:WHERE eql_v2.hmac_256(col) = eql_v2.hmac_256($1).EQL 2.3's functional-index inlining (U-001 / PR #193) makes functional indexes the single recipe for both deployments, and bare-form queries engage them automatically. The docs' central "wrong vs right query form" guidance is now backwards.
Changes
indexes.mdx— rewritten around functional indexes:USING hash (eql_v2.hmac_256), matchUSING gin (eql_v2.bloom_filter), JSONBUSING gin (eql_v2.jsonb_array), rangeUSING btree (eql_v2.ore_block_u64_8_256);queries.mdx— collapsed the self-hosted/Supabase equality split into one bare-form query; fixedORDER BYto the functionaleql_v2.ore_block_u64_8_256(col)form; replaced the deadcs_ste_vec_v2(...)function name.searchable-encryption.mdx— sameORDER BYandcs_ste_vec_v2fixes.Verify before merge
eql_v2.jsonb_array(col) @> eql_v2.jsonb_array($1)(EQL's owndatabase-indexes.mdrecipe). EQL 2.3 also has a typedstevec_query@>path — confirm which is the recommended public recipe, and that the SDK's JSONB query generation matches.eql-2.3.0does not shift any function name vspre.4.Out of scope (follow-ups)
reference/eql/index.mdx— generated byscripts/generate-eql-docs.tsfrom the latest EQL release. Not edited here. It still showsblake3/ocf/ocv; re-runbun run generate-docs:eqlonceeql-2.3.0is released to refresh it.reference/cipher-cell.mdx— documents the payload format with the removedb3/ocf/ocvfields (nowhm/oc). Needs a separate pass.reference/drizzle.mdx,security-architecture.mdx,comparisons/fhe.mdx— operator-family / Blake3 mentions; some (Blake3 as a cipher-cell integrity hash) may still be accurate — needs a crypto-team eye.