Skip to content
HeliosDB HeliosDB Nano

Quick Start Guide

Quick Start Guide

Get up and running with HeliosDB Nano in 5 minutes.

Create a Database

=== “Rust”

```rust
use heliosdb_nano::EmbeddedDatabase;


fn main() -> Result<(), Box<dyn std::error::Error>> {
    // File-based database
    let db = EmbeddedDatabase::new("./mydb")?;


    // Or in-memory
    let db = EmbeddedDatabase::new_in_memory()?;


    Ok(())
}
```

=== “Python”

```python
from heliosdb_nano import Client


# Connect to server
client = Client("http://localhost:8080")


# Or embedded
from heliosdb_nano import EmbeddedDatabase
db = EmbeddedDatabase("./mydb")
```

=== “CLI”

```bash
# Start REPL with file database
heliosdb-nano repl --data-dir ./mydb


# Or in-memory
heliosdb-nano repl --memory
```

Create Tables

-- Users table
CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);


-- Orders table with foreign key concept
CREATE TABLE orders (
    id INTEGER PRIMARY KEY,
    user_id INTEGER NOT NULL,
    total DECIMAL(10,2),
    status TEXT DEFAULT 'pending'
);

Insert Data

-- Single insert
INSERT INTO users (id, name, email) VALUES (1, 'Alice', 'alice@example.com');


-- Multiple rows
INSERT INTO users (id, name, email) VALUES
    (2, 'Bob', 'bob@example.com'),
    (3, 'Carol', 'carol@example.com');


-- Insert with RETURNING
INSERT INTO orders (user_id, total) VALUES (1, 99.99) RETURNING id;

Query Data

-- Basic query
SELECT * FROM users;


-- With conditions
SELECT name, email FROM users WHERE id > 1;


-- Join tables
SELECT u.name, o.total
FROM users u
JOIN orders o ON u.id = o.user_id;


-- Aggregation
SELECT user_id, SUM(total) as total_spent
FROM orders
GROUP BY user_id;

Try Advanced Features

Time-Travel Queries

-- Query data as it existed yesterday
SELECT * FROM orders AS OF TIMESTAMP '2025-01-14 00:00:00';

Database Branching

-- Create a development branch
CREATE DATABASE BRANCH dev FROM main;


-- Switch to branch
USE BRANCH dev;


-- Make changes safely
DELETE FROM users WHERE id = 1;


-- Switch back
USE BRANCH main;
-- Original data is still there!
-- Create table with vector column
CREATE TABLE documents (
    id INTEGER PRIMARY KEY,
    content TEXT,
    embedding VECTOR(384)
);


-- Insert with embedding
INSERT INTO documents (id, content, embedding)
VALUES (1, 'Machine learning basics', '[0.1, 0.2, ...]');


-- Similarity search
SELECT content FROM documents
ORDER BY embedding <-> '[0.15, 0.25, ...]'
LIMIT 5;

REPL Tips

Terminal window
# Show help
\h


# List tables
\d


# Describe table
\d users


# Show branches
\branches


# Toggle timing
\timing

Next Steps