The returned string is the compiled body:

FOR doc_join IN collection [<nested LETs>] FILTER … [SORT …] RETURN …

buildJoinVariable() wraps it into LET name = ( … ) for a regular join, while buildPolymorphicJoinVariable() wraps several such bodies into a single APPEND( ( … ) , ( … ) ) array so the collection can vary with a discriminator field.

Extracting this body from buildJoinVariable() lets a polymorphic join reuse the whole join machinery (filtering, sorting, skinning, nested edges / joins, definition-level gating) per branch. The only addition over the historical logic is $extraConditions, a list of ready-made AQL predicates (typically the discriminator guard) prepended to the branch filter.

Arango::CONDITIONS — restricting which joined documents are kept

The definition may carry extra predicates, appended to the key match. Two shapes: a plain array of AQL predicate strings, or — the useful one — a callable returning such an array. The callable receives three arguments, always:

Arango::CONDITIONS => fn( string $join , string $parent , array $init ) :array =>
    [ $join . '.active == true' ] ,

1. $join — the generated loop variable (a randomKey, so it cannot be hardcoded);
2. $parent — the enclosing document reference, to compare against the parent;
3. $init — the request-level init. Contractual keys only: Arango::AUTHORIZER, AQL::SKIN and Arango::BINDS; the rest is internal.

Declare only the parameters you need. PHP discards the surplus handed to a userland callable, so a one- or two-parameter closure keeps working untouched. An object method or an invokable is accepted too.

Returning [] emits no predicate, which is how a scope stays inert outside an HTTP request (a CLI run has no authorizer): the query is then byte-for-byte the unrestricted one, and no bind is required. A non-array return raises.

⚠️ A bind referenced as text inside a predicate (… NOT IN @hidden) cannot be discovered by the optional-bind pruning of prepareAndExecute(), which looks for aqlBindRef() objects. If a skin can drop this join, name that bind explicitly in the 4th argument of prepareAndExecute(), or ArangoDB rejects the whole query.

This method generates a complete subquery, enclosed in parentheses, which is assigned to a 'LET' variable. It handles:

• Filtering based on the document keys or custom conditions
• Sorting (if $isArray is true)
• Nested edges and joins
• Field selection and skinning

The subquery body itself is produced by buildJoinSubquery(); this wrapper only resolves the LET variable name and parenthesizes the body.

Example output:

LET myJoinVar = (
    FOR doc_join IN @@collection
        FILTER doc_join._key == doc.relatedKey
        RETURN { _key: doc_join._key, name: doc_join.name }
)

Definition-level gating: a definition declaring AQL::REQUIRES that the request-scoped authorizer denies is skipped — its LET is not emitted.

The whole branch machinery (guarding, per-branch permission gating, the FALLBACK branch, the APPEND combine) lives in the shared buildPolymorphicRelationVariable(); this function only resolves the join-specific shared defaults — the parent key path (Arango::PROPERTY, defaulting to $name) and the foreign key attribute (Arango::KEY) — and supplies the per-branch builder that wraps buildJoinSubquery().

The resulting LET always holds an array — exactly like a regular join — so the projection layer (aqlFieldObject()) unwraps it with FIRST() for a Filter::JOIN or keeps the whole array for a Filter::JOINS.

Example output (single Filter::JOIN, two branches):

LET area = APPEND(
  ( FOR doc_join IN warehouses
      FILTER doc_join._key == doc.selector.areaServed
         && doc.selector.areaScope == "…#Warehouse"
      RETURN { _key: doc_join._key, name: doc_join.name } ) ,
  ( FOR doc_join IN subsidiaries
      FILTER doc_join._key == doc.selector.areaServed
         && doc.selector.areaScope == "…#Company"
      RETURN { _key: doc_join._key, name: doc_join.name } )
)

This helper interprets a flexible sort definition and constructs the appropriate AQL 'SORT' expression. Unlike an edge relation, a join has a single document variable ($docRef), so both the explicit sort property and the default fallback target that same reference.

• If $definition is an array: looks for AQL::SORT (property) and AQL::ORDER (ASC/DESC) and sorts by that property on the join document.
• If $definition is a string (legacy): sorts by that string as the property on the join document in ASC order.
• If $definition is null (or AQL::SORT is not set in the array): sorts by the $defaultProperty (e.g. '_key') on the join document in DESC order.