Build your first application

In this tutorial, you build a complete application on Actian VectorAI DB from scratch. By the end, you have a working movie recommendation engine that can store movie descriptions as dense vectors, find semantically similar movies using natural language queries, filter results by genre, year, or rating, update movie information after ingestion, delete outdated records, and inspect collection health and statistics. No prior vector database experience is required. Each step introduces a concept, explains why it matters, and shows the code you need.

What you build

A user describes what they want to watch in natural language — “a suspenseful space movie” — and the system finds the best matches from the database, optionally filtered by genre, year, or minimum rating. The diagram below shows how data flows from raw movie records through embedding and into a searchable vector store.

Prerequisites

Before starting, make sure the following are in place.

Python 3.10 or later.
pip available in your environment (verify with pip --version).
A virtual environment activated (recommended: python -m venv .venv && source .venv/bin/activate).
An Actian VectorAI DB server running (default: localhost:6574).
Internet access on first run — sentence-transformers downloads the embedding model (all-MiniLM-L6-v2, approximately 90 MB) from Hugging Face when you first call SentenceTransformer(EMBED_MODEL).
At least 512 MB of free memory to load the embedding model.

Step 1: Install dependencies

The following command installs the Actian VectorAI SDK and the sentence embedding library. Run it inside your virtual environment.

pip install actian-vectorai-client sentence-transformers

The two packages serve distinct roles in the application.

Package	Purpose
`actian-vectorai-client`	Official Python SDK — async/sync clients, Filter DSL, gRPC transport.
`sentence-transformers`	Open-source library for generating text embeddings.

Step 2: Import libraries and configure

The following snippet imports every class needed for this tutorial and sets three constants that identify the server address, collection name, and embedding model. Running it loads the model into memory and prints the resolved configuration so you can confirm the values before proceeding.

import asyncio
from sentence_transformers import SentenceTransformer

from actian_vectorai import (
    AsyncVectorAIClient,
    Distance,
    Field,
    FilterBuilder,
    PointStruct,
    VectorParams,
)
from actian_vectorai.models.collections import HnswConfigDiff

# Connection and collection settings
SERVER     = "localhost:6574"
COLLECTION = "Movies"

# Embedding model settings — model name and its output dimension must match
EMBED_MODEL = "all-MiniLM-L6-v2"
EMBED_DIM   = 384

# Load the embedding model into memory (downloads on first run)
model = SentenceTransformer(EMBED_MODEL)

print(f"Server:     {SERVER}")
print(f"Collection: {COLLECTION}")
print(f"Model:      {EMBED_MODEL} ({EMBED_DIM} dimensions)")

The table below describes what each import provides.

Import	Purpose
`AsyncVectorAIClient`	Manages the gRPC connection to VectorAI DB.
`Distance`	Enum for similarity metrics (Cosine, Dot, Euclid).
`Field`	Builds type-safe conditions on payload fields.
`FilterBuilder`	Combines conditions with boolean logic (AND / OR / NOT).
`PointStruct`	A data point: ID + vector + payload (metadata).
`VectorParams`	Configuration for the vector space: dimension + distance.
`HnswConfigDiff`	Tuning parameters for the HNSW search index.

Expected output

Server:     localhost:6574
Collection: Movies
Model:      all-MiniLM-L6-v2 (384 dimensions)

The model loader may print a BertModel LOAD REPORT warning about embeddings.position_ids marked as UNEXPECTED. This can be safely ignored — it is a known artefact of loading sentence-transformer weights and does not affect embedding quality.

Step 3: Connect to the server

The following snippet opens a gRPC connection to the server, calls health_check(), and prints the server’s version information. If the connection fails, an exception is raised inside the async with block and the error message identifies the problem.

async def check_connection():
    async with AsyncVectorAIClient(url=SERVER) as client:
        health = await client.health_check()
        print(f"Server health: {health}")

asyncio.run(check_connection())

Expected output

Server health: {'title': 'Actian VectorAI DB', 'version': 'Actian VectorAI DB 1.0.0 / VDE 1.0.0'}

If you see a connection error, verify that the VectorAI DB server is running on localhost:6574. When check_connection() runs, the async with AsyncVectorAIClient(...) block manages the gRPC connection lifecycle. The client opens a channel to SERVER, runs the coroutine body including health_check(), and closes the channel when the block exits, so resources are released even if something fails. The sequence is as follows.

