FQL function reference
All Flows Query Language (FQL) functions are documented below.
General functions
assert
Throws an error with the message if a condition is false.
| Syntax | $assert($cond: bool, $msg: string) => error |
| Example | $assert(user.age <18, "error: user cannot vote!") |
average
Returns the average value of a numeric array.
| Syntax | $average($array: array<num>) =< number |
| Example | $average([1,2,3,4,5]) -> 3 |
boolean
Casts an argument to its effective boolean value.
| Syntax | $boolean($arg: any) => bool |
| Example |
$boolean(0) -> false
$boolean(10) -> true
$boolean("") -> false
$boolean("abc") -> true
|
contains
Returns true if a string contains a pattern.
| Syntax | $contains($str: string, $pattern: string | regex) => bool |
| Example |
$contains("hello, world", "lo") -> true
$contains("hello world", "ab") -> false
|
decodeUrl
Decodes a string from a URL.
| Syntax | $decodeUrl($val: string) => string |
| Example | $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.
| Syntax | $decodeUrlComponent($val: string) => string |
| Example | $decodeUrlComponent("%3Fx%3Dtest") -> "?x=test" |
each
Applies a function to each key/value pair of an object.
| Syntax | $each($obj: object, func: ($val, $key) : any) |
| Example |
"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.
| Syntax | $encodeUrl($val: string) => string |
| Example | $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.
| Syntax | $encodeUrlComponent($val: string) => string |
| Example | $encodeUrlComponent("?x=test") -> "%3Fx%3Dtest" |
eval
Evaluates an expression.
| Syntax | $eval($val:string) => any |
| Example | $eval("[1,$string(2),3]") -> [1,"2",3] |
exists
Returns true if a value is not null or undefined.
| Syntax | $exists($val: any) => bool |
| Example |
$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.
| Syntax | $filter($arr: array, $func: ($e, $index?: number?, $ar: array )=> boolean) => array |
| Example | $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.
| Syntax |
$join($arr: array |
| Example |
$join(["hello", "world"]) -> "helloworld" $join(["hello", "world"], "-") → "hello-world" $join([1,2,3], "..") -> "1..2..3" |
json
Converts an object to a JSON string.
| Syntax | $json($val:any) => string |
| Example | $json({"a": 1, "b" : "hello"}) -> "{"a":1,"b":"hello"}" |
jsonParse
Parses a JSON string into an object.
| Syntax | $jsonParse($val:string) => object |
| Example | $jsonParse('{"one": 1, "two": [3, "four"]}') -> {"one": 1,"two": [ 3,"four"]} |
keys
Returns an array of the keys in an object.
| Syntax |
$keys($obj: object) => array |
| Example |
"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.
| Syntax | $length($str: string) => number |
| Example |
$length("abc") -> 3
$length("") -> 0
|
lookup
Returns the value of a key in an object.
| Syntax | $lookup($obj: object, $key: string) => any |
| Example | ($o := { "name" : "John", "email": "john@gmail.com"}; $lookup($o, "name")) -> "John" |
lowercase
Returns the lowercase version of a string.
| Syntax | $lowercase($str: string) => string |
| Example | $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.
| Syntax | $map($arr: array, $func: ($e, $index?: number?, $ar: array ) : array |
| Example | $map([1,2,3,4,5], fn($e){ $e *2}) -> [2,4,6,8,10] |
max
Returns the maximum value from a numeric array.
| Syntax | $max($array) => number |
| Example | $max([9,2,17,3]) -> 17 |
match
Returns an array of strings that match a pattern.
| Syntax |
$match($str: string, $pattern: string | regex) => array |
| Example | $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.
| Syntax | $merge($arr: array |
| Example | $merge([{"a":1},{"b":2}]) -> {"a": 1,"b": 2} |
not
Returns true if a value is false, or false otherwise.
| Syntax | $not($x: any) => bool |
| Example |
$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).
| Syntax | $pad($str: string, $length: number, $pad?: string) => string |
| Example |
$pad("example", 5) -> "example "
$pad("example", 5, "-") -> "example--"
|
partition
Partitions an array into an array of arrays of size $n.
| Syntax | $partition($array:any, $n: numbers) => array |
| Example |
$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.
| Syntax | $replace($str: string, $pattern: string | regex, $replacement: string) => string |
| Example |
$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.
| Syntax | $reduce(array, function [, init]) |
| Example | $reduce([1,2,3,4], fn($prev, $cur) { $prev*$cur}) ) -> 24 |
split
Splits a string into an array of strings using a pattern.
| Syntax |
$split($str: string, $pattern: string | regex, $flags?: string) => array |
| Example |
$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.
| Syntax | $spread($val: any) => array<object> |
| Example | $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.
| Syntax | $string($value: any, $prettify? true | false) => string |
| Example |
$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).
| Syntax | $substring($str: string, $start: number, $length?: number) => string |
| Example |
$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.
| Syntax | $substringAfter($str: string, $separator: string) => string |
| Example | $substringAfter("abc@gmail.com", "@") -> "gmail.com" |
substringBefore
Returns the substring of a string before the first occurrence of a separator.
| Syntax | $substringBefore($str: string, $separator: string) => string |
| Example | $substringBefore( "john@gmail.com", "@") -> "john" |
sum
Returns the sum of the values of a numeric array.
| Syntax | $sum($array) => number |
| Example | $sum([1,2,3,4]) -> 10 |
trim
Returns a copy of a string with leading and trailing whitespace removed.
| Syntax | $trim($str: string) => string |
| Example | $trim(" Hello \n World ") -> "Hello World" |
type
Returns the type of a value.
| Syntax | $type($val: any) => string |
| Example |
$type("hello") -> "string"
$type(1) -> "number"
$type({}) -> "object"
$type([]) -> "array"
$type(null) -> "null"
|
uppercase
Returns the uppercase version of a string
| Syntax | $uppercase($str: string) => string |
| Example | $uppercase("hello") -> "HELLO" |
uuid
Returns a unique ID (UUID version 4) as a string.
| Syntax | $uuid => string |
| Example | $uuid -> "503c5a9f-b8fb-402a-b0d7-fae17490bdf6" |
Array functions
append
Returns a new array with a value appended (added) to an array.
| Syntax | $append($arr: array, $val: any) => array |
| Example |
$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.
| Syntax | $count($array) => number |
| Example |
$count([1,2,3,4,5]) -> 5 $count([]) -> 0 |
distinct
Returns a new array with the distinct elements of $arr with duplicates eliminated.
| Syntax | $distinct($arr: array) => array |
| Example | $distinct(["a", "b", "b", "c"]) -> ["a", "b", "c"] |
reverse
Returns a new array with the elements of an array in reverse order.
| Syntax | $reverse($arr: array) => array |
| Example | $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.
| Syntax | $shuffle($arr: array) => array |
| Example | $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.
| Syntax | $sort($arr: array, $swapFn: ($l, $r)) => boolean |
| Example |
$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.
| Syntax | $zip($ar1:Array, $ar2:Array, $ar3;Array, ...) => Array |
| Example | $zip([1,2,3],[4,5,6]) -> [[1,4],[2,5],[3,6]] |
Numeric functions
abs
Returns the absolute value of a number.
| Syntax | $abs(n:number) : number |
| Example | $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.
| Syntax | $acos($num: number) => number |
| Example | $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.
| Syntax | $acosh($num: number) => number |
| Example | $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.
| Syntax | $asin($num: number) => number |
| Example | $asin(1) -> 1.5707963267948966 |
asinh
Returns the inverse hyperbolic sine of a number, in radians. The result is between -inf and inf.
| Syntax | $asinh($num: number) => number |
| Example | $asinh(1) -> 1.5707963267948966 |
atan
Returns the arc tangent of a number of radians. The result is between -pi/2 and pi/2.
| Syntax | $atan($num: number) => number |
| Example | $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.
| Syntax | $atanh($num: number) => number |
| Example | $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.
| Syntax | $atan2($x: number, $y: number) => number |
| Example | $atan2(-1, -1) -> -2.356194490192345 |
cbrt
Returns the cube root of a number.
| Syntax | $cbrt($num: number) => number |
| Example | $cbrt(27) -> 3 |
ceil
Returns the smallest integer greater than or equal to a number.
| Syntax | $ceil($num: number) => number |
| Example | $ceil(3.4) -> 4 |
constant
Returns the constant value with the given name. For example: e, ln 2, log2 e, log10 e, pi or π.
| Syntax | $constant($name: string ) => number |
| Example | $constant('e') -> 2.718281828459045 |
cos
Returns the cosine of a number of radians.
| Syntax | $cos($num: number) => number |
| Example | $cos(1) -> 0.5403023058681398 |
cosh
Returns the hyperbolic cosine of a number of radians.
| Syntax | $cosh($num: number) => number |
| Example | $cosh(1) -> 1.5430806348152437 |
exp
Returns e raised to the power of a number, where e = 2.718281… is the base of natural logarithms.
| Syntax | $exp($num: number) => number |
| Example | $exp(16) -> 8886110.520507872 |
floor
Returns the largest integer less than or equal to a number.
| Syntax | $floor($num: number) => number |
| Example | $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.
| Syntax | $formatBase($num: number, $base?: number) => string |
| Example | $formatBase(100, 2) -> "1100100" |
isFinite
Returns true if the value input is not infinity, and false otherwise.
| Syntax | $isFinite( $num: number ) => number |
| Example |
$isFinite(1) -> true $isFinite(inf) -> false |
log
Returns the natural logarithm of a number (base e).
| Syntax | $log($num: number) => number |
| Example | $log(16) -> 2.772588722239781 |
log10
Returns the base 10 logarithm of a number.
| Syntax | $log10($num: number) => number |
| Example | $log10(16) -> 1.2041199826559248 |
log2
Returns the base 2 logarithm of a number.
| Syntax | $log2($num: number) => number |
| Example | $log2(16) -> 4 |
number
Converts a value to a number.
| Syntax | $number($x: string | number | bool) => number |
| Example |
$number("-0.05") -> -0.05
$number(false) -> 0
$number(true) -> 1
|
power
Returns $num raised to the $exp power.
| Syntax | $power($num: number, $exp: number) => number |
| Example |
$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.
| Syntax | $round($num: number, $precision?: number) => number |
| Example |
$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.
| Syntax | $sin($num: number) => number |
| Example | $sin(1) -> 0.8414709848078965 |
sinh
Returns the hyperbolic sine of a number of radians.
| Syntax | $sinh($num: number) => number |
| Example | $sinh(1) -> 1.1752011936438014 |
sqrt
Returns the square root of a number.
| Syntax | $sqrt($num: number) => number |
| Example | $sqrt(16) -> 4 |
tan
Returns the tangent of a number of radians.
| Syntax | $tan($num: number) => number |
| Example | $tan(1) -> 1.5574077246549023 |
tanh
Returns the hyperbolic tangent of a number of radians.
| Syntax | $tanh($num: number) => number |
| Example | $tanh(1) -> 0.7615941559557649 |
Date and time functions
afterDate
Returns true if $timestamp1 is after $timestamp2, false otherwise.
| Syntax | $afterDate($timestamp1: string |number, $timestamp2: string |number) => boolean |
| Example | $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.
| Syntax | $beforeDate($timestamp1: string |number, $timestamp2: string |number) => boolean |
| Example |
$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.
| Syntax | $dateEquals($timestamp1: string |number, $timestamp2: string |number) => boolean |
| Example |
$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.
| Syntax | $datePlus($timestamp1: string |number, $duration: number, $units, ) => number |
| Example |
$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.
| Syntax | $day($timestamp: string |number) => number |
| Example | $day("2023-02-08") -> 8 |
dayOfTheWeek
Returns the day of the week as a number [1=Monday, ... 6=Saturday, 7= Sunday].
| Syntax | $dayOfTheWeek($timestamp: string |number) => number |
| Example |
$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"].
| Syntax | $diffDate($timestamp1: string |number, $timestamp2: string |number, $units : string, ) => number |
| Example |
$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.
| Syntax | $fromMillis($val:number, $picture?: string) => string |
| Example |
$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"].
| Syntax |
$hasSameDate($timestamp1: string |number, $timestamp2: string |number, units?: Array |
| Example |
$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.
| Syntax | $hours($timestamp: string |number) => number |
| Example | $hours("2023-02-08T07:56:14.747+00:00") -> 7 |
milliSeconds
Extracts the milliseconds from a timestamp and returns it as a number.
| Syntax | $milliSeconds($timestamp: string |number) => number |
| Example | $milliSeconds("2023-02-08T07:56:14.747+00:00") -> 747 |
minutes
Extracts the minutes component from a timestamp and returns it as a number.
| Syntax | $minutes($timestamp: string |number) => number |
| Example | $minutes("2023-02-08T07:56:14.747+00:00") -> 56 |
month
Extracts the month component from a timestamp.
| Syntax | $month($timestamp: string |number) => number |
| Example | $month("2023-02-08") -> 2 |
seconds
Extracts the local seconds component from a timestamp and returns it as a number.
| Syntax | $seconds($timestamp: string |number) => number |
| Example | $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.
| Syntax | $toMillis($val:string, $picture?: string) => number |
| Example |
$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.
| Syntax | $year($timestamp: string |number) => number |
| Example | $year("2023-02-08T07:56:14.747+00:00") -> 2023 |
Last modified: 2023/04/21
Additional resources
Videos
Blog posts
