vecs

0.4.5 verified Mon Apr 27 auth: no python

vecs is a pgvector client library by Supabase for managing and querying vector collections backed by PostgreSQL with pgvector. Current version 0.4.5. Release cadence is irregular; latest updates in 2024.

pip install vecs

Common errors

error ModuleNotFoundError: No module named 'vecs' ↓

cause vecs is not installed or installed in a different environment.

fix

Run 'pip install vecs' and ensure you are using the correct Python environment.

error TypeError: Client() takes 1 positional argument but 2 were given ↓

cause Old code using 'vecs.Client(DB_CONNECTION)' used to allow an extra argument or the import pattern changed.

fix

Use 'vx = vecs.Client(DB_CONNECTION)' without additional arguments.

error AttributeError: module 'vecs' has no attribute 'client' ↓

cause Trying to access lowercase 'vecs.client' instead of 'vecs.Client'.

fix

Use 'vecs.Client' with capital C.

error psycopg2.errors.UndefinedObject: type "vector" does not exist ↓

cause The PostgreSQL extension 'vector' (pgvector) is not installed in the database.

fix

Run 'CREATE EXTENSION vector;' in the PostgreSQL database.

Warnings

breaking The library changed from using 'vecs.Client' to 'vecs.Client' (no change) but the underlying API for creating collections changed from 'create_collection' to the current pattern. Old code using 'vecs.client' (lowercase) or 'vecs.create_client' will fail. ↓

fix Use 'import vecs; vx = vecs.Client(DB_CONNECTION)'.

gotcha The 'upsert' method expects records as a list of tuples: (id, vector, metadata). The vector must be a list of floats. Passing numpy arrays may cause issues. ↓

fix Convert numpy arrays to list: vector.tolist().

gotcha Creating an index with 'create_index()' is not automatic; you must call it after upserting data for good performance. Default index is IVFFlat with no parameters; consider specifying index type and parameters. ↓

fix Use 'docs.create_index(measure=vecs.IndexMeasure.cosine_distance, index=vecs.IndexMethod.ivfflat, params=dict(lists=100))'.

deprecated The method 'upsert_docs' and 'query_docs' have been removed. Use 'upsert' and 'query'. ↓

fix Replace 'upsert_docs' with 'upsert' and 'query_docs' with 'query'.

gotcha The 'query' method returns a list of tuples (id, distance, metadata). The distance is the actual distance, not similarity. For cosine distance, lower is better. ↓

fix Check the distance metric used when interpreting results.

Imports

Client
```
import vecs
```
The main object is 'vecs.Client', not 'vecs.client' or 'vecs.Vecs'.
Collection
```
from vecs import Collection
```
Collection is a class used for managing vector collections.

Quickstart

Connect to a Supabase Postgres instance with pgvector, create a collection, upsert vectors, and query.

import vecs

DB_CONNECTION = "postgresql://user:pass@host:5432/db"
vx = vecs.Client(DB_CONNECTION)

# Create a collection of vectors with 384 dimensions
docs = vx.create_collection(name="docs", dimension=384)

# Add vectors
docs.upsert(
    records=[
        ("vec0", [0.1, 0.2, ...], {"key": "val"}),  # truncated for brevity
        ("vec1", [0.3, 0.4, ...], {}),
    ]
)
docs.create_index()

# Query
results = docs.query(
    data=[0.1, 0.2, ...],
    limit=5,
    filters={"key": {"$eq": "val"}}
)
print(results)