pgvector
Open-source vector similarity search for Postgres
CREATE TABLE table (column vector(3));
CREATE INDEX ON table USING ivfflat (column);
SELECT * FROM table ORDER BY column <-> '[1,2,3]' LIMIT 5;
Supports L2 distance, inner product, and cosine distance
Installation
Compile and install the extension (supports Postgres 9.6+)
git clone --branch v0.1.2 https://github.com/ankane/pgvector.git
cd pgvector
make
make install # may need sudo
Then load it in databases where you want to use it
CREATE EXTENSION vector;
Getting Started
Create a vector column with 3 dimensions (replace table
and column
with non-reserved names)
CREATE TABLE table (column vector(3));
Insert values
INSERT INTO table VALUES ('[1,2,3]'), ('[4,5,6]');
Get the nearest neighbor by L2 distance
SELECT * FROM table ORDER BY column <-> '[3,1,2]' LIMIT 1;
Also supports inner product (<#>
) and cosine distance (<=>
)
Note: <#>
returns the negative inner product since Postgres only supports ASC
order index scans on operators
Indexing
Speed up queries with an approximate index. Add an index for each distance function you want to use.
L2 distance
CREATE INDEX ON table USING ivfflat (column);
Inner product
CREATE INDEX ON table USING ivfflat (column vector_ip_ops);
Cosine distance
CREATE INDEX ON table USING ivfflat (column vector_cosine_ops);
Indexes should be created after the table has data for optimal clustering. Also, unlike typical indexes which only affect performance, you may see different results for queries after adding an approximate index.
Index Options
Specify the number of inverted lists (100 by default)
CREATE INDEX ON table USING ivfflat (column) WITH (lists = 100);
Query Options
Specify the number of probes (1 by default)
SET ivfflat.probes = 1;
A higher value improves recall at the cost of speed.
Use SET LOCAL
inside a transaction to set it for a single query
BEGIN;
SET LOCAL ivfflat.probes = 1;
SELECT ...
COMMIT;
Reference
Vector Type
Each vector takes 4 * dimensions + 8
bytes of storage. Each element is a float, and all elements must be finite (no NaN
, Infinity
or -Infinity
). Vectors can have up to 1024 dimensions.
Vector Operators
Operator | Description |
---|---|
+ | element-wise addition |
- | element-wise subtraction |
<-> | Euclidean distance |
<#> | negative inner product |
<=> | cosine distance |
Vector Functions
Function | Description |
---|---|
cosine_distance(vector, vector) | cosine distance |
inner_product(vector, vector) | inner product |
l2_distance(vector, vector) | Euclidean distance |
vector_dims(vector) | number of dimensions |
vector_norm(vector) | Euclidean norm |
Libraries
Libraries that use pgvector:
- Neighbor (Ruby)
Upgrading
0.1.1
Compile and install the latest version and run:
ALTER EXTENSION vector UPDATE TO '0.1.1';
Thanks
Thanks to:
- PASE: PostgreSQL Ultra-High-Dimensional Approximate Nearest Neighbor Search Extension
- Faiss: A Library for Efficient Similarity Search and Clustering of Dense Vectors
- Using the Triangle Inequality to Accelerate k-means
- k-means++: The Advantage of Careful Seeding
- Concept Decompositions for Large Sparse Text Data using Clustering
History
View the changelog
Contributing
Everyone is encouraged to help improve this project. Here are a few ways you can help:
- Report bugs
- Fix bugs and submit pull requests
- Write, clarify, or fix documentation
- Suggest or add new features
To get started with development:
git clone https://github.com/ankane/pgvector.git
cd pgvector
make
make install
To run all tests:
make installcheck # regression tests
make prove_installcheck # TAP tests
To run single tests:
make installcheck REGRESS=vector # regression test
make prove_installcheck PROVE_TESTS=t/001_wal.pl # TAP test
Directories
expected
- expected output for regression testssql
- regression testst
- TAP tests
Resources for contributors