This helper constructs an expression suitable for inclusion in a RETURN { ... } block. It safely checks if the field is an array using IS_ARRAY() and returns its length with LENGTH(). If the field is not an array, it defaults to 0.

Example usage:

aqlFieldArrayCount('tags');
// Produces: "tags: IS_ARRAY(doc.tags) ? doc.tags : null"

// Count elements in a custom document variable "u" with property "authors"
aqlFieldArrayCount('authors', 'edge', '[]');
// Produces: "authors: IS_ARRAY(edge.authors) ? LENGTH(edge.authors) : []"

This helper constructs an expression suitable for inclusion in a RETURN { ... } block. It safely checks if the field is an array using IS_ARRAY() and returns its length with LENGTH(). If the field is not an array, it defaults to 0.

Example usage:

// Count elements in "tags" array in "doc"
aqlFieldArrayCount('tagCount');
// Produces: "tagCount: IS_ARRAY(doc.tags) ? LENGTH(doc.tags) : 0"

// Count elements in a custom document variable "u" with property "authors"
aqlFieldArrayCount('authorCount', 'u', 'authors');
// Produces: "authorCount: IS_ARRAY(u.authors) ? LENGTH(u.authors) : 0"

This helper constructs an expression suitable for inclusion in a RETURN { ... } block. It checks if the field is an array using IS_ARRAY() and returns the first element using FIRST(). If the field is not an array, it returns null.

Example usage:

// Extract the first author from "doc.authors"
aqlFieldArrayFirst('mainAuthor', 'doc.authors');
// Produces: "mainAuthor: IS_ARRAY(doc.authors) ? FIRST(doc.authors) : null"

// Extract the first tag from a custom variable
aqlFieldArrayFirst('firstTag', 'tagsList');
// Produces: "firstTag: IS_ARRAY(tagsList) ? FIRST(tagsList) : null"

This helper builds a snippet suitable for a RETURN { ... } block in AQL. It references a field in the given document (or alias) and wraps it with the TO_BOOL() function, ensuring the value is interpreted as a boolean in AQL.

If $keyName is not provided, the $key parameter is used as both the resulting key in the object and the field name in the document.

Example usage:

// PHP call
aqlFieldBool('isActive');

// Generates
isActive: TO_BOOL(doc.isActive)

Guards the projected value behind a condition — the SQL CASE WHEN … THEN … ELSE … shape, rendered as an AQL ternary:

price: doc.visibility == 'public' ? doc.price : null

The key is always present; only the value switches to the else branch (default null) when the condition is false — it never omits the key (that would require a MERGE, intentionally out of scope). The condition is compiled by buildWhenCondition() (inline, no bind variables) and the else branch by resolveWhenElse().

The $then expression is the already-built scalar projection — the bare field reference (doc.price) or, when the field also declares Field::ALTERS, the transformed value (LOWER(TRIM(doc.price))). The caller (aqlFields()) builds it.

This helper builds a snippet suitable for inclusion in a RETURN { ... } block. It performs the following steps:

1. Checks whether the specified document field contains a valid date string using IS_DATE_STRING().
2. If valid, formats the date to the provided ISO 8601 pattern using DATE_FORMAT().
3. If not valid, returns null.

This ensures that the resulting AQL object always contains a valid ISO-formatted date or null.

Example usage:

// PHP call
aqlFieldDateTime('createdAt');

// Generates
createdAt: IS_DATE_STRING(doc.createdAt) ? DATE_FORMAT(doc.createdAt, "%yyyy-%mm-%ddT%hh:%ii:%ssZ") : null

This helper builds a snippet suitable for inclusion in a RETURN { ... } block. It maps a document property to an object key in the AQL result:

• $key becomes the key in the resulting AQL object.
• $doc and optional $keyName define the field to reference.

If $keyName is omitted, the same name as $key is used.

Example usage:

aqlFieldDefault( 'name'   , 'doc' ) ; // "name: doc.name"
aqlFieldDefault( 'userId' , 'doc' , 'id'); // "userId: doc.id"

This helper handles nested document fields and can include subfields recursively.

• If $options[Field::FIELDS] is provided as an array of subfields, it generates a nested { ... } expression using aqlFields().
• If no subfields are defined, it falls back to a default field expression using aqlFieldDefault().

Example usage:

// Simple document field
aqlFieldDocument('author', 'doc', ['name' => 'author']);
// Produces: "author: doc.author"

// Document field with nested subfields
aqlFieldDocument( 'author', 'doc',
[
    Field::NAME   => 'author',
    Field::FIELDS =>
    [
      'firstName' => Filter::DEFAULT ,
      'lastName'  => Filter::DEFAULT ,
    ]
]);
// Produces: "author: { firstName: doc.author.firstName, lastName: doc.author.lastName }"

