Three Superpowers

The @ Operator

The @ operator is FlinDB's time-travel syntax. It's built directly into the language, not bolted on as an afterthought. No triggers, no event sourcing, no complex setup.

Version-Based Access

Access any previous version of an entity by number. entity@-1 gives you the previous version, entity@-5 gives you five versions ago.

Date-Based Access

Query the exact state of any entity on any date. entity@"2024-01-15" shows you exactly what that entity looked like on January 15th.

Temporal Keywords

// Create and modify
user = User { name: "Juste" }
save user                      // v1

user.name = "Juste G."
save user                      // v2

user.name = "Juste Gnimavo"
save user                      // v3

// Time travel
user@-1                       // "Juste G."
user@-2                       // "Juste"

// Date-based
user@yesterday
user@"2024-01-15"
user@"2024-01-15 14:30"

// Full history
user.history()               // All versions
user.history().length         // 3

The semantic text Type

Mark any text field with semantic and FlinDB automatically generates vector embeddings for AI-powered similarity search. No external services required.

How It Works

• Entity saved with semantic text field
• ZEROCORE generates embedding vector (~10ms)
• Vector stored in optimized index
• Search queries are embedded on-the-fly
• Cosine similarity finds nearest neighbors

Lightweight & Offline

FlinDB uses a lightweight embedding model (~50MB) included in the binary. No external API calls needed. Works completely offline with fast inference.

Available In

Semantic search is available in FLIN AI and FLIN Full editions.

// Define entity with semantic field
entity Product {
    name: text
    description: semantic text  // AI-searchable
    price: money
}

// Add products
save Product {
    name: "ErgoChair Pro",
    description: "Ergonomic office chair
        with lumbar support",
    price: 450 USD
}

// Semantic search - finds by meaning!
results = search "comfortable chair for
    working from home" in Product
    by description

// Finds "ErgoChair Pro" even though
// query doesn't match keywords

Entity-Based Storage

Define your data model with entity declarations. FlinDB automatically creates storage, assigns unique IDs, tracks timestamps, and maintains version history.

System Fields (Automatic)

Every entity automatically has these fields without declaration:

• id - Unique identifier (auto-generated)
• created_at - Creation timestamp
• updated_at - Last update timestamp
• version - Version number

Field Types

Type	Description	Example
text	UTF-8 string	"Hello"
int	64-bit integer	42
number	64-bit float	3.14
bool	Boolean	true
time	UTC timestamp	now
money	Currency value	1000 CFA
file	File reference	uploaded file
semantic text	AI-searchable	"description"

// Define entity
entity Todo {
    title: text
    done: bool = false
    created: time = now
    priority: int = 1
}

// Create and save
todo = Todo { title: "Learn FLIN" }
save todo

// That's it! No setup needed.
// FlinDB automatically:
// - Creates storage
// - Assigns unique ID
// - Tracks created_at, updated_at
// - Maintains version history

// Access system fields
todo.id          // 1
todo.created_at  // timestamp
todo.version     // 1

Chainable Methods

FlinDB's query builder uses a fluent, chainable API. Combine .where(), .order(), and .limit() to build complex queries with simple syntax.

Core Methods

• Entity.all - Get all entities
• Entity.find(id) - Find by ID
• Entity.first(condition) - First match
• Entity.count - Count entities
• .where(condition) - Filter results
• .order(field, direction) - Sort results
• .limit(n) - Limit results
• .offset(n) - Skip results (pagination)

Comparison Operators

Use standard operators: ==, !=, >, <, >=, <=, &&, ||

// Basic queries
todos = Todo.all
todo = Todo.find(42)
total = Todo.count

// Filtering
active = Todo.where(done == false)
urgent = Todo.where(priority > 5)

// Multiple conditions
results = Todo
    .where(done == false)
    .where(priority > 3)

// Ordering
newest = Todo.all.order(created_at, desc)
byPriority = Todo.all.order(priority, asc)

// Chained query
results = Product
    .where(category == "electronics")
    .where(price < 1000)
    .order(rating, desc)
    .limit(10)

// Pagination
page2 = Todo.all.limit(20).offset(20)

One-to-Many

Reference another entity type directly. FlinDB automatically handles the foreign key relationship.

Many-to-Many

Use array syntax [Entity] for many-to-many relationships. No join tables to manage manually.

Self-Reference

Entities can reference themselves with optional fields. Perfect for tree structures like categories or comments.

CRUDD Model

FlinDB uses CRUDD (not CRUD) with two delete operations:

• delete - Soft delete (recoverable, keeps history)
• destroy - Hard delete (permanent, GDPR compliant)

// One-to-Many
entity User { name: text }

entity Post {
    title: text
    author: User  // Reference
}

// Many-to-Many
entity Tag { name: text }

entity Article {
    title: text
    tags: [Tag]  // Array of refs
}

// Self-Reference
entity Category {
    name: text
    parent: Category?  // Optional
}

// CRUDD - Two delete operations
delete user   // Soft (recoverable)
restore user  // Undo soft delete
destroy user  // Hard (permanent)

Write-Ahead Log (WAL)

Every operation is logged before execution. On crash, the WAL automatically replays to restore your database to a consistent state.

Content-Addressable Blobs

Files stored with SHA-256 addressing. Automatic deduplication means storing the same file twice uses no extra space.

Vector Embeddings

Built-in vector storage for semantic search. Fields marked as semantic text automatically generate embeddings.

Cloud Backup Features

• Zstd Compression - 3-5x smaller backup files
• AES-256-GCM - Military-grade encryption
• GCS & R2 - Google Cloud or Cloudflare R2 storage
• PITR - Point-in-time recovery from any moment

.flindb/
├── wal.log           # Write-Ahead Log
├── data/             # Entity snapshots
├── blobs/            # Content-addressable
├── vectors/          # Embeddings
├── indexes/          # Query indexes
├── schema.json       # Auto-schemas
├── meta.json         # Metadata
└── checkpoint.json   # Checkpoint

# Cloud backup to R2
flin backup --to r2://bucket
# Restore from any point
flin restore --at "2024-01-15"