Actian VectorAI DB

Actian VectorAI DB and Python client

The Actian VectorAI DB and Python client. Please review the Known Issues section before deploying.

What is VectorAI DB?

Actian VectorAI DB is a vector database — a specialized database for AI applications that search by meaning, not just keywords. Think of it like this:

• Regular database: "Find products named 'laptop'"
• Vector database: "Find products similar to 'portable computer for students'"

Common use cases: RAG chatbots, semantic search, recommendation engines, anomaly detection.

Important: VectorAI DB does not include an embedding model. You need to bring your own (e.g. sentence-transformers, OpenAI embeddings). It handles storage and search — you handle the embeddings.

About gRPC: The database communicates over gRPC under the hood — you don't need to know anything about it. The Python client handles it for you. If you see gRPC in an error message, it's a connection issue, not a code issue.

How vector embeddings work

Your data gets converted into arrays of numbers called vectors that capture the meaning of the original content. VectorAI DB stores and indexes these for fast semantic search.

What Can You Build?

VectorAI DB is the storage-and-search layer. Pair it with an embedding model and you can build:

• RAG (Retrieval-Augmented Generation) — Chunk documents, embed them, retrieve relevant chunks to ground an LLM. Model: all-MiniLM-L6-v2 (384d, COSINE). See examples/rag/.

• Semantic Search — Index documents, products, or notes and search by meaning instead of keywords. Model: all-MiniLM-L6-v2 (384d) or all-mpnet-base-v2 (768d) for higher quality. See examples/semantic_search.py.
• Recommendation Engine — Embed item descriptions or user preferences, find similar items via nearest-neighbor search. Model: all-MiniLM-L6-v2 (384d). Same API pattern as search.
• Image Similarity Search — Embed images (and optionally text) with CLIP, search across modalities. Model: openai/clip-vit-base-patch32 (512d).
• Code Search — Embed code snippets and docstrings, search codebases by natural language. Model: microsoft/codebert-base (768d).

Popular Embedding Models

Pick a model, embed your data, store the vectors in VectorAI DB. All models below are available on Hugging Face and installable via pip install sentence-transformers or pip install transformers.

• sentence-transformers/all-MiniLM-L6-v2 — 384d, fast general-purpose text embeddings (great default choice)
• sentence-transformers/all-mpnet-base-v2 — 768d, higher quality text embeddings
• BAAI/bge-small-en-v1.5 — 384d, strong quality-to-speed ratio
• openai/clip-vit-base-patch32 — 512d, multimodal (text + images)
• microsoft/codebert-base — 768d, code understanding

Supported platforms

• The VectorAI DB Docker image is currently supported only on Linux/amd64 (x86_64).

  • Supported on Windows using WSL2 (Docker Desktop or Podman Desktop).
  • macOS support on Apple chipsets (M2/M3/M4) through Rosetta 2 and specifying linux/amd64 as platform.
    • Install Rosetta 2 by running softwareupdate --install-rosetta --agree-to-license.
    • Add --platform linux/amd64 to Docker commands.
    • Note: M4 Apple Silicons might encounter a GRPC disconnection error without any container logs. In this case, disable Rosetta in Docker Desktop

• The Python client package is supported on all major platforms (Windows, macOS, and Linux).

  • Python 3.10 or higher is required.

Features

• 🚀 Async & Sync clients - Full async/await support with AsyncCortexClient
• 🔐 Persistent storage - Production-grade data persistence
• 🔍 Type-safe Filter DSL - Fluent API for payload filtering
• ⚡ Smart Batching - Automatic request batching for high throughput
• 📦 Pydantic models - Type hints and validation throughout
• 🎯 gRPC transport - High-performance communication

Quick Install – Pull from DockerHub

1. Make sure you have Docker installed. Note to Mac users with Apple Silicon: Docker Desktop automatically handles running this amd64 image on your ARM Mac.

2. Clone this repository.

3. Start the database:

   docker compose up

Or run in the background:

   docker compose up -d

The database will be available at localhost:50051. The docker-compose.yml file handles the base config required.

4. To stop the container:

   docker compose down