This method creates a sub-query that iterates over an array in the document and returns each element with only the specified fields.

Example output:

addresses: ( FOR item IN doc.addresses RETURN { street: item.street, city: item.city } )

This helper constructs an expression suitable for inclusion in a RETURN { ... } block, converting a document property to a numeric value using TO_NUMBER(). It ensures that non-numeric values are safely handled by AQL.

Behavior:

• $key becomes the key in the resulting AQL object.
• $doc is the document alias or variable.
• $keyName optionally specifies a different property name in the document; defaults to $key.

Example usage:

// PHP call
aqlFieldInt('age');
// Generates: age: TO_NUMBER(doc.age)

aqlFieldInt('id', 'u', 'identifier');
// Generates: id: TO_NUMBER(u.identifier)

This helper constructs an expression suitable for inclusion in a RETURN { ... } block. It returns the translated value of a field using the TRANSLATE() function if a language code is provided. Otherwise, it falls back to the original field value.

Behavior:

• $key is used as the key in the resulting AQL object.
• $doc is the document variable or expression containing the field.
• $keyName allows specifying a different property name in the document; defaults to $key.
• $lang is the optional language code for translation; if null, the original value is returned.

Note: the language is the FOURTH argument; the third is $keyName.

Example usage:

// Translate the "title" field to French (lang is the 4th argument)
aqlFieldTranslate('title', 'doc', null, 'fr');
// Produces: title:TRANSLATE("fr",doc.title,"")

// No translation (lang null) → original field
aqlFieldTranslate('description', 'doc');
// Produces: description:doc.description

// Different property name ($keyName) AND a language
aqlFieldTranslate('label', 'doc', 'name', 'en');
// Produces: label:TRANSLATE("en",doc.name,"")

This function constructs a full URL for a document field by optionally combining:

1. A base URL retrieved from a DI container (if $container and $urlKey are provided).
2. A path pattern ($path) that can contain placeholders in the form {param} or {param:regex}.
3. The document key (defaulting to _key or a custom $keyName).

Placeholders in the path will be replaced by values provided in the $init array under the key Arango::ARGS. If a placeholder has no corresponding value in $init, it remains unchanged in the resulting URL.

Example URL pattern:

'/observation/{observation:[A-Za-z0-9_]+}/workspace/{workspace}/places'

Example usage:

echo aqlFieldUrl(
    key       : 'url',
    options   : [ Field::PATH => '/observation/{observation}/workspace/{workspace}/places' ],
    init      : [ Arango::ARGS => ['observation' => '15454', 'workspace' => '787878'] ],
    container : $container
);
// Returns:
// url:CONCAT('https://base.url/observation/15454/workspace/787878/places','/',doc._key)

Discriminant routing (Field::PATHS):

When Field::PATHS is provided, the path is resolved at query time from a discriminant attribute of the document (default Schema::ADDITIONAL_TYPE, overridable via Field::PROPERTY) using the AQL TRANSLATE() function. Field::PATH is then mandatory and is used as the fallback route for documents whose discriminant value is not present in the map — emitting it as the third TRANSLATE() argument guarantees an unmatched value never leaks the raw discriminant into the URL.

echo aqlFieldUrl(
    key     : 'url',
    options :
    [
        Field::PATH     => '/thing' ,                                  // fallback (mandatory with PATHS)
        Field::PATHS    => [ 'Place' => '/places' , 'Person' => '/people' ] ,
        Field::PROPERTY => Schema::ADDITIONAL_TYPE ,                   // optional discriminant
    ],
    container : $container
);
// Returns:
// url:CONCAT(TRANSLATE(doc.additionalType,{Place:'https://base.url/places',Person:'https://base.url/people'},'https://base.url/thing'),'/',doc._key)

Unlike aqlFieldDocument() — which nests a sub-attribute of the reference (ref.key.subfield) — this helper projects the sub-fields directly against $ref (ref.subfield), so the whole reference is embedded inside a new object under $key. It is the symmetric counterpart of Field::SCOPE : inside an edge traversal it lets a definition hoist the traversal vertex (the related entity) under a named key — e.g. subject — alongside the edge metadata, instead of flattening the vertex fields at the root.

• With Field::FIELDS : projects the listed sub-fields against $ref and wraps them in a { ... } object under $key.
• Without Field::FIELDS : a field whitelist is required by default. Pass Field::RAW => true to deliberately embed the whole reference as-is (key: ref) — every attribute of the vertex/edge, no projection.

