Function reference
jlens implements every built-in function of JSONata 2.2. Each function has a signature
that describes its parameters and result, for example <s-nn?:s>:
| Symbol | Meaning |
|---|---|
s n b l o | string, number, boolean, null, object |
a | array; a single value is wrapped in an array |
a<n> | array of numbers (any type can be given in angle brackets) |
f | function |
j | any JSON value; x any value |
(sf) | either of the types |
? | optional parameter |
+ | one or more |
- | when the argument is missing, the context value is used |
:s | the result type |
Arguments that do not match the signature raise T0410 (wrong type), T0411 (the context
value has the wrong type) or T0412 (an array item has the wrong type).
String functions
Details and examples: String functions.
| Function | Signature | Description |
|---|---|---|
$string($arg, $prettify) | <x-b?:s> | Casts a value to a string; objects and arrays become JSON |
$substring($str, $start, $length) | <s-nn?:s> | Characters from a start position, optionally limited to a length |
$substringBefore($str, $chars) | <s-s:s> | The part of a string before the first occurrence of a substring |
$substringAfter($str, $chars) | <s-s:s> | The part of a string after the first occurrence of a substring |
$lowercase($str) | <s-:s> | Converts a string to lower case |
$uppercase($str) | <s-:s> | Converts a string to upper case |
$length($str) | <s-:n> | Number of characters in a string |
$trim($str) | <s-:s> | Normalizes and trims whitespace |
$pad($str, $width, $char) | <s-ns?:s> | Pads a string to a width; positive pads on the right, negative on the left |
$match($str, $regex, $limit) | <s-f<s:o>n?:a<o>> | Matches a regular expression, returning the matches with their positions and groups |
$contains($str, $token) | <s-(sf):b> | Whether a string contains a substring or matches a regular expression |
$replace($str, $pattern, $replacement, $limit) | <s-(sf)(sf)n?:s> | Replaces occurrences of a substring or regular expression |
$split($str, $separator, $limit) | <s-(sf)n?:a<s>> | Splits a string by a separator or regular expression |
$join($strs, $separator) | <a<s>s?:s> | Joins an array of strings with an optional separator |
Numeric functions
Details and examples: Numeric functions.
| Function | Signature | Description |
|---|---|---|
$formatNumber($value, $picture, $options) | <n-so?:s> | Formats a number with an XPath picture string |
$formatBase($value, $radix) | <n-n?:s> | Formats a number in another base (2 to 36) |
$formatInteger($value, $picture) | <n-s:s> | Formats an integer with an XPath picture string (words, roman, letters, digits) |
$parseInteger($value, $picture) | <s-s:n> | Parses an integer written according to an XPath picture string |
$number($arg) | <(nsb)-:n> | Casts a value to a number |
$floor($arg) | <n-:n> | Rounds down |
$ceil($arg) | <n-:n> | Rounds up |
$round($arg, $precision) | <n-n?:n> | Rounds half to even, optionally to a number of decimal places |
$abs($arg) | <n-:n> | Absolute value |
$sqrt($arg) | <n-:n> | Square root |
$power($arg, $exp) | <n-n:n> | Raises a number to a power |
$random() | <:n> | A pseudo-random number between 0 (inclusive) and 1 (exclusive) |
Aggregation functions
Details and examples: Aggregation functions.
| Function | Signature | Description |
|---|---|---|
$sum($array) | <a<n>:n> | Sum of an array of numbers |
$count($array) | <a:n> | Number of items in an array |
$max($array) | <a<n>:n> | Largest number in an array |
$min($array) | <a<n>:n> | Smallest number in an array |
$average($array) | <a<n>:n> | Mean of an array of numbers |
Boolean functions
Details and examples: Boolean functions.
| Function | Signature | Description |
|---|---|---|
$boolean($arg) | <x-:b> | The effective boolean value of a value |
$not($arg) | <x-:b> | Logical negation of the effective boolean value |
$exists($arg) | <x:b> | Whether a value is defined |
Array functions
Details and examples: Array functions.
| Function | Signature | Description |
|---|---|---|
$zip() | <a+> | Combines arrays item by item into an array of arrays |
$append($arg1, $arg2) | <xx:a> | Concatenates two values into an array |
$reverse($arr) | <a:a> | Reverses an array |
$sort($arr, $comparator) | <af?:a> | Sorts an array, optionally with a comparator function |
$shuffle($arr) | <a:a> | Shuffles an array into a random order |
$distinct($arr) | <x:x> | Removes duplicate values from an array |
Object functions
Details and examples: Object functions.
| Function | Signature | Description |
|---|---|---|
$keys($arg) | <x-:a<s>> | The keys of an object, or the union of keys of an array of objects |
$lookup($input, $key) | <x-s:x> | The value of a key in an object, or in each object of an array |
$spread($arg) | <x-:a<o>> | Splits an object into an array of single-key objects |
$merge($arg) | <a<o>:o> | Merges an array of objects into one; later keys win |
$each($obj, $func) | <o-f:a> | Applies a function to each key/value pair of an object |
Higher-order functions
Details and examples: Higher-order functions.
| Function | Signature | Description |
|---|---|---|
$map($arr, $func) | <af> | Applies a function to each item of an array |
$filter($arr, $func) | <af> | The items of an array for which a predicate holds |
$single($arr, $func) | <af?> | The only item of an array matching a predicate; an error otherwise |
$reduce($sequence, $func, $init) | <afj?:j> | Folds an array into a single value with a function |
$sift($arg, $func) | <o-f?:o> | The key/value pairs of an object for which a predicate holds |
Date and time functions
Details and examples: Date and time functions.
| Function | Signature | Description |
|---|---|---|
$now($picture, $timezone) | <s?s?:s> | The evaluation’s timestamp as an ISO 8601 string, or formatted with a picture |
$millis() | <:n> | The evaluation’s timestamp in milliseconds since the epoch |
$fromMillis($millis, $picture, $timezone) | <n-s?s?:s> | Formats milliseconds since the epoch as a timestamp string |
$toMillis($timestamp, $picture) | <s-s?:n> | Parses a timestamp string into milliseconds since the epoch |
Encoding functions
Details and examples: Encoding functions.
| Function | Signature | Description |
|---|---|---|
$base64encode($str) | <s-:s> | Encodes a string as Base64 (each character taken as a byte) |
$base64decode($str) | <s-:s> | Decodes a Base64 string (each byte becomes a character) |
$encodeUrlComponent($str) | <s-:s> | Percent-encodes a URL component |
$encodeUrl($str) | <s-:s> | Percent-encodes a URL, leaving reserved characters |
$decodeUrlComponent($str) | <s-:s> | Decodes a percent-encoded URL component |
$decodeUrl($str) | <s-:s> | Decodes a percent-encoded URL, leaving reserved characters encoded |
Other functions
Details and examples: Other functions.
| Function | Signature | Description |
|---|---|---|
$error($message) | <s?:x> | Raises an error (D3137) with a message |
$assert($condition, $message) | <bs?:x> | Raises an error (D3141) when a condition is false |
$type($value) | <x:s> | The type of a value: null, number, string, boolean, array, object or function |
$eval($expr, $focus) | <sx?:x> | Parses and evaluates a JSONata expression given as a string |
$clone($arg) | <(oa)-:o> | A deep copy of a value |