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 either a fully qualified PHP class name or a short class name — if unqualified, the engine automatically prepends the configured entity_namespace from database.php: 

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

The via Keyword

Use via to join a related entity through a relationship property. Without it, a second range would produce a cartesian product of both entities — via tells ObjectQuel how the two are connected. The property after via must be a relation declared on the entity, not a plain column: 

// 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)
");

To filter the joined results, use a where clause rather than adding conditions to via: 

$results = $entityManager->executeQuery("
    range of u is App\\Entity\\UserEntity
    range of o is App\\Entity\\OrderEntity via u.orders
    retrieve (u, o)
    where o.status = 'active'
");

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.id)
");

An optional second JSONPath argument filters which records enter the range:

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

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.customerId, summary.total)
    where summary.total > 1000
");

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