docs(encryption): align index & query recipes with EQL 2.3#21
Open
coderdan wants to merge 3 commits into
Open
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
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.