Code Examples - Real-World Implementations

AI / ML

RAG Backend

Build a complete Retrieval-Augmented Generation system with HeliosDB as the vector store. Chunk documents, generate embeddings, store them with HNSW + Product Quantization, and retrieve context for LLM generation.

HNSW index with Product Quantization: about 16× less resident RAM at recall-safe defaults (internal tests, Nano 3.32.1 vs an unquantized index, see benchmarks.html)
Hybrid queries: combine vector similarity with SQL filters
Works with OpenAI, Cohere, or any embedding model
Approximate nearest-neighbour retrieval in SQL, next to your relational filters

Python

class RAGBackend:
    def search(self, query: str, limit=5):
        embedding = self.embed(query)
        # SQL over the PostgreSQL wire (psycopg2 connection)
        with self.conn.cursor() as cur:
            cur.execute(
                "SELECT content FROM documents "
                "ORDER BY embedding <=> %s::vector LIMIT %s",
                (str(embedding), limit),
            )
            return [row[0] for row in cur.fetchall()]

    def answer(self, question: str):
        context = self.search(question)
        return openai.chat.completions.create(
            model="gpt-4",
            messages=[
                {"role": "system",
                 "content": f"Context:\n{context}"},
                {"role": "user",
                 "content": question}
            ]
        )

AI Agents

AI Agent Memory

Give an AI agent persistent memory with plain SQL over the PostgreSQL wire protocol: one table of messages with an embedding column, recent history by insertion order, and related messages by vector distance, here on HeliosDB Nano. Nano's /v1/agents/memory REST API is planned; the current routes return not-implemented errors. Keep the HTTP and MySQL listeners on loopback (the default): API-key authentication for the HTTP API is planned, and a smaller listening surface is good practice anyway. HeliosDB Full serves an agent-memory API at /api/v1/agents/memory on its HTTP gateway (port 8443, with the HELIOSDB_API_KEY set on the server).

Session-scoped conversation history in an ordinary table
Search a session's messages by relevance with an HNSW index
Works with any embedding model; your application writes the embedding with the row
Summarize a session with the LLM client you already use

SQL

-- One row per message
CREATE TABLE agent_messages (
    id         BIGSERIAL PRIMARY KEY,
    session_id TEXT NOT NULL,
    role       TEXT NOT NULL,
    content    TEXT NOT NULL,
    embedding  VECTOR(768)
);
CREATE INDEX idx_agent_messages_embedding
    ON agent_messages USING hnsw (embedding vector_cosine_ops);

-- Store a message ($4: the embedding from your model)
INSERT INTO agent_messages (session_id, role, content, embedding)
VALUES ($1, $2, $3, $4);

-- Context for the next response
SELECT role, content FROM agent_messages
WHERE session_id = $1
ORDER BY id DESC LIMIT 50;

-- Earlier messages relevant to a new question
SELECT role, content FROM agent_messages
WHERE session_id = $1
ORDER BY embedding <=> $2::vector(768)
LIMIT 5;

SaaS

Multi-Tenant SaaS (HeliosDB Lite)

Build a SaaS platform on HeliosDB Lite with tenant isolation through row-level security policies. Policies apply to non-superuser roles that authenticate with a password or SCRAM; superusers bypass them, so connect the application as a non-superuser role. Lite builds from 2026-08-20 onward enforce policies over the PostgreSQL wire and REST; confirm that your build does before relying on it (CREATE POLICY reference).

Row-level security policies in SQL with CREATE POLICY
Policies apply to non-superuser roles with password or SCRAM authentication
In the stock Nano server, row-level security is enforced through the embedded API and the REPL; SQL CREATE POLICY and enforcement for REST and wire clients are planned

SQL

-- HeliosDB Lite: row-level security policy
CREATE POLICY tenant_isolation
ON projects
FOR ALL
USING (tenant_id = current_tenant());
ALTER TABLE projects
    ENABLE ROW LEVEL SECURITY;

-- current_tenant() is NULL when no tenant context
-- is bound, and the policy then denies the row.
-- Connect the application as a non-superuser
-- role with password or SCRAM authentication;
-- superusers bypass row-level security

Search

Semantic Product Search

Implement natural language product search by combining vector similarity with traditional SQL filters. Users search by intent, not keywords — "headphones for working from home" finds noise-canceling headphones even without exact keyword matches.

Hybrid queries: vector similarity + price/category filters
Works with sentence-transformers, OpenAI, or any embedding model
HNSW index for approximate similarity search
Product Quantization cuts resident RAM about 16× at recall-safe defaults (internal tests, Nano 3.32.1 vs an unquantized index, see benchmarks.html)

SQL

-- Semantic search with filters
SELECT name, price,
       embedding <=> $query_vec AS distance
FROM products
WHERE category = 'Electronics'
  AND price < 100
ORDER BY embedding <=> $query_vec
LIMIT 10;

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

Analytics

Event Analytics

Track user behavior with time-series event storage and aggregate with SQL. JSONB properties support flexible event schemas, and time-travel queries let you analyze historical state without separate audit tables.

JSONB properties for flexible event payloads
Time-series aggregation with date_trunc and window functions
Time-travel queries: AS OF TIMESTAMP for historical analysis
Indexed by user + timestamp for efficient range scans

TypeScript

// Track events
await tracker.track("user-123", "page_view",
    { page: "/products", referrer: "google" });
await tracker.track("user-123", "purchase",
    { order_id: "ord-789", total: 29.99 });

// Daily aggregation
const metrics = await query(`
  SELECT date_trunc('day', timestamp) AS period,
         COUNT(*) AS events,
         COUNT(DISTINCT user_id) AS users
  FROM events
  WHERE event_type = 'purchase'
    AND timestamp >= NOW() - INTERVAL '30 days'
  GROUP BY period
  ORDER BY period DESC
`);

DevOps

Feature Flags

Implement database-backed feature flags with percentage-based rollouts, user targeting, and plan-based access control. Deterministic bucket assignment ensures consistent flag evaluation per user.

Boolean flags with percentage-based rollouts
Target specific users or subscription plans
Deterministic hashing for consistent evaluation
Cacheable with instant invalidation on change

SQL + Python

-- Feature flags table
CREATE TABLE feature_flags (
    id TEXT PRIMARY KEY,
    enabled BOOLEAN DEFAULT false,
    rollout_percentage INTEGER DEFAULT 0,
    target_plans TEXT[]
);

INSERT INTO feature_flags VALUES
  ('new_checkout', true, 50,
   ARRAY['pro', 'enterprise']);

# Check flag in application
if flags.is_enabled("new_checkout",
        user_id="user-123",
        plan="pro"):
    show_new_checkout()
else:
    show_old_checkout()

Real-World Implementations