aqlCollectReturn.php
Table of Contents
Functions
- aqlCollectReturn() : string
- Builds the `RETURN` clause that follows an AQL `COLLECT` produced by {@see aqlCollect()}.
Functions
aqlCollectReturn()
Builds the `RETURN` clause that follows an AQL `COLLECT` produced by {@see aqlCollect()}.
aqlCollectReturn([array<string|int, mixed> $spec = [] ][, string|null $explicit = null ]) : string
After a COLLECT, the iteration variable (e.g. doc) is out of scope: only the
grouping variables, the aggregate variables and the optional WITH COUNT variable
remain usable. This helper derives a valid projection from the very same $spec
given to aqlCollect(), so the two always stay in sync.
Behaviour
- An explicit, non-empty
$explicitexpression always wins (RETURN <expr>). - Otherwise the projection is derived from the spec:
- grouping keys (
array_keys(AQL::ASSIGN)) + aggregate keys (array_keys(AQL::AGGREGATE)), - plus the
AQL::WITH_COUNTvariable when present.
- grouping keys (
AQL::AGGREGATEandAQL::WITH_COUNTare mutually exclusive (mirrors aqlCollect()): when an aggregate is present the count variable is ignored.- A pure count (no grouping, no aggregate, only
WITH_COUNT) returns the scalar count (RETURN length), not an object. - When nothing can be projected, an empty string is returned.
AQL::INTO collected documents are intentionally NOT auto-projected (they may be huge);
pass an $explicit projection to expose them.
Examples
echo aqlCollectReturn([ AQL::ASSIGN => ['status' => 'doc.status'] ]);
// RETURN { status }
echo aqlCollectReturn([ AQL::ASSIGN => ['category' => 'doc.category'], AQL::WITH_COUNT => 'count' ]);
// RETURN { category, count }
echo aqlCollectReturn([ AQL::WITH_COUNT => 'length' ]);
// RETURN length
echo aqlCollectReturn([ AQL::ASSIGN => ['y' => 'DATE_YEAR(doc.created)'] ], '{ year: y }');
// RETURN { year: y }
Parameters
- $spec : array<string|int, mixed> = []
-
The same associative spec passed to aqlCollect().
- $explicit : string|null = null
-
An explicit RETURN expression overriding the derivation.
Tags
Return values
string —The compiled AQL RETURN clause, or an empty string when nothing to project.