Skip to content

HeliosDB-Lite API Reference

Complete API reference for all HeliosDB-Lite integration points across languages and deployment modes.

REST API (Server Mode)

Base URL: http://localhost:8080 (default)

Endpoints

Queries

Execute SQL Query

POST /v1/branches/{branch}/query
Content-Type: application/json

Request Body:
{
  "sql": "SELECT * FROM users WHERE id = $1",
  "params": [1]
}

Response (200 OK):
{
  "rows": [
    {"id": 1, "name": "Alice", "email": "alice@example.com"}
  ],
  "columns": ["id", "name", "email"],
  "rows_affected": 0
}

Error Response (400):
{
  "error": {
    "code": "42P01",
    "message": "relation \"users\" does not exist"
  }
}

Execute Natural Language Query

POST /v1/nl/query
Content-Type: application/json

Request Body:
{
  "question": "How many users are from California?",
  "branch": "main"
}

Response (200 OK):
{
  "sql": "SELECT COUNT(*) FROM users WHERE state = 'California'",
  "rows": [{"count": 42}],
  "columns": ["count"]
}

Query at Timestamp (Time-Travel)

POST /v1/branches/{branch}/query
Content-Type: application/json

Request Body:
{
  "sql": "SELECT * FROM users",
  "params": [],
  "as_of_timestamp": "2025-01-01T00:00:00Z"
}

Response (200 OK):
{
  "rows": [...],
  "columns": [...],
  "rows_affected": 0
}

Text Vector Search

POST /v1/vectors/stores/{store}/search/text
Content-Type: application/json

Request Body:
{
  "text": "machine learning",
  "top_k": 10,
  "min_score": 0.5,
  "filter": {"category": "tech"}
}

Response (200 OK):
{
  "results": [
    {
      "id": "doc_123",
      "score": 0.95,
      "content": "Machine learning is...",
      "metadata": {"category": "tech", "year": 2024}
    }
  ]
}

Vector Search by Vector

POST /v1/vectors/stores/{store}/search
Content-Type: application/json

Request Body:
{
  "vector": [0.1, 0.2, 0.3, ...],
  "top_k": 10,
  "min_score": 0.5
}

Response (200 OK):
{
  "results": [
    {
      "id": "doc_123",
      "score": 0.95,
      "content": "...",
      "metadata": {}
    }
  ]
}

Store Text with Embedding

POST /v1/vectors/stores/{store}/texts
Content-Type: application/json

Request Body:
{
  "texts": ["Document 1", "Document 2"],
  "metadatas": [
    {"source": "blog"},
    {"source": "wiki"}
  ]
}

Response (200 OK):
{
  "ids": ["doc_1", "doc_2"]
}

Vector Store Management

List Vector Stores

GET /v1/vectors/stores

Response (200 OK):
{
  "stores": [
    {
      "name": "documents",
      "dimensions": 1536,
      "metric": "cosine",
      "count": 1000
    }
  ]
}

Create Vector Store

POST /v1/vectors/stores
Content-Type: application/json

Request Body:
{
  "name": "documents",
  "dimensions": 1536,
  "metric": "cosine"
}

Response (201 Created):
{
  "name": "documents",
  "dimensions": 1536,
  "metric": "cosine",
  "count": 0
}

Branching

List Branches

GET /v1/branches

Response (200 OK):
{
  "branches": [
    {
      "name": "main",
      "parent": null,
      "created_at": "2025-01-01T00:00:00Z"
    },
    {
      "name": "dev",
      "parent": "main",
      "created_at": "2025-01-10T12:30:00Z"
    }
  ]
}

Create Branch

POST /v1/branches
Content-Type: application/json

Request Body:
{
  "name": "feature-branch",
  "from_branch": "main"
}

Response (201 Created):
{
  "name": "feature-branch",
  "parent": "main",
  "created_at": "2025-01-15T10:00:00Z"
}

Merge Branches

POST /v1/branches/{source}/merge
Content-Type: application/json

Request Body:
{
  "target": "main"
}

Response (200 OK):
{
  "status": "merged",
  "changes": 5
}

Agent Memory

Add Memory

POST /v1/agents/memory/{session_id}/add
Content-Type: application/json

Request Body:
{
  "role": "user",
  "content": "Hello, how can you help?"
}

Response (200 OK):
{
  "status": "stored"
}

Get Memory