AsyncVectorAIClient(url=SERVER) creates a client instance.
async with opens a gRPC channel and verifies the server is reachable.
health_check() pings the server and returns status information.
When the async with block exits, the connection is closed cleanly.

Step 4: Create a collection

A collection is a named container for vectors. Think of it as a table in a relational database, but optimized for similarity search. The following snippet calls get_or_create, which creates the collection if it does not already exist. On subsequent runs it reuses the existing collection without error.

async def create_collection():
    async with AsyncVectorAIClient(url=SERVER) as client:
        # Delete any stale collection from previous runs before creating fresh
        try:
            await client.collections.delete(COLLECTION)
        except Exception:
            pass
        await client.collections.get_or_create(
            name=COLLECTION,
            vectors_config=VectorParams(
                size=EMBED_DIM,
                distance=Distance.Cosine,
            ),
            hnsw_config=HnswConfigDiff(m=16, ef_construct=128),
        )
        # get_info confirms the collection is fully committed on the server
        # before the next script step opens a new connection to write into it
        await client.collections.get_info(COLLECTION)
    print(f"Collection '{COLLECTION}' ready.")

asyncio.run(create_collection())

Parameter	Value	Meaning
`size=384`	Vector dimension	Must match the embedding model’s output dimension.
`distance=Distance.Cosine`	Similarity metric	Cosine similarity is ideal for sentence transformers.
`m=16`	HNSW graph connections	Each node connects to 16 neighbours — balances speed and recall.
`ef_construct=128`	Build-time search width	Higher values improve index quality at the cost of build time.

Why use `get_or_create`

get_or_create is safe to call repeatedly. When the collection does not yet exist, the SDK creates it and returns True. When the collection already exists, the SDK skips creation and returns False. This boolean return value lets you log whether a new collection was provisioned, and your scripts become idempotent — safe to re-run without side effects.

Sync barrier: Always call collections.get_info() immediately after get_or_create() in the same connection block. This confirms the collection is fully committed on the server before the next step opens a new connection to write into it. Without it, a subsequent points.upsert() may raise CollectionNotFoundError even though creation appeared to succeed.

Expected output

Collection 'Movies' ready.

Step 5: Create embedding helpers

def embed_text(text: str) -> list[float]:
    """Convert a single text string to a 384-dimensional vector."""
    return model.encode(text).tolist()

def embed_texts(texts: list[str]) -> list[list[float]]:
    """Convert a batch of text strings to vectors in a single forward pass."""
    return model.encode(texts).tolist()

test_vec = embed_text("A thrilling adventure in space")
print(f"Vector dimension: {len(test_vec)}")
print(f"First 5 values:   {[round(v, 4) for v in test_vec[:5]]}")

Expected output

Vector dimension: 384
First 5 values:   [-0.0234, 0.0891, -0.0567, 0.0123, -0.0456]

The exact values vary by platform. What matters is that the dimension is 384. Batching matters for three reasons.

Speed: embed_texts processes all texts in a single forward pass through the model, which is significantly faster than calling embed_text in a loop.
Efficiency: Batching reduces CPU and memory overhead compared to encoding one string at a time.
Best practice: Always batch when embedding more than a few texts.

Step 6: Prepare your data

Each movie becomes a point in the collection. A point has three parts.

ID — A unique identifier (integer or UUID string).
Vector — An embedding of the movie’s plot description.
Payload — Structured metadata (genre, year, rating, and so on).

The following list defines ten movies that will be embedded and stored in the next step. Each entry includes a plot description that the embedding model will encode into a 384-dimensional vector.

