Added search parameters to EXPLAIN [skip ci]

CHANGELOG.md

@@ -1,10 +1,10 @@
-## 0.8.0 (2024-10-30)
+## 0.8.0 (unreleased)
 
 - Added support for iterative index scans
 - Added casts for arrays to `sparsevec`
-- Improved cost estimation for better index selection when filtering
-- Improved performance of HNSW index scans
+- Improved cost estimation
 - Improved performance of HNSW inserts and on-disk index builds
+- Reduced memory usage for HNSW index scans
 - Dropped support for Postgres 12
 
 ## 0.7.4 (2024-08-05)

META.json

@@ -2,7 +2,7 @@
 	"name": "vector",
 	"abstract": "Open-source vector similarity search for Postgres",
 	"description": "Supports L2 distance, inner product, and cosine distance",
-	"version": "0.8.0",
+	"version": "0.7.4",
 	"maintainer": [
 		"Andrew Kane <andrew@ankane.org>"
 	],
@@ -12,7 +12,7 @@
 	"prereqs": {
 		"runtime": {
 			"requires": {
-				"PostgreSQL": "13.0.0"
+				"PostgreSQL": "12.0.0"
 			}
 		}
 	},
@@ -20,7 +20,7 @@
 		"vector": {
 			"file": "sql/vector.sql",
 			"docfile": "README.md",
-			"version": "0.8.0",
+			"version": "0.7.4",
 			"abstract": "Open-source vector similarity search for Postgres"
 		}
 	},

Makefile

@@ -1,5 +1,5 @@
 EXTENSION = vector
