*** title: FQL function reference updated: 2024-11-08T00:00:00.000Z slug: docs/postman-flows/flows-query-language/function-reference max-toc-depth: 2 ---------------- {/* vale off */} {/* This doc has many vale false positives related to heading capitalization and spelling, due to the code samples and maintaining correct case for commands in the headings. After fixing the valid errors, warnings, and suggestions, I turned off vale for this entire doc. */} All [Flows Query Language](/docs/postman-flows/flows-query-language/introduction-to-fql/) (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\) =\< 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=%D1%88%D0%B5%D0%BB%D0%BB%D1%8B)") -> "[https://mozilla.org/?x=шеллы](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	```json "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=шеллы)") -> "[https://mozilla.org/?x=%D1%88%D0%B5%D0%BB%D0%BB%D1%8B](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	```json $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	```json $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 $json({"a": 1, "b" : "hello"}) -> "{"a":1,"b":"hello"}" ```

### jsonParse Parses a JSON string into an object.

Syntax	$jsonParse($val:string) => object
Example	```json $jsonParse('{"one": 1, "two": [3, "four"]}') -> {"one": 1,"two": [ 3,"four"]} ```

### keys Returns an array of the keys in an object.

Syntax	```json $keys($obj: object) => array ```
Example	```json "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	```json $length("abc") -> 3 $length("") -> 0 ```

### lookup Returns the value of a key in an object.

Syntax	$lookup($obj: object, \$key: string) => any
Example	```json ($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	```json $match($str: string, $pattern: string \| regex) => array ```
Example	```json $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	```json $merge($arr: array
Example	```json $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	```json $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	```json $reduce([1,2,3,4], fn($prev, $cur) { $prev*$cur}) ) -> 24 ```

### split Splits a string into an array of strings using a pattern.

Syntax	```json $split($str: string, $pattern: string \| regex, $flags?: string) => array ```
Example	````json $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	```json $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	```json $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](mailto: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](mailto: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

| **Number** | **Day** | | ---------- | --------- | | 0 | Sunday | | 1 | Monday | | 2 | Tuesday | | 3 | Wednesday | | 4 | Thursday | | 5 | Friday | | 6 | Saturday | ### 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	```json $hasSameDate($timestamp1: string \|number, $timestamp2: string \|number, units?: Array) => boolean ```
Example	```json $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	```json $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