Repository files navigation

Open-source vector similarity search for Postgres

CREATETABLEtable (column vector(3));CREATEINDEXON table USING ivfflat (column vector_l2_ops);SELECT*FROM tableORDER BY column<->'[1,2,3]'LIMIT5;

Supports L2 distance, inner product, and cosine distance

Compile and install the extension (supports Postgres 9.6+)

git clone --branch v0.2.5 https://github.com/pgvector/pgvector.gitcd pgvectormakemake install# may need sudo

Then load it in databases where you want to use it

CREATE EXTENSION vector;

You can also install it withDocker,Homebrew, orPGXN

Create a vector column with 3 dimensions (replacetable andcolumn with non-reserved names)

CREATETABLEtable (column vector(3));

Insert values

INSERT INTO tableVALUES ('[1,2,3]'), ('[4,5,6]');

Get the nearest neighbor by L2 distance

SELECT*FROM tableORDER BY column<->'[3,1,2]'LIMIT1;

Also supports inner product (<#>) and cosine distance (<=>)

Note:<#> returns the negative inner product since Postgres only supportsASC order index scans on operators

Speed up queries with an approximate index. Add an index for each distance function you want to use.

L2 distance

CREATEINDEXON table USING ivfflat (column vector_l2_ops);

Inner product

CREATEINDEXON table USING ivfflat (column vector_ip_ops);

Cosine distance

CREATEINDEXON table USING ivfflat (column vector_cosine_ops);

Indexes should be created after the table has some data for optimal clustering. Also, unlike typical indexes which only affect performance, you may see different results for queries after adding an approximate index.

Specify the number of inverted lists (100 by default)

CREATEINDEXON table USING ivfflat (column opclass) WITH (lists=100);

Agood place to start is4 * sqrt(rows)

Specify the number of probes (1 by default)

SETivfflat.probes=1;

A higher value improves recall at the cost of speed.

UseSET LOCAL inside a transaction to set it for a single query

BEGIN;SET LOCALivfflat.probes=1;SELECT ...COMMIT;

Checkindexing progress with Postgres 12+

SELECT phase, tuples_done, tuples_totalFROM pg_stat_progress_create_index;

The phases are:

1. initializing
2. sampling table
3. performing k-means
4. sorting tuples
5. loading tuples

Note:tuples_done andtuples_total are only populated during theloading tuples phase

Considerpartial indexes for queries with aWHERE clause

CREATEINDEXON table USING ivfflat (column opclass)WHERE (other_column=123);

To index many different values ofother_column, considerpartitioning onother_column.

To speed up queries without an index, increasemax_parallel_workers_per_gather.

SET max_parallel_workers_per_gather=4;

To speed up queries with an index, increase the number of inverted lists (at the expense of recall).

CREATEINDEXON table USING ivfflat (column opclass) WITH (lists=1000);

Each vector takes4 * dimensions + 8 bytes of storage. Each element is a float, and all elements must be finite (noNaN,Infinity or-Infinity). Vectors can have up to 1024 dimensions.

Libraries that use pgvector:

• pgvector-python (Python)
• Neighbor (Ruby)
• pgvector-ruby (Ruby)
• pgvector-node (Node.js)
• pgvector-go (Go)
• pgvector-rust (Rust)
• pgvector-cpp (C++)

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.

Yes, pgvector uses the write-ahead log (WAL), which allows for replication and point-in-time recovery.

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 insrc/vector.h

Get theDocker image with:

docker pull ankane/pgvector

This adds pgvector to thePostgres image.

You can also build the image manually

git clone --branch v0.2.5 https://github.com/pgvector/pgvector.gitcd pgvectordocker build -t pgvector.

On Mac with Homebrew Postgres, you can use:

brew install pgvector/brew/pgvector

Install from thePostgreSQL Extension Network with:

pgxn install vector

Some Postgres providers only support specific extensions. To request a new extension:

• Amazon RDS - follow the instructions onthis page
• Google Cloud SQL - follow the instructions onthis page
• DigitalOcean Managed Databases - vote or comment onthis page
• Azure Database for PostgreSQL - follow the instructions onthis page

Install the latest version and run:

ALTER EXTENSION vectorUPDATE;

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

View thechangelog

Everyone is encouraged to help improve this project. Here are a few ways you can help:

• Report bugs
• Fix bugs andsubmit pull requests
• Write, clarify, or fix documentation
• Suggest or add new features

To get started with development:

git clone https://github.com/pgvector/pgvector.gitcd pgvectormakemake install

To run all tests:

make installcheck# regression testsmake prove_installcheck# TAP tests

To run single tests:

make installcheck REGRESS=functions# regression testmake prove_installcheck PROVE_TESTS=test/t/001_wal.pl# TAP test

To enable benchmarking:

make clean&& PG_CFLAGS=-DIVFFLAT_BENCH make&& make install

Resources for contributors

• Extension Building Infrastructure
• Index Access Method Interface Definition
• Generic WAL Records