DQL function reference
DQL function reference
All DronaHQ Query Language (DQL) functions are documented below.
Contents
General functions
assert
Throws an error with the message if a condition is false.
DQL
$assert($cond: bool, $msg: string) => error
Result
$assert(user.age < 18,"error: user cannot vote!")
average
Returns the average value of a numeric array.
DQL
$average($array: array(num)) => number
Result
$average([1,2,3,4,5]) -> 3
boolean
Casts an argument to its effective boolean value.
DQL
$boolean($arg: any) => bool
Result
$boolean(0) -> false
$boolean(10) -> true
$boolean("") -> false
$boolean("abc") -> true
contains
Returns true if a string contains a pattern.
DQL
$contains($str: string, $pattern: string | regex) => bool
Result
$contains("hello, world", "lo") -> true
$contains("hello world", "ab") -> false
decodeUrl
Decodes a string from a URL.
DQL
$decodeUrl($val: string) => string
Result
$decodeUrl("https://mozilla.org/?x=%D1%88%D0%B5%D0%BB%D0%BB%D1%8B") -> "https://mozilla.org/?x=шеллы"
decodeUrlComponent
Decodes a string from a component previously created with encodeUrlComponent.
DQL
$decodeUrlComponent($val: string) => string
Result
$decodeUrlComponent("%3Fx%3Dtest") -> "?x=test"
each
Applies a function to each key/value pair of an object.
DQL
$each($obj: object, func: ($val, $key) : any)
Result
"Address": {
"Street": "Hursley Park",
"City": "Winchester",
"Postcode": "SO21 2JN"
}
$each(Address, fn($v, $k) {$k & ": " & $v}) ->
[
"Street: Hursley Park",
"City: Winchester",
"Postcode: SO21 2JN"
]
encodeUrl
Encodes a value into a URL.
DQL
$encodeUrl($val: string) => string
Result
$encodeUrl("https://mozilla.org/?x=шеллы") -> "https://mozilla.org/?x=%D1%88%D0%B5%D0%BB%D0%BB%D1%8B"
encodeUrlComponent
Encodes a value into a component for a URL.
DQL
$encodeUrlComponent($val: string) => string
Result
$encodeUrlComponent("?x=test") -> "%3Fx%3Dtest"
eval
Evaluates an expression.
DQL
$eval($val:string) => any
Result
$eval("[1,$string(2),3]") -> [1,"2",3]
exists
Returns true if a value is not null or undefined.
DQL
$exists($val: any) => bool
Result
$exists("hello") -> true
$exists([1,2,3]) -> true
$exists("a" : 1, "b": 2) -> true
$exists(null) -> false
$exists(blah) -> false
filter
Returns an array of elements which satisfy the predicate defined in a function.
DQL
$filter($arr: array, $func: ($e, $index?: number?, $ar: array )=> boolean) => array
Result
$filter([1,2,3,4,5], fn($e){ '$e>3'}) -> [4, 5]
join
Joins the elements of an array into a string using the optional separator string.
DQL
$join($arr: array, $separator?: string) => string
Result
$join(["hello", "world"]) -> "helloworld"
$join(["hello", "world"], "-") → "hello-world"
$join([1,2,3], "..") -> "1..2..3"
json
Converts an object to a JSON string.
DQL
$json($val:any) => string
Result
>$json({"a": 1, "b" : "hello"}) -> {"a":1,"b":"hello"}
jsonParse
Parses a JSON string into an object.
DQL
$jsonParse($val:string) => object
Result
$jsonParse('{"one": 1, "two": [3, "four"]}') -> {"one": 1,"two": [ 3,"four"]}
keys
Returns an array of the keys in an object.
DQL
$keys($obj: object) => array
Result
"Product": [
{
"Product Name": "Bowler Hat",
"ProductID": 858383,
"SKU": "0406654608",
"Description": {
"Colour": "Purple",
"Width": 300,
"Height": 200,
"Depth": 210,
"Weight": 0.75
},
"Price": 34.45,
"Quantity": 2
}
]
$keys(Product) -> ["Product Name", "ProductID", "SKU", "Description", "Price", "Quantity"]
length
Returns the length of a string.
DQL
$length($str: string) => number
Result
$length("abc") -> 3
$length("") -> 0
lookup
Returns the value of a key in an object.
DQL
$lookup($obj: object, $key: string) => any
Result
($o := { "name" : "John", "email": "john@gmail.com"}; $lookup($o, "name")) -> "John"
lowercase
Returns the lowercase version of a string.
DQL
$lowercase($str: string) => string
Result
$lowercase("Hello World") -> "hello world"
map
Maps each element of an array using a function and returns a new array with all the mapped elements.
DQL
$map($arr: array, $func: ($e, $index?: number?, $ar: array )) : array
Result
$map([1,2,3,4,5], fn($e){ $e *2}) -> [2,4,6,8,10]
max
Returns the maximum value from a numeric array.
DQL
$max($array) => number
Result
$max([9,2,17,3]) -> 17
match
Returns an array of strings that match a pattern.
DQL
$match($str: string, $pattern: string | regex) => array
Result
$match("ababbabbbcc",/a(b+)/) -> ["ab", "abb", "abbb"]
merge
Returns a new object with the properties of each object in an array of objects merged into it.
DQL
$merge($arr: array) => object
Result
$merge([{"a":1},{"b":2}]) -> {"a": 1,"b": 2}
not
Returns true if a value is false, or false otherwise
DQL
$not($x: any) => bool
Result
$not(true) -> false
$not(false) -> true
$not(null) -> true
$not(0) -> true
$not(100) -> false
$not("") -> true
$not("hello") -> false
pad
Returns a copy of a string padded to a length with $pad (if provided).
DQL
$pad($str: string, $length: number, $pad?: string) => string
Result
$pad("example", 5) -> "example "
$pad("example", 5, "-") -> "example--"
partition
Partitions an array into an array of arrays of size $n.
DQL
$partition($array:any, $n: numbers) => array
Result
$partition([1,2,3,4,5,6,7,8,9,10], 2) -> [[1,2], [3,4], [5,6], [7,8], [9,10]]
$partition([1,2,3,4,5,6,7,8,9,10], 3) -> [[1,2,3], [4,5,6], [7,8,9], [10]]
replace
Returns a string with all occurrences of a pattern replaced by a replacement string.
DQL
$replace($str: string, $pattern: string | regex, $replacement: string) => string
Result
$replace("Hello World", "World", "Everyone") -> "Hello Everyone"
$replace("the cat sat on the mat", "at", "it") -> "the cit sit on the mit"
reduce
Reduces an array to some value using a function.
DQL
$reduce(array, function [, init])
Result
$reduce([1,2,3,4], fn($prev, $cur) { $prev*$cur}) -> 24
split
Splits a string into an array of strings using a pattern.
DQL
$split($str: string, $pattern: string | regex, $flags?: string) => array
Result
$split("so many words", " ") -> [ "so", "many", "words" ]
$split("so many words", " ", 2) -> [ "so", "many" ]
$split("too much, punctuation. hard; to read", /[ ,.;]+/) -> ["too", "much", "punctuation", "hard", "to", "read"]
spread
Returns an array of objects with a single key/value pair, where the key is the name of the property and the value is the value of the property.
DQL
$spread($val: any) => array(object)
Result
$spread({ "a": 1, "b": 2}) -> [ { "a" : 1}, {"b": 2}]
string
Returns the string representation of the input value; if $prettify is true, the output string is formatted for readability.
DQL
$string($value: any, $prettify? true | false) => string
Result
$string({"a": 1, "b": 2}) -> {"a":1, "b" : 2}
$string(5) -> "5"
$string([1,2,3]) -> ["1", "2", "3"]
substring
Returns a substring of a string starting at $start and with length $length (if provided).
DQL
$substring($str: string, $start: number, $length?: number) => string
Result
$substring("hello world", 0, 5) -> "hello"
$substring("hello world", -5, 5) -> "world"
substringAfter
Returns the substring of a string after the first occurrence of a separator.
DQL
$substringAfter($str: string, $separator: string) => string
Result
$substringAfter("abc@gmail.com", "@") -> "gmail.com"
substringBefore
Returns the substring of a string before the first occurrence of a separator.
DQL
$substringBefore($str: string, $separator: string) => string
Result
$substringBefore( "john@gmail.com", "@") -> "john"
sum
Returns the sum of the values of a numeric array.
DQL
$sum($array) => number
Result
$sum([1,2,3,4]) -> 10
trim
Returns a copy of a string with leading and trailing whitespace removed.
DQL
$trim($str: string) => string
Result
$trim(" Hello \n World ") -> "Hello World"
type
Returns the type of a value.
DQL
$type($val: any) => string
Result
$type("hello") -> "string"
$type(1) -> "number"
$type({}) -> "object"
$type([]) -> "array"
$type(null) -> "null"
uppercase
Returns the uppercase version of a string
DQL
$uppercase($str: string) => string
Result
$uppercase("hello") -> "HELLO"
uuid
Returns a unique ID (UUID version 4) as a string.
DQL
$uuid => string
Result
$uuid -> "503c5a9f-b8fb-402a-b0d7-fae17490bdf6"
Array functions
append
Returns a new array with a value appended (added) to an array.
DQL
$append($arr: array, $val: any) => array
Result
$append([1,2,3], [5,6]) -> [1,2,3,4,5,6]
$append([1,2,3], 5) -> [1,2,3,5]
count
Returns the number of elements in an array.
DQL
$count($array) => number
Result
$count([1,2,3,4,5]) -> 5
$count([]) -> 0
distinct
Returns a new array with the distinct elements of $arr with duplicates eliminated.
DQL
$distinct($arr: array) => array
Result
$distinct(["a", "b", "b", "c"]) -> ["a", "b", "c"]
reverse
Returns a new array with the elements of an array in reverse order.
DQL
$reverse($arr: array) => array
Result
$reverse([1,2,3,4,5]) -> [5,4,3,2,1]
shuffle
Returns a new array with the elements of an array in random order.
DQL
$shuffle($arr: array) => array
Result
$shuffle([1,2,3,4]) -> [3,1,4,2]
sort
A higher-order function that sorts the elements of an array using the $swapFn function. The comparator function takes two arguments. If it returns true, the elements will be swapped.
DQL
$sort($arr: array, $swapFn: ($l, $r)) => boolean
Result
$sort([13,2,8,6,15], fn($l, $r) { '$l > $r' }) -> [2,6,8,13,15]
$sort([13,2,8,6,15], fn($l, $r) { '$l < $r' }) -> [15,13,8,6,2]
zip
Takes two or more arrays and convolves (zips) each value from a set of arrays.
DQL
$zip($ar1:Array, $ar2:Array, $ar3;Array, ...) => Array
Result
$zip([1,2,3],[4,5,6]) -> [[1,4],[2,5],[3,6]]
Numeric functions
abs
Returns the absolute value of a number.
DQL
$abs(n:number) : number
Result
$abs(-1) -> 1
acos
Returns the arc cosine of a number of radians. The result is between 0 and pi. The number must be between -1 and 1.
DQL
$acos($num: number) => number
Result
$acos(1) -> 0
acosh
Returns the inverse hyperbolic cosine of a number, in radians. The number must be number between 1 and inf. The result is between 0 and inf.
DQL
$acosh($num: number) => number
Result
$acosh(1) -> 0
asin
Returns the arc sine of a number of radians. The result is between -pi/2 and pi/2. The number must be between -1 and 1.
DQL
$asin($num: number) => number
Result
$asin(1) -> 1.5707963267948966
asinh
Returns the inverse hyperbolic sine of a number, in radians. The result is between -inf and inf.
DQL
$asinh($num: number) => number
Result
$asinh(1) -> 1.5707963267948966
atan
Returns the arc tangent of a number of radians. The result is between -pi/2 and pi/2.
DQL
$atan($num: number) => number
Result
$atan(1) -> 0.7853981633974483
atanh
Returns the inverse hyperbolic tangent of a number, in radians. The number must be between -1 and 1. The result is between -inf and inf.
DQL
$atanh($num: number) => number
Result
$atanh(1) -> inf
atan2
Returns atan(y / x), in radians. The result is between -pi and pi. The vector in the plane from the origin to point (x, y) makes this angle with the positive X axis. The signs of both inputs are known to it, so it can compute the correct quadrant for the angle. For example, atan(1) and atan2(1, 1) are both pi/4, but atan2(-1, -1) is -3*pi/4.
DQL
$atan2($x: number, $y: number) => number
Result
$atan2(-1, -1) -> -2.356194490192345
cbrt
Returns the cube root of a number.
DQL
$cbrt($num: number) => number
Result
$cbrt(27) -> 3
ceil
Returns the smallest integer greater than or equal to a number.
DQL
$ceil($num: number) => number
Result
$ceil(3.4) -> 4
constant
Returns the constant value with the given name. For example: e, ln 2, log2 e, log10 e, pi or π.
DQL
$constant($name: string ) => number
Result
$constant('e') -> 2.718281828459045
cos
Returns the cosine of a number of radians.
DQL
$cos($num: number) => number
Result
$cos(1) -> 0.5403023058681398
cosh
Returns the hyperbolic cosine of a number of radians.
DQL
$cosh($num: number) => number
Result
$cosh(1) -> 1.5430806348152437
exp
Returns e raised to the power of a number, where e = 2.718281… is the base of natural logarithms.
DQL
$exp($num: number) => number
Result
$exp(16) -> 8886110.520507872
floor
Returns the largest integer less than or equal to a number.
DQL
$floor($num: number) => number
Result
$floor(3.4) -> 3
formatBase
Converts a number to a string in the optional base number system, if a base is not supplied, base 10 is used to create the string.
DQL
$formatBase($num: number, $base?: number) => string
Result
$formatBase(100, 2) -> "1100100"
isFinite
Returns true if the value input is not infinity, and false otherwise.
DQL
$isFinite( $num: number ) => number
Result
$isFinite(1) -> true
$isFinite(inf) -> false
log
Returns the natural logarithm of a number (base e).
DQL
$log($num: number) => number
Result
$log(16) -> 2.772588722239781
log10
Returns the base 10 logarithm of a number.
DQL
$log10($num: number) => number
Result
$log10(16) -> 1.2041199826559248
log2
Returns the base 2 logarithm of a number.
DQL
$log2($num: number) => number
Result
$log2(16) -> 4
number
Converts a value to a number.
DQL
$number($x: string | number | bool) => number
Result
$number("-0.05") -> -0.05
$number(false) -> 0
$number(true) -> 1
power
Returns $num raised to the $exp power.
DQL
$power($num: number, $exp: number) => number
Result
$power(2, 3) -> 8
$power(3,4) -> 81
round
Rounds a number to the optional precision number of decimal places. If precision is negative, then its value specifies which column to round to on the left side of the decimal place.
DQL
$round($num: number, $precision?: number) => number
Result
$round(123.456) -> 123
$round(123.456, 2) -> 123.46
$round(123.456, -1) -> 120
$round(123.456, -2) -> 100
$round(125, -1) -> 120
$round(125.456,-1) -> 130
sin
Returns the sine of a number of radians.
DQL
$sin($num: number) => number
Result
$sin(1) -> 0.8414709848078965
sinh
Returns the hyperbolic sine of a number of radians.
DQL
$sinh($num: number) => number
Result
$sinh(1) -> 1.1752011936438014
sqrt
Returns the square root of a number.
DQL
$sqrt($num: number) => number
Result
$sqrt(16) -> 4
tan
Returns the tangent of a number of radians.
DQL
$tan($num: number) => number
Result
$tan(1) -> 1.5574077246549023
tanh
Returns the hyperbolic tangent of a number of radians.
DQL
$tanh($num: number) => number
Result
$tanh(1) -> 0.7615941559557649
Date and time functions
afterDate
Returns true if $timestamp1 is after $timestamp2, false otherwise.
DQL
$afterDate($timestamp1: string |number, $timestamp2: string |number) => boolean
Result
$afterDate("2023-02-09", "2023-02-08") -> true $afterDate("2023-02-08", "2023-02-08") -> false
beforeDate
Returns true if $timestamp1 is before $timestamp2, false otherwise.
DQL
$beforeDate($timestamp1: string |number, $timestamp2: string |number) => boolean
Result
$beforeDate("2023-02-07", "2023-02-08") -> true
$beforeDate("2023-02-08", "2023-02-08") -> false
dateEquals
Returns true if the two timestamps are the same, false otherwise.
DQL
$dateEquals($timestamp1: string |number, $timestamp2: string |number) => boolean
Result
$dateEquals("2023-02-08", "2023-02-08") -> true
$dateEquals("2023-02-08", "2023-02-07") -> false
datePlus
Adds a duration of type $units which can be one of ["years", "months", "days", "hours", "minutes", "seconds", "milliseconds"], to a $timestamp and returns the new timestamp. If $duration is less than zero, then it will be subtracted from the $timestamp.
DQL
$datePlus($timestamp1: string |number, $duration: number, $units, ) => number
Result
$datePlus("2023-02-07", 2, "days") -> 1675900800000
$datePlus("2023-02-07", 2, "months") -> 1680825600000
day
Extracts the day from a timestamp and returns it as a number.
DQL
$day($timestamp: string |number) => number
Result
$day("2023-02-08") -> 8
dayOfTheWeek
Returns the day of the week as a number [1=Monday, ... 6=Saturday, 7= Sunday].
DQL
$dayOfTheWeek($timestamp: string |number) => number
Result
$dayOftheWeek("2023-02-08") -> 3
$dayOftheWeek("2023-02-07") -> 2
diffDate
Returns the difference between two timestamps in the units specified which can be one of ["years", "months", "days", "hours", "minutes", "seconds", "milliseconds"].
DQL
$diffDate($timestamp1: string |number, $timestamp2: string |number, $units : string, ) => number
Result
$diffDate("2023-02-08", "2023-01-22", "days") -> 17
$diffDate("2023-02-08", "2023-01-22","hours") -> 408
fromMillis
Converts a number of milliseconds since the epoch to a string. $picture is optional, if not provided it will default to ISO format. Picture specs are as per Unicode date format standards.
DQL
$fromMillis($val:number, $picture?: string) => string
Result
$fromMillis(1521801216617, "dd/M/yyyy") -> "23/3/2018"
$fromMillis(1522616700000, "E EEEE") -> "7 Sunday"
hasSameDate
Returns true if the components specified in $units of the two timestamps are the same, false otherwise. $units is an array with one or more strings from ["years", "months", "days", "hours", "minutes", "seconds", "milliseconds"].
DQL
$hasSameDate($timestamp1: string |number, $timestamp2: string |number, units?: Array) => boolean
Result
$hasSameDate("23-02-08", "2019-02-08", ["month", "day"]) -> true
$hasSameDate("2023-02-01", "2023-02-08", ["month", "year"]) -> true
$hasSameDate("23-02-01", "2023-02-08", ["month", "year"]) -> true
$hasSameDate("2023-02-01T07:15:54.730Z", "2023-02-01T14:00:22.340Z", ["year","month", "day"]) -> true
hours
Extracts the local hour component from a timestamp and returns it as a number.
DQL
$hours($timestamp: string |number) => number
Result
$hours("2023-02-08T07:56:14.747+00:00") -> 7
milliSeconds
Extracts the milliseconds from a timestamp and returns it as a number.
DQL
>$milliSeconds($timestamp: string |number) => number
Result
$milliSeconds("2023-02-08T07:56:14.747+00:00") -> 747
minutes
Extracts the minutes component from a timestamp and returns it as a number.
DQL
$minutes($timestamp: string |number) => number
Result
$minutes("2023-02-08T07:56:14.747+00:00") -> 56
month
Extracts the month component from a timestamp.
DQL
$month($timestamp: string |number) => number
Result
$month("2023-02-08") -> 2
seconds
Extracts the local seconds component from a timestamp and returns it as a number.
DQL
$seconds($timestamp: string |number) => number
Result
$seconds("2023-02-08T07:56:14.747+00:00") -> 14
toMillis
Converts a string to a number of milliseconds since the epoch. $picture is optional, if not provided it will default to ISO format. Picture specs are as per Unicode date format standards.
DQL
$toMillis($val:string, $picture?: string) => number
Result
$toMillis("1970-01-01T00:00:00.001Z") -> 1
$toMillis("2018-03-27", "yyyy-MM-dd") -> 1522108800000
$toMillis("21 August 2017", "dd MMMM yyyy") -> 1503273600000
year
Extracts the year component from a timestamp and returns it as a number.
DQL
$year($timestamp: string |number) => number
Result
$year("2023-02-08T07:56:14.747+00:00") -> 2023