Python client for Antarys vector database, optimized for large-scale vector operations with built-in caching, parallel processing, and dimension validation.

Antarys Python SDK

Data exchange using a Antarys REST API

Your LLM

RAG

Python client for Antarys vector database, optimized for large-scale vector operations with built-in caching, parallel processing, and dimension validation.

Requirements: Python 3.7+ and asyncio support required

Warning: since Antarys is in preview major API can occur and bugs might be appear, report your issues here

Installation

Install the Package

Install via pip package

pip install antarys

Optional Performance Dependencies

For accelerated performance, install additional dependencies:

pip install numba lz4

These dependencies significantly improve performance for large-scale operations but are not required for basic usage.

Quick Start

Here's a complete example to get you started:

import asyncio
from antarys import Client

async def main():
    # Initialize client with performance optimizations
    client = Client(
        host="http://localhost:8080",
        connection_pool_size=100,  # Auto-sized based on CPU count
        use_http2=True,
        cache_size=1000,
        thread_pool_size=16
    )

    # Create collection
    await client.create_collection(
        name="my_vectors",
        dimensions=1536,
        enable_hnsw=True,
        shards=16
    )

    vectors = client.vector_operations("my_vectors")

    # Upsert vectors
    await vectors.upsert([
        {"id": "1", "values": [0.1] * 1536, "metadata": {"category": "A"}},
        {"id": "2", "values": [0.2] * 1536, "metadata": {"category": "B"}}
    ])

    # Query similar vectors
    results = await vectors.query(
        vector=[0.1] * 1536,
        top_k=10,
        include_metadata=True
    )

    await client.close()

asyncio.run(main())

Pro Tip: Always remember to call await client.close() to properly cleanup resources!

Core Concepts

Collections

Collections are containers for your vectors with specific configurations for optimal performance.

# Create collection with optimized parameters
await client.create_collection(
    name="vectors",
    dimensions=1536,  # Required: vector dimensions
    enable_hnsw=True,  # Enable HNSW indexing for fast ANN
    shards=16,  # Parallel processing shards
    m=16,  # HNSW connectivity parameter
    ef_construction=200  # HNSW construction quality
)

# List collections
collections = await client.list_collections()
for collection in collections:
    print(f"Collection: {collection['name']}")

# Delete collection
await client.delete_collection("vectors")

Warning: This operation is irreversible and will delete all vectors in the collection.

Vector Operations

Single Vector Operations

Upsert Vectors

Insert or update vectors in your collection

Query Vectors

Search for similar vectors using various algorithms

Delete Vectors

Remove vectors by ID from your collection

Upsert

vectors = client.vector_operations("my_collection")

data = [
    {
        "id": "1",
        "values": [0.1, 0.2, 0.3],  # Must match collection dimensions
        "metadata": {"category": "example", "timestamp": 1234567890}
    },
    {
        "id": "2", 
        "values": [0.4, 0.5, 0.6],  # Must match collection dimensions
        "metadata": {"category": "example", "timestamp": 1234567891}
    }
]

# Upsert single vector
await vectors.upsert(data)

Batch Operations for Large Scale Data

Performance Tip: Use batch operations for inserting large amounts of data to maximize throughput.

# Upload multiple vectors in batches for large scale
batch = []
for i in range(1000):
    vector_record = {
        "id": f"vector_{i}",
        "vector": [random.random() for _ in range(1536)],  # Use "vector" key
        "metadata": {
            "category": f"category_{i % 5}",
            "timestamp": int(time.time()),
            "batch_id": 1
        }
    }
    batch.append(vector_record)

result = await vectors.upsert_batch(batch)

Vector Query

# Single vector similarity search
results = await vectors.query(
    vector=[0.1] * 1536,
    top_k=10,
    include_values=False,  # Exclude vector values for faster response
    include_metadata=True,  # Include metadata in results
    filter={"category": "A"},  # Metadata filtering
    use_ann=True,  # Use approximate nearest neighbors (HNSW)
    threshold=0.7  # Minimum similarity filter (0.0 for all results)
)

for match in results["matches"]:
    print(f"ID: {match['id']}, Score: {match['score']}")

# Multiple vector queries in parallel
query_vectors = [[0.1] * 1536, [0.2] * 1536, [0.3] * 1536]

batch_results = await vectors.batch_query(
    vectors=query_vectors,
    top_k=5,
    include_metadata=True,
    validate_dimensions=True
)

for i, result in enumerate(batch_results["results"]):
    print(f"Query {i}: {len(result['matches'])} matches")

# Advanced query with HNSW parameters
results = await vectors.query(
    vector=query_vector,
    top_k=100,
    include_values=False,  # Reduce response size
    include_metadata=True,
    use_ann=True,  # Fast approximate search
    ef_search=200,  # Higher quality (vs speed)
    skip_cache=False  # Leverage cache
)