movies = [
    {
        "title": "Interstellar",
        "plot": "A team of explorers travel through a wormhole in space to ensure humanity's survival on a dying Earth.",
        "genre": "sci-fi", "year": 2014, "rating": 8.7, "director": "Christopher Nolan",
    },
    {
        "title": "The Shawshank Redemption",
        "plot": "A banker sentenced to life in prison forms an unlikely friendship and finds hope through acts of common decency.",
        "genre": "drama", "year": 1994, "rating": 9.3, "director": "Frank Darabont",
    },
    {
        "title": "Inception",
        "plot": "A thief who steals corporate secrets through dream-sharing technology is given the task of planting an idea in a target's mind.",
        "genre": "sci-fi", "year": 2010, "rating": 8.8, "director": "Christopher Nolan",
    },
    {
        "title": "The Dark Knight",
        "plot": "Batman faces the Joker, a criminal mastermind who plunges Gotham City into anarchy and forces the Dark Knight to confront his beliefs.",
        "genre": "action", "year": 2008, "rating": 9.0, "director": "Christopher Nolan",
    },
    {
        "title": "Pulp Fiction",
        "plot": "The lives of two mob hitmen, a boxer, a gangster, and his wife intertwine in four tales of violence and redemption.",
        "genre": "crime", "year": 1994, "rating": 8.9, "director": "Quentin Tarantino",
    },
    {
        "title": "The Matrix",
        "plot": "A computer hacker discovers that reality is a simulation created by machines and joins a rebellion to free humanity.",
        "genre": "sci-fi", "year": 1999, "rating": 8.7, "director": "The Wachowskis",
    },
    {
        "title": "Forrest Gump",
        "plot": "A slow-witted but kind-hearted man from Alabama witnesses and unwittingly influences several historical events in the 20th century.",
        "genre": "drama", "year": 1994, "rating": 8.8, "director": "Robert Zemeckis",
    },
    {
        "title": "Alien",
        "plot": "The crew of a commercial spaceship encounters a deadly extraterrestrial creature that begins hunting them one by one.",
        "genre": "horror", "year": 1979, "rating": 8.5, "director": "Ridley Scott",
    },
    {
        "title": "Goodfellas",
        "plot": "The story of Henry Hill and his life in the mob, covering his relationship with his wife and his mob partners.",
        "genre": "crime", "year": 1990, "rating": 8.7, "director": "Martin Scorsese",
    },
    {
        "title": "Blade Runner 2049",
        "plot": "A young blade runner discovers a long-buried secret that leads him to track down a former blade runner who has been missing for thirty years.",
        "genre": "sci-fi", "year": 2017, "rating": 8.0, "director": "Denis Villeneuve",
    },
]

print(f"Loaded {len(movies)} movies.")

Step 7: Embed and store the data

async def ingest_movies():
    plots   = [m["plot"] for m in movies]
    vectors = embed_texts(plots)

    points = []
    for i, (movie, vector) in enumerate(zip(movies, vectors)):
        points.append(PointStruct(
            id=i,
            vector=vector,
            payload={
                "title":    movie["title"],
                "plot":     movie["plot"],
                "genre":    movie["genre"],
                "year":     movie["year"],
                "rating":   movie["rating"],
                "director": movie["director"],
            },
        ))

    async with AsyncVectorAIClient(url=SERVER) as client:
        await client.points.upsert(COLLECTION, points=points)
        await client.vde.flush(COLLECTION)
        count = await client.vde.get_vector_count(COLLECTION)

    print(f"Stored {len(points)} movies. Total in collection: {count}")

asyncio.run(ingest_movies())

Expected output

After a successful upsert and flush, the stored count matches the number of points sent. The total reported by get_vector_count confirms all ten movies were persisted.

Stored 10 movies. Total in collection: 10

The ingestion pipeline runs through five stages.

embed_texts converts all 10 plots into 384-dimensional vectors in one batch.
Each movie becomes a PointStruct with an integer ID, the plot vector, and the full metadata as payload.
points.upsert sends the points to the server (“upsert” means insert-or-update).
vde.flush ensures the data is persisted to disk immediately.
vde.get_vector_count confirms how many vectors are stored.

Step 8: Run your first semantic search

async def search_movies(query: str, top_k: int = 5):
    query_vector = embed_text(query)

    async with AsyncVectorAIClient(url=SERVER) as client:
        results = await client.points.search(
            COLLECTION,
            vector=query_vector,
            limit=top_k,
            with_payload=True,
        ) or []

    return results

query   = "a suspenseful movie set in outer space"
results = asyncio.run(search_movies(query))

print(f"Query: \"{query}\"\n")
for r in results:
    p = r.payload
    print(f"  {r.score:.4f}  {p['title']} ({p['year']}) — {p['genre']} — ★{p['rating']}")

Parameter	Value	Purpose
`vector`	Query embedding	The search finds vectors closest to this one.
`limit=5`	Top 5 results	Maximum number of results to return.
`with_payload=True`	Include metadata	Returns title, genre, year, and other fields with each result.

Expected output

Query: "a suspenseful movie set in outer space"

4244  Alien (1979) — horror — ★8.5
3576  Interstellar (2014) — sci-fi — ★8.7
1724  Blade Runner 2049 (2017) — sci-fi — ★8.0
1622  The Dark Knight (2008) — action — ★9.0

