Quickstart
Want to explore the code examples interactively? Check out our Jupyter Notebook walkthrough that demonstrates Zvec in action — including a hands-on multi-modal image search example.
Installation
pip install zvecCreate a Collection
A collection stores your documents. Each document contains scalar fields and vector embeddings.
Define a schema and create a collection. A schema has two parts: fields for scalar data and vectors for vector embeddings.
import zvec
# Define a collection schema
collection_schema = zvec.CollectionSchema(
name="my_collection",
fields=[
zvec.FieldSchema(
name="publish_year",
data_type=zvec.DataType.INT32,
index_param=zvec.InvertIndexParam(enable_range_optimization=True),
),
],
vectors=[
zvec.VectorSchema(
name="embedding",
data_type=zvec.DataType.VECTOR_FP32,
dimension=768,
index_param=zvec.HnswIndexParam(metric_type=zvec.MetricType.COSINE),
),
],
)
# Create a collection
collection = zvec.create_and_open(
path="./my_collection_data",
schema=collection_schema,
)Important: The field names you define here (publish_year, embedding) must be used exactly as written when inserting or querying data.
Add Documents
Insert documents with scalar fields and vector embeddings:
collection.insert(
zvec.Doc(
id="book_1", # Unique document ID
vectors={"embedding": [0.1] * 768}, # Replace with your actual vector
fields={"publish_year": 1936},
)
)Important: Field names must match exactly. The publish_year field and embedding vector must use the same names you defined in your schema.
Optimize a Collection
New vectors are buffered on insert. Call optimize() to build the vector index for faster search:
collection.optimize()Retrieve a Document by ID
Fetch a document directly by its id:
result = collection.fetch(ids="book_1")
print(result)let result = collection.fetchSync("book_1");
console.log(result);Search with Vectors
Basic Similarity Search
Use query() to find documents most similar to a given vector embedding:
result = collection.query(
zvec.VectorQuery(
field_name="embedding",
vector=[0.3] * 768, # Replace with your actual vector
),
topk=10,
)
print(result)Results are ranked by similarity score.
let result = collection.querySync({
fieldName: "embedding",
vector: Array(768).fill(0.3), // Replace with your actual vector
topk: 10
});
console.log(result);Results are ranked by similarity score.
Filtered Similarity Search
Combine vector search with conditional filters — only matching documents are considered during search:
result = collection.query(
zvec.VectorQuery(
field_name="embedding",
vector=[0.3] * 768, # Replace with your actual vector
),
topk=10,
filter="publish_year > 1936",
)
print(result)let result = collection.querySync({
fieldName: "embedding",
vector: Array(768).fill(0.3), // Replace with your actual vector
topk: 10,
filter: "publish_year > 1936"
});
console.log(result);Inspect a Collection
View the collection's schema:
print(collection.schema)View the collection's statistics:
print(collection.stats)Delete a Document
Delete a document by its ID:
collection.delete(ids="book_1")Delete documents by filter condition:
collection.delete_by_filter(filter="publish_year < 1900")✨ You're all set to store, retrieve, and search vector data with Zvec!
💙 Thank you for your interest in Zvec! We hope you enjoy exploring what Zvec can do!