Range Definitions

A range definition declares which data a query operates on and assigns each one a short alias. Every alias you use in retrieve, where, or sort by must be declared as a range first. ObjectQuel supports three kinds: database entity ranges, JSON file ranges, and inline subquery ranges.

explanation

Database Entity Ranges

The most common kind. The syntax is range of [alias] is [EntityClass], where the entity class is a fully qualified PHP class name:

$results = $entityManager->executeQuery("
    range of p is App\\Entity\\ProductEntity
    retrieve (p)
");

The via Keyword

Use via to traverse a relationship from an already-declared alias, rather than ranging over the full entity table. This is how you join related entities. The expression after via is either a property path or a compound logical expression:

// Traverse a relationship property
$results = $entityManager->executeQuery("
    range of u is App\\Entity\\UserEntity
    range of o is App\\Entity\\OrderEntity via u.orders
    retrieve (u, o)
");

// Traverse and filter in one expression
$results = $entityManager->executeQuery("
    range of u is App\\Entity\\UserEntity
    range of o is App\\Entity\\OrderEntity via u.orders and o.status = 'active'
    retrieve (u, o)
");
Declare ranges in dependency order. Any alias referenced in a via clause must be declared on a preceding line. Always declare parent entities before the children that depend on them.

JSON Source Ranges

A JSON source range behaves like a database entity range in most respects — you can use it in retrieve, where, and sort by just as you would any entity alias. The one exception is that via traversal is not supported, since JSON files have no relationships to traverse. Instead of an entity class, you point it at a JSON file using json_source: 

$results = $entityManager->executeQuery("
    range of p is json_source(\"/path/to/products.json\")
    retrieve (p)
");

An optional second argument filters which records enter the range:

$results = $entityManager->executeQuery("
    range of p is json_source(\"/path/to/products.json\", \"active = true\")
    retrieve (p)
");

Subquery Ranges

A range can be defined as an inline subquery enclosed in parentheses. How ObjectQuel executes it depends on what the subquery contains: if it references a json_source, ObjectQuel runs the subquery first and uses its result set as the data source for the outer query; otherwise, it injects the subquery directly into the FROM clause of the generated SQL:

$results = $entityManager->executeQuery("
    range of summary is (
        range of o is App\\Entity\\OrderEntity
        retrieve (o.customerId, total=sum(o.total))
    )
    retrieve (summary) where summary.total > 1000
");

// $results contains records shaped as:
// [
//     ['customerId' => 4, 'total' => 1250.00],
//     ['customerId' => 11, 'total' => 3400.00],
// ]