In this example, the embedding model captures semantic similarity rather than exact keyword matching. The query “suspenseful movie set in outer space” returns “Alien” and “Interstellar” even though none of the exact query words appear in their plot descriptions. Search quality depends on the model and dataset.

limit is a maximum, not a guarantee. The number of results returned depends on how many points in the collection score above the internal threshold. Scores reflect the specific model and dataset — do not compare absolute score values across different models or collections.

Step 9: Filter by metadata

Filters restrict the candidate set before vector ranking. Actian VectorAI DB provides the Field and FilterBuilder classes for this purpose.

Filter by genre

async def search_by_genre(query: str, genre: str, top_k: int = 5):
    query_vector = embed_text(query)

    filter_obj = (
        FilterBuilder()
        .must(Field("genre").eq(genre))
        .build()
    )

    async with AsyncVectorAIClient(url=SERVER) as client:
        results = await client.points.search(
            COLLECTION,
            vector=query_vector,
            limit=top_k,
            filter=filter_obj,
            with_payload=True,
        ) or []

    return results

results = asyncio.run(search_by_genre("an exciting adventure", "sci-fi"))

print("Genre filter: sci-fi\n")
for r in results:
    p = r.payload
    print(f"  {r.score:.4f}  {p['title']} ({p['year']})")

Expected output

Genre filter: sci-fi

2818  Interstellar (2014)
2295  The Matrix (1999)
2080  Blade Runner 2049 (2017)

Filter by minimum rating

async def search_highly_rated(query: str, min_rating: float, top_k: int = 5):
    query_vector = embed_text(query)

    filter_obj = (
        FilterBuilder()
        .must(Field("rating").gte(min_rating))
        .build()
    )

    async with AsyncVectorAIClient(url=SERVER) as client:
        results = await client.points.search(
            COLLECTION,
            vector=query_vector,
            limit=top_k,
            filter=filter_obj,
            with_payload=True,
        ) or []

    return results

results = asyncio.run(search_highly_rated("intense crime story", 8.8))

print("Filter: rating >= 8.8\n")
for r in results:
    p = r.payload
    print(f"  {r.score:.4f}  {p['title']} — ★{p['rating']}")

Expected output

Filter: rating >= 8.8

4255  Pulp Fiction — ★8.9
3292  The Shawshank Redemption — ★9.3
3026  Inception — ★8.8
2964  Forrest Gump — ★8.8
2887  The Dark Knight — ★9.0

Step 10: Combine multiple filters

FilterBuilder supports three types of boolean logic.

Method	Meaning	SQL equivalent
`.must()`	All conditions must match.	`AND`
`.should()`	At least one condition should match.	`OR`
`.must_not()`	Exclude any points that match.	`NOT`

async def advanced_search(query: str, top_k: int = 5):
    query_vector = embed_text(query)

    filter_obj = (
        FilterBuilder()
        .must(Field("year").gte(2000))
        .must(Field("rating").gte(8.5))
        .must_not(Field("genre").eq("drama"))
        .build()
    )

    async with AsyncVectorAIClient(url=SERVER) as client:
        results = await client.points.search(
            COLLECTION,
            vector=query_vector,
            limit=top_k,
            filter=filter_obj,
            with_payload=True,
        ) or []

    return results

results = asyncio.run(advanced_search("mind-bending thriller"))

print("Filters: year >= 2000, rating >= 8.5, NOT drama\n")
for r in results:
    p = r.payload
    print(f"  {r.score:.4f}  {p['title']} ({p['year']}) — {p['genre']} — ★{p['rating']}")

Expected output

Filters: year >= 2000, rating >= 8.5, NOT drama

  0.2724  Inception (2010) — sci-fi — ★8.8

Step 11: Retrieve a specific movie by ID

async def get_movie(movie_id: int):
    async with AsyncVectorAIClient(url=SERVER) as client:
        points = await client.points.get(
            COLLECTION,
            ids=[movie_id],
            with_payload=True,
        )

    if not points:
        print(f"Movie {movie_id} not found.")
        return None

    p = points[0].payload
    print(f"ID {movie_id}: {p['title']} ({p['year']}) — {p['genre']} — ★{p['rating']}")
    print(f"  Plot: {p['plot']}")
    return points[0]

asyncio.run(get_movie(0))

Expected output

ID 0: Interstellar (2014) — sci-fi — ★8.7
  Plot: A team of explorers travel through a wormhole in space to ensure humanity's survival on a dying Earth.

Step 12: Update movie metadata