-EXTVERSION = 0.8.0
+EXTVERSION = 0.7.4
 
 MODULE_big = vector
 DATA = $(wildcard sql/*--*--*.sql)

Makefile.win

@@ -1,5 +1,5 @@
 EXTENSION = vector
-EXTVERSION = 0.8.0
+EXTVERSION = 0.7.4
 
 DATA_built = sql\$(EXTENSION)--$(EXTVERSION).sql
 OBJS = src\bitutils.obj src\bitvec.obj src\halfutils.obj src\halfvec.obj src\hnsw.obj src\hnswbuild.obj src\hnswinsert.obj src\hnswscan.obj src\hnswutils.obj src\hnswvacuum.obj src\ivfbuild.obj src\ivfflat.obj src\ivfinsert.obj src\ivfkmeans.obj src\ivfscan.obj src\ivfutils.obj src\ivfvacuum.obj src\sparsevec.obj src\vector.obj

README.md

@@ -17,11 +17,11 @@ Plus [ACID](https://en.wikipedia.org/wiki/ACID) compliance, point-in-time recove
 
 ### Linux and Mac
 
-Compile and install the extension (supports Postgres 13+)
+Compile and install the extension (supports Postgres 12+)
 
 ```sh
 cd /tmp
-git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git
+git clone --branch v0.7.4 https://github.com/pgvector/pgvector.git
 cd pgvector
 make
 make install # may need sudo
@@ -46,7 +46,7 @@ Then use `nmake` to build:
 ```cmd
 set "PGROOT=C:\Program Files\PostgreSQL\16"
 cd %TEMP%
-git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git
+git clone --branch v0.7.4 https://github.com/pgvector/pgvector.git
 cd pgvector
 nmake /F Makefile.win
 nmake /F Makefile.win install
@@ -324,7 +324,7 @@ For a large number of workers, you may also need to increase `max_parallel_worke
 
 ### Indexing Progress
 
-Check [indexing progress](https://www.postgresql.org/docs/current/progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING)
+Check [indexing progress](https://www.postgresql.org/docs/current/progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING) with Postgres 12+
 
 ```sql
 SELECT phase, round(100.0 * blocks_done / nullif(blocks_total, 0), 1) AS "%" FROM pg_stat_progress_create_index;
@@ -410,7 +410,7 @@ For a large number of workers, you may also need to increase `max_parallel_worke
 
 ### Indexing Progress
 
-Check [indexing progress](https://www.postgresql.org/docs/current/progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING)
+Check [indexing progress](https://www.postgresql.org/docs/current/progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING) with Postgres 12+
 
 ```sql
 SELECT phase, round(100.0 * tuples_done / nullif(tuples_total, 0), 1) AS "%" FROM pg_stat_progress_create_index;
@@ -427,49 +427,25 @@ Note: `%` is only populated during the `loading tuples` phase
 
 ## Filtering
 
-There are a few ways to index nearest neighbor queries with a `WHERE` clause.
+There are a few ways to index nearest neighbor queries with a `WHERE` clause
 
 ```sql
 SELECT * FROM items WHERE category_id = 123 ORDER BY embedding <-> '[3,1,2]' LIMIT 5;
 ```
 
-A good place to start is creating an index on the filter column. This can provide fast, exact nearest neighbor search in many cases. Postgres has a number of [index types](https://www.postgresql.org/docs/current/indexes-types.html) for this: B-tree (default), hash, GiST, SP-GiST, GIN, and BRIN.
+Create an index on one [or more](https://www.postgresql.org/docs/current/indexes-multicolumn.html) of the `WHERE` columns for exact search
 
 ```sql
 CREATE INDEX ON items (category_id);
 ```
 
-For multiple columns, consider a [multicolumn index](https://www.postgresql.org/docs/current/indexes-multicolumn.html).
-
-```sql
-CREATE INDEX ON items (location_id, category_id);
-```
-
-Exact indexes work well for conditions that match a low percentage of rows. Otherwise, [approximate indexes](#indexing) can work better.
-
-```sql
-CREATE INDEX ON items USING hnsw (embedding vector_l2_ops);
-```
-
-With approximate indexes, filtering is applied *after* the index is scanned. If a condition matches 10% of rows, with HNSW and the default `hnsw.ef_search` of 40, only 4 rows will match on average. For more rows, increase `hnsw.ef_search`.
-
-```sql
-SET hnsw.ef_search = 200;
-```
-
-Starting with 0.8.0, you can enable [iterative index scans](#iterative-index-scans), which will automatically scan more of the index when needed.
-
-```sql
-SET hnsw.iterative_scan = strict_order;
-```
-
-If filtering by only a few distinct values, consider [partial indexing](https://www.postgresql.org/docs/current/indexes-partial.html).
+Or a [partial index](https://www.postgresql.org/docs/current/indexes-partial.html) on the vector column for approximate search
 
 ```sql
 CREATE INDEX ON items USING hnsw (embedding vector_l2_ops) WHERE (category_id = 123);
 ```
 
-If filtering by many different values, consider [partitioning](https://www.postgresql.org/docs/current/ddl-partitioning.html).
+Use [partitioning](https://www.postgresql.org/docs/current/ddl-partitioning.html) for approximate search on many different values of the `WHERE` columns
 
 ```sql
 CREATE TABLE items (embedding vector(3), category_id int) PARTITION BY LIST(category_id);
@@ -477,11 +453,11 @@ CREATE TABLE items (embedding vector(3), category_id int) PARTITION BY LIST(cate
 
 ## Iterative Index Scans
 
-*Added in 0.8.0*
+*Unreleased*
 
-With approximate indexes, queries with filtering can return less results since filtering is applied *after* the index is scanned. Starting with 0.8.0, you can enable iterative index scans, which will automatically scan more of the index until enough results are found (or it reaches `hnsw.max_scan_tuples` or `ivfflat.max_probes`).
+With approximate indexes, queries with filtering can return less results (due to post-filtering). Starting with 0.8.0, you can enable iterative index scans. If too few results from the initial scan match the filters, the scan will resume until enough results are found (or it reaches `hnsw.max_scan_tuples` or `ivfflat.max_probes`). This can significantly improve recall.
 
-Iterative scans can use strict or relaxed ordering.
+There are two modes for iterative scans: strict and relaxed.
 
 Strict ensures results are in the exact order by distance
 
@@ -517,7 +493,7 @@ Note: Place any other filters inside the CTE
 
 ### Iterative Scan Options
 
-Since scanning a large portion of an approximate index is expensive, there are options to control when a scan ends.
+Since scanning a large portion of an approximate index is expensive, there are options to control when a scan ends
 
 #### HNSW
 
@@ -535,7 +511,18 @@ Specify the max amount of memory to use, as a multiple of `work_mem` (1 by defau
 SET hnsw.scan_mem_multiplier = 2;
 ```
 
-Note: Try increasing this if increasing `hnsw.max_scan_tuples` does not improve recall
+You can see when increasing this is needed by enabling debug messages
+
+```sql
+SET client_min_messages = debug1;
+```
+
+which will show when a scan reaches the memory limit
+
+```text
+DEBUG:  hnsw index scan reached memory limit after 20000 tuples
+HINT:  Increase hnsw.scan_mem_multiplier to scan more tuples.
+```
 
 #### IVFFlat
 
@@ -1153,7 +1140,7 @@ This adds pgvector to the [Postgres image](https://hub.docker.com/_/postgres) (r
 You can also build the image manually:
 
 ```sh
-git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git
+git clone --branch v0.7.4 https://github.com/pgvector/pgvector.git
 cd pgvector
 docker build --pull --build-arg PG_MAJOR=17 -t myuser/pgvector .
 ```

src/hnsw.c

@@ -77,21 +77,21 @@ HnswInit(void)
 
 	DefineCustomIntVariable("hnsw.ef_search", "Sets the size of the dynamic candidate list for search",
 							"Valid range is 1..1000.", &hnsw_ef_search,
-							HNSW_DEFAULT_EF_SEARCH, HNSW_MIN_EF_SEARCH, HNSW_MAX_EF_SEARCH, PGC_USERSET, 0, NULL, NULL, NULL);
+							HNSW_DEFAULT_EF_SEARCH, HNSW_MIN_EF_SEARCH, HNSW_MAX_EF_SEARCH, PGC_USERSET, GUC_EXPLAIN, NULL, NULL, NULL);
 
 	DefineCustomEnumVariable("hnsw.iterative_scan", "Sets the mode for iterative scans",
 							 NULL, &hnsw_iterative_scan,
-							 HNSW_ITERATIVE_SCAN_OFF, hnsw_iterative_scan_options, PGC_USERSET, 0, NULL, NULL, NULL);
+							 HNSW_ITERATIVE_SCAN_OFF, hnsw_iterative_scan_options, PGC_USERSET, GUC_EXPLAIN, NULL, NULL, NULL);
 
 	/* This is approximate and does not affect the initial scan */
 	DefineCustomIntVariable("hnsw.max_scan_tuples", "Sets the max number of tuples to visit for iterative scans",
 							NULL, &hnsw_max_scan_tuples,
-							20000, 1, INT_MAX, PGC_USERSET, 0, NULL, NULL, NULL);
+							20000, 1, INT_MAX, PGC_USERSET, GUC_EXPLAIN, NULL, NULL, NULL);
 
 	/* Same range as hash_mem_multiplier */
 	DefineCustomRealVariable("hnsw.scan_mem_multiplier", "Sets the multiple of work_mem to use for iterative scans",
 							 NULL, &hnsw_scan_mem_multiplier,
-							 1, 1, 1000, PGC_USERSET, 0, NULL, NULL, NULL);
+							 1, 1, 1000, PGC_USERSET, GUC_EXPLAIN, NULL, NULL, NULL);
 
 	MarkGUCPrefixReserved("hnsw");
 }

