Version bump to 0.5.0 [skip ci]

CHANGELOG.md

@@ -1,4 +1,4 @@
-## 0.5.0 (unreleased)
+## 0.5.0 (2023-08-28)
 
 - Added HNSW index type
 - Added support for parallel index builds

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.4.4",
+	"version": "0.5.0",
 	"maintainer": [
 		"Andrew Kane <andrew@ankane.org>"
 	],
@@ -20,7 +20,7 @@
 		"vector": {
 			"file": "sql/vector.sql",
 			"docfile": "README.md",
-			"version": "0.4.4",
+			"version": "0.5.0",
 			"abstract": "Open-source vector similarity search for Postgres"
 		}
 	},

Makefile

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

Makefile.win

@@ -1,5 +1,5 @@
 EXTENSION = vector
-EXTVERSION = 0.4.4
+EXTVERSION = 0.5.0
 
 OBJS = 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\vector.obj
 HEADERS = src\vector.h

README.md

@@ -18,7 +18,7 @@ Compile and install the extension (supports Postgres 11+)
 
 ```sh
 cd /tmp
-git clone --branch v0.4.4 https://github.com/pgvector/pgvector.git
+git clone --branch v0.5.0 https://github.com/pgvector/pgvector.git
 cd pgvector
 make
 make install # may need sudo
@@ -157,7 +157,16 @@ SELECT category_id, AVG(embedding) FROM items GROUP BY category_id;
 
 By default, pgvector performs exact nearest neighbor search, which provides perfect recall.
 
-You can add an index to use approximate nearest neighbor search, which trades some recall for performance. Unlike typical indexes, you will see different results for queries after adding an approximate index.
+You can add an index to use approximate nearest neighbor search, which trades some recall for speed. Unlike typical indexes, you will see different results for queries after adding an approximate index.
+
+Supported index types are:
+
+- [IVFFlat](#ivfflat)
+- [HNSW](#hnsw) - *added in 0.5.0*
+
+## IVFFlat
+
+An IVFFlat index divides vectors into lists, and then searches a subset of those lists that are closest to the query vector. It has faster build times and uses less memory than HNSW, but has lower query performance (in terms of speed-recall tradeoff).
 
 Three keys to achieving good recall are:
 
@@ -206,7 +215,63 @@ SELECT ...
 COMMIT;
 ```
 
