vector

This Release
vector 0.1.8
Date
Status
Stable
Other Releases
Abstract
Open-source vector similarity search for Postgres
Description
Supports L2 distance, inner product, and cosine distance
Released By
ankane
License
PostgreSQL
Resources
Special Files
Tags

Extensions

vector 0.1.8
Open-source vector similarity search for Postgres

Documentation

CHANGELOG
CHANGELOG

README

pgvector

Open-source vector similarity search for Postgres

sql 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

Build Status

Installation

Compile and install the extension (supports Postgres 9.6+)

sh git clone --branch v0.1.8 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

sql CREATE EXTENSION vector;

You can also install it with Docker, Homebrew, or PGXN

Getting Started

Create a vector column with 3 dimensions (replace table and column with non-reserved names)

sql CREATE TABLE table (column vector(3));

Insert values

sql INSERT INTO table VALUES ('[1,2,3]'), ('[4,5,6]');

Get the nearest neighbor by L2 distance

sql 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

sql CREATE INDEX ON table USING ivfflat (column);

Inner product

sql CREATE INDEX ON table USING ivfflat (column vector_ip_ops);

Cosine distance

sql 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)

sql CREATE INDEX ON table USING ivfflat (column) WITH (lists = 100);

Query Options

Specify the number of probes (1 by default)

sql 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

sql BEGIN; SET LOCAL ivfflat.probes = 1; SELECT ... COMMIT;

Partial Indexes

Consider partial indexes for queries with a WHERE clause

sql CREATE INDEX ON table USING ivfflat (column) WHERE (other_column = 123);

To index many different values of other_column, consider partitioning on other_column.

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:

Additional Installation Methods

Docker

Get the Docker image with:

sh docker pull ankane/pgvector

This adds pgvector to the Postgres image.

You can also build the image manually

sh git clone --branch v0.1.8 https://github.com/ankane/pgvector.git cd pgvector docker build -t pgvector .

Homebrew

On Mac with Homebrew Postgres, you can use:

sh brew install ankane/brew/pgvector

PGXN

Install from the PostgreSQL Extension Network with:

sh pgxn install vector

Hosted Postgres

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

  • Amazon RDS - follow the instructions on this page
  • Google Cloud SQL - follow the instructions on this page
  • DigitalOcean Managed Databases - follow the instructions on this page
  • Azure Database for PostgreSQL - follow the instructions on this page

Upgrading

Install the latest version and run:

sql ALTER EXTENSION vector UPDATE;

Thanks

Thanks to:

History

View the changelog

Contributing

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

To get started with development:

sh git clone https://github.com/ankane/pgvector.git cd pgvector make make install

To run all tests:

sh make installcheck # regression tests make prove_installcheck # TAP tests

To run single tests:

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

Resources for contributors