pg.ddx.io pgvector/pgvector GitHub issues and pull requests
help / color / mirror / Atom feed[pgvector/pgvector] PR #1061: Changed default for ivfflat.probes to sqrt(lists)
4+ messages / 2 participants
[nested] [flat]
* [pgvector/pgvector] PR #1061: Changed default for ivfflat.probes to sqrt(lists)
@ 2026-11-11 15:57 "YidaWeng (@YidaWeng)" <noreply+YidaWeng@github.com>
0 siblings, 0 replies; 4+ messages in thread
From: YidaWeng (@YidaWeng) @ 2026-11-11 15:57 UTC (permalink / raw)
To: pgvector/pgvector <noreply+pgvector-pgvector@github.com>
## Summary
Makes `ivfflat.probes` default to `sqrt(lists)` by treating `0` as "auto":
- `ivfflat.probes = 0` (new default) uses `ceil(sqrt(lists))`
- positive values keep the existing fixed behavior
- the value is resolved in both `ivfflatbeginscan` and
`ivfflatcostestimate`, so plans and execution agree
This is the "Maybe: make `sqrt(lists)` the default for `ivfflat.probes`" item
from the 0.9.0 plan (#1042). Opening as a draft to get feedback on the default
before merging; happy to switch to a different fraction or cap.
## Motivation
The current default is `1`, i.e. `1/lists` of the index is scanned: 1% at
`lists = 100`, 0.1% at `lists = 1000`. On SIFT1M (`lists = 1000`) that gives
recall@10 of 0.315. `sqrt(lists)` scans `1/sqrt(lists)` (10% at 100 lists,
3.2% at 1000) and gives 0.980.
## Benchmarks
PostgreSQL 18.6 (Homebrew), macOS arm64 (Apple Silicon), assertions enabled,
warm cache. 20 queries, recall@10 against exact seq-scan ground truth, 5
repetitions, p50/p95 from per-query timings. Index built with
`maintenance_work_mem = 1GB`.
| dataset | probes=1 (old) | sqrt(lists) (new) | probes=lists |
|---|---|---|---|
| SIFT1M, lists=1000 | 0.315 / 0.42 ms | 0.980 / 13.75 ms (32) | 1.000 / 405 ms |
| uniform 100k x 3d, lists=100 | 0.895 / 0.14 ms | 1.000 / 1.33 ms (10) | 1.000 / 17.5 ms |
| uniform 100k x 128d, lists=100 | 0.050 / 0.29 ms | 0.345 / 2.55 ms (10) | 1.000 / 27.7 ms |
| clustered 100k x 128d, lists=100 | 0.180 / 0.27 ms | 0.610 / 2.75 ms (10) | 1.000 / 30.5 ms |
| uniform 1M x 128d, lists=1000 | 0.015 / 0.39 ms | 0.210 / 14.1 ms (32) | 1.000 / n/a |
SIFT curve around the proposed default:
| probes | recall@10 | p50 |
|---|---|---|
| 1 | 0.315 | 0.42 ms |
| 8 | 0.805 | 2.65 ms |
| 10 | 0.835 | 3.33 ms |
| 16 | 0.940 | 6.50 ms |
| 32 | 0.980 | 13.75 ms |
| 50 | 1.000 | 20.25 ms |
Uniform random 128d is a pathological case (distances concentrate); it is
included as a lower bound. SIFT and the clustered set are more representative.
Full sweeps and the driver script are available if useful; they are not
included in the diff.
## Planner behavior
- With `lists = 100` and `lists = 1000`, the planner still chooses the IVFFlat
index for `ORDER BY ... LIMIT 10` under default settings.
- With very small indexes (`lists = 5`), the new ratio is 3/5 and the planner
prefers a seq scan. The existing cost test pins `probes = 1` so it keeps
testing the cost model rather than the default.
- A selective attribute index is now chosen over IVFFlat for one filtered
query; the test previously had a `# TODO Use attribute index` there, so the
test now expects `attribute_idx`.
## Tests
- `make installcheck`: 14/14
- `make prove_installcheck`: 49 files, 1261 tests, all passing
- New `test/t/049_ivfflat_probes_default.pl` checks that default and explicit
`ceil(sqrt(lists))` produce identical results and identical plans for
`lists` 100 and 1000, the default `SHOW` value, and the range check
## Open questions
- Is `0` an acceptable sentinel, or would you prefer detecting the default
via `pg_settings.source`?
- `sqrt(lists)` is aggressive on latency (32x on SIFT1M). Would a smaller
fraction (e.g. `sqrt(lists)/2`) or a cap be preferable?
inline patch 1: CHANGELOG.md, README.md, src/ivfflat.c and 7 more (+103/-12 lines) download inline-1.patch
diff --git a/CHANGELOG.md b/CHANGELOG.md
index dfce94f52..cbd3119b7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,7 @@
- Added `vector_dims` function for `sparsevec`
- Improved performance of HNSW inserts with `sparsevec`
- Improved `amvalidate` for indexes
+- Changed default for `ivfflat.probes` to `sqrt(lists)`
- Improved property testing for indexes
- Fixed possible error with iterative index scans during HNSW vacuuming
- Dropped support for Postgres 13 and 14
diff --git a/README.md b/README.md
index f5fde78f3..8271c0cb3 100644
--- a/README.md
+++ b/README.md
@@ -377,7 +377,7 @@ Supported types are:
### Query Options
-Specify the number of probes (1 by default)
+Specify the number of probes (defaults to `sqrt(lists)`)
```sql
SET ivfflat.probes = 10;
@@ -385,6 +385,8 @@ SET ivfflat.probes = 10;
A higher value provides better recall at the cost of speed, and it can be set to the number of lists for exact nearest neighbor search (at which point the planner won’t use the index)
+The default value of `0` uses `sqrt(lists)`, so the number of probes scales with the index size. Set a positive value to use a fixed number of probes.
+
Use `SET LOCAL` inside a transaction to set it for a single query
```sql
diff --git a/src/ivfflat.c b/src/ivfflat.c
index e9659582f..0c6d5304e 100644
--- a/src/ivfflat.c
+++ b/src/ivfflat.c
@@ -52,8 +52,8 @@ IvfflatInit(void)
IVFFLAT_DEFAULT_LISTS, IVFFLAT_MIN_LISTS, IVFFLAT_MAX_LISTS, AccessExclusiveLock);
DefineCustomIntVariable("ivfflat.probes", "Sets the number of probes",
- "Valid range is 1..lists.", &ivfflat_probes,
- IVFFLAT_DEFAULT_PROBES, IVFFLAT_MIN_LISTS, IVFFLAT_MAX_LISTS, PGC_USERSET, 0, NULL, NULL, NULL);
+ "Valid range is 0..lists (0 uses sqrt(lists))", &ivfflat_probes,
+ IVFFLAT_DEFAULT_PROBES, IVFFLAT_MIN_PROBES, IVFFLAT_MAX_LISTS, PGC_USERSET, 0, NULL, NULL, NULL);
DefineCustomEnumVariable("ivfflat.iterative_scan", "Sets the mode for iterative scans",
NULL, &ivfflat_iterative_scan,
@@ -135,7 +135,7 @@ ivfflatcostestimate(PlannerInfo *root, IndexPath *path, double loop_count,
lists = IVFFLAT_DEFAULT_LISTS;
/* Get the ratio of lists that we need to visit */
- ratio = ((double) ivfflat_probes) / lists;
+ ratio = ((double) IvfflatGetProbes(lists)) / lists;
if (ratio > 1.0)
ratio = 1.0;
diff --git a/src/ivfflat.h b/src/ivfflat.h
index ab3ac9927..0356d3db0 100644
--- a/src/ivfflat.h
+++ b/src/ivfflat.h
@@ -3,6 +3,8 @@
#include "postgres.h"
+#include <math.h>
+
#include "access/genam.h"
#include "access/generic_xlog.h"
#include "access/parallel.h"
@@ -61,7 +63,8 @@ typedef Pointer Item;
#define IVFFLAT_DEFAULT_LISTS 100
#define IVFFLAT_MIN_LISTS 1
#define IVFFLAT_MAX_LISTS 32768
-#define IVFFLAT_DEFAULT_PROBES 1
+#define IVFFLAT_DEFAULT_PROBES 0
+#define IVFFLAT_MIN_PROBES 0
/* Build phases */
/* PROGRESS_CREATEIDX_SUBPHASE_INITIALIZE is 1 */
@@ -106,6 +109,23 @@ extern int ivfflat_probes;
extern int ivfflat_iterative_scan;
extern int ivfflat_max_probes;
+/*
+ * Get the number of probes
+ *
+ * A value of 0 uses sqrt(lists), which scales the number of probes with the
+ * index size instead of requiring a fixed value for every index.
+ */
+static inline int
+IvfflatGetProbes(int lists)
+{
+ int probes = ivfflat_probes;
+
+ if (probes == 0)
+ probes = (int) ceil(sqrt((double) lists));
+
+ return Max(probes, 1);
+}
+
typedef enum IvfflatIterativeScanMode
{
IVFFLAT_ITERATIVE_SCAN_OFF,
diff --git a/src/ivfscan.c b/src/ivfscan.c
index e63e03708..fd44babaa 100644
--- a/src/ivfscan.c
+++ b/src/ivfscan.c
@@ -347,7 +347,7 @@ ivfflatbeginscan(Relation index, int nkeys, int norderbys)
IvfflatScanOpaque so;
int lists;
int dimensions;
- int probes = ivfflat_probes;
+ int probes;
int maxProbes;
MemoryContext oldCtx;
@@ -356,6 +356,8 @@ ivfflatbeginscan(Relation index, int nkeys, int norderbys)
/* Get lists and dimensions from metapage */
IvfflatGetMetaPageInfo(index, &lists, &dimensions);
+ probes = IvfflatGetProbes(lists);
+
if (ivfflat_iterative_scan != IVFFLAT_ITERATIVE_SCAN_OFF)
maxProbes = Max(ivfflat_max_probes, probes);
else
diff --git a/test/expected/ivfflat_vector.out b/test/expected/ivfflat_vector.out
index ec3f778bc..a3a8c42a5 100644
--- a/test/expected/ivfflat_vector.out
+++ b/test/expected/ivfflat_vector.out
@@ -108,7 +108,8 @@ SELECT * FROM t ORDER BY val <-> '[3,3,3]';
val
---------
[1,2,3]
-(1 row)
+ [1,1,1]
+(2 rows)
SET ivfflat.max_probes = 2;
SELECT * FROM t ORDER BY val <-> '[3,3,3]';
@@ -155,13 +156,12 @@ DROP TABLE t;
SHOW ivfflat.probes;
ivfflat.probes
----------------
- 1
+ 0
(1 row)
SET ivfflat.probes = 0;
-ERROR: 0 is outside the valid range for parameter "ivfflat.probes" (1 .. 32768)
SET ivfflat.probes = 32769;
-ERROR: 32769 is outside the valid range for parameter "ivfflat.probes" (1 .. 32768)
+ERROR: 32769 is outside the valid range for parameter "ivfflat.probes" (0 .. 32768)
SHOW ivfflat.iterative_scan;
ivfflat.iterative_scan
------------------------
diff --git a/test/t/009_ivfflat_filtering.pl b/test/t/009_ivfflat_filtering.pl
index 72b2c535b..5061398f7 100644
--- a/test/t/009_ivfflat_filtering.pl
+++ b/test/t/009_ivfflat_filtering.pl
@@ -101,8 +101,7 @@
$explain = $node->safe_psql("postgres", qq(
EXPLAIN ANALYZE SELECT i FROM tst WHERE c = $c ORDER BY v <-> '$query' LIMIT $limit;
));
-# TODO Use attribute index
-like($explain, qr/Index Scan using idx/);
+like($explain, qr/attribute_idx/);
# Test partial index
$node->safe_psql("postgres", "CREATE INDEX partial_idx ON tst USING ivfflat (v vector_l2_ops) WITH (lists = 5) WHERE (c = $c);");
diff --git a/test/t/036_ivfflat_bit_centers.pl b/test/t/036_ivfflat_bit_centers.pl
index be77ee260..1d1845e41 100644
--- a/test/t/036_ivfflat_bit_centers.pl
+++ b/test/t/036_ivfflat_bit_centers.pl
@@ -29,6 +29,7 @@
my $actual = $node->safe_psql("postgres", qq(
SET enable_seqscan = off;
+ SET ivfflat.probes = 1;
SELECT i FROM tst ORDER BY v <~> '$v' LIMIT 100;
));
my @actual_ids = split("\n", $actual);
diff --git a/test/t/040_ivfflat_cost.pl b/test/t/040_ivfflat_cost.pl
index 1c311a37d..f6e38c46d 100644
--- a/test/t/040_ivfflat_cost.pl
+++ b/test/t/040_ivfflat_cost.pl
@@ -35,11 +35,13 @@
my $query = "[" . join(",", @r) . "]";
my $explain = $node->safe_psql("postgres", qq(
+ SET ivfflat.probes = 1;
EXPLAIN ANALYZE SELECT i FROM tst ORDER BY v <-> '$query' LIMIT $limit;
));
like($explain, qr/Index Scan using idx/);
$explain = $node->safe_psql("postgres", qq(
+ SET ivfflat.probes = 1;
EXPLAIN ANALYZE SELECT i FROM tst WHERE v <-> '$query' < 1 ORDER BY v <-> '$query' LIMIT $limit;
));
like($explain, qr/Index Scan using idx/);
diff --git a/test/t/049_ivfflat_probes_default.pl b/test/t/049_ivfflat_probes_default.pl
new file mode 100644
index 000000000..e482aeb51
--- /dev/null
+++ b/test/t/049_ivfflat_probes_default.pl
@@ -0,0 +1,64 @@
+use strict;
+use warnings FATAL => 'all';
+use PostgreSQL::Test::Cluster;
+use PostgreSQL::Test::Utils;
+use Test::More;
+
+# Initialize node
+my $node = PostgreSQL::Test::Cluster->new('node');
+$node->init;
+$node->start;
+
+# Create table and index
+$node->safe_psql("postgres", "CREATE EXTENSION vector;");
+$node->safe_psql("postgres", "CREATE TABLE tst (i int4, v vector(3));");
+$node->safe_psql("postgres", "SELECT setseed(0.5);");
+$node->safe_psql("postgres",
+ "INSERT INTO tst SELECT i, ARRAY[random(), random(), random()] FROM generate_series(1, 20000) i;"
+);
+
+my $query = "[0.1,0.2,0.3]";
+
+# Default is 0 (auto)
+is($node->safe_psql("postgres", "LOAD 'vector'; SHOW ivfflat.probes"), "0", "default probes");
+
+# Check each number of lists
+foreach my $case ([100, 10], [1000, 32])
+{
+ my ($lists, $expected) = @$case;
+
+ $node->safe_psql("postgres", "DROP INDEX IF EXISTS idx;");
+ $node->safe_psql("postgres",
+ "SET maintenance_work_mem = '256MB'; CREATE INDEX idx ON tst USING ivfflat (v vector_l2_ops) WITH (lists = $lists);");
+
+ my $default_results = $node->safe_psql("postgres", qq(
+ SET enable_seqscan = off;
+ SELECT i FROM tst ORDER BY v <-> '$query' LIMIT 10;
+ ));
+ my $explicit_results = $node->safe_psql("postgres", qq(
+ SET enable_seqscan = off;
+ SET ivfflat.probes = $expected;
+ SELECT i FROM tst ORDER BY v <-> '$query' LIMIT 10;
+ ));
+ is($default_results, $explicit_results,
+ "default matches $expected probes with lists = $lists");
+
+ my $default_plan = $node->safe_psql("postgres", qq(
+ SET enable_seqscan = off;
+ EXPLAIN SELECT i FROM tst ORDER BY v <-> '$query' LIMIT 10;
+ ));
+ my $explicit_plan = $node->safe_psql("postgres", qq(
+ SET enable_seqscan = off;
+ SET ivfflat.probes = $expected;
+ EXPLAIN SELECT i FROM tst ORDER BY v <-> '$query' LIMIT 10;
+ ));
+ is($default_plan, $explicit_plan,
+ "default cost matches $expected probes with lists = $lists");
+}
+
+# Negative values are rejected
+my ($ret, $stdout, $stderr) = $node->psql("postgres", "LOAD 'vector'; SET ivfflat.probes = -1;");
+isnt($ret, 0, "negative probes rejected");
+like($stderr, qr/outside the valid range/, "negative probes error");
+
+done_testing();
^ permalink raw [nested|flat] 4+ messages in thread
* Re: [pgvector/pgvector] PR #1061: Changed default for ivfflat.probes to sqrt(lists)
@ 2026-11-11 19:00 "ankane (@ankane)" <noreply+ankane@github.com>
2 siblings, 0 replies; 4+ messages in thread
From: ankane (@ankane) @ 2026-11-11 19:00 UTC (permalink / raw)
To: pgvector/pgvector <noreply+pgvector-pgvector@github.com>
@ankane closed this.
^ permalink raw [nested|flat] 4+ messages in thread
* Re: [pgvector/pgvector] PR #1061: Changed default for ivfflat.probes to sqrt(lists)
@ 2026-11-11 19:00 "ankane (@ankane)" <noreply+ankane@github.com>
2 siblings, 0 replies; 4+ messages in thread
From: ankane (@ankane) @ 2026-11-11 19:00 UTC (permalink / raw)
To: pgvector/pgvector <noreply+pgvector-pgvector@github.com>
Hi @YidaWeng, there are already branches for this ([ivfflat-default-probes](https://github.com/pgvector/pgvector/compare/master...ivfflat-default-probes) and [ivfflat-default-probes2](https://github.com/pgvector/pgvector/compare/master...ivfflat-default-probes2)).
^ permalink raw [nested|flat] 4+ messages in thread
* Re: [pgvector/pgvector] PR #1061: Changed default for ivfflat.probes to sqrt(lists)
@ 2026-11-13 06:46 "YidaWeng (@YidaWeng)" <noreply+YidaWeng@github.com>
2 siblings, 0 replies; 4+ messages in thread
From: YidaWeng (@YidaWeng) @ 2026-11-13 06:46 UTC (permalink / raw)
To: pgvector/pgvector <noreply+pgvector-pgvector@github.com>
Thanks, I missed those branches — closing this. `ivfflat-default-probes2` looks like the right place for the change.
^ permalink raw [nested|flat] 4+ messages in thread
end of thread, other threads:[~2026-11-13 06:46 UTC | newest]
Thread overview: 4+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2026-11-11 15:57 [pgvector/pgvector] PR #1061: Changed default for ivfflat.probes to sqrt(lists) "YidaWeng (@YidaWeng)" <noreply+YidaWeng@github.com>
2026-11-11 19:00 ` "ankane (@ankane)" <noreply+ankane@github.com>
2026-11-11 19:00 ` "ankane (@ankane)" <noreply+ankane@github.com>
2026-11-13 06:46 ` "YidaWeng (@YidaWeng)" <noreply+YidaWeng@github.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox