FQL function reference

All Flows Query Language (FQL) functions are documented below.

Logical Operators

and

Returns true if all provided conditions are true. In the example below, value1 has a value of 20.

Syntax condition1 and condition2
Example 
value1 > 18 and value1 < 100 -> true
value1 > 18 and value1 > 100 -> false

or

Returns true if at least one of the provided conditions is true. In the example below, value1 has a value of 20.

Syntax condition1 or condition2
Example 
value1 < 18 or value1 < 100 -> true
value1 < 18 or value1 > 100 -> false

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 can't 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 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 isn't 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, $separator?: string) => string
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) => object
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 isn't 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 isn't 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.

Syntax $dayOfTheWeek($timestamp: string |number) => number
Example 
$dayOftheWeek("2023-02-08") -> 3
$dayOftheWeek("2023-02-07") -> 2
NumberDay
0Sunday
1Monday
2Tuesday
3Wednesday
4Thursday
5Friday
6Saturday

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) => boolean
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: 2024/11/08

Additional resources

Videos

Flows Query Language (FQL) | Postman Flows

Blog posts

Advanced FQL expressions in Postman Flows
Postmanaut dancing. Illustration.