Payload fields can be updated without re-embedding the vector.

async def update_movie_rating(movie_id: int, new_rating: float):
    async with AsyncVectorAIClient(url=SERVER) as client:
        await client.points.set_payload(
            COLLECTION,
            payload={"rating": new_rating},
            ids=[movie_id],
        )
    print(f"Updated movie {movie_id} rating to ★{new_rating}")

asyncio.run(update_movie_rating(0, 8.8))
asyncio.run(get_movie(0))

Expected output

Updated movie 0 rating to ★8.8
ID 0: Interstellar (2014) — sci-fi — ★8.8
  Plot: A team of explorers travel through a wormhole in space to ensure humanity's survival on a dying Earth.

set_payload merges the provided fields into the existing payload. Three properties define its behaviour.

Merge behaviour: Only the specified fields are updated. All other fields in the existing payload remain unchanged.
No re-embedding: The vector stays the same — only the metadata is modified, so there is no reprocessing cost.
Immediate effect: Subsequent searches and retrievals reflect the updated values right away.

Add new fields

set_payload can also add entirely new keys to a point.

async def add_tags(movie_id: int, tags: list[str]):
    async with AsyncVectorAIClient(url=SERVER) as client:
        await client.points.set_payload(
            COLLECTION,
            payload={"tags": tags},
            ids=[movie_id],
        )
    print(f"Added tags to movie {movie_id}: {tags}")

asyncio.run(add_tags(0, ["space", "wormhole", "survival", "time-dilation"]))
asyncio.run(get_movie(0))

Expected output

Added tags to movie 0: ['space', 'wormhole', 'survival', 'time-dilation']
ID 0: Interstellar (2014) — sci-fi — ★8.8
  Plot: A team of explorers travel through a wormhole in space to ensure humanity's survival on a dying Earth.

This code calls add_tags with movie ID 0 and a list of four descriptive tags. The set_payload call merges the new tags field into the existing payload, leaving all previously stored fields — title, plot, genre, year, rating, and director — unchanged.

Step 13: Delete points

Delete by ID

async def delete_movie(movie_id: int):
    async with AsyncVectorAIClient(url=SERVER) as client:
        await client.points.delete(COLLECTION, ids=[movie_id])
        await client.vde.flush(COLLECTION)
        count = await client.vde.get_vector_count(COLLECTION)
    print(f"Deleted movie {movie_id}. Remaining: {count}")

asyncio.run(delete_movie(9))

Expected output

The vector count drops from 10 to 9, confirming that movie ID 9 (Blade Runner 2049) was removed from the collection.

Deleted movie 9. Remaining: 9

This code passes ID 9 — corresponding to “Blade Runner 2049”, the last movie in the dataset — to points.delete(). After the deletion, vde.get_vector_count reads the updated total and prints it so you can confirm the point was removed.

Delete by filter

async def delete_low_rated(min_rating: float):
    filter_obj = (
        FilterBuilder()
        .must(Field("rating").lt(min_rating))
        .build()
    )

    async with AsyncVectorAIClient(url=SERVER) as client:
        count_before = await client.vde.get_vector_count(COLLECTION)
        await client.points.delete(COLLECTION, filter=filter_obj)
        await client.vde.flush(COLLECTION)
        count_after = await client.vde.get_vector_count(COLLECTION)

    print(f"Deleted movies with rating < {min_rating}. Before: {count_before}, After: {count_after}")

# Uncomment the line below to run — this permanently removes points from the collection
# asyncio.run(delete_low_rated(8.6))

Step 14: Count points

The following snippet counts the total number of points in the collection, then runs filtered counts to check how many sci-fi movies exist, how many have a rating of 8.8 or higher, and how many were directed by Christopher Nolan.

async def count_movies():
    async with AsyncVectorAIClient(url=SERVER) as client:
        total = await client.vde.get_vector_count(COLLECTION)
        all_points, _ = await client.points.scroll(
            COLLECTION, limit=1000, with_payload=True, with_vectors=False,
        )

    sci_fi       = sum(1 for p in all_points if p.payload.get("genre") == "sci-fi")
    highly_rated = sum(1 for p in all_points if p.payload.get("rating", 0) >= 8.8)
    nolan        = sum(1 for p in all_points if p.payload.get("director") == "Christopher Nolan")

    print(f"Total movies: {total}")
    print(f"Sci-fi movies: {sci_fi}")
    print(f"Movies with rating >= 8.8: {highly_rated}")
    print(f"Christopher Nolan movies: {nolan}")

