vecs

What it is and what it does

vecs is a lightweight Python wrapper around PostgreSQL's pgvector extension, designed to simplify vector storage and retrieval operations. It provides a client interface for creating collections of vectors, upserting records with associated metadata, building indices for fast search, and querying with metadata filtering. The package handles the connection management and SQL generation needed to work with pgvector, abstracting away direct database interaction.

The package is intended for developers building semantic search, similarity matching, or embedding-based applications on top of PostgreSQL. It requires an existing PostgreSQL instance with pgvector already installed—there is no embedded database or managed service bundled with the package itself. Use it when you have vector data to store alongside relational data and want to leverage PostgreSQL's existing infrastructure rather than adopting a separate vector database.

Use it for

• Build semantic search over documents by storing embeddings and querying with similarity filters.
• Implement recommendation systems by storing user/item embeddings and finding nearest neighbors.
• Add vector similarity matching to existing PostgreSQL applications without migrating to a specialized vector store.
• Query embeddings with metadata constraints, e.g., find similar vectors only from a specific time period or category.
• Prototype vector search workflows before committing to a dedicated vector database.

Worth the install?

AI-flagged interpretation of the facts on this page. Verify before relying on it.

Install

vecs on PyPI

Before you install

Installation friction is high: the package itself has no runtime dependencies, but requires an external PostgreSQL database with pgvector extension already configured and accessible. The project shows aging maintenance status with the last commit on 2025-04-09 and no releases since 2024-12-13, though the repository remains active and not archived.

Requires a PostgreSQL database with pgvector extension already installed and running, plus a valid connection string to access it.

License in practice

MIT license permits commercial and private use with minimal restrictions, making it suitable for most projects. You must include the license text in distributions.

Quickstart

pip install vecs

import vecs
vx = vecs.create_client("postgresql://:@:/<db_name>")
docs = vx.get_or_create_collection(name="docs", dimension=3)
docs.upsert(records=[("id", [0.1, 0.2, 0.3], {"meta": "data"})])
results = docs.query(data=[0.4, 0.5, 0.6], limit=1)

Package facts

Evidence: vecs-0.4.5.tar.gz

Tags

More Database packages

See also pgvector · llama-index-vector-stores-postgres · pgvecto-rs · pgserver · upstash-vector · pg0-embedded · sqlite-vec · nano-vectordb · apache-airflow-providers-pgvector · nucliadb-utils