Version bump to 0.4.1 [skip ci]

.gitignore

@@ -1,4 +1,5 @@
 /dist/
+/log/
 /results/
 /tmp_check/
 /sql/vector--?.?.?.sql
@@ -7,6 +8,7 @@ regression.*
 *.so
 *.bc
 *.dll
+*.dylib
 *.obj
 *.lib
 *.exp

CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.4.1 (2023-03-21)
+
+- Improved performance of cosine distance
+- Fixed index scan count
+
 ## 0.4.0 (2023-01-11)
 
 If upgrading with Postgres < 13, see [this note](https://github.com/pgvector/pgvector#040).

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

Makefile

@@ -1,5 +1,5 @@
 EXTENSION = vector
-EXTVERSION = 0.4.0
+EXTVERSION = 0.4.1
 
 MODULE_big = vector
 DATA = $(wildcard sql/*--*.sql)
@@ -61,4 +61,4 @@ dist:
 .PHONY: docker
 
 docker:
-	docker build --pull --no-cache -t ankane/pgvector:latest .
+	docker build --pull --no-cache --platform linux/amd64 -t ankane/pgvector:latest .

Makefile.win

@@ -1,5 +1,5 @@
 EXTENSION = vector
-EXTVERSION = 0.4.0
+EXTVERSION = 0.4.1
 
 OBJS = src\ivfbuild.obj src\ivfflat.obj src\ivfinsert.obj src\ivfkmeans.obj src\ivfscan.obj src\ivfutils.obj src\ivfvacuum.obj src\vector.obj
 

README.md

@@ -17,7 +17,7 @@ Supports L2 distance, inner product, and cosine distance
 Compile and install the extension (supports Postgres 11+)
 
 ```sh
-git clone --branch v0.4.0 https://github.com/pgvector/pgvector.git
+git clone --branch v0.4.1 https://github.com/pgvector/pgvector.git
 cd pgvector
 make
 make install # may need sudo
@@ -55,6 +55,28 @@ Also supports inner product (`<#>`) and cosine distance (`<=>`)
 
 Note: `<#>` returns the negative inner product since Postgres only supports `ASC` order index scans on operators
 
+## Querying
+
+Use a `SELECT` clause to get the distance
+
+```sql
+SELECT embedding <-> '[3,1,2]' AS distance FROM items;
+```
+
+Use a `WHERE` clause to get rows within a certain distance
+
+```sql
+SELECT * FROM items WHERE embedding <-> '[3,1,2]' < 5;
+```
+
+Note: Combine with `ORDER BY` and `LIMIT` to use an index
+
+Get the average of vectors
+
+```sql
+SELECT AVG(embedding) FROM items;
+```
+
 ## Indexing
 
 Speed up queries with an approximate index. Add an index for each distance function you want to use.
@@ -97,7 +119,7 @@ Specify the number of probes (1 by default)
 SET ivfflat.probes = 1;
 ```
 
-A higher value improves recall at the cost of speed.
+A higher value improves 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)
 
 Use `SET LOCAL` inside a transaction to set it for a single query
 
@@ -159,6 +181,49 @@ To speed up queries with an index, increase the number of inverted lists (at the
 CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 1000);
 ```
 
+Use `EXPLAIN ANALYZE` to debug performance.
+
+```sql
+EXPLAIN ANALYZE SELECT * FROM items ORDER BY embedding <-> '[3,1,2]' LIMIT 1;
+```
+
+## Languages
+
+Use pgvector from any language with a Postgres client. You can even generate and store vectors in one language and query them in another.
+
+Language | Libraries / Examples
+--- | ---
+C++ | [pgvector-cpp](https://github.com/pgvector/pgvector-cpp)
+C# | [pgvector-dotnet](https://github.com/pgvector/pgvector-dotnet)
+Elixir | [pgvector-elixir](https://github.com/pgvector/pgvector-elixir)
+Go | [pgvector-go](https://github.com/pgvector/pgvector-go)
+Java, Scala | [pgvector-java](https://github.com/pgvector/pgvector-java)
+Julia | [pgvector-julia](https://github.com/pgvector/pgvector-julia)
+Lua | [pgvector-lua](https://github.com/pgvector/pgvector-lua)
+Node.js | [pgvector-node](https://github.com/pgvector/pgvector-node)
+PHP | [pgvector-php](https://github.com/pgvector/pgvector-php)
+Python | [pgvector-python](https://github.com/pgvector/pgvector-python)
+R | [pgvector-r](https://github.com/pgvector/pgvector-r)
+Ruby | [pgvector-ruby](https://github.com/pgvector/pgvector-ruby), [Neighbor](https://github.com/ankane/neighbor)
+Rust | [pgvector-rust](https://github.com/pgvector/pgvector-rust)
+
+## Frequently Asked Questions
+
+#### How many vectors can be stored in a single table?
+
+A non-partitioned table has a limit of 32 TB by default in Postgres. A partitioned table can have thousands of partitions of that size.
+
+#### Is replication supported?
+
+Yes, pgvector uses the write-ahead log (WAL), which allows for replication and point-in-time recovery.
+
+#### What if I want to index vectors with more than 2,000 dimensions?
+
+Two things you can try are:
+
+1. use dimensionality reduction
+2. compile Postgres with a larger block size (`./configure --with-blocksize=32`) and edit the limit in `src/ivfflat.h`
+
 ## Reference
 
 ### Vector Type
@@ -191,36 +256,6 @@ Function | Description
 --- | ---
 avg(vector) → vector | arithmetic mean
 
-## Libraries
-
-Language | Libraries
---- | ---
-Python | [pgvector-python](https://github.com/pgvector/pgvector-python)
-Ruby | [Neighbor](https://github.com/ankane/neighbor), [pgvector-ruby](https://github.com/pgvector/pgvector-ruby)
-Node | [pgvector-node](https://github.com/pgvector/pgvector-node)
-Go | [pgvector-go](https://github.com/pgvector/pgvector-go)
-PHP | [pgvector-php](https://github.com/pgvector/pgvector-php)
-Rust | [pgvector-rust](https://github.com/pgvector/pgvector-rust)
-C++ | [pgvector-cpp](https://github.com/pgvector/pgvector-cpp)
-Elixir | [pgvector-elixir](https://github.com/pgvector/pgvector-elixir)
-
-## Frequently Asked Questions
-
-#### How many vectors can be stored in a single table?
-
-A non-partitioned table has a limit of 32 TB by default in Postgres. A partitioned table can have thousands of partitions of that size.
-
-#### Is replication supported?
-
-Yes, pgvector uses the write-ahead log (WAL), which allows for replication and point-in-time recovery.
-
-#### What if I want to index vectors with more than 2,000 dimensions?
-
-Two things you can try are:
-
-1. use dimensionality reduction
-2. compile Postgres with a larger block size (`./configure --with-blocksize=32`) and edit the limit in `src/ivfflat.h`
-
 ## Additional Installation Methods
 
 ### Docker
@@ -231,12 +266,12 @@ Get the [Docker image](https://hub.docker.com/r/ankane/pgvector) with:
 docker pull ankane/pgvector
 ```
 
-This adds pgvector to the [Postgres image](https://hub.docker.com/_/postgres).
+This adds pgvector to the [Postgres image](https://hub.docker.com/_/postgres) (run it the same way).
 
-You can also build the image manually
+You can also build the image manually:
 
 ```sh
-git clone --branch v0.4.0 https://github.com/pgvector/pgvector.git
+git clone --branch v0.4.1 https://github.com/pgvector/pgvector.git
 cd pgvector
 docker build -t pgvector .
 ```
@@ -259,7 +294,7 @@ pgxn install vector
 
 ### conda-forge
 
-Install from [conda-forge](https://anaconda.org/conda-forge/pgvector) with:
+With Conda Postgres, install from [conda-forge](https://anaconda.org/conda-forge/pgvector) with:
 
 ```sh
 conda install -c conda-forge pgvector
@@ -269,12 +304,14 @@ This method is [community-maintained](https://github.com/conda-forge/pgvector-fe
 
 ## Hosted Postgres
 
-Some Postgres providers only support specific extensions. To request a new extension:
+pgvector is available on [these providers](https://github.com/pgvector/pgvector/issues/54).
+
+To request a new extension on other providers:
 
 - Amazon RDS - follow the instructions on [this page](https://aws.amazon.com/rds/postgresql/faqs/)
 - Google Cloud SQL - vote or comment on [this page](https://issuetracker.google.com/issues/265172065)
 - DigitalOcean Managed Databases - vote or comment on [this page](https://ideas.digitalocean.com/app-framework-services/p/pgvector-extension-for-postgresql)
-- Azure Database for PostgreSQL - vote or comment on [this page](https://feedback.azure.com/d365community/idea/7b423322-6189-ed11-a81b-000d3ae49307)
+- Azure Database - vote or comment on [this page](https://feedback.azure.com/d365community/idea/7b423322-6189-ed11-a81b-000d3ae49307)
 
 ## Upgrading
 

sql/vector--0.4.0--0.4.1.sql

@@ -0,0 +1,2 @@
+-- complain if script is sourced in psql, rather than via CREATE EXTENSION
+\echo Use "ALTER EXTENSION vector UPDATE TO '0.4.1'" to load this file. \quit

src/ivfscan.c

@@ -5,6 +5,7 @@
 #include "access/relscan.h"
 #include "ivfflat.h"
 #include "miscadmin.h"
+#include "pgstat.h"
 #include "storage/bufmgr.h"
 
 #include "catalog/pg_operator_d.h"
@@ -267,6 +268,9 @@ ivfflatgettuple(IndexScanDesc scan, ScanDirection dir)
 	{
 		Datum		value;
 
+		/* Count index scan for stats */
+		pgstat_count_index_scan(scan->indexRelation);
+
 		/* Safety check */
 		if (scan->orderByData == NULL)
 			elog(ERROR, "cannot scan ivfflat index without order");

src/ivfvacuum.c

@@ -143,6 +143,11 @@ ivfflatvacuumcleanup(IndexVacuumInfo *info, IndexBulkDeleteResult *stats)
 {
 	Relation	rel = info->index;
 
+	if (info->analyze_only)
+		return stats;
+
+	/* stats is NULL if ambulkdelete not called */
+	/* OK to return NULL if index not changed */
 	if (stats == NULL)
 		return NULL;
 

src/vector.c

@@ -416,7 +416,7 @@ array_to_vector(PG_FUNCTION_ARGS)
 		else if (ARR_ELEMTYPE(array) == FLOAT4OID)
 			result->x[i] = DatumGetFloat4(elemsp[i]);
 		else if (ARR_ELEMTYPE(array) == NUMERICOID)
-			result->x[i] = DatumGetFloat4(DirectFunctionCall1(numeric_float4, NumericGetDatum(elemsp[i])));
+			result->x[i] = DatumGetFloat4(DirectFunctionCall1(numeric_float4, elemsp[i]));
 		else
 			ereport(ERROR,
 					(errcode(ERRCODE_DATA_EXCEPTION),
@@ -568,7 +568,8 @@ cosine_distance(PG_FUNCTION_ARGS)
 		normb += bx[i] * bx[i];
 	}
 
-	PG_RETURN_FLOAT8(1 - (distance / (sqrt(norma) * sqrt(normb))));
+	/* Use sqrt(a * b) over sqrt(a) * sqrt(b) */
+	PG_RETURN_FLOAT8(1 - (distance / sqrt(norma * normb)));
 }
 
 /*
@@ -822,7 +823,7 @@ vector_accum(PG_FUNCTION_ARGS)
 	if (newarr)
 	{
 		for (int i = 0; i < dim; i++)
-			statedatums[i + 1] = Float8GetDatumFast(x[i]);
+			statedatums[i + 1] = Float8GetDatumFast((double) x[i]);
 	}
 	else
 	{

src/vector.h

@@ -3,6 +3,10 @@
 
 #include "postgres.h"
 
+#if PG_VERSION_NUM >= 160000
+#include "varatt.h"
+#endif
+
 #define VECTOR_MAX_DIM 16000
 
 #define VECTOR_SIZE(_dim)		(offsetof(Vector, x) + sizeof(float)*(_dim))

test/expected/cast.out

@@ -22,6 +22,12 @@ SELECT ARRAY[1,2,3]::float8[]::vector;
  [1,2,3]
 (1 row)
 
+SELECT ARRAY[1,2,3]::numeric[]::vector;
+  array  
+---------
+ [1,2,3]
+(1 row)
+
 SELECT '{NULL}'::real[]::vector;
 ERROR:  array must not containing NULLs
 SELECT '{NaN}'::real[]::vector;

test/expected/functions.out

@@ -50,6 +50,18 @@ SELECT cosine_distance('[1,2]', '[0,0]');
              NaN
 (1 row)
 
+SELECT cosine_distance('[1,1]', '[1,1]');
+ cosine_distance 
+-----------------
+               0
+(1 row)
+
+SELECT cosine_distance('[1,1]', '[-1,-1]');
+ cosine_distance 
+-----------------
+               2
+(1 row)
+
 SELECT cosine_distance('[1,2]', '[3]');
 ERROR:  different vector dimensions 2 and 1
 SELECT avg(v) FROM unnest(ARRAY['[1,2,3]'::vector, '[3,5,7]']) v;

test/sql/cast.sql

@@ -2,6 +2,7 @@ SELECT ARRAY[1,2,3]::vector;
 SELECT ARRAY[1.0,2.0,3.0]::vector;
 SELECT ARRAY[1,2,3]::float4[]::vector;
 SELECT ARRAY[1,2,3]::float8[]::vector;
+SELECT ARRAY[1,2,3]::numeric[]::vector;
 SELECT '{NULL}'::real[]::vector;
 SELECT '{NaN}'::real[]::vector;
 SELECT '{Infinity}'::real[]::vector;

test/sql/functions.sql

@@ -12,6 +12,8 @@ SELECT inner_product('[1,2]', '[3]');
 
 SELECT round(cosine_distance('[1,2]', '[2,4]')::numeric, 5);
 SELECT cosine_distance('[1,2]', '[0,0]');
+SELECT cosine_distance('[1,1]', '[1,1]');
+SELECT cosine_distance('[1,1]', '[-1,-1]');
 SELECT cosine_distance('[1,2]', '[3]');
 
 SELECT avg(v) FROM unnest(ARRAY['[1,2,3]'::vector, '[3,5,7]']) v;

test/t/007_inserts.pl

@@ -2,7 +2,7 @@ use strict;
 use warnings;
 use PostgresNode;
 use TestLib;
-use Test::More tests => 5;
+use Test::More tests => 7;
 
 my $dim = 768;
 
@@ -32,10 +32,19 @@ $node->pgbench(
 	}
 );
 
+sub idx_scan
+{
+	# Stats do not update instantaneously
+	# https://www.postgresql.org/docs/current/monitoring-stats.html#MONITORING-STATS-VIEWS
+	sleep(1);
+	$node->safe_psql("postgres", "SELECT idx_scan FROM pg_stat_user_indexes WHERE indexrelid = 'tst_v_idx'::regclass;");
+}
+
 my $expected = 10000 + 5 * 100 * 10;
 
 my $count = $node->safe_psql("postgres", "SELECT COUNT(*) FROM tst;");
 is($count, $expected);
+is(idx_scan(), 0);
 
 $count = $node->safe_psql("postgres", qq(
 	SET enable_seqscan = off;
@@ -43,3 +52,4 @@ $count = $node->safe_psql("postgres", qq(
 	SELECT COUNT(*) FROM (SELECT v FROM tst ORDER BY v <-> (SELECT v FROM tst LIMIT 1)) t;
 ));
 is($count, $expected);
+is(idx_scan(), 1);

vector.control

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