Type cast functions

As mentioned before, some of the operators expect their operands to have a certain data type. For example, the logical operators expect their operands to be boolean values, and the arithmetic operators expect their operands to be numeric values. If an operation is performed with operands of an unexpected type, the operation will fail with an error. To avoid such failures, value types can be converted explicitly in a query. This is called type casting.

In an AQL query, type casts are performed only upon request and not implicitly. This helps avoiding unexpected results. All type casts have to be performed by invoking a type cast function. AQL offers several type cast functions for this task. Each of the these functions takes an operand of any data type and returns a result value of type corresponding to the function name (e.g. TO_NUMBER() will return a number value):

• TO_BOOL(value): Takes an input value of any type and converts it into the appropriate boolean value as follows:
  • null is converted to false.
  • Numbers are converted to true if they are unequal to 0, and to false otherwise.
  • Strings are converted to true if they are non-empty, and to false otherwise.
  • Arrays are always converted to true.
  • Objects / documents are always converted to true.
• TO_NUMBER(value): Takes an input value of any type and converts it into a numeric value as follows:
  • null and false are converted to the value 0.
  • true is converted to 1.
  • Numbers keep their original value.
  • Strings are converted to their numeric equivalent if the string contains a valid representation of a number. Whitespace at the start and end of the string is allowed. String values that do not contain any valid representation of a number will be converted to null.
  • An empty array is converted to 0, an array with one member is converted into the result of TO_NUMBER() for its sole member. An array with two or more members is converted to null.
  • An object / document is converted to null.
• TO_STRING(value): Takes an input value of any type and converts it into a string value as follows:
  • null is converted to the string “null”
  • false is converted to the string “false”, true to the string “true”
  • Numbers are converted to their string representations.
  • An empty array is converted to the empty string. An array with one member is converted to the result of TO_STRING() for its sole member. An array with two or more members is converted to a comma-separated array with the string representation of its members.
  • An object / document is converted to the string [object Object].
• TO_ARRAY(value): Takes an input value of any type and converts it into an array value as follows:
  • null is converted to an empty array.
  • Boolean values, numbers and strings are converted to an array containing the original value as its single element.
  • Arrays keep their original value.
  • Objects / documents are converted to an array containing their attribute values as array elements
• TO_LIST(value): This is an alias for TO_ARRAY.

Type check functions

AQL also offers functions to check the data type of a value at runtime. The following type check functions are available. Each of these functions takes an argument of any data type and returns true if the value has the type that is checked for, and false otherwise.

The following type check functions are available:

• IS_NULL(value): Checks whether value is a null value

• IS_BOOL(value): Checks whether value is a boolean value

• IS_NUMBER(value): Checks whether value is a numeric value

• IS_STRING(value): Checks whether value is a string value

• IS_ARRAY(value): Checks whether value is an array value

• IS_LIST(value): This is an alias for IS_ARRAY

• IS_OBJECT(value): Checks whether value is an object / document value

• IS_DOCUMENT(value): This is an alias for IS_OBJECT

• IS_DATESTRING(value): Checks whether value is a string that can be used in a date function. This includes partial dates such as 2015 or 2015-10 and strings containing invalid dates such as 2015-02-31. The function will return false for all non-string values, even if some of them may be usable in date functions.