Skip to content

feat: fixed-effort search parameters for cross-engine parity - #2

Open
Saccilotto wants to merge 1 commit into
feat/oracle-clientfrom
feat/oracle-search-parity
Open

feat: fixed-effort search parameters for cross-engine parity#2
Saccilotto wants to merge 1 commit into
feat/oracle-clientfrom
feat/oracle-search-parity

Conversation

@Saccilotto

@SaccilottoSaccilotto commented Aug 22, 2026

Copy link
Copy Markdown
Collaborator

Stacked on #1 — review that first; this pull request shows only the parity commit.

Problem

Oracle and pgvector answer approximate search under different contracts, and the client only exposed one of them.

Oracle's approximate search is driven by an adaptive accuracy target: "return results at least this accurate", with the engine deciding how much work that takes. pgvector is driven by fixed effort: ef_search and probes say exactly how much work to do, and the accuracy follows.

Comparing the two as shipped compares an engine that adapts per query against one that does not. Whatever difference appears in recall or QPS is not attributable to the engines — it is partly an artefact of the contract each was asked to honour. Oracle does support fixed-effort search; the client simply had no way to ask for it.

Change

Two opt-in options that reach the fixed-effort forms of Oracle's search clause:

  • --ef-search on HNSW, emitting WITH TARGET ACCURACY PARAMETERS (EFSEARCH n) — the direct analogue of pgvector's ef_search
  • --neighbor-partition-probes on IVF, emitting (NEIGHBOR PARTITION PROBES n) — the analogue of pgvector's probes

Both are unset by default, and 0 is accepted as an explicit "stay adaptive", so the existing target-accuracy behaviour is untouched unless a run asks otherwise. The same parameters appear in the UI configuration.

Validation

On a live Oracle 23.26.1 instance, Performance1536D50K on HNSW:

search contractrecallthroughput
adaptive, target accuracy 95 (default)0.996344 qps
fixed effort, EFSEARCH 1280.980508 qps

That is the trade-off the parity comparison needs to be able to observe, and it is invisible without these options. Both SQL forms were verified against 23.26.1 before being wired in; unit tests cover the sentinel and the parameter emission.


Terms, for review

  • TARGET ACCURACY (adaptive): Oracle's default search contract — fix the quality ("≥95% accurate"), spend whatever work it takes per query.
  • EFSEARCH / NEIGHBOR PARTITION PROBES (fixed effort): fix the work — candidates examined on the HNSW graph / partitions opened in IVF — and let accuracy follow. This is exactly pgvector's ef_search/probes contract, which is why exposing it makes Oracle-vs-pgvector runs comparable like-for-like.
  • recall@k / QPS: quality (fraction of the true k nearest neighbours found) and speed (queries per second). The measured trade-off here — adaptive 0.996 @ 344 qps vs EFSEARCH 128 0.980 @ 508 qps — is the behaviour the option exists to expose.

Part of GRINPROJS-PUCRS/expdb#367

WITH TARGET ACCURACY PARAMETERS (EFSEARCH n) on HNSW and (NEIGHBOR PARTITION
PROBES n) on IVF -- the direct analogues of pgvector's ef_search/probes, so
cross-engine runs can compare identical search effort instead of adaptive
accuracy vs fixed effort. Exposed as --ef-search / --neighbor-partition-probes
CLI options and Streamlit inputs; unset (or 0) keeps the adaptive TARGET
ACCURACY behaviour unchanged.
Both syntaxes verified live on Oracle 23.26.1 (Free): EFSEARCH 128 on
Performance1536D50K/HNSW gives recall 0.9803 at 508 qps vs 0.996 at 344 qps
with the adaptive default.
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@Saccilotto