Q‑Pie

Single FileCustom LanguageJSON Engine

Q‑Pie is a self‑contained database workbench, optimized for tablets and designed for experimentation, teaching, prototyping, and custom language development. It runs entirely in the browser — no backend, no dependencies, no installation.

Q‑Pie provides:

• A custom SQL‑like query language
• A tokenizer, parser, AST, and compiler
• A JSON‑backed execution engine
• JOIN, WHERE, GROUP BY, HAVING, ORDER BY, LIMIT
• INSERT, UPDATE, DELETE
• Syntax highlighting and autocomplete
• Schema explorer and JSON import/export
• Error highlighting and a minimal, focused UI

2. Core Concepts

Q‑Pie is built around four internal layers that mirror real database engines.

2.1 Tokenizer

Breaks raw text into meaningful tokens:

• Identifiers
• Numbers
• Strings
• Operators
• Punctuation
• Keywords

2.2 Parser

Consumes tokens and produces an AST (Abstract Syntax Tree) that represents the structure of the query.

2.3 Compiler

Transforms the AST into standard SQL. This is useful for debugging, teaching, or comparing the custom syntax to SQL.

2.4 Execution Engine

Executes the AST directly against an in‑memory JSON database. Q‑Pie is both a compiler and a database engine, all inside your browser.

3. The Q‑Pie Language

Q‑Pie uses a simplified SQL‑like syntax designed to be readable and easy to parse.

GET columns FROM table
[JOIN table2 ON condition]
[WHERE condition]
[GROUP BY field]
[HAVING condition]
[ORDER BY field [ASC|DESC]]
[LIMIT n];

GET * FROM users;

GET name, age FROM users
WHERE age > 18
ORDER BY age DESC
LIMIT 10;

GET u.name, COUNT(o.id) FROM users u
JOIN orders o ON u.id = o.user_id
GROUP BY u.id
HAVING COUNT(o.id) > 1;

ADD INTO table (col1, col2, col3)
VALUES (val1, val2, val3);

ADD INTO users (name, email, age)
VALUES ("Alice", "alice@example.com", 30);

CHANGE table
SET col1 = val1, col2 = val2
[WHERE condition];

CHANGE users
SET status = "inactive"
WHERE last_login < "2024-01-01";

DROP FROM table
[WHERE condition];

DROP FROM users
WHERE status = "inactive";

4. Conditions and Expressions

Q‑Pie supports simple boolean expressions:

age > 18
status = "active"
total >= 50

And logical chaining:

age > 18 AND status = "active"

Parentheses are not yet supported by design, keeping the engine simple and predictable.

5. JOINs

Q‑Pie supports INNER JOIN:

JOIN table2 ON condition

Example

GET users.name, orders.total
FROM users
JOIN orders ON users.id = orders.user_id;

JOINs are executed by merging rows where the ON condition evaluates to true.

6. Aggregation

Supported aggregate functions:

• COUNT(x)
• SUM(x)
• AVG(x)
• MIN(x)
• MAX(x)

Aggregates require GROUP BY.

Example

GET user_id, SUM(total)
FROM orders
GROUP BY user_id;

7. ORDER BY

Q‑Pie supports:

ORDER BY field
ORDER BY field DESC

Multiple fields are not yet supported, by design.

8. LIMIT

Use LIMIT to restrict the number of returned rows:

LIMIT 10

9. JSON Database

Q‑Pie stores all data in a simple JSON object:

DB = {
  users: [...],
  orders: [...],
  products: [...]
}

This database is editable, exportable, importable, and fully in‑memory.

10. Importing & Exporting the Database

10.1 Export

Click Export DB in the toolbar.

This downloads a database.json file containing the entire in‑memory database.

10.2 Import

Click Import DB and select a .json file. Q‑Pie loads it into memory and updates the schema sidebar.

The JSON format must be:

{
  "tableName": [
    { "col1": "value", "col2": 123 },
    ...
  ]
}

11. Interface

Q‑Pie’s interface is divided into four main areas.

11.1 Editor

• Syntax highlighting
• Autocomplete for keywords and functions
• Error highlighting
• Multi‑line editing
• Tab inserts spaces

11.2 Compiled SQL Panel

Shows the SQL equivalent of your custom query. This is useful for understanding how Q‑Pie maps its language to SQL semantics.

11.3 Result Panel

Displays:

• Rows returned for GET queries
• rowCount for SELECT
• affectedRows for INSERT/UPDATE/DELETE
• Inserted/updated row data where relevant

11.4 Schema Sidebar

Lists all tables and their columns. Clicking a table inserts a template query like:

GET * FROM tableName
LIMIT 10;

11.5 Scrolling Behavior in the Result Panel

Q‑Pie’s result viewer is designed to handle large tables gracefully. In most environments, the table viewer supports both horizontal and vertical scrolling automatically. However, some web‑app containers (especially mobile webviews or hybrid app wrappers) may intercept native scroll events, causing vertical scrolling to clash with pull‑to‑refresh or parent container behavior.

17.1 ID‑Based Scroll Container

To ensure consistent behavior across all environments, Q‑Pie uses an id-based scroll container for the result panel. This isolates scrolling to a single element and prevents parent containers from hijacking scroll events.

WHERE id > 11 
WHERE id > 22 (etc)

This approach avoids issues such as:

• Pull‑to‑refresh triggering during long scrolls
• Scroll events being swallowed by parent containers
• Vertical scrolling failing in mobile or embedded environments

17.2 Why This Method Works

By giving the #result element its own scroll context, Q‑Pie ensures that vertical scrolling behaves consistently regardless of the host environment. This method is especially reliable in mobile webviews, Electron‑style wrappers, and other embedded browser contexts.

12. Error Handling

Q‑Pie highlights errors in:

• Parsing (invalid syntax)
• Compilation (unexpected AST shapes)
• Execution (invalid operations on the JSON DB)

When an error occurs:

• The editor border turns red
• The compiled SQL panel shows -- ERROR --
• The result panel shows the error message

13. Architecture Overview

User Input
   ↓
Tokenizer
   ↓
Parser → AST
   ↓
Compiler → SQL (display only)
   ↓
Execution Engine → JSON DB
   ↓
Results

This architecture mirrors real database engines, making Q‑Pie a powerful learning tool as well as a practical sandbox.

14. Extending Q‑Pie

Q‑Pie is intentionally simple and hackable. You can extend it by modifying:

• The tokenizer regex
• The parser functions
• The execution engine
• The UI and layout

Common extensions include:

• Parentheses in expressions
• LEFT/RIGHT/FULL JOIN
• ORDER BY multiple fields
• Table editor UI
• Persistent storage (LocalStorage / IndexedDB)
• CREATE TABLE / ALTER TABLE
• Subqueries

15. Philosophy

Q‑Pie is built on three principles:

15.1 Transparency

Everything is visible and understandable. No hidden layers, no magic.

15.2 Minimalism

No frameworks, no dependencies, no build steps. Just HTML, CSS, and JavaScript.

15.3 Hackability

You can modify any part of the system without breaking the rest. Q‑Pie is a living codebase, not a black box.

16. Summary

Q‑Pie is a compact, elegant, fully functional query engine and database workbench that fits inside a single HTML file. It’s ideal for:

• Learning how SQL engines work
• Teaching parsing, ASTs, and compilers
• Prototyping custom query languages
• Running small datasets in the browser
• Experimenting with database concepts

It’s simple enough to understand in an afternoon, but powerful enough to grow with your ideas.