Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vectoraidb.actian.com/llms.txt

Use this file to discover all available pages before exploring further.

This short guide shows you how to create a collection, insert vectors, and perform similarity search using the Python SDK.
VectorAI DB Required: This quickstart requires VectorAI DB running in a Docker container. Docker deployment is the only supported version at the moment. Setup Instructions →

​
Prerequisites

To use the Python SDK, make sure you have:
  • Python 3.10 or later
  • numpy 1.26 or later
  • grpcio 1.80 or later
  • pydantic 2.10 or later
Follow these steps to install and begin using the SDK:

​
Step 1: Install the SDK

Install the VectorAI DB Python SDK using pip: 
pip install actian-vectorai-client

​
Step 2: Run the Docker container

Download and run the VectorAI DB Docker container: 
docker pull actian/vectorai:latest
docker run -d --name vectorai \
  -v ./local_data:/var/lib/actian-vectorai \
  -p 6573-6575:6573-6575 \
  -e ACTIAN_VECTORAI_ACCEPT_EULA=YES \
  actian/vectorai:latest
Port 6573 is for the RESTful API, 6574 for gRPC, and 6575 for Local UI. The /var/lib/actian-vectorai directory is the containers location for storing Actian VectorAI DB. It should be volume-mounted to persist the data. This command hosts the RESTful API on localhost:6573, the server on localhost:6574, and the Local UI on localhost:6575.

​
Step 3: Create a collection

Connect to the VectorAI server and create a collection named products with dimension 128 and cosine distance metric. 
from actian_vectorai import VectorAIClient, VectorParams, Distance

with VectorAIClient("localhost:6574") as client:
    # Check server connection
    info = client.health_check()
    print(f"Connected to {info['title']} v{info['version']}")
    
    # Create collection
    client.collections.create(
        "products",
        vectors_config=VectorParams(size=128, distance=Distance.Cosine)
    )
    print("Collection 'products' created successfully")

​
Step 4: Generate sample data

Create a function to generate sample product vectors with metadata: 
import random
from typing import List
from actian_vectorai import PointStruct

def generate_sample_products(
    num_products: int = 100,
    dimension: int = 128,
    base_price: float = 10.0,
    price_variance: float = 100.0,
    seed: int = None
) -> List[PointStruct]:
    if seed is not None:
        random.seed(seed)
    
    categories = ["electronics", "clothing", "food"]
    points = []
    
    for i in range(num_products):
        category = categories[i % 3]
        price = float(i * base_price + random.random() * price_variance)
        in_stock = (i % 2 == 0)
        
        points.append(
            PointStruct(
                id=i,
                vector=[random.gauss(0, 1) for _ in range(dimension)],
                payload={
                    "id": i,
                    "category": category,
                    "price": round(price, 2),
                    "in_stock": in_stock,
                }
            )
        )
    
    return points

​
Step 5: Insert vectors

Generate and insert vectors into the collection: 
from actian_vectorai import VectorAIClient

NUM_VECTORS = 100
DIMENSION = 128

with VectorAIClient("localhost:6574") as client:
    print(f"Inserting {NUM_VECTORS} vectors...")
    
    # Generate sample data
    points = generate_sample_products(
        NUM_VECTORS, 
        DIMENSION, 
        seed=42
    )

    # Batch insert
    client.points.upsert("products", points)
    print(f"✓ Inserted {NUM_VECTORS} vectors")
    
    # Verify count
    count = client.points.count("products")
    print(f"Vector count: {count}")

​
Step 6: Search for similar vectors

Perform similarity search to find the top five most similar vectors: 
from actian_vectorai import VectorAIClient
import random

DIMENSION = 128
COLLECTION = "products"

with VectorAIClient("localhost:6574") as client:
    # Search for similar vectors
    print("Searching for similar vectors...")
    query = [random.gauss(0, 1) for _ in range(DIMENSION)]
    results = client.points.search(COLLECTION, vector=query, limit=5)
    
    print(f"Found {len(results)} results:")
    for i, result in enumerate(results):
        print(f"[{i+1}] ID: {result.id}, Score: {result.score:.4f}")
    
    # Get vector with payload
    print("\nRetrieving vector details...")
    retrieved = client.points.get(COLLECTION, ids=[results[0].id])
    print(f"Top result payload: {retrieved[0].payload}")
Example output: 
Searching for similar vectors...
Found 5 results:
[1] ID: 39, Score: 29.2119
[2] ID: 54, Score: 27.3639
[3] ID: 76, Score: 23.6023
[4] ID: 31, Score: 21.2087
[5] ID: 22, Score: 17.9858

Retrieving vector details...
Top result payload: {'price': 451.6, 'id': 39, 'in_stock': False, 'category': 'electronics'}

​
Step 7: Delete collection

When you’re done, clean up by deleting the collection: 
from actian_vectorai import VectorAIClient

with VectorAIClient("localhost:6574") as client:
    client.collections.delete("products")
    print("Collection 'products' deleted successfully")

​
Next steps

Documentation

Explore complete technical documentation