asyncio.run(count_movies())

Expected output

Counts reflect the state after Step 12 (Interstellar’s rating updated to 8.8) and Step 13 (Blade Runner 2049 deleted).

Total movies: 9
Sci-fi movies: 3
Movies with rating >= 8.8: 6
Christopher Nolan movies: 3

The rating >= 8.8 count is 6, not 5 as you might expect from the raw dataset. This is because Interstellar’s rating was updated from 8.7 to 8.8 in Step 12 before this count runs.

Step 15: Inspect collection status

async def inspect_collection():
    # Map raw integer enum values returned by the server to human-readable strings
    STATUS_MAP    = {1: "green", 2: "yellow", 3: "red"}
    VDE_STATE_MAP = {0: "active", 1: "inactive"}

    async with AsyncVectorAIClient(url=SERVER) as client:
        info  = await client.collections.get_info(COLLECTION)
        state = await client.vde.get_state(COLLECTION)
        count = await client.vde.get_vector_count(COLLECTION)

    print(f"Collection: {COLLECTION}")
    print(f"  Status:       {STATUS_MAP.get(info.status, info.status)}")
    print(f"  VDE state:    {VDE_STATE_MAP.get(state, state)}")
    print(f"  Vector count: {count}")

asyncio.run(inspect_collection())

Expected output

Collection: Movies
  Status:       green
  VDE state:    active
  Vector count: 9

collections.get_info() and vde.get_state() return raw integer enum values, not strings. Use the STATUS_MAP and VDE_STATE_MAP dictionaries above to convert them. A VDE state of active (integer 0) means the collection is ready for searches regardless of the Status value. A Status of red after deletions is normal and does not affect search quality.

This code connects to the server, calls collections.get_info to retrieve the collection’s operational status and vector configuration, then calls vde.get_state to read the current VDE lifecycle state, and finally calls vde.get_vector_count to confirm the number of stored vectors. All three values are printed together so you can verify the collection is healthy and correctly configured before running searches.

Step 16: List all collections

async def list_collections():
    async with AsyncVectorAIClient(url=SERVER) as client:
        names = await client.collections.list()

    print(f"Collections on server ({len(names)}):")
    for name in names:
        print(f"  - {name}")

asyncio.run(list_collections())

Expected output

Because only one collection was created in this tutorial, collections.list() returns a single entry. The count in the header updates automatically as collections are added or removed.

Collections on server (1):
  - Movies

This code calls collections.list(), which returns the names of all collections currently provisioned on the server. In this tutorial only one collection has been created, so the output lists Movies as the single entry.

Step 17: Put it all together — a complete search function

async def recommend_movies(
    query: str,
    genre:         str | None   = None,
    min_year:      int | None   = None,
    min_rating:    float | None = None,
    exclude_genre: str | None   = None,
    top_k: int = 5,
):
    """Recommend movies using semantic search with optional filters."""
    query_vector = embed_text(query)

    fb = FilterBuilder()
    if genre:
        fb = fb.must(Field("genre").eq(genre))
    if min_year is not None:       # explicit None check — 0 is a valid year
        fb = fb.must(Field("year").gte(min_year))
    if min_rating is not None:     # explicit None check — 0.0 is a valid rating
        fb = fb.must(Field("rating").gte(min_rating))
    if exclude_genre:
        fb = fb.must_not(Field("genre").eq(exclude_genre))
    filter_obj = fb.build()

    async with AsyncVectorAIClient(url=SERVER) as client:
        results = await client.points.search(
            COLLECTION,
            vector=query_vector,
            limit=top_k,
            filter=filter_obj,
            with_payload=True,
        ) or []

    filters_desc = []
    if genre:         filters_desc.append(f"genre={genre}")
    if min_year:      filters_desc.append(f"year>={min_year}")
    if min_rating:    filters_desc.append(f"rating>={min_rating}")
    if exclude_genre: filters_desc.append(f"NOT {exclude_genre}")

    print(f"\n  Query: \"{query}\"")
    print(f"  Filters: {', '.join(filters_desc) or 'none'}  |  results: {len(results)}\n")

    for r in results:
        p = r.payload
        print(f"    {r.score:.4f}  {p['title']} ({p['year']}) — {p['genre']} — ★{p['rating']}")
        print(f"           {p['plot'][:90]}…")
    print()

asyncio.run(recommend_movies("a mind-bending sci-fi movie"))

