AI & Vectors

Python client

Manage unstructured vector stores in PostgreSQL.


Supabase provides a Python client called vecs for managing unstructured vector stores. This client provides a set of useful tools for creating and querying collections in PostgreSQL using the pgvector extension.

Quick start

Let's see how Vecs works using a local database. Make sure you have the Supabase CLI installed on your machine.

Initialize your project

Start a local Postgres instance in any folder using the init and start commands. Make sure you have Docker running!


_10
# Initialize your project
_10
supabase init
_10
_10
# Start Postgres
_10
supabase start

Create a collection

Inside a Python shell, run the following commands to create a new collection called "docs", with 3 dimensions.


_10
import vecs
_10
_10
# create vector store client
_10
vx = vecs.create_client("postgresql://postgres:postgres@localhost:54322/postgres")
_10
_10
# create a collection of vectors with 3 dimensions
_10
docs = vx.get_or_create_collection(name="docs", dimension=3)

Add embeddings

Now we can insert some embeddings into our "docs" collection using the upsert() command:


_13
import vecs
_13
_13
# create vector store client
_13
docs = vecs.get_or_create_collection(name="docs", dimension=3)
_13
_13
# a collection of vectors with 3 dimensions
_13
vectors=[
_13
("vec0", [0.1, 0.2, 0.3], {"year": 1973}),
_13
("vec1", [0.7, 0.8, 0.9], {"year": 2012})
_13
]
_13
_13
# insert our vectors
_13
docs.upsert(vectors=vectors)

Query the collection

You can now query the collection to retrieve a relevant match:


_10
import vecs
_10
_10
docs = vecs.get_or_create_collection(name="docs", dimension=3)
_10
_10
# query the collection filtering metadata for "year" = 2012
_10
docs.query(
_10
data=[0.4,0.5,0.6], # required
_10
limit=1, # number of records to return
_10
filters={"year": {"$eq": 2012}}, # metadata filters
_10
)

Deep dive

For a more in-depth guide on vecs collections, see API.

Resources