GET /v1/agents/memory/{session_id}/messages?limit=50

Response (200 OK):
{
  "messages": [
    {
      "id": "msg_1",
      "role": "user",
      "content": "Hello",
      "timestamp": "2025-01-15T10:00:00Z"
    }
  ]
}

Search Memory

POST /v1/agents/memory/{session_id}/search
Content-Type: application/json

Request Body:
{
  "query": "What did we discuss about performance?",
  "top_k": 5
}

Response (200 OK):
{
  "results": [
    {
      "id": "msg_123",
      "content": "Performance is critical for production...",
      "score": 0.92
    }
  ]
}

Document Management

List Collections

GET /v1/documents/collections

Response (200 OK):
{
  "collections": [
    {
      "name": "knowledge_base",
      "document_count": 150,
      "chunk_count": 1200,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

Create Collection

POST /v1/documents/collections
Content-Type: application/json

Request Body:
{
  "name": "knowledge_base",
  "chunk_size": 512,
  "chunk_overlap": 50
}

Response (201 Created):
{
  "name": "knowledge_base",
  "chunk_size": 512,
  "chunk_overlap": 50,
  "created_at": "2025-01-15T10:00:00Z"
}

Upload Document

POST /v1/documents/collections/{collection}/documents
Content-Type: multipart/form-data

Form Data:
- file: (binary file content)
- metadata: {"source": "manual", "author": "admin"}

Response (201 Created):
{
  "id": "doc_abc123",
  "filename": "guide.pdf",
  "chunks": 25,
  "status": "processed"
}

Search Documents (RAG)

POST /v1/documents/collections/{collection}/search
Content-Type: application/json

Request Body:
{
  "query": "How do I configure authentication?",
  "top_k": 5,
  "include_content": true
}

Response (200 OK):
{
  "results": [
    {
      "chunk_id": "chunk_123",
      "document_id": "doc_abc",
      "content": "Authentication can be configured...",
      "score": 0.95,
      "metadata": {"source": "guide.pdf", "page": 5}
    }
  ]
}

Schema Inference

Infer Schema from JSON

POST /v1/schema/infer
Content-Type: application/json

Request Body:
{
  "format": "json",
  "data": [
    {"id": 1, "name": "Alice", "score": 95.5},
    {"id": 2, "name": "Bob", "score": 87.3}
  ],
  "table_name": "students"
}

Response (200 OK):
{
  "sql": "CREATE TABLE students (\n  id INTEGER,\n  name TEXT,\n  score REAL\n);",
  "columns": [
    {"name": "id", "type": "INTEGER", "nullable": false},
    {"name": "name", "type": "TEXT", "nullable": false},
    {"name": "score", "type": "REAL", "nullable": false}
  ]
}

Infer Schema from CSV

POST /v1/schema/infer
Content-Type: application/json

Request Body:
{
  "format": "csv",
  "data": "id,name,score\n1,Alice,95.5\n2,Bob,87.3",
  "table_name": "students"
}

Response (200 OK):
{
  "sql": "CREATE TABLE students (...);",
  "columns": [...]
}

Chat Completion (AI)

Chat Completion

POST /v1/chat/completions
Content-Type: application/json

Request Body:
{
  "session_id": "session_123",
  "message": "What tables have a customer_id column?",
  "include_sql": true
}

Response (200 OK):
{
  "response": "I found 3 tables with a customer_id column: orders, invoices, and support_tickets.",
  "sql_executed": "SELECT table_name FROM pg_columns WHERE column_name = 'customer_id'",
  "results": [
    {"table_name": "orders"},
    {"table_name": "invoices"},
    {"table_name": "support_tickets"}
  ]
}

Query Management

Cancel Query

POST /v1/queries/{query_id}/cancel

Response (200 OK):
{
  "status": "cancelled",
  "query_id": "q_abc123"
}

List Active Queries

GET /v1/queries/active

Response (200 OK):
{
  "queries": [
    {
      "id": "q_abc123",
      "sql": "SELECT * FROM large_table",
      "started_at": "2025-01-15T10:00:00Z",
      "duration_ms": 5000,
      "state": "running"
    }
  ]
}

Tenant Management

List Tenants

GET /v1/tenants

Response (200 OK):
{
  "tenants": [
    {
      "id": 1,
      "name": "acme_corp",
      "plan": "enterprise",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

Create Tenant

POST /v1/tenants
Content-Type: application/json

Request Body:
{
  "name": "acme_corp",
  "plan": "enterprise",
  "isolation": "schema"
}

Response (201 Created):
{
  "id": 1,
  "name": "acme_corp",
  "plan": "enterprise",
  "isolation": "schema",
  "created_at": "2025-01-15T10:00:00Z"
}

Get Tenant Usage

GET /v1/tenants/{tenant_id}/usage

Response (200 OK):
{
  "tenant_id": 1,
  "storage_bytes": 1073741824,
  "connections_active": 5,
  "queries_per_second": 100,
  "quota": {
    "storage_bytes": 10737418240,
    "max_connections": 50,
    "max_qps": 1000
  }
}

Set Tenant Context

POST /v1/tenants/context
Content-Type: application/json

Request Body:
{
  "tenant_id": 1
}

Response (200 OK):
{
  "status": "context_set",
  "tenant_id": 1,
  "tenant_name": "acme_corp"
}

Health & Status

Health Check

GET /health

Response (200 OK):
{
  "status": "healthy",
  "version": "2.4.0-beta",
  "uptime_seconds": 3600
}

PostgreSQL Wire Protocol (Server Mode)

Standard PostgreSQL protocol on port 5432.

Connection String Format

postgresql://[user[:password]@][host][:port]/[database]

Examples:
postgresql://localhost:5432/mydb
postgresql://user:password@db.example.com:5432/mydb
postgres://localhost/mydb

Supported Features

  • Standard SQL (DML/DDL)
  • Parameterized queries ($1, $2, ...)
  • Transactions (BEGIN/COMMIT/ROLLBACK)
  • Multiple data types
  • Indexes
  • Transactions with isolation levels

Supported Client Libraries

  • Python: psycopg2, asyncpg, sqlalchemy
  • JavaScript/Node: pg, node-postgres, sequelize
  • Rust: sqlx, tokio-postgres, diesel
  • Go: database/sql, pgx, sqlc
  • Java: JDBC, Hibernate
  • .NET: Npgsql, Entity Framework
  • PHP: PDO, php-pgsql

Rust API (Native/Embedded Mode)

Core Types

pub struct EmbeddedDatabase {
    // ...
}

pub struct QueryResult {
    pub rows: Vec<HashMap<String, Value>>,
    pub columns: Vec<String>,
    pub rows_affected: i64,
}

pub struct VectorSearchResult {
    pub id: String,
    pub score: f64,
    pub content: Option<String>,
    pub metadata: Option<HashMap<String, Value>>,
}

pub enum Value {
    Null,
    Bool(bool),
    Int4(i32),
    Int8(i64),
    Float4(f32),
    Float8(f64),
    String(String),
    Bytes(Vec<u8>),
    Json(serde_json::Value),
    Vector(Vec<f32>),
}

Core Methods

impl EmbeddedDatabase {
    // Lifecycle
    pub fn new(path: &str) -> Result<Self>;
    pub fn new_in_memory() -> Result<Self>;
    pub fn with_config(path: &str, config: Config) -> Result<Self>;

    // Query execution
    pub fn execute(&self, sql: &str, params: &[Value]) -> Result<()>;
    pub fn query(&self, sql: &str, params: &[Value]) -> Result<QueryResult>;
    pub fn query_row(&self, sql: &str, params: &[Value]) -> Result<Option<Row>>;

    // Transactions
    pub fn begin_transaction(&self) -> Result<Transaction>;

    // Vector operations
    pub fn vector_search(&self, store: &str, query: &str, top_k: usize)
        -> Result<Vec<VectorSearchResult>>;
    pub fn store_text(&self, store: &str, text: &str,
        metadata: Option<HashMap<String, Value>>) -> Result<String>;

    // Branching
    pub fn create_branch(&self, name: &str, from: Option<&str>,
        options: Option<BranchOptions>) -> Result<()>;
    pub fn merge_branch(&self, source: &str, target: &str) -> Result<()>;
    pub fn drop_branch(&self, name: &str) -> Result<()>;
    pub fn switch_branch(&self, name: &str) -> Result<()>;

    // Time-travel
    pub fn query_as_of_timestamp(&self, sql: &str,
        timestamp: &str, params: &[Value]) -> Result<QueryResult>;
    pub fn query_as_of_transaction(&self, sql: &str,
        txn_id: u64, params: &[Value]) -> Result<QueryResult>;
}

Trait Methods

pub trait ToSqlValue {
    fn to_sql_value(&self) -> Value;
}

impl ToSqlValue for i32 { ... }
impl ToSqlValue for i64 { ... }
impl ToSqlValue for f64 { ... }
impl ToSqlValue for String { ... }
impl ToSqlValue for &str { ... }
impl ToSqlValue for bool { ... }
impl ToSqlValue for Vec<f32> { ... }

Python SDK API

Client

class Client:
    def __init__(
        self,
        base_url: str = "http://localhost:8080",
        api_key: Optional[str] = None,
        branch: str = "main",
        timeout: float = 30.0
    ) -> None: ...

    async def query(
        self,
        sql: str,
        params: Optional[List[Any]] = None,
        branch: Optional[str] = None
    ) -> QueryResult: ...

    async def execute(
        self,
        sql: str,
        params: Optional[List[Any]] = None
    ) -> int: ...

    async def nl_query(
        self,
        question: str
    ) -> Tuple[QueryResult, str]: ...

    async def vector_search(
        self,
        store: str,
        query: str,
        top_k: int = 10,
        min_score: Optional[float] = None,
        filter: Optional[Dict[str, Any]] = None
    ) -> List[VectorSearchResult]: ...

    async def store_text(
        self,
        store: str,
        text: str,
        metadata: Optional[Dict[str, Any]] = None
    ) -> str: ...

    async def create_vector_store(
        self,
        name: str,
        dimensions: int,
        metric: str = "cosine"
    ) -> Dict[str, Any]: ...

    async def list_vector_stores(self) -> List[Dict[str, Any]]: ...

    async def create_branch(
        self,
        name: str,
        from_branch: Optional[str] = None
    ) -> Dict[str, Any]: ...

    async def merge_branch(self, source: str, target: str) -> None: ...

    async def memory_add(
        self,
        session_id: str,
        role: str,
        content: str
    ) -> None: ...

    async def memory_get(
        self,
        session_id: str,
        limit: int = 50
    ) -> List[Dict[str, Any]]: ...

    async def memory_search(
        self,
        session_id: str,
        query: str,
        top_k: int = 5
    ) -> List[VectorSearchResult]: ...

    async def close(self) -> None: ...

Data Classes

@dataclass
class QueryResult:
    rows: List[Dict[str, Any]]
    columns: List[str]
    rows_affected: int = 0

@dataclass
class VectorSearchResult:
    id: str
    score: float
    content: Optional[str] = None
    metadata: Optional[Dict[str, Any]] = None

@dataclass
class VectorStore:
    name: str
    dimensions: int
    metric: str
    count: int

@dataclass
class Branch:
    name: str
    parent: Optional[str] = None
    created_at: str = ""

@dataclass
class Message:
    role: str
    content: str
    timestamp: Optional[str] = None

TypeScript SDK API

Client

class HeliosDBClient {
    constructor(config: ClientConfig);

    async query(sql: string, params?: any[]): Promise<QueryResult>;

    async execute(sql: string, params?: any[]): Promise<number>;

    async nlQuery(question: string): Promise<[QueryResult, string]>;

    async vectorSearch(
        store: string,
        query: string,
        options?: VectorSearchOptions
    ): Promise<VectorSearchResult[]>;

    async storeText(
        store: string,
        text: string,
        metadata?: Record<string, any>
    ): Promise<string>;

    async createVectorStore(
        name: string,
        dimensions: number,
        metric?: string
    ): Promise<Record<string, any>>;

    async listVectorStores(): Promise<Record<string, any>[]>;

    async createBranch(
        name: string,
        fromBranch?: string
    ): Promise<Record<string, any>>;

    async mergeBranch(source: string, target: string): Promise<void>;

    async memoryAdd(
        sessionId: string,
        role: string,
        content: string
    ): Promise<void>;

    async memoryGet(
        sessionId: string,
        limit?: number
    ): Promise<Record<string, any>[]>;

    async memorySearch(
        sessionId: string,
        query: string,
        topK?: number
    ): Promise<VectorSearchResult[]>;

    async close(): Promise<void>;
}

Types

interface QueryResult {
    rows: Record<string, any>[];
    columns: string[];
    rows_affected?: number;
}

interface VectorSearchResult {
    id: string;
    score: number;
    content?: string;
    metadata?: Record<string, any>;
}

interface ClientConfig {
    baseUrl?: string;
    apiKey?: string;
    branch?: string;
    timeout?: number;
}

interface VectorSearchOptions {
    topK?: number;
    minScore?: number;
    filter?: Record<string, any>;
}

Go SDK API

Client

type Client struct {
    // ...
}

func NewClient(baseURL, apiKey string) *Client

func (c *Client) Query(ctx context.Context, sql string,
    params ...interface{}) (*QueryResult, error)

func (c *Client) Execute(ctx context.Context, sql string,
    params ...interface{}) (int64, error)

func (c *Client) NLQuery(ctx context.Context, question string)
    (*QueryResult, string, error)

func (c *Client) VectorSearch(ctx context.Context, store, query string,
    opts ...*SearchOptions) ([]VectorSearchResult, error)

func (c *Client) StoreText(ctx context.Context, store, text string,
    metadata map[string]interface{}) (string, error)

func (c *Client) CreateBranch(ctx context.Context, name string,
    fromBranch ...string) error

func (c *Client) MergeBranch(ctx context.Context, source, target string) error

func (c *Client) MemoryAdd(ctx context.Context, sessionID, role, content string)
    error

func (c *Client) MemoryGet(ctx context.Context, sessionID string,
    limit int) ([]map[string]interface{}, error)

func (c *Client) MemorySearch(ctx context.Context, sessionID, query string,
    topK int) ([]VectorSearchResult, error)

func (c *Client) Close() error

Types

type QueryResult struct {
    Rows         []map[string]interface{}
    Columns      []string
    RowsAffected int64
}

type VectorSearchResult struct {
    ID       string
    Score    float64
    Content  *string
    Metadata map[string]interface{}
}

type SearchOptions struct {
    TopK     int
    MinScore *float64
    Filter   map[string]interface{}
}

Error Codes & Responses

HTTP Status Codes

Code Meaning Example
200 Success Query executed
201 Created Resource created
400 Bad Request Invalid SQL syntax
401 Unauthorized Invalid API key
404 Not Found Table not found
429 Rate Limited Too many requests
500 Server Error Internal error

PostgreSQL Error Codes (SQLSTATE)

Code Class Meaning
00000 SUCCESS Success
42P01 SYNTAX_ERROR Relation does not exist
42P02 SYNTAX_ERROR Column does not exist
23505 INTEGRITY Unique violation
23503 INTEGRITY Foreign key violation
25001 TRANSACTION Transaction failed

Configuration Reference

Server Configuration (heliosdb.toml)

[storage]
path = "./heliosdb-data"
cache_size = 536870912
compression = "zstd"
in_memory = false

[server]
listen_addr = "0.0.0.0"
port = 5432
max_connections = 100

[performance]
enable_simd = true
worker_threads = 4

[encryption]
enabled = false
algorithm = "aes256-gcm"
key_source = { environment = "HELIOSDB_KEY" }

[vector]
pq_enabled = true
pq_auto_compress = true

Environment Variables

HELIOSDB_PORT=5432
HELIOSDB_LISTEN_ADDR=0.0.0.0
HELIOSDB_DATA_DIR=./data
HELIOSDB_ENCRYPTION_KEY=...
HELIOSDB_LOG_LEVEL=info

Rate Limits & Quotas

Rate Limiting (Server Mode)

  • Default: 1000 requests/second per IP
  • Configurable via max_connections
  • WebSocket connections: 100/second

Resource Limits

  • Max query size: No hard limit
  • Max result rows: Limited by memory
  • Max vector dimensions: 4096
  • Max text length: 2 GB per cell

Changelog & Versioning

Versioning Scheme

MAJOR.MINOR.PATCH[-PRERELEASE]

  • MAJOR: Breaking API changes
  • MINOR: New features (backward compatible)
  • PATCH: Bug fixes
  • PRERELEASE: alpha, beta, rc

Compatibility

  • SDK versions must match server major version
  • Patch versions are forward compatible
  • Minor versions are forward compatible

Support & Contact

  • GitHub Issues: https://github.com/heliosdb/heliosdb-lite/issues
  • Documentation: https://docs.heliosdb.com
  • Email: support@heliosdb.com

Last Updated: December 2025 API Version: v3.4 (stable) SDK Versions: Python 3.4, TypeScript 3.4, Go 3.4, Rust 3.4