Oihana PHP Arango

aqlFields.php

Table of Contents

Functions

aqlFields()  : string|null
Applies AQL filters to a set of fields and returns a string representation suitable for inclusion in an AQL query.

Functions

aqlFields()

Applies AQL filters to a set of fields and returns a string representation suitable for inclusion in an AQL query.

aqlFields(array<string|int, mixed>|null $fields[, string $docRef = AQL::DOC ][, ContainerInterface|null $container = null ][, array<string|int, mixed> $init = [] ][, string|null $edgeRef = null ]) : string|null

This method iterates over the provided fields and applies the corresponding filter function based on the Field::FILTER option for each field. The generated expressions are then concatenated into a single string, separated by ', '.

Supported filters include:

  • Scalar fields: BOOL, INT, DATETIME, DEFAULT
  • Special fields: TRANSLATE, DISTANCE, REVISION
  • Document relations: EDGE, EDGE_SINGLE, EDGE_COUNT, JOIN, JOIN_ARRAY, JOIN_MULTIPLE, UNIQUE_NAME

Each field can also define additional options:

  • Field::NAME : The target field name in the document (optional)
  • Field::UNIQUE : Unique variable name to use for the AQL expression (optional)
  • Field::QUOTED : Double-quote the output label (for keys that are not bare identifiers, e.g. "my-key": …). The attribute access is then reached with backticks (doc.my-key``), the valid AQL form — never doc."my-key". A Field::NAME still overrides the source attribute (only the label is quoted).
  • Field::REQUIRES : Optional permission subject(s) — when present and the request-scoped authorizer denies them, the field is dropped from the projection (read-side gating).
  • Field::ALTERS : Optional alt transformation chain wrapping the projected value (e.g. ["trim","lower"] => name: LOWER(TRIM(doc.name))). Applied only to the default scalar projection (key: doc.key); ignored on typed/structural filters (BOOL, DATETIME, EDGE, JOIN, …).
  • Field::SCOPE : Optional projection source — Scope::VERTEX (default) reads the field from $docRef, Scope::EDGE reads it from $edgeRef (the traversal edge). The edge scope is only valid inside an edge sub-query (where $edgeRef is provided) and only on filters that project from a reference; it throws otherwise. Scope::EDGE equals AQL::EDGE, so both forms are interchangeable.
Parameters
$fields : array<string|int, mixed>|null

Array of fields definitions to filter. The array keys are the field identifiers, and the values are arrays of options (filter, name, unique, quoted, requires). If null or empty, the method returns null.

$docRef : string = AQL::DOC

The document reference to use in AQL expressions. Defaults to AQL::DOC.

$container : ContainerInterface|null = null

The optional DI Container reference.

$init : array<string|int, mixed> = []

Optional associative array definition.

$edgeRef : string|null = null

The traversal edge reference, used to project fields flagged with Field::SCOPE => Scope::EDGE. Only set inside an edge sub-query; null everywhere else.

Tags
throws
ContainerExceptionInterface
Exception
NotFoundExceptionInterface
UnsupportedOperationException
ValidationException

When a (non-quoted) source attribute name is unsafe.

example 
use oihana\arango\enums\Field;
use oihana\arango\enums\Filter;
use function oihana\arango\db\helpers\aqlFields;

// Default scalar projection (no options) — `key: doc.key`
aqlFields([ 'name' => [] ]);
// name:doc.name

// Several fields, with typed conversions, joined by ', '
aqlFields([
    'name'   => [] ,
    'price'  => [ Field::FILTER => Filter::NUMBER ] ,
    'active' => [ Field::FILTER => Filter::BOOL ] ,
]);
// name:doc.name, price:TO_NUMBER(doc.price), active:TO_BOOL(doc.active)

// Array projection
aqlFields([ 'tags' => [ Field::FILTER => Filter::ARRAY ] ]);
// tags:IS_ARRAY(doc.tags) ? doc.tags : []

// Custom document reference (e.g. inside an edge/join sub-query)
aqlFields([ 'tags' => [ Field::FILTER => Filter::ARRAY ] ], 'edge');
// tags:IS_ARRAY(edge.tags) ? edge.tags : []

// Edge-scoped projection inside an edge sub-query (Field::SCOPE): the field
// is read from the edge variable instead of the target vertex. Combine with
// Field::NAME to avoid a label collision with a vertex field.
aqlFields(
    [
        'name'  => [] ,
        'since' => [ Field::FILTER => Filter::DATETIME , Field::NAME => 'created' , Field::SCOPE => Scope::EDGE ] ,
    ] ,
    'v_42' , null , [] , 'e_42'
);
// name:v_42.name, since:DATE_ISO8601(e_42.created)

// Wrap the reference under a named key (Filter::WRAP): the symmetric
// companion of Field::SCOPE. Inside an edge traversal it nests the vertex
// under a key (e.g. `subject`) beside the edge metadata, instead of
// flattening the vertex fields at the root. A field whitelist is required
// unless Field::RAW => true is set (then the whole reference is embedded).
aqlFields(
    [
        'role'    => [ Field::SCOPE => Scope::EDGE ] ,
        'subject' => [ Field::FILTER => Filter::WRAP , Field::FIELDS => [ 'id' => [] , 'givenName' => [] ] ] ,
    ] ,
    'v_42' , null , [] , 'e_42'
);
// role:e_42.role, subject:{id:v_42.id, givenName:v_42.givenName}

// Alias: output key differs from the source attribute (Field::NAME)
aqlFields([ 'slug' => [ Field::NAME => 'title' ] ]);
// slug:doc.title

// Output-side transformation chain (Field::ALTERS), applied to the value
aqlFields([ 'name' => [ Field::ALTERS => [ 'trim' , 'lower' ] ] ]);
// name:LOWER(TRIM(doc.name))

// Quoted label for a non-identifier key (Field::QUOTED): the label is
// double-quoted, the attribute access uses backticks (valid AQL)
aqlFields([ 'my-key' => [ Field::QUOTED => true ] ]);
// "my-key":doc.`my-key`

// Quoted label + alias: only the label is quoted, the source is the alias
aqlFields([ 'slug' => [ Field::NAME => 'title' , Field::QUOTED => true ] ]);
// "slug":doc.title
since
1.0.0
author

Marc Alcaraz

Return values
string|null —

A string containing the filtered fields as AQL expressions, suitable for use in a RETURN or LET statement. Returns null if the input $fields is null or empty.

On this page

Search results