src/hnswscan.c

@@ -240,8 +240,8 @@ hnswgettuple(IndexScanDesc scan, ScanDirection dir)
 			if (so->discarded == NULL)
 				break;
 
-			/* Reached max number of tuples or memory limit */
-			if (so->tuples >= hnsw_max_scan_tuples || MemoryContextMemAllocated(so->tmpCtx, false) > so->maxMemory)
+			/* Reached max number of tuples */
+			if (so->tuples >= hnsw_max_scan_tuples)
 			{
 				if (pairingheap_is_empty(so->discarded))
 					break;
@@ -249,6 +249,21 @@ hnswgettuple(IndexScanDesc scan, ScanDirection dir)
 				/* Return remaining tuples */
 				so->w = lappend(so->w, HnswGetSearchCandidate(w_node, pairingheap_remove_first(so->discarded)));
 			}
+			/* Prevent scans from consuming too much memory */
+			else if (MemoryContextMemAllocated(so->tmpCtx, false) > so->maxMemory)
+			{
+				if (pairingheap_is_empty(so->discarded))
+				{
+					ereport(DEBUG1,
+							(errmsg("hnsw index scan reached memory limit after " INT64_FORMAT " tuples", so->tuples),
+							 errhint("Increase hnsw.scan_mem_multiplier to scan more tuples.")));
+
+					break;
+				}
+
+				/* Return remaining tuples */
+				so->w = lappend(so->w, HnswGetSearchCandidate(w_node, pairingheap_remove_first(so->discarded)));
+			}
 			else
 			{
 				/*

src/ivfflat.c

@@ -39,16 +39,16 @@ IvfflatInit(void)
 
 	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);
+							IVFFLAT_DEFAULT_PROBES, IVFFLAT_MIN_LISTS, IVFFLAT_MAX_LISTS, PGC_USERSET, GUC_EXPLAIN, NULL, NULL, NULL);
 
 	DefineCustomEnumVariable("ivfflat.iterative_scan", "Sets the mode for iterative scans",
 							 NULL, &ivfflat_iterative_scan,
-							 IVFFLAT_ITERATIVE_SCAN_OFF, ivfflat_iterative_scan_options, PGC_USERSET, 0, NULL, NULL, NULL);
+							 IVFFLAT_ITERATIVE_SCAN_OFF, ivfflat_iterative_scan_options, PGC_USERSET, GUC_EXPLAIN, NULL, NULL, NULL);
 
 	/* If this is less than probes, probes is used */
 	DefineCustomIntVariable("ivfflat.max_probes", "Sets the max number of probes for iterative scans",
 							NULL, &ivfflat_max_probes,
-							IVFFLAT_MAX_LISTS, IVFFLAT_MIN_LISTS, IVFFLAT_MAX_LISTS, PGC_USERSET, 0, NULL, NULL, NULL);
+							IVFFLAT_MAX_LISTS, IVFFLAT_MIN_LISTS, IVFFLAT_MAX_LISTS, PGC_USERSET, GUC_EXPLAIN, NULL, NULL, NULL);
 
 	MarkGUCPrefixReserved("ivfflat");
 }

