Getting Started

• 1: Overview
• 2: Installation

1 - Overview

An introduction to the pgvecto.rs.

What is pgvecto.rs

pgvecto.rs is a Postgres extension that provides vector similarity search functions. It is written in Rust and based on pgrx. It is currently in the beta status, we invite you to try it out in production and provide us with feedback. Read more at 📝our launch blog.

Comparison with pgvector

Checkout pgvecto.rs vs pgvector for more details.

Quick start

For new users, we recommend using the Docker image to get started quickly.

docker run \
  --name pgvecto-rs-demo \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -d tensorchord/pgvecto-rs:pg16-v0.2.0

Then you can connect to the database using the psql command line tool. The default username is postgres, and the default password is mysecretpassword.

psql postgresql://postgres:mysecretpassword@localhost:5432/postgres

Run the following SQL to ensure the extension is enabled.

DROP EXTENSION IF EXISTS vectors;
CREATE EXTENSION vectors;

pgvecto.rs introduces a new data type vector(n) denoting an n-dimensional vector. The n within the brackets signifies the dimensions of the vector.

You could create a table with the following SQL.

-- create table with a vector column

CREATE TABLE items (
  id bigserial PRIMARY KEY,
  embedding vector(3) NOT NULL -- 3 dimensions
);

You can then populate the table with vector data as follows.

-- insert values

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

-- or insert values using a casting from array to vector

INSERT INTO items (embedding)
VALUES (ARRAY[1, 2, 3]::real[]), (ARRAY[4, 5, 6]::real[]);

We support three operators to calculate the distance between two vectors.

• <->: squared Euclidean distance, defined as $\Sigma (x_i - y_i) ^ 2$.
• <#>: negative dot product, defined as $- \Sigma x_iy_i$.
• <=>: cosine distance, defined as $1 - \frac{\Sigma x_iy_i}{\sqrt{\Sigma x_i^2 \Sigma y_i^2}}$.

-- call the distance function through operators

-- squared Euclidean distance
SELECT '[1, 2, 3]'::vector <-> '[3, 2, 1]'::vector;
-- negative dot product
SELECT '[1, 2, 3]'::vector <#> '[3, 2, 1]'::vector;
-- cosine distance
SELECT '[1, 2, 3]'::vector <=> '[3, 2, 1]'::vector;

You can search for a vector simply like this.

-- query the similar embeddings
SELECT * FROM items ORDER BY embedding <-> '[3,2,1]' LIMIT 5;

A simple Question-Answering application

Please check out the Question-Answering application tutorial.

Half-precision floating-point

vecf16 type is the same with vector in anything but the scalar type. It stores 16-bit floating point numbers. If you want to reduce the memory usage to get better performance, you can try to replace vector type with vecf16 type.

For more usage of vecf16, please refer to vector types.

Sparse vector

svector type is a sparse vector type. It stores a vector in a sparse format. It is suitable for vectors with many zeros.

For more usage of svector, please refer to vector types.

Binary vector

bvector type is a binary vector type. It is a fixed-length bit string. Except for above 3 distances, we also support jaccard distance <~>, which defined as $1 - \frac{|X\cap Y|}{|X\cup Y|}$. And hamming distance is the same with squared Euclidean distance, you can use <-> operator to calculate it. We also provide binarize function to construct a bvector from a vector, which set the positive elements to 1, otherwise 0.

For more usage of bvector, please refer to vector types.

Roadmap 🗂️

Please check out ROADMAP.

Contribute 😊

We welcome all kinds of contributions from the open-source community, individuals, and partners.

• Join our discord community!
• To build from the source, please read our contributing documentation and development tutorial.

Talk with us

💬 Interested in talking with us about your experience building or managing AI/ML applications?

Set up a time to chat!

2 - Installation

There are four ways to install pgvecto.rs.

Docker

The easiest way to try pgvecto.rs is to run it from a ready-to use Docker image.

docker run \
  --name pgvecto-rs-demo \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  -d tensorchord/pgvecto-rs:pg16-v0.2.0

Then you can connect to the database using the psql command line tool. The default username is postgres, and the default password is mysecretpassword.

psql postgresql://postgres:mysecretpassword@localhost:5432/postgres

