Select a value

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

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

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.

Utility Functions

EQ

Returns a boolean indicating whether the two arguments are equal to one another.

Example

EQ(1, 1)
=> true
GT

Returns a boolean indicating whether an integer is greater than another.

Example

GT(1, 2)
=> false
GT(2, 2)
=> false
GT(2, 1)
=> true
GTE

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
LT

Returns a boolean indicating whether an integer is less than another.

Example

LT(1, 2)
=> true
LT(2, 2)
=> false
LT(2, 1)
=> false
LT

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
MAP

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]
TO_INTEGER

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
TO_NUMBER

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

Array Functions

Creates an array of values by either extracting a value from an object based on it's key or transforming it with another function.

COMPACT

Removes all "false", "null", "0", and "''" values from an array.

Example

COMPACT([1, null, 0, "", false, 2])
=> [1, 2]
CONCAT

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]
DIFFERENCE

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]
FLATTEN

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
INITIAL

Returns all but the last item within an array.

Example

INITIAL([1, 2, 3])
=> [1, 2]
INTERSECTION

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]
LAST

Returns the last item within an array.

Example

LAST([1, 2, 3])
=> 3
LENGTH

Returns the total number of items within the array.

Example

LENGTH([1, 2, 3, 4])
=> 4
SLICE

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]
TAIL

Returns all but the first item within an array.

Example

TAIL([1, 2, 3])
=> [2, 3]
TAKE

Returns an array that includes the number of items provided by the second argument.

Example

TAKE([1, 2, 3], 2)
=> [1, 2]
UNION

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]
UNIQ

Returns a duplicate-free version of the provided array.

Example

UNIQ([1, 2, 1, 3])
=> [1, 2, 3]
WITHOUT

Returns an array that does not include the values provided after the first argument.

Example

WITHOUT([1, 2, 3], 2)
=> [1, 3]
XOR

Returns an array that is the symmetric difference of all provided arrays.

Example

XOR([1, 2], [2, 3])
=> [1, 3]

Math Functions

These functions allow you calculate numbers using common utilities.

ADD

Adds two numbers together.

Example

ADD(1,2)
=> 3
CEIL

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
DIVIDE

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
FLOOR

Divides one integer from another.

Example

FLOOR(1.5)
=> 1
FLOOR(0.055, 2)
=> 0.05
FLOOR(1550, -2)
=> 1500
MAX

Returns the largest integer within an array of integers.

Example

MAX([1,2,3,4])
=> 4
MEAN

Returns the mean for an array of integers.

Example

MEAN([1,2,3,4])
=> 2.5
MIN

Returns the smallest integer within an array of integers.

Example

MIN([1,2,3,4])
=> 1
MULTIPLY

Multiplies one integer by another.

Example

MULTIPLY(5, 2)
=> 10
ROUND

Rounds an integer up or down to a given precision.

Example

ROUND(1.005)
=> 1
ROUND(1.005,2)
=> 1.01
SUBTRACT

Subtracts one integer from another.

Example

SUBTRACT(10, 2)
=> 8
SUM

Adds all integers within an array.

Example

SUM([1,2,3,4])
=> 10

Object Functions

These functions allow you to transform and easily access data within JSON objects.

AT

Creates an array of values corresponding to paths of objects.

Example

AT({ "a": [{b: 1}, 2] }, ["a[0].b", "a[1]"])
=> [1, 2]
GET

Returns the value from within an object at the given path.

Example

GET({ "a": [{b: 1}, 2] }, "a[0].b")
=> [1, 2]
KEYS

Returns an array of all keys within an object.

Example

KEYS({ "a": 1, "b": 2, "c": 3})
=> ["a", "b", "c"]
VALUES

Returns an array of all values within an object.

Example

VALUES({ "a": 1, "b": 2, "c": 3})
=> [1, 2, 3]