This article outlines the JMESPath functions supported by Templafy's External Data Source Transformation.
Prerequisites
|
Supported Functions
These functions are part of the JMESPath community library in addition to some custom Templafy functions:
abs
Returns the absolute value of the provided number argument. Below the syntax:
abs(number)
Example 1: abs with a positive input
{"NumberValue": 10}
{AbsValue: abs(NumberValue)}
{"AbsValue": 10}
Example 2: abs with a negative input
{"NumberValue": -5}
{AbsValue: abs(NumberValue)}
{"AbsValue": 5}
avg
Returns the average of the elements in a provided array. Values in the array must be numbers. Below the syntax:
avg(array[number])
Example 1: avg with input as an array
{"NumberArray": [2,4,30]}
{AverageA: avg(NumberArray)}
{"AverageA": 12}
Example 2: avg with input as an object
{"Num_A": 2,"Num_B": 4, "Num_C": 30}
{AverageB: avg([Num_A,Num_B,Num_C])}
{"AverageB": 12}
ceil
Returns the next highest integer value by rounding up a decimal number. Below the syntax:
ceil(number)
Example 1: ceil on a number with one digit
{"Number": 6.7}
{CeilValue: ceil(Number)}
{CeilValue: 7}
Example 2: ceil on a number with two digits
{"Number": 3.24}
{CeilValue: ceil(Number)}
{CeilValue: 4}
contains
Returns true if the subject (array or string) contains the provided search value. Returns false if not.
If searching an array, the function returns true if the search is equal to one of the elements. Below the syntax:
contains(arrayOrString, search_value)
Example 1: contains on an object
{"EmployeeNotes": "Steven was promoted to sales manager in March.
Mr. Buchanan has completed the courses Successful Telemarketing
and International Sales Management."}
{Contains_A: contains(EmployeeNotes, 'International Sales Management')}
{"Contains_A": true}
Example 2: contains with an existent result on an array of objects
{"OrderDetails": [
{
"OrderID": 1234,
"ProductID": "11"
},
{
"OrderID": 1248,
"ProductID": "42"
}
]}
{Contains_B: contains(OrderDetails[*].ProductID, '11')}
{"Contains_B":true}
Example 3: contains on a non-existent result on an array of objects
{"OrderDetails": [
{
"OrderID": 1234,
"ProductID": "11"
},
{
"OrderID": 1248,
"ProductID": "42"
}
]}
{Contains_C: contains(OrderDetails[*].ProductID, '4')}
{"Contains_C": false}
ends_with
Returns true if the subject ends with the specified string, otherwise returns false. Below the syntax:
ends_with(Subject_string, Search_string)
Example 1: end_with yielding to a result
{"Title": "Sales Manager"}
{IsManager: ends_with(Title, 'Manager')}
{"IsManager": true}
Example 2: end_with not yielding to a result
{"Title": "Manager Assistant"}
{IsManager: ends_with(Title, 'Manager')}
{"IsManager": false}
find_first
Returns the zero-based index of the first occurrence where the searched substring appears in the subject (or null
if it does not appear). Start and End parameters are optional and allow for restricting the index range in which the substring must be found. If omitted, start will default to 0, and end will default to length(subject)-1
, which is the end of the subject string. Below the syntax:
find_first(Subject_string, Substring, Start, End)
Example 1: find_first with one match
{"Location": "201-Office-New York City"}
{StartIndex: find_first(Location, 'Office-')}
{"StartIndex": 4}
Example 2: find_first with multiple matches
{"ProdList": "AB|CD|EF|GH"}
{StartIndex: find_first(ProdList, '|')}
{"StartIndex":2}
Example 3: find_first with multiple matches and with a start parameter
{"ProdList": "AB|CD|EF|GH"}
{StartIndex: find_first(ProdList, '|', 3)}
{"StartIndex":5}
Example 4: find_first with a start and end parameters
{"ProdList": "AB|CD|EF|GH"}
{StartIndex: find_first(ProdList, 'GH', 0,10)}
{"StartIndex":9}
Example 5: find_first with a start and end parameters not yielding to a result
{"ProdList": "AB|CD|EF|GH"}
{StartIndex: find_first(ProdList, 'GH', 0,8)}
{"StartIndex": null}
find_last
Returns the zero-based index of the last occurrence where the searched substring appears in the subject (or null
if it does not appear). Start and End parameters are optional and allow for restricting the index range in which the substring must be found. If omitted, start will default to 0, and end will default to length(subject)-1
, which is the end of the subject string. Below the syntax:
find_last(Subject_string, Substring, Start, End)
Example 1: find_last with one match
{"Location": "201-Office-New York City"}
{Index: find_last(Location, '-')}
{"Index": 10}
Example 2: find_last with multiple matches
{"ProdList": "AB|CD|EF|GH"}
{Index: find_last(ProdList, '|')}
{"Index": 8}
Example 3: find_last with multiple matches, start and end parameters
{"ProdList": "AB|CD|EF|GH"}
{Index: find_last(ProdList, '|',0,7)}
{"Index": 5}
Example 4: find_last with start and end parameters not yielding to a result
{"ProdList": "AB|CD|EF|GH"}
{Index: find_last(ProdList, 'GH',0,9)}
{"Index": null}
floor
Returns the next lowest integer value by rounding down a decimal number.
Syntax
floor(number)
Example 1: floor on a number with one digit
{"Number": 6.7}
{FloorValue: floor(Number)}
{"FloorValue: 6}
Example 2: floor on a number with two digits
{"Number": 3.24}
{FloorValue: floor(Number)}
{"FloorValue: 3}
format
Custom Templafy function.
Formats the provided number or datetime value into a string following the defined format and optional culture parameters.
For numbers, format strings are defined here.
For datetime values, format strings are defined here.
Culture is a language culture name defined by ISO-63901. If the culture parameter is omitted, then the invariant culture is used. Below the syntax:
format(number, format, culture) or format(datetime, format, culture)
Example 1: format with en-US culture
{"UnitPrice": 18.2000}
{Price: format(UnitPrice, 'n2', 'en-US')}
{"Price": "18.20"}
Example 2: format with es-ES culture
{"UnitPrice": 18.2000}
{Price: format(UnitPrice, 'n2', 'es-ES')}
{"Price": "18,20"}
Example 3: format with no culture set
{"UnitPrice": 18.2000}
{Price: format(UnitPrice, 'n')}
{"Price": "18.2000"}
Example 4: format with specific datetime formatting
{"Date": "02-19-2021"}
{FormatDate: format(to_datetime(Date, 'MM-dd-yyyy', 'en-US'), 'g', 'en-US')}
{"FormatDate":"'2/19/2021 12:00 AM"}
from_items
Returns an object from a provided array of key value pairs. Below the syntax:
from_items(array[])
Example
{"Orders": [["ProdA",5],["ProdB",2],["ProdC",10]]}
{OrderAmt: from_items(Orders)}
{"OrderAmt": {"ProdA": 5, "ProdB": 2, "ProdC": 10}}
group_by
Groups an array of objects using the provided expression parameter as the grouping key. The result is an object whose keys are the unique set of strings from the grouping parameter, and the values are an array of objects matching the specified group criteria.
Any object from the input that does not match the group criteria will not be included in the output. Below the syntax:
group_by(array[object], expression)
Example
{"orders": [
{
"OrderID": 1234,
"ProductID": "11"
},
{
"OrderID": 1248,
"ProductID": "42"
},
{
"OrderID": 1253,
"ProductID": "11"
},
]}
{GroupedOrders: group_by(orders, &ProductID)}
{"GroupedOrders": {
"11": [
{
"OrderID": 1234,
"ProductID": "11"
},
{
"OrderID": 1253,
"ProductID": "11"
}],
"42": [
{
"OrderID": 1248,
"ProductID": "42"
}]
}
}
items
Returns an array of key-value pairs for a provided input object. Each pair is returned as a two-item array where the first item is the key, and the second item is the value. Below the syntax:
items(object{})
Example
{"OrderAmt": {"ProdA": 5, "ProdB": 2, "ProdC": 10}}
{Orders: items(OrderAmt)}
{"Orders": [["ProdA",5],["ProdB",2],["ProdC",10]]}
join
Returns all elements of the specified array joined together using the provided argument as a separator between each. Below the syntax:
join(Separator, array[string])
Example 1: join with an array of strings
{"Products":["AB", "CD", "EF", "GH"]}
{ProdList: join(', ', Products)}
{"ProdList": "AB, CD, EF, GH"}
Example 2: join with an object as an input
{"FirstName": "Lisa", "LastName": "Crosby"}
{FullName: join(' ',[FirstName, LastName])}
{"FullName": "Lisa Crosby"}
keys
Returns an array containing the keys of a provided object.
Note: the keys associated with a provided object are inherently unordered. This means that keys will not be returned in any specific order. Below the syntax:
keys(object{})
Example 1: keys with an empty object
{"EmptyObject": {}}
{Keys: keys(EmptyObject)}
{"Keys":[]}
Example 2: keys with an object
{"Products": {"AB": 2, "CD":5, "EF": 10}}
{ProdNames: keys(Products)}
{ProdNames: ["AB","EF","CD"]}
length
Returns the length of the given argument using the following types of rules:
- string: returns the number of code points in the string (this essentially means number of Unicode characters).
- array: returns the number of elements in the array.
- object: returns the number of key-value pairs in the object.
Below the syntax:
length(subject)
Example 1: length of a string
{"String": "This is a string!"}
{Length: length(String)}
{"Length": 17}
Example 2: length of an array of strings
{"Products":["AB", "CD", "EF", "GH"]}
{NumProducts: length(Products)}
{"NumProducts": 4}
Example 3: length of an object
{"OrderAmt": {"ProdA": 5, "ProdB": 2, "ProdC": 10}}
{NumOrders: length(OrderAmt)}
{"NumOrders": 3}
Example 4: length of an array of objects
{"OrderDetails": [
{
"OrderID": 1234,
"ProductID": "11"
},
{
"OrderID": 1248,
"ProductID": "42"
}
]}
{NumOrders: length(OrderDetails)}
{"NumOrders": 2}
lower
Returns the lowercase provided string. Below the syntax:
lower(string)
Example 1: lower of an all-caps string
{"String": "VALUE"}
{NewString: lower(String)}
{"NewString": "value"}
Example 2: lower of a string with mix uppercase/lowercase characters
{"String": "User TYped string"}
{NewString: lower(String)}
{"NewString": "user typed string"}
map
Applies the specified expression to each element in the provided array. Below the syntax:
map(expression, array[])
Example
{"OrderDetails": [
{
"OrderID": 1234,
"Price": 1400
},
{
"OrderID": 1248,
"Price": 980
},
{
"OrderID": 1249,
"OtherField": "value"
}
]}
{DiscountedPrices: map(&Price*`0.85`, Order_Details)}
{"DiscountedPrices": [1190,833,null]}
max
Returns the highest found number in the provided array argument. An empty array will return a value of null
. Below the syntax:
max(array[number]) or max(array[string])
Example 1: max on an array of numbers
{"Numbers": [-2, 3.2, 1.01]}
{MaxNumber: max(Numbers)}
{"MaxNumber": 3.2}
Example 2: max an array of strings
{"Strings": ["a","b","c"]}
{MaxString: max(Strings)}
{"MaxString": "c"}
max_by
Returns the maximum element in a provided array using the defined expression as the comparison key. Below the syntax:
max_by(array[elements], expression)
Example
{"OrderDetails": [
{
"OrderID": 1234,
"Quantity": 5
},
{
"OrderID": 1248,
"Quantity": 41
},
{
"OrderID": 1248,
"Quantity": 27
}
]}
{MaxOrder: max_by(OrderDetails, &Quantity)}
{"MaxOrder": {
"OrderID": 1248,
"Quantity": 41
}
}
merge
Returns one object with the defined objects merged. This function combines multiple objects into one where the first object is the base, and the subsequent objects override or add to the base object. Below the syntax:
merge(object1, object2,...)
Example 1: merge of two objects
{
"Object_one": {
"one": "a",
"two": "b"
},
"Object_two":{
"three": "c",
"four": "d"
}
}
{FullObject: merge(Object_one, Object_two)}
{"FullObject": {
"one": "a",
"two": "b",
"three": "c",
"four": "d"
}
}
Example 2: merge of three objects
{
"Object_one": {
"one": "a",
"two": "b"
},
"Object_two":{
"three": "c",
"four": "d"
},
"Object_three":{
"three": "override",
"five": "e"
}
}
{FullObject: merge(Object_one, Object_two, Object_three)}
{"FullObject": {
"one": "a",
"two": "b",
"three": "override",
"four": "d",
"five": "e"
}
}
min
Returns the lowest found number in the provided array. Below the syntax:
min(array[number]) or min(array[string])
Example 1: min on an array of numbers
{"Numbers": [-2, 3.2, 1.01]}
{MinNumber: min(Numbers)}
{"MinNumber": -2}
Example 2: min on an array of strings
{"Strings": ["a","b","c"]}
{MinString: min(Strings)}
{"MinString":"a"}
min_by
Returns the minimum element in a provided array using the defined expression as the comparison key. Below the syntax:
min_by(array[elements], expression)
Example
{"OrderDetails": [
{
"OrderID": 1234,
"Quantity": 5
},
{
"OrderID": 1248,
"Quantity": 41
},
{
"OrderID": 1248,
"Quantity": 27
}
]}
{MinOrder: min_by(OrderDetails, &Quantity)}
{"MinOrder": {
"OrderID": 1234,
"Quantity": 5
}
}
not_null
Returns the first argument that does not resolve to null
. This function accepts one or more arguments and will evaluate them in order until a non-null argument is encountered. If all arguments values resolve to null
, then a value of null
is returned. Below the syntax:
not_null(argument1, argument2, ...)
Example 1: not_null not yielding to a result
{"a": null,
"b": null,
"c": "string",
"d": []}
{first_value: not_null(a, e, b, d, c)}
{"first_value": []}
Example 2: not_null yielding to a result
{"a": null,
"b": null,
"c": "string",
"d": []}
{first_value: not_null(a, c, b, d)
{"first_value": "string"}
pad_left
Adds characters to the beginning of a specified string to return a string of at least the specified width. The optional pad string parameter specifies the character that will be added, but if not specified, a space will be used. Below the syntax:
pad_left(subject_string, width, pad_character)
Example 1: pad_left on a string with a width
{"a": "string"}
{padded_string: pad_left(a, `7`)}
{"padded_string": " string"}
Example 2: pad_left on a string with a with and a pad_character resulting in adding characters
{"a": "string"}
{padded_string: pad_left(a, `10`, -)}
{"padded_string": "----string"}
Example 3: pad_left on a string with a with and a pad_character resulting in doing nothing
{"a": "string"}
{padded_string: pad_left(a, `2`, -)}
{"padded_string": "string"}
pad_right
Adds characters to the end of a specified string to return a string of at least the specified width. The optional pad string parameter specifies the character that will be added, but if not specified, a space will be used. Below the syntax:
pad_right(subject_string, width, pad_character)
Example 1: pad_right on a string with a width
{"a": "string"}
{padded_string: pad_right(a, `7`)}
{"padded_string": " string"}
Example 2: pad_right on a string with a with and a pad_character resulting in adding characters
{"a": "string"}
{padded_string: pad_right(a, `10`, -)}
{"padded_string": "string----"}
Example 3: pad_right on a string with a with and a pad_character resulting in doing nothing
{"a": "string"}
{padded_string: pad_right(a, `2`, -)}
{"padded_string": "string"}
replace
Replaces the occurrences of the specified old substring with the defined new substring in a given subject string.
If the count option parameter is added, it will determine how many occurrences of the old substring are to be replaced. If omitted, all instances will be replaced. Below the syntax:
replace(subject_string, old_substring, new_substring, count)
Example
{"Summary": "The SVP of Marketing, James, is in charge of all marketing efforts.
James reports result to the CEO every quarter.
One of James's duties is social marketing."}
{New_Summary: replace(Summary, 'James', 'Amanda')}
{"New_Summary": "The SVP of Marketing, Amanda, is in charge of all marketing efforts.
Amanda reports result to the CEO every quarter.
One of Amanda's duties is social marketing."}
reverse
Reverses the order of the specified string or array. Below the syntax:
reverse(string) or reverse(array[])
Example 1: reverse on a string
{"string": "AB|CD|EF"}
{rev_string: reverse(string)}
{"rev_string": "FE|DC|BA"}
Example 2: reverse on an array
{"array": [1,2,3,4]}
{rev_array: reverse(array)}
{"rev_array": [4,3,2,1]}
sort
Returns a sorted list of elements in an array. The input array must be a list of strings or numbers. Below the syntax:
sort(array[number]) or sort(array[string])
Example 1: sort on an array of numbers
{"Numbers": [4, 7, -2, 0.1]}
{OrderedNumbers: sort(Numbers)}
{"OrderedNumbers": [-2, 0.1, 4, 7]}
Example 2: sort on an array of strings
{"Strings": ["Orange", "Banana", "Apple", "Grape"]}
{OrderedStrings: sort(Strings)
{"OrderedStrings":["Apple", "Banana", "Grape", "Orange"]}
sort_by
Sorts an array by the provided expression as the sort key. For each element of the array, the expression is evaluated, and the resulting value is used when sorting the elements. The result of the expression must be a number or a string. Below the syntax:
sort_by(array[elements], expression)
Example
{"people": [
{"name":"AB", "tenure": 2},
{"name":"CD", "tenure": 7},
{"name":"EF", "tenure": 1}
]}
{PeopleSort: sort_by(people, &tenure)}
{"PeopleSort": [
{"name":"EF", "tenure": 1},
{"name":"AB", "tenure": 2},
{"name":"CD", "tenure": 7}
]}
split
Given a subject string, this function breaks up the string on occurrence of the provided search string and returns an array containing each partial string between occurrences of the search string.
The optional count parameter specifies the max number of split points in the string. If omitted, all instances of the search parameter are split. Below the syntax:
split(SubjectString, SearchString, Count)
Example 1: split of a string with a SearchString parameter
{"ProdList": "AB|CD|EF|GH"}
{SplitArray: split(ProdList, '|')}
{"SplitArray": ["AB", "CD", "EF", "GH"]}
Example 2: split of a string with a SearchString and a count parameter
{"String": "red-blue-yellow-green-orange-purple"}
{SplitArray: split(String, '-', `3`)}
{"SplitArray": ["red", "blue", "yellow", "green-orange-purple"]}
start_with
Returns true
if the provided subject string starts with the specified prefix string, otherwise returns false
. Below the syntax:
starts_with(SubjectString, prefix)
Example
{"String": "Value"}
{result: starts_with(String, 'va')}
{"result": true}
sum
Returns the sum of the provided array. Below the syntax:
sum(array[number])
Example 1: sum on an array of numbers
{"Numbers": [1, 4, 20, 5]}
{Total: sum(Numbers)}
{"Total": 30}
Example 2: sum on an array of objects
{"OrderDetails": [
{
"OrderID": 1234,
"Quantity": 11
},
{
"OrderID": 1248,
"Quantity": 42
}
]}
{Total: sum(OrderDetails[*].Quantity)}
{"Total": 53}
to_array
Returns a one element array containing the passed argument. If the argument is already an array, the passed in value will be returned. Below the syntax:
to_array(argument)
Example 1: to_array on a string
{"String": "String Value"}
{Array: to_array(String)}
{"Array": ['String Value']}
Example 2: to_array on a number
{"Number": 20}
{Array: to_array(Number)}
{"Array": [20]}
to_datetime
Returns a standardized datetime object from a provided string. The format parameter is expected as a datetime format string to use for parsing the provided string following this standard. The culture parameter is a language culture name to define the output date format based on ISO-639-1. Below the syntax:
to_datetime(string, format, culture)
Example
{"DateString": "3 Feb 2021"}
{date: to_datetime("DateString, 'd MMM yyyy', 'en-US')}
{"date":"2021-02-03T00:00:00"}
to_number
Returns the parsed number of an input string. If a number is passed, that number value will be returned. Any other data types passed will return null
. Below the syntax:
to_number(argument)
Example 1: to_number on a numeric string
{"OrderQuantity": "47"}
{OrdersNumber: to_number(OrderQuantity)}
{"OrdersNumber": 47}
Example 2: to_number on a non-numeric string
{"OrderQuantity": "47 units"}
{OrdersNumber: to_number(OrderQuantity)}
{"OrdersNumber": null}
to_string
Returns the JSON encoded value of the object. If a string is provided, it will return the passed as a string value. Below the syntax:
to_string(argument)
Example 1: to_string on a number
{"OrderID": 1234}
{StringOrder: to_string(OrderID)}
{"StringOrder": "1234"}
Example 2: to_string on null
{"ShippingID": null}
{ShippingString: to_string(ShippingID)}
{"ShippingString": "null"}
Example 3: to_string on an array
{"Numbers": [1, 4, 20, 5]}
{String: to_string(Numbers)}
{"String": "[1, 4, 20, 5]"}
trim
Removes the leading and trailing characters from a given subject string found in the optional characters parameter. If this is not present, whitespace characters are removed from the subject string. Below the syntax:
trim(SubjectString, characters)
Example 1: trim on a string without character parameter
{"Email": "email@example.com "}
{CleanEmail: trim(Email)}
{"CleanEmail": "email@example.com"}
Example 2: trim on a string with a character parameter
{"String": "subject string"}
{NewString: trim(String, 'ugs')}
{"NewString": "bject strin"}
trim_left
Removes the leading characters from a given subject string found in the optional characters parameter. If the characters parameter is not present, whitespace characters are removed from the subject string. Below the syntax:
trim_left(SubjectString, characters)
Example 1: trim_left on a string without character parameter
{"Email": "email@example.com "}
{NewEmail: trim_left(Email)}
{"CleanEmail": "email@example.com "}
Example 2: trim_left on a string with a character parameter
{"String": "subject string"}
{NewString: trim_left(String, 'ugs')}
{"NewString": "bject string"}
trim_right
Removes the trailing characters from a given subject string found in the optional characters parameter. If the characters parameter is not present, whitespace characters are removed from the subject string. Below the syntax:
trim_right(SubjectString, characters)
Example 1: trim_right on a string without character parameter
{"Email": " name@example.com "}
{NewEmail: trim_right(Email)}
{"NewEmail":" name@example.com"}
Example 2: trim_right on a string with a character parameter
{"String": "subject string"}
{NewString: trim_right(String, 'ugs')}
{"NewString": "subject strin"}
type
Returns the JavaScript data type of the provided argument as a string value. Possible return values are:
- number
- string
- boolean
- array
- object
- null
Below the syntax:
type(argument)
Example 1: type on a boolean
{"subject": false}
{subjectType: type(subject)}
{"subjectType": "boolean"}
Example 2: type on a string
{"subject": "customer name"}
{subjectType: type(subject)}
{"subjectType": "string"}
Example 3: type on an array
{"subject": ["abc":123, "def":456]}
{subjectType: type(subject)}
{"subjectType": "array"}
upper
Returns the uppercase subject string. Below the syntax:
upper(SubjectString)
Example
{"String": "string value"}
{UpperString: upper(String)}
{"UpperString": "STRING VALUE"}
values
Returns the values of the provided object. Below the syntax:
values(object{})
NoteThe values associated with a provided object are inherently unordered. This means that values will not be returned in any specific order. |
Example
{"Products": {"AB": 2, "CD":5, "EF": 10}}
{ProdValues: values(Products)}
{"ProdValues": [5, 2, 10]}
zip
Accepts one or more arrays as arguments and returns an array of arrays in which the i-th array contains the i-th element from each of the argument arrays. The returned array is truncated to the length of the shortest argument array. Below the syntax:
zip(array[any], array[any], ...)
Example 1: zip on two arrays of numbers
{"array_one":[1,2,3],
"array_two": [4,5,6]}
{zippedArray: zip(array_one, array_two)}
{"zippedArray": [
[1,4],
[2,5],
[3,6]
]}
Example 2: zip on two arrays of strings
{"A_Products": ["AB": 2, "CD":5, "EF": 10],
"B_Products": ["GH": 7, "IJ": 4, "KL": 12, "MN":42]}
{CompProducts: zip(A_Products, B_Products)}
{"CompProducts": [
["AB":2, "GH": 7],
["CD": 5, "IJ": 4],
["EF": 10, "KL":12]
]}
Example 3: type on an array of objects
{"OrderDetails": [
{
"OrderID": 1234,
"Quantity": 11
},
{
"OrderID": 1248,
"Quantity": 42
}
]}
{ZippedDetails: zip(OrderDetails)}
{"ZippedDetails":[
[{
"OrderID": 1234,
"Quantity": 11
}],
[{
"OrderID": 1248,
"Quantity": 42
}]
]}
Comments
Article is closed for comments.