Formulas

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]