Setup for M1 Macbook Users

Step 1: Clone repo from GitHub

Step 2: Have Docker Desktop running

Step 3: Run docker compose up in the root folder of the db. Note: you might encounter a platform incompatibility warning, you can ignore that

Step 4: In a new terminal window in the same folder make the Python virtual environment using python3.11 -m venv .venv

Step 5: Run source .venv/bin/activate to activate virtual environment

Step 6: Run pip install ./actiancortex-0.1.0b1-py3-none-any.whl to install the VectorAI DB Python client from the bundled wheel file

Step 7: Validate by running PYTHONPATH=. python examples/quick_start.py

📥 Docker container installation – with the .tar image file (not included in this repository)

Load the container archive into your container environment:

docker image load -i Actian_VectorAI_DB_Beta.tar

Container ports and volumes

The container exposes port 50051 and stores its logs and persisted collections in the /data directory, which you should map to a host directory to persist data outside the container.

Port conflict? If port 50051 is already in use, change the host port in the compose file:

ports:
  - "50052:50051"  # Use any free port on the left side

Then connect with CortexClient("localhost:50052").

Deploy container with Docker run

To deploy the container using docker run:

docker run -d --name vectoraidb -v ./data:/data -p 50051:50051 localhost/actian/vectoraidb:1.0b

Deploy container with Docker compose

To deploy the container using docker compose, create a docker-compose.yml file with this service definition and start it with docker compose up.

services:
    vectoraidb:
       image: localhost/actian/vectoraidb:1.0b
       #platform: linux/amd64   # Uncomment on macOS
       container_name: vectoraidb
       ports:
         - "50051:50051"
       volumes:
         - ./data:/data
       restart: unless-stopped
       stop_grace_period: 2m

Note: Collections and logs are persisted under the mounted /data directory

Examine container logs

The VectorAI DB server writes useful informational messages and errors to its log. These logs are often the best place to start when diagnosing failed requests or unexpected behavior.

You can access the server logs in two ways:

• Use docker logs <container-name> to stream or inspect the container logs directly.
• Read the log file at /data/vde.log from the host directory you mapped to /data when starting the container.

📥 Python environment setup

Here's how to create and activate a virtual environment:

Linux/macOS:

python -m venv .venv
source .venv/bin/activate

Windows (Command Prompt):

python -m venv .venv
.venv\Scripts\activate.bat

Windows (PowerShell):

python -m venv .venv
.venv\Scripts\Activate.ps1

📥 Install Python client

Install the Python client with pip:

pip install actiancortex-0.1.0b1-py3-none-any.whl

For detailed API documentation, see docs/api.md.

🚀 Quickstart

Sync client and async client quickstarts are available.

Sync client

from cortex import CortexClient, DistanceMetric

with CortexClient("localhost:50051") as client:
    # Health check
    version, uptime = client.health_check()
    print(f"Connected to {version}")

    # Create collection
    client.create_collection(
        name="products",
        dimension=128,
        distance_metric=DistanceMetric.COSINE,
    )

    # Insert vectors
    client.upsert("products", id=0, vector=[0.1]*128, payload={"name": "Product A"})

    # Batch insert
    client.batch_upsert(
        "products",
        ids=[1, 2, 3],
        vectors=[[0.2]*128, [0.3]*128, [0.4]*128],
        payloads=[{"name": f"Product {i}"} for i in [1, 2, 3]],
    )

    # Search
    results = client.search("products", query=[0.1]*128, top_k=5)
    for r in results:
        print(f"ID: {r.id}, Score: {r.score}")

    # Cleanup
    client.delete_collection("products")

Async client

import asyncio
from cortex import AsyncCortexClient

async def main():
    async with AsyncCortexClient("localhost:50051") as client:
        # All methods are async
        await client.create_collection("demo", 128)
        await client.upsert("demo", id=0, vector=[0.1]*128)
        results = await client.search("demo", [0.1]*128, top_k=5)
        await client.delete_collection("demo")

asyncio.run(main())

