Every Edition Is a Complete Document + AI Platform
Most databases treat document storage, vector search, and AI as separate add-ons requiring external infrastructure. HeliosDB treats them as first-class citizens across every edition -- from a browser tab running WASM to a distributed enterprise cluster. The difference between editions is not what you can do, but where and how far you can scale it.
| Capability | Nano (Edge/Browser) | Lite (Embedded/Server) | Full (Enterprise) |
|---|---|---|---|
| Supabase Storage API | Yes | Yes | Yes |
| Document Handler REST API | Yes | Yes | Yes |
| Document Chunking | 4 strategies | 4 strategies | 4 strategies + custom |
| Semantic Search | Yes | Yes | Yes |
| RAG Pipeline | Built-in | Built-in | Multi-strategy + re-ranking |
| AI Providers | 5 (OpenAI, Anthropic, Local, HuggingFace, Custom) | 5 | 5 + enterprise connectors |
| Vector Search | In-memory | HNSW + PQ + SIMD | Distributed HNSW |
| ACID Transactions | Single-node | Full MVCC | Distributed MVCC |
| Time-Travel Queries | Limited | Full | Full + cross-node |
| Branch Isolation | Git-integrated | Native branches | Native branches |
| Encryption at Rest | Browser sandbox | TDE (AES-256-GCM) | TDE + key rotation |
| MongoDB-Style API | -- | -- | DocumentStore crate |
| Foreign Data Wrappers | -- | -- | 7 types (S3, PG, MySQL, ...) |
| Change Streams | -- | -- | Collection-level |
| Deployment Target | Browser, IoT, Edge | Server, Desktop, Container | Cluster, Cloud, Hybrid |
| Binary Size | < 5 MB (WASM) | ~60 MB | ~120 MB |
| Configuration | Zero-config | Zero-config | Config file or env vars |
Nano is the only database engine that runs a complete document + vector + RAG pipeline inside a browser tab or IoT device. It compiles to WASM with no native dependencies.
Nano implements the Supabase Storage API, so existing Supabase client libraries work unchanged:
import { createClient } from '@supabase/supabase-js';
// Connect to HeliosDB-Nano (same API as Supabase)
const helios = createClient('http://localhost:3000', 'your-api-key');
// Create a storage bucket
const { data, error } = await helios.storage.createBucket('contracts', {
public: false,
fileSizeLimit: 52428800, // 50 MB
allowedMimeTypes: ['application/pdf', 'text/plain', 'text/markdown']
});
// Upload a document
const file = new File(['Contract text...'], 'nda-2026.pdf');
await helios.storage.from('contracts').upload('legal/nda-2026.pdf', file);
// Generate a signed URL (expires in 1 hour)
const { data: url } = await helios.storage
.from('contracts')
.createSignedUrl('legal/nda-2026.pdf', 3600);The Document Handler REST API ingests documents, automatically chunks them, generates embeddings, and makes everything searchable -- all in a single API call:
// Ingest a document with automatic chunking and embedding
const response = await fetch('http://localhost:3000/api/v1/documents', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
content: longDocumentText,
metadata: { category: 'legal', author: 'Jane Doe' },
chunking: {
strategy: 'semantic', // fixed | sentence | paragraph | semantic
chunk_size: 512,
overlap: 50
},
embed: true, // auto-generate vector embeddings
vector_store: 'contracts' // target vector collection
})
});Chunking strategies:
| Strategy | Best For | How It Works |
|---|---|---|
fixed | Uniform-length processing | Splits at character boundaries with overlap |
sentence | Natural language text | Splits on sentence boundaries (default) |
paragraph | Structured documents | Splits on paragraph breaks |
semantic | Maximum retrieval accuracy | Uses embedding similarity to find natural breakpoints |
Nano ships a complete RAG (Retrieval-Augmented Generation) pipeline that connects document retrieval directly to LLM generation:
const ragResponse = await fetch('http://localhost:3000/api/v1/rag/query', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
query: 'What are the termination clauses in our NDA?',
config: {
vector_stores: ['contracts'],
top_k: 5,
min_score: 0.7,
rerank: true,
include_sources: true
},
model: 'gpt-4o',
temperature: 0.3
})
});
const { answer, sources } = await ragResponse.json();
// answer: "The NDA contains three termination clauses..."
// sources: [{ document_id: "nda-2026", chunk_index: 14, score: 0.94 }, ...]Switch between providers without changing application code:
// OpenAI
{ "provider": "openai", "model": "gpt-4o", "api_key": "sk-..." }
// Anthropic
{ "provider": "anthropic", "model": "claude-sonnet-4-20250514", "api_key": "sk-ant-..." }
// Local LLM (Ollama, llama.cpp, vLLM)
{ "provider": "local", "endpoint": "http://localhost:11434", "model": "llama3.2" }
// HuggingFace Inference
{ "provider": "huggingface", "model": "mistralai/Mixtral-8x7B", "api_key": "hf_..." }
// Custom endpoint (any OpenAI-compatible API)
{ "provider": "custom", "endpoint": "https://my-model.internal/v1", "model": "my-fine-tune" }Nano persists data in the browser using three storage backends:
| Backend | Capacity | Persistence | Use Case |
|---|---|---|---|
| IndexedDB | ~1 GB+ | Persistent | Default, most reliable |
| OPFS (Origin Private File System) | ~10 GB+ | Persistent | Large datasets, near-native I/O |
| LocalStorage | ~5-10 MB | Persistent | Small configs, fallback |
Nano includes Git integration for version-controlled document pipelines:
// Documents are version-tracked through Git-style operations
await helios.rpc('git_commit', {
message: 'Updated Q4 financial report with December actuals',
branch: 'finance/q4-2026'
});
// Branch isolation for draft workflows
await helios.rpc('git_checkout', { branch: 'drafts/annual-report' });
// ... make changes on the draft branch ...
await helios.rpc('git_merge', {
source: 'drafts/annual-report',
target: 'main'
});Lite is the embedded edition designed for server-side applications, desktop software, and containerized microservices. It adds ACID transactions, hardware-accelerated vector search, encryption, and time-travel to the document stack.
Lite includes the full Supabase Storage API, Document Handler, and RAG pipeline from Nano. It adds production-grade features on top.
Lite uses a three-layer vector search architecture optimized for server hardware:
-- Connect via PostgreSQL wire protocol (psql, any PG driver)
-- Create a table with vector embeddings
CREATE TABLE documents (
id SERIAL PRIMARY KEY,
title TEXT NOT NULL,
content TEXT,
category TEXT,
embedding VECTOR(1536),
created_at TIMESTAMP DEFAULT NOW()
);
-- Create an HNSW index for fast approximate nearest-neighbor search
CREATE INDEX idx_docs_embedding ON documents
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 200);
-- Semantic search: find the 10 most similar documents
SELECT id, title, category,
embedding <=> '[0.1, -0.3, 0.5, ...]'::vector AS distance
FROM documents
ORDER BY embedding <=> '[0.1, -0.3, 0.5, ...]'::vector
LIMIT 10;Vector search internals:
| Component | Purpose |
|---|---|
| HNSW (Hierarchical Navigable Small World) | Graph-based ANN index for sub-millisecond search |
| Product Quantization | Compresses vectors 4-8x, keeps full dataset in memory |
| SIMD Acceleration | AVX2/SSE4 for distance computations on x86; NEON on ARM |
Every document operation participates in MVCC transactions -- including chunking and embedding:
import psycopg2
conn = psycopg2.connect("host=localhost port=5432 dbname=helios")
cur = conn.cursor()
try:
# All three operations are atomic
cur.execute("""
INSERT INTO documents (title, content, embedding)
VALUES ('Q4 Report', %s, %s)
""", (report_text, embedding_vector))
cur.execute("""
INSERT INTO document_chunks (doc_id, chunk_index, content, embedding)
SELECT currval('documents_id_seq'), idx, chunk, embed
FROM unnest(%s::text[], %s::vector[]) WITH ORDINALITY AS t(chunk, embed, idx)
""", (chunks, chunk_embeddings))
cur.execute("""
INSERT INTO document_metadata (doc_id, key, value)
VALUES (currval('documents_id_seq'), 'status', '"published"')
""")
conn.commit() # All-or-nothing: document + chunks + metadata
except Exception:
conn.rollback() # Nothing written on failureQuery any document as it existed at any point in the past:
-- What did the contract say last Tuesday?
SELECT title, content
FROM documents
AS OF TIMESTAMP '2026-02-10 14:30:00'
WHERE title = 'Service Agreement v3';
-- Compare two versions of a document
SELECT
old.content AS previous_version,
new.content AS current_version
FROM documents AS OF TIMESTAMP '2026-01-15' old
JOIN documents new ON old.id = new.id
WHERE new.title = 'Privacy Policy';Create isolated branches to stage document changes without affecting production:
-- Create a review branch
SELECT helios_branch_create('review/legal-update');
-- Switch to the branch
SELECT helios_branch_checkout('review/legal-update');
-- Make changes on the branch (invisible to main)
UPDATE documents SET content = 'Updated terms...'
WHERE title = 'Terms of Service';
-- When approved, merge back
SELECT helios_branch_merge('review/legal-update', 'main');All document content, chunks, and embeddings are encrypted with AES-256-GCM Transparent Data Encryption:
-- Enable TDE (one-time setup)
SELECT helios_tde_init('aes-256-gcm');
-- All subsequent writes are automatically encrypted at the storage layer.
-- No application code changes required.
-- Queries work identically -- decryption is transparent.
INSERT INTO documents (title, content, embedding)
VALUES ('Classified Report', 'Top secret content...', '[0.1, 0.2, ...]'::vector);
-- This query decrypts transparently
SELECT * FROM documents WHERE title = 'Classified Report';| Attribute | Value |
|---|---|
| Binary size | ~60 MB |
| Configuration | Zero-config (single binary) |
| Protocol | PostgreSQL wire protocol (any PG client) |
| Concurrency | Multi-threaded MVCC |
| Storage backend | O_DIRECT (bypass OS page cache) |
| Max dataset | Limited by disk |
Full is the distributed edition for organizations that need MongoDB-style document APIs, cross-cloud data federation, and multi-node document consistency.
Full includes the complete Supabase Storage API, Document Handler, RAG pipeline, vector search, ACID transactions, time-travel, branching, and TDE from Lite. It adds enterprise-scale capabilities on top.
Full includes a dedicated DocumentStore crate that provides a MongoDB-compatible interface for teams migrating from MongoDB or preferring a document-oriented API:
from heliosdb import DocumentStore
store = DocumentStore("helios://cluster.internal:5432/mydb")
# Create a collection with JSON Schema validation
store.create_collection("invoices", schema={
"type": "object",
"required": ["vendor", "amount", "date"],
"properties": {
"vendor": { "type": "string" },
"amount": { "type": "number", "minimum": 0 },
"date": { "type": "string", "format": "date" },
"line_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"description": { "type": "string" },
"quantity": { "type": "integer" },
"unit_price": { "type": "number" }
}
}
}
}
})
# Insert documents (validated against schema)
store.invoices.insert_one({
"vendor": "Acme Corp",
"amount": 15000.00,
"date": "2026-02-18",
"line_items": [
{"description": "Consulting", "quantity": 40, "unit_price": 375.00}
]
})# Find with query operators
results = store.invoices.find({
"amount": {"$gt": 10000},
"vendor": {"$regex": "^Acme"},
"date": {"$gte": "2026-01-01"}
})
# Supported operators:
# Comparison: $eq, $ne, $gt, $gte, $lt, $lte
# Logical: $and, $or, $not, $nor
# Element: $exists, $type
# Array: $in, $nin, $all, $elemMatch, $size
# String: $regex# Revenue by vendor for Q1 2026
pipeline = store.invoices.aggregate([
{"$match": {"date": {"$gte": "2026-01-01", "$lt": "2026-04-01"}}},
{"$group": {
"_id": "$vendor",
"total_revenue": {"$sum": "$amount"},
"invoice_count": {"$sum": 1},
"avg_invoice": {"$avg": "$amount"}
}},
{"$sort": {"total_revenue": -1}},
{"$project": {
"vendor": "$_id",
"total_revenue": 1,
"invoice_count": 1,
"avg_invoice": {"$round": ["$avg_invoice", 2]}
}}
])
# Supported pipeline stages:
# $match, $group, $sort, $project, $limit, $skip, $unwind, $lookupReact to document changes in real time:
# Watch for changes on the invoices collection
stream = store.invoices.watch(pipeline=[
{"$match": {"operationType": {"$in": ["insert", "update"]}}}
])
for change in stream:
if change["operationType"] == "insert":
doc = change["fullDocument"]
print(f"New invoice: {doc['vendor']} - ${doc['amount']}")
elif change["operationType"] == "update":
print(f"Updated fields: {change['updateDescription']['updatedFields']}")Query Parquet, CSV, and JSON files sitting on S3 or MinIO directly with SQL -- no ETL, no data movement:
-- Create an S3 foreign server
CREATE SERVER s3_data_lake
FOREIGN DATA WRAPPER s3_fdw
OPTIONS (
endpoint 'https://s3.us-east-1.amazonaws.com',
region 'us-east-1',
access_key_id 'AKIA...',
secret_access_key '...'
);
-- Map an S3 bucket path to a virtual table
CREATE FOREIGN TABLE sales_parquet (
order_id BIGINT,
customer TEXT,
amount NUMERIC(12,2),
order_date DATE,
region TEXT
) SERVER s3_data_lake
OPTIONS (
bucket 'analytics-lake',
path 'sales/2026/',
format 'parquet'
);
-- Query S3 data with standard SQL (predicate pushdown to Parquet)
SELECT region, SUM(amount) AS revenue
FROM sales_parquet
WHERE order_date >= '2026-01-01'
GROUP BY region
ORDER BY revenue DESC;| FDW Type | Connects To | Use Case |
|---|---|---|
| S3 | S3, MinIO, R2 | Query Parquet/CSV/JSON on object storage |
| PostgreSQL | Any PG instance | Federated queries across PG clusters |
| MySQL | MySQL / MariaDB | Cross-database joins |
| MongoDB | MongoDB Atlas or self-hosted | Unified SQL over MongoDB collections |
| REST API | Any HTTP/JSON endpoint | Query APIs as tables |
| Azure Synapse | Azure Synapse Analytics | Hybrid cloud analytics |
| BigQuery | Google BigQuery | Cross-cloud warehouse queries |
Full extends the built-in RAG pipeline with enterprise features:
from heliosdb import RagEngine
rag = RagEngine("helios://cluster.internal:5432/mydb")
response = rag.query(
question="What were our top compliance risks in 2025?",
config={
"retrieval_strategies": [
{"type": "semantic", "weight": 0.6, "top_k": 10},
{"type": "keyword", "weight": 0.2, "top_k": 10},
{"type": "metadata", "weight": 0.2, "filters": {"category": "compliance"}}
],
"reranker": "cross-encoder", # Re-rank with cross-encoder model
"citation_tracking": True, # Track which chunks support each claim
"max_context_tokens": 8000
},
model="claude-sonnet-4-20250514"
)
print(response.answer)
for citation in response.citations:
print(f" [{citation.index}] {citation.document_title}, chunk {citation.chunk_id} "
f"(score: {citation.relevance_score:.2f})")Full ensures document operations are consistent across a multi-node cluster:
-- Documents written on any node are globally consistent
BEGIN;
INSERT INTO documents (title, content) VALUES ('Global Policy', '...');
INSERT INTO document_chunks (doc_id, content, embedding)
VALUES (currval('documents_id_seq'), '...', '[...]'::vector);
COMMIT;
-- Both rows visible on all nodes after commitHeliosDB is the first database to unify four capabilities that have historically required separate systems, separate infrastructure, and complex ETL pipelines:
Documents are not blobs stored alongside the database -- they are in the database, governed by the same MVCC transactions, constraints, and recovery guarantees as every other row.
Vector indexes (HNSW with Product Quantization and SIMD acceleration) run in the same process as the query engine. There is no network hop to a separate vector database, no synchronization lag, no eventual consistency between your documents and their embeddings.
When a document is inserted or updated, HeliosDB can automatically chunk it, generate embeddings, and index the vectors -- all within the same transaction that writes the document itself. There is no external ETL pipeline, no Kafka topic, no Lambda function, and no window of time where the document exists but its embeddings do not.
-- One statement: insert document, auto-chunk, auto-embed, index
INSERT INTO documents (title, content, auto_embed)
VALUES ('Quarterly Report', 'Full report text here...', true);
-- Immediately searchable (same transaction)
SELECT title, content <=> query_embedding AS relevance
FROM documents
WHERE content @@ 'revenue growth'
ORDER BY relevance
LIMIT 5;HeliosDB connects to local language models (Ollama, llama.cpp, vLLM) running on the same machine or network. Documents never leave the perimeter. This enables:
A typical document AI stack without HeliosDB:
| Component | Product | Purpose |
|---|---|---|
| Document storage | S3 / MinIO | Store blobs |
| Metadata database | PostgreSQL | Track document metadata |
| Vector database | Pinecone / Weaviate | Store embeddings |
| Embedding pipeline | Airflow + OpenAI API | Generate vectors |
| Search engine | Elasticsearch | Full-text search |
| RAG framework | LangChain / LlamaIndex | Orchestrate retrieval + generation |
| Message queue | Kafka / SQS | Glue everything together |
Seven systems, seven failure modes, seven bills, eventual consistency between all of them.
With HeliosDB, this becomes one binary, one connection string, one transaction boundary.
All three editions share the same storage format and SQL dialect. Migrating from Nano to Lite, or Lite to Full, is a data copy -- not a rewrite:
# Export from Lite
helios dump --format=native --output=backup.helios
# Import into Full
helios-full restore --input=backup.heliosApplication code using the PostgreSQL wire protocol works unchanged across Lite and Full. Supabase Storage API calls work unchanged across all three editions.
Get started with HeliosDB in minutes. Open source, free to use.