qail-core 0.5.1-alpha

Core parser and transpiler for QAIL
Documentation
qail-core-0.5.1-alpha has been yanked.

🪝 QAIL — The Horizontal Query Language

Stop writing strings. Hook your data.

Crates.io License Rust

The Manifesto

SQL is vertical, verbose, and clunky inside modern codebases.

QAIL is horizontal, dense, and composable. It treats database queries like a pipeline, using symbols to hook data and pull it into your application.

-- The Old Way (SQL)
SELECT id, email, role FROM users WHERE active = true LIMIT 1;

# The QAIL Way
get::users•@id@email@role[active=true][lim=1]

One line. Zero ceremony. Maximum velocity.

The Philosophy

  1. Constraint: Vertical space is precious. SQL blocks interrupt the flow of code reading. QAIL flows with your logic.
  2. Density: Symbols (@, •, []) convey more information per pixel than keywords (SELECT, FROM, WHERE).
  3. The Star Rule: If you need 50 columns, fetch the struct (@*). If you need 3, list them. Listing 20 columns manually is an anti-pattern. QAIL encourages "all or nothing" density.

Is it still Horizontal? Yes. The language itself is horizontal because it uses symbols instead of keywords. But we give you the Vertical Escape Hatch (tabs/newlines) so you can organize complex logic however you see fit, without fighting the parser. Horizontal is the identity; Vertical is the layout.

📖 Quick Reference

Symbol Name Function SQL Equivalent
:: The Gate Defines the action SELECT, INSERT, UPDATE
! The Unique Distinct modifier SELECT DISTINCT
• The Pivot Connects action to table FROM table
@ The Hook Selects specific columns col1, col2
[] The Cage Constraints & Filters WHERE, LIMIT, SET
-> The Link Inner Join INNER JOIN
<- The Left Left Join LEFT JOIN
->> The Right Right Join RIGHT JOIN
~ The Fuse Fuzzy / Partial Match ILIKE '%val%'
| The Split Logical OR OR
& The Bind Logical AND AND
^! The Peak Sort Descending ORDER BY ... DESC
^ The Rise Sort Ascending ORDER BY ... ASC
* The Star All / Wildcard *
[*] The Deep Array Unnest UNNEST(arr)
$ The Var Parameter Injection $1, $2
lim= The Limit Row limit LIMIT n
off= The Skip Offset for pagination OFFSET n

🚀 Installation

CLI (Recommended)

cargo install qail

As a Library

# Cargo.toml
[dependencies]
qail = "0.5.0-alpha"

💡 Usage

CLI — The qail Command

# Fetch all users
qail 'get::users•@*'

# Get specific columns with filter
qail 'get::orders•@id@total@status[user_id=$1][lim=10]' --bind 42

# Update a record
qail 'set::users•[verified=true][id=$1]' --bind 7

# Delete with condition
qail 'del::sessions•[expired_at<now]'

# Transpile only (don't execute)
qail 'get::users•@*[active=true]' --dry-run

As a Library

use qail::prelude::*;

#[tokio::main]
async fn main() -> Result<(), QailError> {
    let db = QailDB::connect("postgres://localhost/mydb").await?;

    // Parse and execute
    let users: Vec<User> = db
        .query("get::users•@id@email@role[active=true][lim=10]")
        .fetch_all()
        .await?;

    // Or use the builder for type-safe composition
    let query = qail::get("users")
        .hook(&["id", "email", "role"])
        .cage("active", true)
        .limit(10);

    let users: Vec<User> = db.run(query).fetch_all().await?;

    Ok(())
}

📚 Syntax Deep Dive

A. Simple Fetch (get::)

-- SQL
SELECT id, email, role FROM users WHERE active = true LIMIT 1;

# QAIL
get::users•@id@email@role[active=true][lim=1]

B. Mutation (set::)

-- SQL
UPDATE user_verifications SET consumed_at = now() WHERE id = $1;

# QAIL
set::user_verifications•[consumed_at=now][id=$1]

Note: In set:: mode, the first [] is the payload (SET), the second [] is the filter (WHERE).

C. Deletion (del::)

-- SQL
DELETE FROM sessions WHERE expired_at < now();

# QAIL
del::sessions•[expired_at<now]

D. Complex Search with Fuzzy Match

-- SQL
SELECT * FROM ai_knowledge_base 
WHERE active = true 
AND (topic ILIKE $1 OR question ILIKE $1 OR EXISTS (SELECT 1 FROM unnest(keywords) k WHERE k ILIKE $1))
ORDER BY created_at DESC
LIMIT 5;

# QAIL
get::ai_knowledge_base•@*[active=true][topic~$1|question~$1|keywords[*]~$1][^!created_at][lim=5]