Note: To use the sync CortexClient in async contexts (e.g., MCP servers, FastAPI), wrap calls with asyncio.to_thread(). For fully async code, use AsyncCortexClient instead.

What Can I Do With Retrieved Vectors?

Once you retrieve results, the payload is where your real data lives. Some ideas:

• RAG: Feed the retrieved text chunks into an LLM (OpenAI, Ollama, etc.) as context
• Recommendations: Use the returned IDs to look up items in your own database
• Anomaly detection: Flag results whose score falls below a similarity threshold
• Note-taking / personal search: Store notes as vectors, search them by meaning later

Results look like this:

for result in results:
    print(result.score)    # similarity score
    print(result.payload)  # your original data, e.g. {"text": "...", "source": "..."}

📚 Core API

Collection management

Method	Description
create_collection(name, dimension, ...)	Create new collection
delete_collection(name)	Delete collection
has_collection(name)	Check if exists
collection_exists(name)	Alias for has_collection
recreate_collection(name, dimension, ...)	Delete and recreate
open_collection(name)	Open for operations
close_collection(name)	Close collection

Vector operations

Method	Description
upsert(collection, id, vector, payload)	Insert/update single vector
batch_upsert(collection, ids, vectors, payloads)	Batch insert
get(collection, id)	Get vector by ID
get_many(collection, ids)	Get multiple vectors
retrieve(collection, ids)	Alias for get_many
delete(collection, id)	Delete vector
count(collection)	Get vector count
scroll(collection, limit, cursor)	Paginate through vectors

Search operations

Method	Description
search(collection, query, top_k)	K-NN search
search_filtered(collection, query, filter, top_k)	Filtered search

Maintenance

Method	Description
flush(collection)	Flush to disk
get_stats(collection)	Get statistics
health_check()	Check server health

🔍 Filter DSL

Type-safe filter building for payload queries:

from cortex.filters import Filter, Field

# Simple conditions
filter = Filter().must(Field("category").eq("electronics"))

# Range conditions
filter = Filter().must(Field("price").range(gte=100, lte=500))

# Combined conditions
filter = (
    Filter()
    .must(Field("category").eq("electronics"))
    .must(Field("price").lte(500))
    .must_not(Field("deleted").eq(True))
)

# Use in search
results = client.search_filtered("products", query_vector, filter, top_k=10)

📖 Examples

🌟 Featured: End-to-End RAG Example

New to vector databases? Start here! The RAG example shows how VectorAI DB integrates into a complete AI application:

# Install dependencies
pip install -r examples/rag/requirements.txt

# Run the RAG example
python examples/rag/rag_example.py

See examples/rag/README.md for a detailed walkthrough of building a Retrieval-Augmented Generation application.

Other Examples

# Quick start - recommended starting point
python examples/quick_start.py

# Semantic search with filtering
python examples/semantic_search.py

# Async operations
python examples/async_example.py

# Batch operations
python examples/batch_upsert.py

📊 Storage

Cortex uses persistent storage as the default backend. This provides:

• ✅ Production-grade persistence
• ✅ Transactional safety
• ✅ High-performance I/O

🔧 Configuration

HNSW parameters

client.create_collection(
    name="vectors",
    dimension=128,
    hnsw_m=32,              # Edges per node (default: 16)
    hnsw_ef_construct=256,  # Build-time neighbors (default: 200)
    hnsw_ef_search=100,     # Search-time neighbors (default: 50)
)

Distance metrics

• COSINE - Cosine similarity (default, recommended for normalized vectors)
• EUCLIDEAN - L2 distance
• DOT - Dot product

📦 Dependencies

• grpcio>=1.68.1 - gRPC transport
• protobuf>=5.29.2 - Protocol buffers
• numpy>=2.2.1 - Vector operations
• pydantic>=2.10.4 - Data validation

🐞 Known issues

• CRTX-202: Closing or deleting collections while read/write operations are in progress is not supported.
• CRTX-232: scroll API uses the term cursor to indicate the offset.
• CRTX-233: get_many API does not return the vector IDs.

📄 License

Proprietary - Actian Corporation

---

Copyright © 2025-2026 Actian Corporation. All Rights Reserved.