The wrapped reference may also carry its own relations. The sub-fields can include the usual relation markers (Filter::EDGE / Filter::EDGES / Filter::EDGES_COUNT for edges, Filter::JOIN / Filter::JOINS for joins) and the field declares a companion Field::EDGES / Field::JOINS map of sub-relations that start from the wrapped vertex — exactly the same shape as a top-level projection (fields markers beside an edges/joins registry). The backing LET variables are emitted upstream by buildVariables() with $ref as the traversal root, so the related entities nest inside the wrapped object (e.g. subject.worksFor) in a single query. Field::RAW is mutually exclusive with Field::EDGES / Field::JOINS (a verbatim reference has no projected object to nest into).

Example usage:

// Wrap the traversal vertex under "subject", with a projection
aqlFieldWrap( 'subject', 'v',
[
    Field::FIELDS =>
    [
        'id'        => Filter::DEFAULT ,
        'givenName' => Filter::DEFAULT ,
    ]
]);
// Produces: "subject: { id: v.id, givenName: v.givenName }"

// Wrap the vertex AND nest one of its relations under the wrapped key.
// The sub-edge declares the cardinality marker in Field::FIELDS and the
// traversal definition in Field::EDGES (here reached INBOUND).
aqlFieldWrap( 'subject', 'v',
[
    Field::FIELDS =>
    [
        'id'       => Filter::DEFAULT ,
        'name'     => Filter::DEFAULT ,
        'worksFor' => [ Field::FILTER => Filter::EDGE , Field::UNIQUE => 'worksFor_e1' ] ,
    ] ,
    Field::EDGES =>
    [
        'worksFor' => [ AQL::MODEL => OrgHasMember::class , AQL::DIRECTION => Traversal::INBOUND ] ,
    ] ,
]);
// Produces (the worksFor_e1 LET being emitted upstream against `v`):
// "subject: { id: v.id, name: v.name, worksFor: (IS_OBJECT(worksFor_e1) ? … ) }"

// Wrap the whole vertex as-is (opt-in)
aqlFieldWrap( 'subject', 'v', [ Field::RAW => true ] );
// Produces: "subject: v"

Mirrors the recursive grammar of the flat ?filter= DSL (HasFilterConditions) — so a condition written for a filter reads the same here — but compiles inline (no bind variables), because the projection layer (aqlFields()) carries none.

Disambiguation:

• string → a truthiness leaf: 'active' → TO_BOOL(doc.active).
• associative array → an explicit leaf (see buildWhenLeaf()).
• list whose first element is a logic keyword (and / or / not) → a group over the remaining conditions; not expects exactly one condition.
• list whose elements are all arrays → an implicit AND group.
• list of scalars → a single leaf [ '<attr>', '<op>'?, <value> ].

Examples:

buildWhenCondition( 'active' );
// TO_BOOL(doc.active)

buildWhenCondition( [ 'visibility', 'public' ] );
// doc.visibility == 'public'

buildWhenCondition( [ [ 'a', 'x' ], [ 'b', 'gt', 0 ] ] );
// (doc.a == 'x' && doc.b > 0)

buildWhenCondition( [ 'or', [ 'role', 'admin' ], [ 'owner', 'eq', true ] ] );
// (doc.role == 'admin' || doc.owner == true)

buildWhenCondition( [ 'not', [ 'anonymized', true ] ] );
// !(doc.anonymized == true)

A leaf compares a document attribute against a value (or tests its truthiness). Two declaration forms are accepted:

• Compact list — [ '<attr>' ] (truthy), [ '<attr>', <value> ] (equality), [ '<attr>', '<op>', <value> ] (explicit comparator).
• Associative — [ FilterParam::KEY => '<attr>', FilterParam::OP => '<op>', FilterParam::VAL => <value>, FilterParam::ALT => <chain> ]. Without FilterParam::VAL the leaf is a truthiness test.

The compared attribute (left) and the value (right) may be wrapped by an alt chain — same "lower" / { key, val } / { key, val:true } mirror vocabulary as the flat filters (resolved by resolveAltSides()). The value is inlined via aqlValue() (the projection layer carries no bind variables; a WHEN value is developer-declared static configuration, never user input). The attribute is validated by assertAttributeName().

Only the infix comparators (eq, ne, ge, gt, le, lt, in, nin, like, nlike, match, nmatch) are supported; a function-form operator (contains, sw, ew, regex, …) throws — use the flat ?filter= for those.

Two forms:

• Attribute reference — [ Field::PROPERTY => '<attr>' ] → doc.<attr> (validated by assertAttributeName()), so the fallback can mirror another document attribute.
• Literal — anything else (a scalar, an array of scalars, or null — the default) is inlined via aqlValue().