Basic similarity search

Basic search returns the most similar vectors to your query. Provide a query vector and the number of results to return. VectorAI DB uses your collection’s distance metric to rank results by similarity. This is the fastest search type because it performs only vector similarity computation without additional filtering or data retrieval. Use it when you need only semantic similarity without metadata filtering.

import asyncio
from actian_vectorai import AsyncVectorAIClient
import random

async def main():
    # Connect to VectorAI DB server
    async with AsyncVectorAIClient("localhost:6574") as client:
        # Generate or use your query vector
        query_vector = [random.gauss(0, 1) for _ in range(128)]
        
        # Search for top 10 similar vectors
        results = await client.points.search(
            "my_collection",  # Collection name
            vector=query_vector,  # Query vector
            limit=10  # Number of results
        )
        
        # Display results
        for result in results:
            print(f"ID: {result.id}, Score: {result.score}")

asyncio.run(main())

Each result includes these fields:

id: The unique identifier of the matching point.
score: Similarity score based on the collection’s distance metric.
payload: Metadata dictionary (only if with_payload=True).
vector: Vector embedding (only if with_vectors=True).

Search with payload filters

Filtered search combines vector similarity with metadata conditions. The filter evaluates alongside vector similarity, not instead of it. Use filtered search to combine semantic search with business rules like price ranges, availability status, or category restrictions.

import asyncio
from actian_vectorai import AsyncVectorAIClient, FilterBuilder, Field
import random

async def main():
    async with AsyncVectorAIClient("localhost:6574") as client:
        # Generate query vector
        query_vector = [random.gauss(0, 1) for _ in range(128)]

        # Build filter: electronics under $500
        filter = FilterBuilder()\
            .must(Field("category").eq("electronics"))\
            .must(Field("price").lt(500.0))\
            .build()

        # Search with filter
        results = await client.points.search(
            "my_collection",
            vector=query_vector,
            limit=10,
            filter=filter
        )

        for result in results:
            print(f"Product: {result.payload['name']}")
            print(f"Price: ${result.payload['price']}")
            print(f"Score: {result.score}")

asyncio.run(main())

Learn more about filter syntax and operators in the filtering documentation.

Each result includes these fields:

id: The unique identifier of the matching point.
score: Similarity score for points that passed the filter.
payload: Metadata dictionary showing filtered attributes.

Universal query API

The query() method provides a unified interface for all search operations, including vector search, payload-based ordering, and batch queries. This API simplifies complex queries and offers more flexibility than the basic search() method.

Basic query

Use query() for standard vector search:

import asyncio
from actian_vectorai import AsyncVectorAIClient
import random

async def main():
    # Connect to VectorAI DB server
    async with AsyncVectorAIClient("localhost:6574") as client:
        # Generate query vector
        query_vector = [random.gauss(0, 1) for _ in range(128)]
        
        # Query with vector
        results = await client.points.query(
            "my_collection",  # Collection name
            query=query_vector,  # Query vector
            limit=10  # Number of results
        )
        
        # Display results
        for result in results:
            print(f"ID: {result.id}, Score: {result.score}")
            print(f"Payload: {result.payload}")

asyncio.run(main())

Each result includes these fields:

id: The unique identifier of the matching point.
score: Similarity score based on the collection’s distance metric.
payload: Metadata dictionary containing point data.

Order by payload field

Sort results by payload fields without using vectors:

import asyncio
from actian_vectorai import AsyncVectorAIClient

async def main():
    # Connect to VectorAI DB server
    async with AsyncVectorAIClient("localhost:6574") as client:
        # Sort by price (ascending)
        results = await client.points.query(
            "products",  # Collection name
            order_by="price",  # Sort field
            limit=10  # Number of results
        )
        
        # Display cheapest products
        print("Cheapest products:")
        for result in results:
            print(f"{result.payload['name']}: ${result.payload['price']}")
        
        # Sort by price (descending)
        results = await client.points.query(
            "products",  # Collection name
            order_by="-price",  # Prefix with '-' for descending
            limit=10  # Number of results
        )
        
        # Display most expensive products
        print("\nMost expensive products:")
        for result in results:
            print(f"{result.payload['name']}: ${result.payload['price']}")