-### Indexing Progress
+## HNSW
+
+An HNSW index creates a multilayer graph. It has slower build times and uses more memory than IVFFlat, but has better query performance (in terms of speed-recall tradeoff). There’s no training step like IVFFlat, so the index can be created without any data in the table.
+
+Add an index for each distance function you want to use.
+
+L2 distance
+
+```sql
+CREATE INDEX ON items USING hnsw (embedding vector_l2_ops);
+```
+
+Inner product
+
+```sql
+CREATE INDEX ON items USING hnsw (embedding vector_ip_ops);
+```
+
+Cosine distance
+
+```sql
+CREATE INDEX ON items USING hnsw (embedding vector_cosine_ops);
+```
+
+Vectors with up to 2,000 dimensions can be indexed.
+
+### Index Options
+
+Specify HNSW parameters
+
+- `m` - the max number of connections per layer (16 by default)
+- `ef_construction` - the size of the dynamic candidate list for constructing the graph (64 by default)
+
+```sql
+CREATE INDEX ON items USING hnsw (embedding vector_l2_ops) WITH (m = 16, ef_construction = 64);
+```
+
+### Query Options
+
+Specify the size of the dynamic candidate list for search (40 by default)
+
+```sql
+SET hnsw.ef_search = 100;
+```
+
+A higher value provides better recall at the cost of speed.
+
+Use `SET LOCAL` inside a transaction to set it for a single query
+
+```sql
+BEGIN;
+SET LOCAL hnsw.ef_search = 100;
+SELECT ...
+COMMIT;
+```
+
+## Indexing Progress
 
 Check [indexing progress](https://www.postgresql.org/docs/current/progress-reporting.html#CREATE-INDEX-PROGRESS-REPORTING) with Postgres 12+
 
@@ -217,8 +282,8 @@ SELECT phase, tuples_done, tuples_total FROM pg_stat_progress_create_index;
 The phases are:
 
 1. `initializing`
-2. `performing k-means`
-3. `sorting tuples`
+2. `performing k-means` (IVFFlat only)
+3. `assigning tuples` (IVFFlat only)
 4. `loading tuples`
 
 Note: `tuples_done` and `tuples_total` are only populated during the `loading tuples` phase
@@ -283,7 +348,7 @@ SELECT * FROM items ORDER BY embedding <#> '[3,1,2]' LIMIT 5;
 
 ### Approximate Search
 
-To speed up queries with an index, increase the number of inverted lists (at the expense of recall).
+To speed up queries with an IVFFlat index, increase the number of inverted lists (at the expense of recall).
 
 ```sql
 CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 1000);
@@ -359,7 +424,7 @@ or choose to store vectors inline:
 ALTER TABLE items ALTER COLUMN embedding SET STORAGE PLAIN;
 ```
 
-#### Why are there less results for a query after adding an index?
+#### Why are there less results for a query after adding an IVFFlat index?
 
 The index was likely created with too little data for the number of lists. Drop the index until the table has more data.
 
@@ -375,32 +440,32 @@ Each vector takes `4 * dimensions + 8` bytes of storage. Each element is a singl
 
 ### Vector Operators
 
-Operator | Description
---- | ---
-\+ | element-wise addition
-\- | element-wise subtraction
-\* | element-wise multiplication [unreleased]
-<-> | Euclidean distance
-<#> | negative inner product
-<=> | cosine distance
+Operator | Description | Added
+--- | --- | ---
+\+ | element-wise addition |
+\- | element-wise subtraction |
+\* | element-wise multiplication | 0.5.0
+<-> | Euclidean distance |
+<#> | negative inner product |
+<=> | cosine distance |
 
 ### Vector Functions
 
-Function | Description
---- | ---
-cosine_distance(vector, vector) → double precision | cosine distance
-inner_product(vector, vector) → double precision | inner product
-l2_distance(vector, vector) → double precision | Euclidean distance
-l1_distance(vector, vector) → double precision | taxicab distance [unreleased]
-vector_dims(vector) → integer | number of dimensions
-vector_norm(vector) → double precision | Euclidean norm
+Function | Description | Added
+--- | --- | ---
+cosine_distance(vector, vector) → double precision | cosine distance |
+inner_product(vector, vector) → double precision | inner product |
+l2_distance(vector, vector) → double precision | Euclidean distance |
+l1_distance(vector, vector) → double precision | taxicab distance | 0.5.0
+vector_dims(vector) → integer | number of dimensions |
+vector_norm(vector) → double precision | Euclidean norm |
 
 ### Aggregate Functions
 
-Function | Description
---- | ---
-avg(vector) → vector | arithmetic mean
-sum(vector) → vector | sum [unreleased]
+Function | Description | Added
+--- | --- | ---
+avg(vector) → vector | average |
+sum(vector) → vector | sum | 0.5.0
 
 ## Installation Notes
 
@@ -444,7 +509,7 @@ Then use `nmake` to build:
 
 ```cmd
 set "PGROOT=C:\Program Files\PostgreSQL\15"
-git clone --branch v0.4.4 https://github.com/pgvector/pgvector.git
+git clone --branch v0.5.0 https://github.com/pgvector/pgvector.git
 cd pgvector
 nmake /F Makefile.win
 nmake /F Makefile.win install
@@ -465,9 +530,8 @@ 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.4.4 https://github.com/pgvector/pgvector.git
+git clone --branch v0.5.0 https://github.com/pgvector/pgvector.git
 cd pgvector
-git cherry-pick 237a6df
 docker build --build-arg PG_MAJOR=15 -t myuser/pgvector .
 ```
 

src/hnsw.h

@@ -36,7 +36,7 @@
 #define HNSW_DEFAULT_M	16
 #define HNSW_MIN_M	2
 #define HNSW_MAX_M		100
-#define HNSW_DEFAULT_EF_CONSTRUCTION	40
+#define HNSW_DEFAULT_EF_CONSTRUCTION	64
 #define HNSW_MIN_EF_CONSTRUCTION	4
 #define HNSW_MAX_EF_CONSTRUCTION		1000
 #define HNSW_DEFAULT_EF_SEARCH	40

src/hnswutils.c

@@ -623,10 +623,6 @@ HnswSearchLayer(Datum q, List *ep, int ef, int lc, Relation index, FmgrInfo *pro
 
 				Assert(!e->element->deleted);
 
-				/* Skip self for vacuuming update */
-				if (skipElement != NULL && e->element->blkno == skipElement->blkno && e->element->offno == skipElement->offno)
-					continue;
-
 				/* Make robust to issues */
 				if (e->element->level < lc)
 					continue;
@@ -913,10 +909,10 @@ HnswUpdateConnection(HnswElement element, HnswCandidate * hc, int m, int lc, int
 }
 
 /*
- * Remove elements being deleted
+ * Remove elements being deleted or skipped
  */
 static List *
-RemoveElementsBeingDeleted(List *w)
+RemoveElements(List *w, HnswElement skipElement)
 {
 	ListCell   *lc2;
 	List	   *w2 = NIL;
@@ -925,6 +921,10 @@ RemoveElementsBeingDeleted(List *w)
 	{
 		HnswCandidate *hc = (HnswCandidate *) lfirst(lc2);
 
+		/* Skip self for vacuuming update */
+		if (skipElement != NULL && hc->element->blkno == skipElement->blkno && hc->element->offno == skipElement->offno)
+			continue;
+
 		if (list_length(hc->element->heaptids) != 0)
 			w2 = lappend(w2, hc);
 	}
@@ -963,20 +963,27 @@ HnswInsertElement(HnswElement element, HnswElement entryPoint, Relation index, F
 	if (level > entryLevel)
 		level = entryLevel;
 
+	/* Add one for existing element */
+	if (existing)
+		efConstruction++;
+
 	/* 2nd phase */
 	for (int lc = level; lc >= 0; lc--)
 	{
 		int			lm = HnswGetLayerM(m, lc);
 		List	   *neighbors;
+		List	   *lw;
 
 		w = HnswSearchLayer(q, ep, efConstruction, lc, index, procinfo, collation, true, skipElement);
 
-		/* Elements being deleted can help with search */
+		/* Elements being deleted or skipped can help with search */
 		/* but should be removed before selecting neighbors */
 		if (index != NULL)
-			w = RemoveElementsBeingDeleted(w);
+			lw = RemoveElements(w, skipElement);
+		else
+			lw = w;
 
-		neighbors = SelectNeighbors(w, lm, lc, procinfo, collation, NULL);
+		neighbors = SelectNeighbors(lw, lm, lc, procinfo, collation, NULL);
 
 		AddConnections(element, neighbors, lm, lc);
 

vector.control

@@ -1,4 +1,4 @@
 comment = 'vector data type and ivfflat access method'
-default_version = '0.4.4'
+default_version = '0.5.0'
 module_pathname = '$libdir/vector'
 relocatable = true