aqlFieldNumber.php
Table of Contents
Functions
- aqlFieldNumber() : string
- Generates an AQL key/value expression for a numeric field.
Functions
aqlFieldNumber()
Generates an AQL key/value expression for a numeric field.
aqlFieldNumber(string $key[, string $doc = AQL::DOC ][, string|null $keyName = null ][, array<string|int, mixed> $options = [] ]) : string
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:
$keybecomes the key in the resulting AQL object.$docis the document alias or variable.$keyNameoptionally 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)
Abstaining (Field::NULLABLE):
TO_NUMBER() converts even when there is nothing to convert: a document that says nothing
about the attribute comes back with 0, indistinguishable from one that really stores 0
— « it is free » and « we have no price » collapse into one value. An opt-in
Field::NULLABLE guards the cast behind the presence of the attribute, and Field::ELSE
picks what is said instead (default null):
aqlFieldNumber( 'price' , 'doc' , null , [ Field::NULLABLE => true ] ) ;
// price:doc.price != null ? TO_NUMBER(doc.price) : null
The test is != null, not IS_NUMBER(): TO_NUMBER() exists precisely to accept what
is not a number — a document storing "42" counts as 42 today — so a type test would
make all of them abstain. The question asked is only « is the attribute there? ». Without
the marker the emitted AQL is unchanged, byte for byte.
Parameters
- $key : string
-
The logical key to use in the AQL return object.
- $doc : string = AQL::DOC
-
The document variable or alias (default:
doc/AQL::DOC). - $keyName : string|null = null
-
Optional property name in the document if different from
$key. - $options : array<string|int, mixed> = []
-
The field definition, read for the optional guard (
Field::NULLABLE,Field::ELSE).
Tags
Return values
string —AQL key/value snippet for numeric conversion (e.g. "age: TO_NUMBER(doc.age)").