asyncio.run(main())

Each result includes these fields:

id: The unique identifier of the point.
payload: Metadata dictionary containing the point data.
score: Ordering score (may be null when using order_by without vector query).

Order-by queries support these scenarios:

Find highest or lowest prices.
Sort by date, newest or oldest.
Rank by rating or popularity.
Browse without semantic search.

Batch queries

Execute multiple queries in a single request:

import asyncio
from actian_vectorai import AsyncVectorAIClient
import random

async def main():
    # Connect to VectorAI DB server
    async with AsyncVectorAIClient("localhost:6574") as client:
        # Create multiple query vectors
        queries = [
            [random.gauss(0, 1) for _ in range(128)]  # Generate query vector
            for _ in range(5)  # Create 5 queries
        ]
        
        # Batch query
        batch_results = await client.points.query_batch(
            "my_collection",  # Collection name
            queries=queries,  # List of query vectors
            limit=5  # Results per query
        )
        
        # Process results for each query
        for i, results in enumerate(batch_results):
            print(f"\nQuery {i + 1} results:")
            for result in results:
                print(f"  ID: {result.id}, Score: {result.score:.4f}")

asyncio.run(main())

Batch queries provide these advantages:

Single network round trip for multiple queries
Better throughput than individual requests
Reduced server overhead
Ideal for multiquery RAG applications

The method returns a list of result sets, one for each query. Each result set contains:

id: The unique identifier of the matching point.
score: Similarity score for the query.
payload: Metadata dictionary if requested.
vector: Vector embedding if requested.

Query with filters and ordering

Combine vector search with filters and custom ordering:

import asyncio
from actian_vectorai import AsyncVectorAIClient, FilterBuilder, Field
import random

async def main():
    # Connect to VectorAI DB server
    async with AsyncVectorAIClient("localhost:6574") as client:
        # Generate query vector
        query_vector = [random.gauss(0, 1) for _ in range(128)]
        
        # Complex query: vector search + filter + sort
        filter = FilterBuilder()\
            .must(Field("category").eq("electronics"))\
            .must(Field("in_stock").eq(True))\
            .build()
        
        # Search with filter and ordering
        results = await client.points.query(
            "products",  # Collection name
            query=query_vector,  # Query vector
            filter=filter,  # Apply filter
            order_by="price",  # Sort results by price
            limit=10  # Number of results
        )
        
        # Display results
        print("Electronics in stock, sorted by price:")
        for result in results:
            print(f"{result.payload['name']}: "
                  f"${result.payload['price']} "
                  f"(similarity: {result.score:.3f})")

asyncio.run(main())

Each result includes these fields:

id: The unique identifier of the matching point.
score: Relevance score based on similarity or ordering criteria.
payload: Metadata dictionary containing the point data.

Choose between query() and search()

Use query() when:

Sorting by payload fields (order-by)
Running batch queries
You need the unified API for consistency
Building flexible query systems

Use search() when:

Pure vector similarity search
Simpler code is preferred
Using established search patterns
No need for order-by or batching

Interpret semantic search results

Each search result contains these components:

Required fields

id: Vector identifier as an integer.
score: Similarity measure as a float.

Optional fields

payload: Metadata dictionary when with_payload=True.
vector: Embedding array when with_vectors=True.

​Search with payload filters

​Universal query API

​Basic query

​Order by payload field

​Batch queries

​Query with filters and ordering

​Choose between query() and search()

​Interpret semantic search results

​Required fields

​Optional fields

Search with payload filters

Universal query API

Basic query

Order by payload field

Batch queries

Query with filters and ordering

Choose between query() and search()

Interpret semantic search results

Required fields

Optional fields