vecs Python Client

Indexes are heuristic data structures used to optimize query performance for a collection.

While you can query a collection without an index, doing so will emit a Python warning and is extremely slow in production because every query vector must be checked against every single record in the collection. An index pre-computes distances between key points in the vector space, allowing for much faster traversal and searching.

Key constraints:

• Only one index may exist per collection.
• An index optimizes a collection for a specific distance measure.
• Index creation time grows with the number of records and vector dimensions. Expect sub-minute responses for a few thousand records, but several minutes for larger collections.

Adapters are an optional feature used to transform data before it is added to or queried from a collection. They allow you to interact with collections using your preferred data type (e.g., raw text) instead of manually managing vector conversions.

Key characteristics:

• Lazy Transformation: Transformations are applied lazily.
• Efficiency: They can internally batch operations, making them more memory and CPU efficient than manual transformations.
• Pipelines: Adapters can be composed of multiple AdapterStep objects to create multi-stage preprocessing pipelines (e.g., chunking text followed by embedding it).
• Data Interface: Adapters process data in the form of Iterable[Tuple[str, Any, Optional[Dict]]], where each tuple represents (id, media, metadata). While primarily used to transform the media part, they can also modify id or metadata.

Every vecs collection is backed by a standard Postgres table where rows map 1:1 to vector records. While you can safely perform SELECT queries on these tables from outside the vecs client, you should avoid issuing DDL (Data Definition Language) commands directly to the underlying tables to prevent corruption of the collection state.

The underlying table schema follows this pattern:

create table <collection_name> (
    id string primary key,
    vec vector(<dimension>),
    metadata jsonb
)

Metadata is stored as binary JSON. You can use the following JSON primitive types for your metadata values:

• Boolean
• String
• Number

Note on limits and performance:

• The technical limit for a metadata field associated with a vector is 1GB.
• For optimal performance, keep metadata fields as small as possible and use scalar key-value pairs.

In vecs, a collection consists of vector records. Each record is composed of three primary fields:

• id: A unique String identifier.
• vec: A list of numbers (Numeric[]) representing the vector embedding.
• metadata: A JSON object containing arbitrary key-value pairs for filtering and additional context.

Example of a record structure: ("vec1", [0.1, 0.2, 0.3], {"year": 1990})

# Example record representation
("vec1", [0.1, 0.2, 0.3], {"year": 1990})

Install the vecs Python client using pip. Ensure you have Python 3.7 or higher installed.

pip install vecs

To perform a similarity search, embed your query string using the same Hugging Face endpoint used for the dataset. Then, use the sentences.query() method, passing the query embedding, a limit, and optionally include_value=True to retrieve the original text/values alongside the distance.

query_sentence = "A quick animal jumps over a lazy one."

# create an embedding for the query sentence
response = requests.post(
    huggingface_endpoint_url,
    headers={
        "Authorization": f"Bearer {huggingface_api_key}",
        "Content-Type": "application/json"
    },
    json={"inputs": query_sentence}
)
query_embedding = response.json()["embeddings"]

# query the 'sentences' collection for the most similar sentences
results = sentences.query(
    data=query_embedding,
    limit=3,
    include_value = True
)

# print the results
for result in results:
    print(result)

To use adapters that involve text embeddings (like TextEmbedding), you must install vecs with the text_embedding optional dependency.

pip install "vecs[text_embedding]"

Once you have generated embeddings, use the vecs.Client to connect to your PostgreSQL database. You can then create a collection with a specific dimension (e.g., 384 for sentence-transformers/all-MiniLM-L6-v2) and upsert your records. It is recommended to call create_index() on the collection to enable fast similarity searches.

import vecs

DB_CONNECTION = "postgresql://<user>:<password>@<host>:<port>/<db_name>"

# create vector store client
vx = vecs.Client(DB_CONNECTION)

# create a collection named 'sentences' with 384 dimensional vectors
sentences = vx.get_or_create_collection(name="sentences", dimension=384)

# upsert the embeddings into the 'sentences' collection
sentences.upsert(records=records)

# create an index for the 'sentences' collection
sentences.create_index()