src/ivfscan.c

@@ -114,6 +114,7 @@ GetScanItems(IndexScanDesc scan, Datum value)
 {
 	IvfflatScanOpaque so = (IvfflatScanOpaque) scan->opaque;
 	TupleDesc	tupdesc = RelationGetDescr(scan->indexRelation);
+	double		tuples = 0;
 	TupleTableSlot *slot = so->vslot;
 	int			batchProbes = 0;
 
@@ -160,6 +161,8 @@ GetScanItems(IndexScanDesc scan, Datum value)
 				ExecStoreVirtualTuple(slot);
 
 				tuplesort_puttupleslot(so->sortstate, slot);
+
+				tuples++;
 			}
 
 			searchPage = IvfflatPageGetOpaque(page)->nextblkno;
@@ -168,6 +171,12 @@ GetScanItems(IndexScanDesc scan, Datum value)
 		}
 	}
 
+	if (tuples < 100 && ivfflat_iterative_scan == IVFFLAT_ITERATIVE_SCAN_OFF)
+		ereport(DEBUG1,
+				(errmsg("index scan found few tuples"),
+				 errdetail("Index may have been created with little data."),
+				 errhint("Recreate the index and possibly decrease lists.")));
+
 	tuplesort_performsort(so->sortstate);
 
 #if defined(IVFFLAT_MEMORY)

src/sparsevec.c

@@ -4,7 +4,6 @@
 #include <math.h>
 
 #include "catalog/pg_type.h"
-#include "common/shortest_dec.h"
 #include "common/string.h"
 #include "fmgr.h"
 #include "halfutils.h"
@@ -13,10 +12,17 @@
 #include "sparsevec.h"
 #include "utils/array.h"
 #include "utils/builtins.h"
-#include "utils/float.h"
 #include "utils/lsyscache.h"
 #include "vector.h"
 
+#if PG_VERSION_NUM >= 120000
+#include "common/shortest_dec.h"
+#include "utils/float.h"
+#else
+#include <float.h>
+#include "utils/builtins.h"
+#endif
+
 typedef struct SparseInputElement
 {
 	int32		index;

test/expected/hnsw_vector.out

@@ -190,6 +190,4 @@ SHOW hnsw.scan_mem_multiplier;
 
 SET hnsw.scan_mem_multiplier = 0;
 ERROR:  0 is outside the valid range for parameter "hnsw.scan_mem_multiplier" (1 .. 1000)
-SET hnsw.scan_mem_multiplier = 1001;
-ERROR:  1001 is outside the valid range for parameter "hnsw.scan_mem_multiplier" (1 .. 1000)
 DROP TABLE t;

test/sql/hnsw_vector.sql

@@ -109,6 +109,5 @@ SET hnsw.max_scan_tuples = 0;
 SHOW hnsw.scan_mem_multiplier;
 
 SET hnsw.scan_mem_multiplier = 0;
-SET hnsw.scan_mem_multiplier = 1001;
 
 DROP TABLE t;

test/t/043_hnsw_iterative_scan.pl

@@ -56,4 +56,13 @@ foreach ((30000, 50000, 70000))
 	cmp_ok($avg, '<', $expected + 2);
 }
 
+my ($ret, $stdout, $stderr) = $node->psql("postgres", qq(
+	SET enable_seqscan = off;
+	SET hnsw.iterative_scan = relaxed_order;
+	SET client_min_messages = debug1;
+	SET work_mem = '1MB';
+	SELECT COUNT(*) FROM (SELECT v FROM tst WHERE i % 10000 = 0 ORDER BY v <-> (SELECT v FROM tst LIMIT 1) LIMIT 11) t;
+));
+like($stderr, qr/hnsw index scan reached memory limit after \d+ tuples/);
+
 done_testing();

vector.control

@@ -1,4 +1,4 @@
 comment = 'vector data type and ivfflat and hnsw access methods'
-default_version = '0.8.0'
+default_version = '0.7.4'
 module_pathname = '$libdir/vector'
 relocatable = true