Developer Guides

In-depth tutorials for HeliosDB Nano features

Getting Started

Guide	Description	Time
Quick Start	Basic setup and first queries	5 min
Authentication	Bearer tokens and API keys	10 min

Core Features

Vector Search

Build semantic search, RAG backends, and AI-native applications.

Topics covered:

HNSW index configuration
Product Quantization for compression
Cosine, Euclidean, and IP distance metrics
Hybrid queries (filters + similarity)

-- Create vector-enabled table
CREATE TABLE documents (
    id UUID PRIMARY KEY,
    content TEXT,
    embedding VECTOR(1536)
);

-- Create HNSW index
CREATE INDEX ON documents
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 200);

-- Similarity search
SELECT content, embedding <-> $query AS distance
FROM documents
ORDER BY embedding <-> $query
LIMIT 10;

Full Vector Search Guide →

Multi-Tenancy

Build SaaS platforms with automatic tenant isolation.

Topics covered:

Row-Level Security (RLS) policies
Tenant plans and quotas
Isolation modes (Shared, Schema, Database)
Per-tenant tokens

-- Enable RLS
CREATE POLICY tenant_isolation ON orders
    USING (tenant_id = current_setting('app.tenant_id')::uuid);

ALTER TABLE orders ENABLE ROW LEVEL SECURITY;

Full Multi-Tenancy Guide →

Database Branching

Git-like workflows for your database.

Topics covered:

Creating and switching branches
Feature branch workflows
Preview environments
Branch merging strategies

-- Create feature branch
CREATE BRANCH feature_new_pricing FROM main;

-- Work in isolation
USE BRANCH feature_new_pricing;
ALTER TABLE products ADD COLUMN discount_tier INT;

-- Merge when ready
MERGE BRANCH feature_new_pricing INTO main;

Full Branching Guide →

Time Travel

Query historical data without audit tables.

Topics covered:

Point-in-time queries
Retention configuration
Compliance and auditing
Change tracking

-- Query past data
SELECT * FROM orders
AS OF TIMESTAMP '2024-01-01 00:00:00';

-- Compare changes
SELECT
    current.price AS now,
    past.price AS then
FROM products current
JOIN products AS OF TIMESTAMP '2024-01-01' past
    ON current.id = past.id
WHERE current.price != past.price;

Full Time Travel Guide →

Materialized Views

Automatic query caching with smart refresh.

Topics covered:

Creating materialized views
Refresh strategies (manual, scheduled, incremental)
CPU-aware scheduling
Dependency tracking

-- Create materialized view
CREATE MATERIALIZED VIEW monthly_revenue AS
SELECT
    date_trunc('month', created_at) AS month,
    SUM(amount) AS revenue,
    COUNT(*) AS order_count
FROM orders
GROUP BY 1;

-- Refresh
REFRESH MATERIALIZED VIEW monthly_revenue;

Full Materialized Views Guide →

Encryption

Transparent data encryption with minimal overhead.

Topics covered:

AES-256-GCM configuration
Key management
Performance impact (<3%)
Compliance requirements

# Start with encryption
./heliosdb-nano --mode server --encryption-key $KEY

Full Encryption Guide →

Integration Guides

Language SDKs

Language	Status	Link
Python	Recommended	Python SDK
JavaScript/TypeScript	Recommended	JS/TS SDK
Go	Community	Go SDK
Rust	Native	Rust Crate

Framework Integration

Framework	Guide
Next.js	Next.js Integration
FastAPI	FastAPI Integration
Express	Express Integration
Actix	Actix Integration

AI/ML Platforms

Platform	Guide
LangChain	LangChain Vector Store
LlamaIndex	LlamaIndex Integration
OpenAI	OpenAI Embeddings

Operations

Deployment

Environment	Guide
Docker	Docker Deployment
Kubernetes	K8s Deployment
AWS	AWS Deployment
Fly.io	Fly.io Deployment

Monitoring

Backup & Recovery

Best Practices

Performance

Use appropriate indexes

-- For vector search
CREATE INDEX USING hnsw (embedding vector_cosine_ops);

-- For filtered queries
CREATE INDEX ON products (category, price);

Optimize vector dimensions
- Use Product Quantization for large embeddings
- Consider smaller models (384-dim vs 1536-dim)
Connection pooling
- Use connection pools in your application
- Configure max_connections appropriately

Security

Always use HTTPS in production
Rotate tokens regularly
Use RLS for tenant isolation
Enable audit logging

Schema Design

Include tenant_id in multi-tenant tables
Use UUIDs for distributed systems
Add created_at/updated_at timestamps
Use JSONB for flexible metadata

Troubleshooting

Common Issues

Issue	Solution
Connection refused	Check server is running, port is correct
Token expired	Refresh token before expiry
Slow queries	Check EXPLAIN output, add indexes
Out of memory	Increase limits, optimize queries

Getting Help

Need a guide that’s not listed? Request a guide