Skip to main content
The PgvectorHandshake class provides seamless integration between Chonkie’s chunking system and PostgreSQL with pgvector. It uses the vecs client library from Supabase underneath to provide a higher-level API with automatic indexing, metadata filtering, and simplified connection management. Store your Chonkie chunks in PostgreSQL with vector embeddings and perform semantic search without ever leaving the Chonkie SDK.

​
Installation

Before using the Pgvector handshake, make sure to install the required dependencies: 
pip install chonkie[pgvector]
You’ll also need PostgreSQL with the pgvector extension installed: 
-- Connect to your database and enable pgvector
CREATE EXTENSION IF NOT EXISTS vector;

​
Initialization

from chonkie import PgvectorHandshake

# Initialize with individual connection parameters
handshake = PgvectorHandshake(
    host="localhost",
    port=5432,
    database="your_database",
    user="your_user",
    password="your_password",
    collection_name="chonkie_chunks"
)

# Or use a connection string
handshake = PgvectorHandshake(
    connection_string="postgresql://user:password@localhost:5432/database"
)

# Or use an existing vecs client
import vecs
client = vecs.create_client("postgresql://user:password@localhost:5432/database")
handshake = PgvectorHandshake(client=client, collection_name="my_collection")

​
Usage

from chonkie import PgvectorHandshake, RecursiveChunker

# Initialize the handshake
handshake = PgvectorHandshake(
    host="localhost",
    database="my_database",
    user="my_user",
    password="my_password"
)

# Create some chunks
chunker = RecursiveChunker(chunk_size=2048)
chunks = chunker.chunk("Chonkie makes PostgreSQL vector search easy!")

# Write chunks to PostgreSQL
handshake.write(chunks)

# Search for similar chunks
results = handshake.search(
    query="PostgreSQL vector search",
    limit=5
)

for result in results:
    print(f"Text: {result['text']}")
    print(f"Similarity: {result['similarity']:.3f}")
    print("---")

# Create an HNSW index for better performance
handshake.create_index(method="hnsw")

# Or create with custom parameters
handshake.create_index(
    method="hnsw",
    m=16,
    ef_construction=64
)

​
Parameters

​
client
Optional[vecs.Client]
default:"None"
An existing vecs.Client instance. If provided, other connection parameters are ignored.
​
host
str
default:"localhost"
PostgreSQL host address.
​
port
int
default:"5432"
PostgreSQL port number.
​
database
str
default:"postgres"
PostgreSQL database name.
​
user
str
default:"postgres"
PostgreSQL username.
​
password
str
default:"postgres"
PostgreSQL password.
​
connection_string
Optional[str]
default:"None"
Full PostgreSQL connection string. If provided, individual connection parameters are ignored.
​
collection_name
str
default:"chonkie_chunks"
Name of the collection to store chunks in.
​
embedding_model
Union[str, BaseEmbeddings]
default:"minishlab/potion-retrieval-32M"
Embedding model to use. Can be a model name or a BaseEmbeddings instance.
​
vector_dimensions
Optional[int]
default:"None"
Number of dimensions for the vector embeddings. If not provided, will be inferred from the embedding model.
⌘I