Basic similarity search

Search for the most similar vectors to your query.

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.

Python

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).

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:

Python

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:

Python

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:

Python

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:

Python

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.