# Or multi-line for readability:
get::ai_knowledge_base•@*
  [active=true]
  [topic~$1 | question~$1 | keywords[*]~$1]
  [^!created_at]
  [lim=5]

E. Joins

# Inner join (default)
get::users->orders•@name@total
# → SELECT name, total FROM users INNER JOIN orders ON orders.user_id = users.id

# Left join (include users without orders)
get::users<-orders•@name@total
# → SELECT name, total FROM users LEFT JOIN orders ON orders.user_id = users.id

# Right join
get::orders->>customers•@*
# → SELECT * FROM orders RIGHT JOIN customers ON customers.order_id = orders.id

F. DISTINCT Queries (v0.5+)

# Get unique roles
get!::users•@role
# → SELECT DISTINCT role FROM users

# Distinct with filter
get!::orders•@status[created_at>'2024-01-01']
# → SELECT DISTINCT status FROM orders WHERE created_at > '2024-01-01'

G. Pagination (OFFSET)

# Page 3 (20 items per page)
get::products•@*[lim=20][off=40]
# → SELECT * FROM products LIMIT 20 OFFSET 40

⚙️ Configuration

Create a .qailrc or qail.toml in your project root:

[connection]
driver = "postgres"           # postgres | mysql | sqlite
url = "postgres://localhost/mydb"

[output]
format = "table"              # table | json | csv
color = true

[safety]
confirm_mutations = true      # Prompt before UPDATE/DELETE
dry_run_default = false

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                      QAIL Pipeline                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   "get::users•@*[active=true]"                              │
│              │                                              │
│              ▼                                              │
│   ┌─────────────────────┐                                   │
│   │   Parser (nom)      │  → Tokenize symbols               │
│   └─────────┬───────────┘                                   │
│             │                                               │
│             ▼                                               │
│   ┌─────────────────────┐                                   │
│   │   AST (QailCmd)     │  → Structured representation      │
│   └─────────┬───────────┘                                   │
│             │                                               │
│             ▼                                               │
│   ┌─────────────────────┐                                   │
│   │ Transpiler (SQL)    │  → Generate valid SQL             │
│   └─────────┬───────────┘                                   │
│             │                                               │
│             ▼                                               │
│   ┌─────────────────────┐                                   │
│   │ Engine (sqlx)       │  → Execute against DB             │
│   └─────────────────────┘                                   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Core Structs

pub struct QailCmd {
    pub action: Action,         // GET, SET, DEL, ADD
    pub table: String,
    pub columns: Vec<Column>,
    pub cages: Vec<Cage>,       // Filters, limits, sorts
    pub bindings: Vec<Value>,
}

pub enum Action {
    Get,    // SELECT
    Set,    // UPDATE
    Del,    // DELETE
    Add,    // INSERT
}

pub struct Cage {
    pub kind: CageKind,         // Filter, Limit, Sort, Payload
    pub conditions: Vec<Condition>,
}

pub struct Condition {
    pub column: String,
    pub op: Operator,           // Eq, Ne, Gt, Lt, Fuzzy, In
    pub value: Value,
}

🗺️ Roadmap

Phase 1: Parser ✅

  • Lexer for QAIL symbols
  • nom parser combinators
  • AST generation

Phase 2: Transpiler ✅

  • PostgreSQL codegen
  • MySQL codegen
  • SQLite codegen
  • JOINs (INNER, LEFT, RIGHT)
  • DISTINCT, OFFSET, RETURNING

Phase 3: Engine ✅

  • Async execution (sqlx)
  • Connection pooling
  • Multi-driver support (Postgres/MySQL/SQLite)
  • Transaction support
  • Prepared statement caching

Phase 4: Ecosystem ✅

  • VS Code extension (syntax highlighting)
  • qail! compile-time macro
  • Struct generation (gen::)
  • Language server (LSP)
  • REPL mode

E. The Flagship Comparison (Complex Joins)

Scenario: Find verified users who joined after 2024 and booked under the 'SUMMER' campaign.

-- SQL (7 lines, cognitive load high)
SELECT u.* 
FROM users u
JOIN bookings b ON b.user_id = u.id
WHERE u.created_at >= '2024-01-01'
  AND u.email_verified = true
  AND b.campaign_code ILIKE '%SUMMER%'
ORDER BY u.created_at DESC
LIMIT 50;

# QAIL (1 line, cognitive load low)
get::users->bookings•@*[created_at>='2024-01-01'][email_verified=true][bookings.campaign_code~'SUMMER'][^!created_at][lim=50]

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

# Clone the repo
git clone https://github.com/your-username/qail.git
cd qail

# Run tests
cargo test

# Run with example
cargo run -- "get::users•@*[lim=5]" --dry-run

📄 License

MIT © 2025 QAIL Contributors