asyncio.run(recommend_movies(
    "an intense crime story",
    min_rating=8.8,
))

asyncio.run(recommend_movies(
    "a feel-good movie about life",
    exclude_genre="crime",
    min_year=1990,
))

Expected output

Three calls are made with different queries and filter combinations. Each block shows the active filters and how many results matched before the ranked list is printed.

  Query: "a mind-bending sci-fi movie"
  Filters: none  |  results: 5

    0.3180  The Matrix (1999) — sci-fi — ★8.7
           A computer hacker discovers that reality is a simulation created by machines and joins a r…
    0.2747  Alien (1979) — horror — ★8.5
           The crew of a commercial spaceship encounters a deadly extraterrestrial creature that begi…
    0.2609  Inception (2010) — sci-fi — ★8.8
           A thief who steals corporate secrets through dream-sharing technology is given the task of…

  Query: "an intense crime story"
  Filters: rating>=8.8  |  results: 2

    0.4317  Pulp Fiction (1994) — crime — ★8.9
           The lives of two mob hitmen, a boxer, a gangster, and his wife intertwine in four tales of…
    0.3621  The Shawshank Redemption (1994) — drama — ★9.3
           A banker sentenced to life in prison forms an unlikely friendship and finds hope through a…

  Query: "a feel-good movie about life"
  Filters: NOT crime, year>=1990  |  results: 5

    0.3058  The Shawshank Redemption (1994) — drama — ★9.3
           A banker sentenced to life in prison forms an unlikely friendship and finds hope through a…
    0.1866  Forrest Gump (1994) — drama — ★8.8
           A slow-witted but kind-hearted man from Alabama witnesses and unwittingly influences sever…
    …

The first call searches without any filters. The second applies min_rating >= 8.8. The third combines exclude_genre="crime" with min_year=1990. Each call prints the query, active filters, result count, and ranked movies with truncated plot descriptions.

Step 18: Cleanup

async def cleanup():
    async with AsyncVectorAIClient(url=SERVER) as client:
        count = await client.vde.get_vector_count(COLLECTION)
        print(f"Collection '{COLLECTION}' contains {count} movies.")

        await client.vde.flush(COLLECTION)
        print("Data flushed to disk.")

        # Uncomment the next two lines to permanently delete the collection:
        # await client.collections.delete(COLLECTION)
        # print(f"Collection '{COLLECTION}' deleted.")

asyncio.run(cleanup())

Expected output

The vector count reflects the state of the collection after all previous steps. The flush confirmation line indicates that any pending writes have been safely persisted to disk.

Collection 'Movies' contains 9 movies.
Data flushed to disk.

This code reads the current vector count from the collection, prints it, then calls vde.flush to ensure any pending writes are persisted to disk. The two lines that delete the collection are commented out — they are safe to uncomment when the tutorial data is no longer needed, but the collection is preserved by default so the data remains available for further experimentation.

What you learned

Concept	API	What it does
Connect	`AsyncVectorAIClient(url=...)`	Open a gRPC connection to VectorAI DB.
Health check	`client.health_check()`	Verify the server is reachable.
Create collection	`collections.get_or_create(vectors_config=VectorParams(...))`	Define a vector space with dimension and distance metric.
Embed text	`SentenceTransformer.encode()`	Convert text to a numerical vector.
Store data	`points.upsert(collection, points=[PointStruct(...)])`	Insert or update points with vectors and metadata.
Persist	`vde.flush(collection)`	Write pending data to disk.
Semantic search	`points.search(collection, vector=..., limit=5)`	Find the most similar vectors.
Filter (equality)	`Field("genre").eq("sci-fi")`	Match a specific value.
Filter (range)	`Field("rating").gte(8.5)`	Numeric comparison.
Filter (exclude)	`FilterBuilder().must_not(...)`	Exclude matching points.
Combine filters	`FilterBuilder().must(...).must(...).build()`	Boolean AND/OR/NOT logic.
Get by ID	`points.get(collection, ids=[0])`	Retrieve specific points.
Update metadata	`points.set_payload(collection, payload={...}, ids=[0])`	Merge new fields into existing payloads.
Delete by ID	`points.delete(collection, ids=[0])`	Remove specific points.
Delete by filter	`points.delete(collection, filter=...)`	Remove points matching conditions.
Count	`vde.get_vector_count()` + `points.scroll()`	Total and filtered counts.
Collection info	`collections.get_info(collection)`	Status and configuration.
Collection state	`vde.get_state(collection)`	VDE lifecycle state.
List collections	`collections.list()`	All collection names on the server.
Delete collection	`collections.delete(collection)`	Remove a collection entirely.