Delete Vectors

# Delete vectors by ID
await vectors.delete(["vector_1", "vector_2", "vector_3"])

# Get vector by ID
vector_data = await vectors.get_vector("vector_1")

# Count vectors in collection
count = await vectors.count_vectors()

Performance Optimization

Client Configuration

Auto-sizing: Many parameters auto-size based on your system's CPU count for optimal performance.

client = Client(
    host="http://localhost:8080",

    # Connection Pool Optimization
    connection_pool_size=100,  # High concurrency (auto: CPU_COUNT * 5)
    timeout=120,  # Extended timeout for large operations

    # HTTP/2 and Compression
    use_http2=True,  # Enable HTTP/2 multiplexing
    compression=True,  # Enable response compression

    # Caching Configuration
    cache_size=1000,  # Client-side query cache
    cache_ttl=300,  # Cache TTL in seconds

    # Threading and Parallelism
    thread_pool_size=16,  # CPU-bound operations (auto: CPU_COUNT * 2)

    # Retry Configuration
    retry_attempts=5,  # Network resilience

    # Debug Mode
    debug=True  # Performance monitoring
)

Batch Operation Tuning

Optimal Batch Upsert

# Optimal batch upsert parameters
await vectors.upsert(
    vectors=large_dataset,
    batch_size=5000,  # Optimal for network efficiency
    parallel_workers=8,  # Match server capability
    validate_dimensions=True,  # Prevent dimension errors
    show_progress=True
)

High-Throughput Query Configuration

# High-throughput query configuration
results = await vectors.query(
    vector=query_vector,
    top_k=100,
    include_values=False,  # Reduce response size
    include_metadata=True,
    use_ann=True,  # Fast approximate search
    ef_search=200,  # Higher quality (vs speed)
    skip_cache=False  # Leverage cache
)

Server-Side Optimization

HNSW Index Parameters

HNSW Tuning: Higher ef_construction values improve search quality but increase indexing time.

await client.create_collection(
    name="high_performance",
    dimensions=1536,
    enable_hnsw=True,

    # HNSW Tuning
    m=16,  # Connectivity (16-64 for high recall)
    ef_construction=200,  # Graph construction quality (200-800)
    shards=32,  # Parallel processing (match CPU cores)
)

# Query-time HNSW parameters
results = await vectors.query(
    vector=query_vector,
    ef_search=200,  # Search quality (100-800) | Higher means accuracy over speed and ram consumption 
    use_ann=True  # Enable HNSW acceleration
)

Memory and Resource Management

# Force commit for persistence
await client.commit()

# Clear client-side caches
await client.clear_cache()
await vectors.clear_cache()

# Proper resource cleanup
await client.close()

Advanced Features

Dimension Validation

# Automatic dimension validation
is_valid = await vectors.validate_vector_dimensions([0.1] * 1536)

# Get collection dimensions
dims = await vectors.get_collection_dimensions()

Cache Performance Monitoring

# Get cache statistics
stats = vectors.get_cache_stats()
print(f"Cache hit rate: {stats['hit_rate']:.2%}")
print(f"Cache size: {stats['cache_size']}")

Monitor cache hit rates to optimize your query patterns and cache settings.

Data Types

The client uses strongly typed interfaces for better development experience:

from antarys.types import VectorRecord, SearchResult, SearchParams

# Type-safe vector record
record: VectorRecord = {
    "id": "example",
    "values": [0.1, 0.2, 0.3],
    "metadata": {"key": "value"}
}

# Search parameters
params = SearchParams(
    vector=[0.1] * 1536,
    top_k=10,
    include_metadata=True,
    threshold=0.8
)

Health Monitoring

Monitor your Antarys server and collection health:

# Check server health
health = await client.health()
print(f"Status: {health['status']}")

# Get server information
info = await client.info()
print(f"Version: {info['version']}")
print(f"Uptime: {info['uptime']}")

# Collection statistics
collection_info = await client.describe_collection("vectors")
print(f"Vector count: {collection_info.get('vector_count', 0)}")
print(f"Index type: {collection_info.get('index_type', 'none')}")

Best Practice: Regularly monitor your server health and collection statistics in production environments.

Quick Start

Antarys Python SDK

Installation

Install the Package

Optional Performance Dependencies

Quick Start

Core Concepts

Collections

Vector Operations

Single Vector Operations

Upsert Vectors

Query Vectors

Delete Vectors

Upsert

Batch Operations for Large Scale Data

Vector Query

Delete Vectors

Performance Optimization

Client Configuration

Batch Operation Tuning

Optimal Batch Upsert

High-Throughput Query Configuration

Server-Side Optimization

HNSW Index Parameters

Memory and Resource Management

Advanced Features

Dimension Validation

Cache Performance Monitoring

Data Types

Health Monitoring

Next Steps

API Reference

Samples

Troubleshooting

On this page