Skip to main content
Get up and running with Zvec in less than 5 minutes. This guide walks you through creating your first vector collection, inserting documents, and performing similarity search.

​
Prerequisites

Before you begin, make sure you have Zvec installed: 
pip install zvec
Zvec requires Python 3.10-3.12 or Node.js 16+. See the Installation Guide for platform requirements.

​
Step-by-Step Guide

1

Define a schema

First, define the structure of your collection. A schema specifies the vector dimensions and data types.
import zvec

# Define collection schema
schema = zvec.CollectionSchema(
    name="example",
    vectors=zvec.VectorSchema(
        "embedding", 
        zvec.DataType.VECTOR_FP32, 
        dimension=4
    )
)
Choose your dimension based on your embedding model (e.g., 384 for MiniLM, 1536 for OpenAI ada-002).
2

Create and open a collection

Create a new collection and open it for operations. The collection is persisted to disk.
# Create and open collection
collection = zvec.create_and_open(
    path="./zvec_example", 
    schema=schema
)
The path specifies where the collection data is stored. The directory will be created if it doesn’t exist.
3

Insert documents

Insert documents with their vector embeddings. Each document has an ID and a vector.
# Insert documents
collection.insert([
    zvec.Doc(id="doc_1", vectors={"embedding": [0.1, 0.2, 0.3, 0.4]}),
    zvec.Doc(id="doc_2", vectors={"embedding": [0.2, 0.3, 0.4, 0.1]}),
    zvec.Doc(id="doc_3", vectors={"embedding": [0.3, 0.1, 0.2, 0.4]}),
])
You can also include metadata fields:
collection.insert([
    zvec.Doc(
        id="doc_1", 
        vectors={"embedding": [0.1, 0.2, 0.3, 0.4]},
        fields={"title": "First Document", "category": "news"}
    ),
])
4

Query for similar vectors

Search for the most similar vectors using a query vector.
# Search by vector similarity
results = collection.query(
    zvec.VectorQuery("embedding", vector=[0.4, 0.3, 0.3, 0.1]),
    topk=10
)

# Results: list of {'id': str, 'score': float, ...}
print(results)

[
    {'id': 'doc_2', 'score': 0.9847, 'vectors': {...}},
    {'id': 'doc_1', 'score': 0.9123, 'vectors': {...}},
    {'id': 'doc_3', 'score': 0.8654, 'vectors': {...}}
]
Results are automatically sorted by score in descending order (highest similarity first).
5

Add filters (optional)

Combine vector search with metadata filters for more precise results.
# Query with filters
results = collection.query(
    zvec.VectorQuery("embedding", vector=[0.4, 0.3, 0.3, 0.1]),
    topk=10,
    filter="category = 'news'"
)
Learn more about filtering in the Filtering Guide.

​
Complete Example

Here’s a complete working example you can run:
complete_example.py
import zvec

# Define schema
schema = zvec.CollectionSchema(
    name="my_documents",
    vectors=zvec.VectorSchema("embedding", zvec.DataType.VECTOR_FP32, 4)
)

# Create collection
collection = zvec.create_and_open(path="./my_collection", schema=schema)

# Insert documents
collection.insert([
    zvec.Doc(id="doc_1", vectors={"embedding": [0.1, 0.2, 0.3, 0.4]}),
    zvec.Doc(id="doc_2", vectors={"embedding": [0.2, 0.3, 0.4, 0.1]}),
    zvec.Doc(id="doc_3", vectors={"embedding": [0.3, 0.1, 0.2, 0.4]}),
])

# Query
results = collection.query(
    zvec.VectorQuery("embedding", vector=[0.4, 0.3, 0.3, 0.1]),
    topk=3
)

# Print results
for result in results:
    print(f"ID: {result['id']}, Score: {result['score']:.4f}")

​
Next Steps

Now that you have Zvec running, explore these topics to build more advanced applications:

Core Concepts

Learn about collections, schemas, vectors, and indexing

Dense Vectors

Work with dense embeddings for semantic search

Hybrid Search

Combine dense and sparse vectors for better results

API Reference

Explore the complete API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us