Common patterns quick reference

Pattern 1: Search with optional filters

Use is not None rather than a truthiness check to avoid silently skipping valid falsy values such as 0.0.

fb = FilterBuilder()
if genre:
    fb = fb.must(Field("genre").eq(genre))
if min_rating is not None:
    fb = fb.must(Field("rating").gte(min_rating))
filter_obj = fb.build()

Pattern 2: Upsert is idempotent

Calling upsert with the same ID replaces the existing point, so ingestion scripts can be re-run safely without creating duplicates. This makes bulk ingestion pipelines robust to restarts.

Pattern 3: Always flush after writes

Call vde.flush() immediately after points.upsert() to ensure data survives server restarts. Without it, recent writes may be lost if the server crashes.

await client.points.upsert(COLLECTION, points=points)
await client.vde.flush(COLLECTION)

Pattern 4: Use `get_or_create` for collections

get_or_create is safe to run on every application startup. It creates the collection if it does not exist and does nothing if it already does, so startup code does not need a separate existence check.

await client.collections.get_or_create(name=COLLECTION, vectors_config=...)

Next steps

Predicate filters — Master the full Filter DSL with all field types and operators.
Similarity search fundamentals — Explore search parameters, score thresholds, and pagination.
Use open-source embedding models — Choose the right model for production.
Optimizing retrieval quality — Tune HNSW parameters and search settings.

Predicate filters

Master the full Filter DSL with all field types and operators.

Similarity search fundamentals

Explore search parameters, score thresholds, and pagination.

Use open-source embedding models

Choose the right model and configure quantization for production.

Optimizing retrieval quality

Tune HNSW parameters, quantization, and search settings.

​What you build

​Prerequisites

​Step 1: Install dependencies

​Step 2: Import libraries and configure

​Expected output

​Step 3: Connect to the server

​Expected output

​Step 4: Create a collection

​Why use get_or_create

​Expected output

​Step 5: Create embedding helpers

​Expected output

​Step 6: Prepare your data

​Step 7: Embed and store the data

​Expected output

​Step 8: Run your first semantic search

​Expected output

​Step 9: Filter by metadata

​Filter by genre

​Expected output

​Filter by minimum rating

​Expected output

​Step 10: Combine multiple filters

​Expected output

​Step 11: Retrieve a specific movie by ID

​Expected output

​Step 12: Update movie metadata

​Expected output

​Add new fields

​Expected output

​Step 13: Delete points

​Delete by ID

​Expected output

​Delete by filter

​Step 14: Count points

​Expected output

​Step 15: Inspect collection status

​Expected output

​Step 16: List all collections

​Expected output

​Step 17: Put it all together — a complete search function

​Expected output

​Step 18: Cleanup

​Expected output

​What you learned

​Common patterns quick reference

​Pattern 1: Search with optional filters

​Pattern 2: Upsert is idempotent

​Pattern 3: Always flush after writes

​Pattern 4: Use get_or_create for collections

​Next steps

Predicate filters

Similarity search fundamentals

Use open-source embedding models

Optimizing retrieval quality

What you build

Prerequisites

Step 1: Install dependencies

Step 2: Import libraries and configure

Expected output

Step 3: Connect to the server

Expected output

Step 4: Create a collection

Why use `get_or_create`

Expected output

Step 5: Create embedding helpers

Expected output

Step 6: Prepare your data

Step 7: Embed and store the data

Expected output

Step 8: Run your first semantic search

Expected output

Step 9: Filter by metadata

Filter by genre

Expected output

Filter by minimum rating

Expected output

Step 10: Combine multiple filters

Expected output

Step 11: Retrieve a specific movie by ID

Expected output

Step 12: Update movie metadata

Expected output

Add new fields

Expected output

Step 13: Delete points

Delete by ID

Expected output

Delete by filter

Step 14: Count points

Expected output

Step 15: Inspect collection status

Expected output

Step 16: List all collections

Expected output

Step 17: Put it all together — a complete search function

Expected output

Step 18: Cleanup

Expected output

What you learned

Common patterns quick reference

Pattern 1: Search with optional filters

Pattern 2: Upsert is idempotent

Pattern 3: Always flush after writes

Pattern 4: Use `get_or_create` for collections

Next steps