ATON Query Language Reference

Overview

ATON includes a powerful SQL-like query language for filtering, sorting, and projecting data before or after encoding.

Basic Syntax

tableName [SELECT fields] [WHERE conditions] [ORDER BY field [ASC|DESC]] [LIMIT n] [OFFSET n]

All clauses except the table name are optional.

Clauses

SELECT

Specifies which fields to include in results.

users SELECT id, name, email

Without SELECT, all fields are returned.

WHERE

Filters records based on conditions.

users WHERE active = true
users WHERE age > 21 AND country = 'US'

ORDER BY

Sorts results by a field.

products ORDER BY price ASC
products ORDER BY created_at DESC

Default is ASC if not specified.

LIMIT

Limits the number of results.

users LIMIT 10

OFFSET

Skips a number of results (for pagination).

users LIMIT 10 OFFSET 20

Comparison Operators

| Operator | Description | Example | |----------|-------------|---------| | = | Equal to | status = 'active' | | != | Not equal to | status != 'deleted' | | <> | Not equal to (alt) | status <> 'deleted' | | < | Less than | price < 100 | | > | Greater than | price > 50 | | <= | Less than or equal | age <= 65 | | >= | Greater than or equal | score >= 80 |

Special Operators

LIKE

Pattern matching with wildcards: - % matches any sequence of characters - _ matches any single character

users WHERE name LIKE 'John%'      -- Starts with John
users WHERE email LIKE '%@gmail.com'  -- Ends with @gmail.com
users WHERE code LIKE 'A_B'        -- A, any char, B

IN

Matches any value in a list.

products WHERE category IN ('Electronics', 'Computers', 'Phones')
users WHERE role IN ('admin', 'moderator')

NOT IN

Excludes values in a list.

orders WHERE status NOT IN ('cancelled', 'refunded')

BETWEEN

Matches values within a range (inclusive).

products WHERE price BETWEEN 100 AND 500
users WHERE age BETWEEN 18 AND 65

Logical Operators

AND

Both conditions must be true.

users WHERE active = true AND verified = true

OR

Either condition must be true.

products WHERE category = 'Electronics' OR category = 'Computers'

NOT

Negates a condition.

users WHERE NOT deleted = true

Parentheses

Group conditions for complex logic.

users WHERE (role = 'admin' OR role = 'moderator') AND active = true

Data Types in Queries

Strings

Use single or double quotes:

WHERE name = 'John'
WHERE name = "John"

Numbers

No quotes needed:

WHERE price > 99.99
WHERE count = 42

Booleans

Use lowercase without quotes:

WHERE active = true
WHERE deleted = false

NULL

Use lowercase without quotes:

WHERE deleted_at = null

PHP Usage Examples

Basic Query

use Aton\QueryEngine;

$engine = new QueryEngine();
$data = [
    'users' => [
        ['id' => 1, 'name' => 'Alice', 'age' => 30, 'active' => true],
        ['id' => 2, 'name' => 'Bob', 'age' => 25, 'active' => false],
        ['id' => 3, 'name' => 'Carol', 'age' => 35, 'active' => true],
    ]
];

$query = $engine->parse("users WHERE active = true");
$results = $engine->execute($data, $query);
// Returns Alice and Carol

Complex Query

$query = $engine->parse(
    "users WHERE age >= 25 AND active = true ORDER BY age DESC LIMIT 10"
);
$results = $engine->execute($data, $query);

With Field Selection

$query = $engine->parse("users SELECT id, name WHERE active = true");
$results = $engine->execute($data, $query);
// Returns [['id' => 1, 'name' => 'Alice'], ['id' => 3, 'name' => 'Carol']]

Encode with Query

use Aton\ATON;

$aton = ATON::encodeWithQuery($data, "users WHERE active = true ORDER BY name");

Output includes query annotation:

@query[users WHERE active = true ORDER BY name]

@schema[id:int, name:str, age:int, active:bool]

users(2):
  1, "Alice", 30, true
  3, "Carol", 35, true

Error Handling

use Aton\Exceptions\ATONQueryException;

try {
    $query = $engine->parse("invalid query syntax here");
} catch (ATONQueryException $e) {
    echo "Query error: " . $e->getMessage();
}

Common errors: - Unknown table name - Invalid operator - Syntax errors - Type mismatches

Performance Tips

1. Use LIMIT for large datasets
2. Filter early with WHERE to reduce data
3. Select only needed fields with SELECT
4. Index-friendly conditions (equals before ranges)

Query Wrapper Format

Queries can be wrapped in @query[] annotation:

@query[users WHERE active = true ORDER BY name]

This is automatically handled by the parser.