Run the following SQL to ensure the extension is enabled.

DROP EXTENSION IF EXISTS vectors;
CREATE EXTENSION vectors;

To achieve full performance, please mount the volume to pg data directory by adding the option like -v $PWD/pgdata:/var/lib/postgresql/data

You can configure PostgreSQL by the reference of the parent image in https://hub.docker.com/_/postgres/.

From Debian package

Debian packages(.deb) are used in distributions based on Debian, such as Ubuntu and many others. They can be easily installed by dpkg or apt-get.

1. Download the deb package in the release page, and type sudo apt install vectors-pg15-*.deb to install the deb package.

2. Configure your PostgreSQL by modifying the shared_preload_libraries and search_path to include the extension.

psql -U postgres -c 'ALTER SYSTEM SET shared_preload_libraries = "vectors.so"'
psql -U postgres -c 'ALTER SYSTEM SET search_path TO "$user", public, vectors'
# You need restart the PostgreSQL cluster to take effects.
sudo systemctl restart postgresql.service   # for pgvecto.rs running with systemd

3. Connect to the database and enable the extension.

DROP EXTENSION IF EXISTS vectors;
CREATE EXTENSION vectors;

From ZIP package

For systems that are not Debian based and cannot run a Docker container, please follow these steps to install:

1. Before install, make sure that you have the necessary packages installed, including PostgreSQL, pg_config, unzip, wget.

# Example for RHEL 9 dnf
# Please check your package manager
sudo dnf install -y unzip wget libpq-devel
sudo dnf module install -y postgresql:15/server
sudo postgresql-setup --initdb
sudo systemctl start postgresql.service
sudo systemctl enable postgresql.service

2. Verify whether $pkglibdir and $shardir have been set by PostgreSQL.

pg_config --pkglibdir
# Print something similar to:
# /usr/lib/postgresql/15/lib or
# /usr/lib64/pgsql

pg_config --sharedir
# Print something similar to:
# /usr/share/postgresql/15 or
# /usr/share/pgsql

3. Download the zip package in the release page and extract it to a temporary directory.

wget https://github.com/tensorchord/pgvecto.rs/releases/download/v0.2.1/vectors-pg15_x86_64-unknown-linux-gnu_0.2.1.zip -O vectors.zip
unzip vectors.zip -d vectors

4. Copy the extension files to the PostgreSQL directory.

# Copy library to `$pkglibdir`
sudo cp vectors/vectors.so $(pg_config --pkglibdir)/
# Copy schema to `$shardir`
sudo cp vectors/vectors--* $(pg_config --sharedir)/extension/
sudo cp vectors/vectors.control $(pg_config --sharedir)/extension/

5. Configure your PostgreSQL by modifying the shared_preload_libraries and search_path to include the extension.

psql -U postgres -c 'ALTER SYSTEM SET shared_preload_libraries = "vectors.so"'
psql -U postgres -c 'ALTER SYSTEM SET search_path TO "$user", public, vectors'
# You need restart the PostgreSQL cluster to take effects.
sudo systemctl restart postgresql.service   # for pgvecto.rs running with systemd

6. Connect to the database and enable the extension.

DROP EXTENSION IF EXISTS vectors;
CREATE EXTENSION vectors;

From source

Before building from source, you could refer to the development guide to set up the development environment.

1. Then you could build and install the extension.

sed -e "s/@CARGO_VERSION@/0.0.0/g" ./vectors.control  # 0.0.0 here is the version number that you need
sudo cp -a ./sql/upgrade/. $(pg_config --sharedir)/extension
cargo pgrx install --sudo --release

2. Configure your PostgreSQL by modifying the shared_preload_libraries and search_path to include the extension.

psql -U postgres -c 'ALTER SYSTEM SET shared_preload_libraries = "vectors.so"'
psql -U postgres -c 'ALTER SYSTEM SET search_path TO "$user", public, vectors'
# You need restart the PostgreSQL cluster to take effects.
sudo systemctl restart postgresql.service   # for pgvecto.rs running with systemd
service postgresql restart  # for pgvecto.rs running in envd

3. Connect to the database and enable the extension.

DROP EXTENSION IF EXISTS vectors;
CREATE EXTENSION vectors;