Formulas enable you to transform data returned from any API. You can use formulas to transform API data into KPIs or query parameters for paginated queries. Formulas have two different components, functions and data tokens.
Data tokens enable you to access values within the response for an API. Data tokens will be represented as the path to a given value within an object. We will traverse the entire JSON response and assign a data token for each leaf node within the response.
For the following API response:
{ "followers": 2, "meta": { "has_more": true }, "profile": { "email": "hello@commonality.com" }, "posts": [ { "name": "My cool post" } ] }
For the following data tokens will be made available to you:
@followers
@meta.has_more
@profile.email
@posts
Note that we do not create data tokens for arrays of data. Instead you can use functions to transform the values contained within data tokens to achieve your desired output.
Functions allow you to transform the data returned from an API. With functions, you can iterate over arrays of data, convert values from strings to numbers, and traverse complex responses.
Returns a boolean indicating whether the two arguments are equal to one another.
Example
EQ(1, 1)
=> true
Returns a boolean indicating whether an integer is greater than another.
Example
GT(1, 2)
=> false
GT(2, 2)
=> false
GT(2, 1)
=> true
Returns a boolean indicating whether an integer is greater than or equal to another.
Example
GTE(1, 2)
=> false
GTE(2, 2)
=> true
GTE(2, 1)
=> true
Returns a boolean indicating whether an integer is less than another.
Example
LT(1, 2)
=> true
LT(2, 2)
=> false
LT(2, 1)
=> false
Returns a boolean indicating whether an integer is less than or equal to another.
Example
LT(1, 2)
=> true
LT(2, 2)
=> true
LT(2, 1)
=> false
Allows you to iterate over an array of values and transform or extract values. If a string is passed as the second argument, the function will attempt to extract a value from an object using the string as a key. If a function is passed as a second argument, the function will iterate over every item within the array and transform the value using the provided function.
Example
MAP([{ impressions: 1 }, { impressions: 2 }, { impressions: 3 }], "impressions")
=> [1, 2, 3]
MAP(["1", "2", "3"], TO_INTEGER)
=> [1, 2, 3]
Converts a value to the nearest whole number, this function will also convert strings to integers if possible.
Example
TO_INTEGER("4.4")
=> 4
TO_INTEGER(3.2)
=> 3
Converts a value to a number, this function will also convert strings to numbers if possible.
Example
TO_NUMBER("4.4")
=> 4.4
TO_NUMBER(3.2)
=> 3.2
Creates an array of values by either extracting a value from an object based on it's key or transforming it with another function.
Removes all "false", "null", "0", and "''" values from an array.
Example
COMPACT([1, null, 0, "", false, 2])
=> [1, 2]
Creates a new array by concatenating any new values or arrays to the end of the input array.
Example
CONCAT([1], 2, [3])
=> [1, 2, 3]
When passed two arrays, this function will find the unique values not included in the second array. The values returned by the function will only include values within the first array provided.
Example
DIFFERENCE([1, 2, 3], [3, 4, 5]
=> [1, 2]
Flattens an array, a single level deep.
Example
FLATTEN([[1], 2])
=> [1, 2]
Returns the first item within an array.
Example
HEAD([1, 2, 3])
=> 1
Returns all but the last item within an array.
Example
INITIAL([1, 2, 3])
=> [1, 2]
When passed two arrays, this function will find the unique values that are also included in all arrays. The values returned by the function will only include values within the first array provided.
Example
INTERSECTION([1, 2, 3], [3, 4, 5]
=> [3]
Returns the last item within an array.
Example
LAST([1, 2, 3])
=> 3
Returns the total number of items within the array.
Example
LENGTH([1, 2, 3, 4])
=> 4
Returns an array staring from the index provided by the second argument, up to but not including the index provided by the third argument.
Example
SLICE([1, 2, 3], 0, 2)
=> [1, 2]
Returns all but the first item within an array.
Example
TAIL([1, 2, 3])
=> [2, 3]
Returns an array that includes the number of items provided by the second argument.
Example
TAKE([1, 2, 3], 2)
=> [1, 2]
Returns an array that contains the unique values, in order, from all provided arrays.
Example
UNION([1, 2, 3], [3, 4, 5], [5, 6, 7])
=> [1, 2, 4, 6 ,7]
Returns a duplicate-free version of the provided array.
Example
UNIQ([1, 2, 1, 3])
=> [1, 2, 3]
Returns an array that does not include the values provided after the first argument.
Example
WITHOUT([1, 2, 3], 2)
=> [1, 3]
Returns an array that is the symmetric difference of all provided arrays.
Example
XOR([1, 2], [2, 3])
=> [1, 3]
These functions allow you calculate numbers using common utilities.
Adds two numbers together.
Example
ADD(1,2)
=> 3
Rounds an integer up to a given precision point, if none is specified the integer is rounded to the nearest whole number.
Example
CEIL(1.5)
=> 2
CEIL(1.00005, 2)
=> 1.01
Rounds an integer down to a given precision point, if none is specified the integer is rounded to the nearest whole number.
Example
DIVIDE(10, 2)
=> 5
Divides one integer from another.
Example
FLOOR(1.5)
=> 1
FLOOR(0.055, 2)
=> 0.05
FLOOR(1550, -2)
=> 1500
Returns the largest integer within an array of integers.
Example
MAX([1,2,3,4])
=> 4
Returns the mean for an array of integers.
Example
MEAN([1,2,3,4])
=> 2.5
Returns the smallest integer within an array of integers.
Example
MIN([1,2,3,4])
=> 1
Multiplies one integer by another.
Example
MULTIPLY(5, 2)
=> 10
Rounds an integer up or down to a given precision.
Example
ROUND(1.005)
=> 1
ROUND(1.005,2)
=> 1.01
Subtracts one integer from another.
Example
SUBTRACT(10, 2)
=> 8
Adds all integers within an array.
Example
SUM([1,2,3,4])
=> 10
These functions allow you to transform and easily access data within JSON objects.
Creates an array of values corresponding to paths of objects.
Example
AT({ "a": [{b: 1}, 2] }, ["a[0].b", "a[1]"])
=> [1, 2]
Returns the value from within an object at the given path.
Example
GET({ "a": [{b: 1}, 2] }, "a[0].b")
=> [1, 2]
Returns an array of all keys within an object.
Example
KEYS({ "a": 1, "b": 2, "c": 3})
=> ["a", "b", "c"]
Returns an array of all values within an object.
Example
VALUES({ "a": 1, "b": 2, "c": 3})
=> [1, 2, 3]
© Commonality, LLC 2021