Transformation filters (preview)

Transformation filters are a simple way to alter your query results in Supermetrics API using Liquid filter syntax.

"fields": [
  {"id":"campaign_name", "transform":"downcase | replace: 'number', '#'"},
  {"id":"impressions", "transform":"times: 100"}
]

For more complex use cases, please consider using custom fields.

What's a preview?

Features and behaviour in public preview may be changed without notice, or can even be removed. Please do not rely on this functionality in production integrations.

Filter syntax

Transformation filters follow the Liquid filter syntax, where multiple filters are performed in sequence to alter the source value. First filter receives the field value, and each following filter receives the value from the previous filter.

As an example, these filters would transform string "CAMPAIGN" into "Campaigns":

downcase | capitalize | append: "s"
Syntax details
  • Each filter should be separated by pipe character.
  • Filter names are case-sensitive.
  • Spaces around pipe characters, filters and parameters are optional.
  • You can use either single or double quotes for string values.
  • Multiple parameters for a filter should be separated by a comma.

Supported filters

Conversion filters
country_code
Convert string into country code
string | country_code: <default>  string

Convert a country name string into two-letter, ISO 3166-1 alpha-2 country code. Empty strings are left intact. This conversion understands different ways a country name can be expressed.

  • default string
    Optional. Default value to use when string is not recognized as a country. Defaults to an empty string.
"--" | country_code ""
"--" | country_code: "unknown" "unknown"
"USA" | country_code "US"
"United States" | country_code "US"
"United States of America" | country_code "US"
country_name
Convert string into country name
string | country_name: <default>  string

Convert different ways a country name can be expressed into a consistent version of the country name. Empty strings are left intact.

  • default string
    Optional. Default value to use when string is not recognized as a country. Defaults to an empty string.
"--" | country_name ""
"--" | country_name: "unknown" "unknown"
"US" | country_name "United States of America"
"USA" | country_name "United States of America"
"United States" | country_name "United States of America"
currency
Convert number into given currency
number | currency: <symbol>  number

Convert the source value into a given currency symbol using historical EOD exchange rates. Your data source query must be compatible with automatic inclusion of date and currency code fields. See currency conversion for additional details.

  • symbol string
    Required. Target currency symbol. Case-insensitive. See fixer.io/symbols for all supported values.
15.3 | currency: "eur" 15.61633
15.3 | currency: "usd" 14.99008
Please note that this filter might not work for all data sources and queries just yet. Let us know of any issues you might encounter.
percent
Multiply number by 100
number | percent  float

Multiply a ratio number by 100 to turn it into a percentage number.

8 | percent 800.0
0.153 | percent 15.3
ratio
Divide number by 100
number | ratio  float

Divide a percentage number by 100 to turn it into a ratio number.

800 | ratio 8.0
15.3 | ratio 0.153

Encoding filters
hmac_sha1
Convert string into keyed SHA-1 hash
any | hmac_sha1: <secret>  string

Converts a string into a keyed SHA-1 hash using the HMAC method. Non-string source values are turned into strings first. Based on a Liquid filter.

  • secret string
    Required. Secret key in plain text.
"my_value" | hmac_sha1: "my_secret" "658b82efb..."
hmac_sha256
Convert string into keyed SHA-256 hash
any | hmac_sha256: <secret>  string

Converts a string into a keyed SHA-256 hash using the HMAC method. Non-string source values are turned into strings first. Based on a Liquid filter.

  • secret string
    Required. Secret key in plain text.
"my_value" | hmac_sha256: "my_secret" "ec9f49df76..."
md5
Convert string into MD5 hash
any | md5  string

Converts a string into an MD5 hash. Non-string source values are turned into strings first. Based on a Liquid filter.

"my_value" | md5 "733cc7e65..."
sha1
Convert string into SHA-1 hash
any | sha1  string

Converts a string into a SHA-1 hash. Non-string source values are turned into strings first. Based on a Liquid filter.

"my_value" | sha1 "b4e9e630b..."
sha256
Convert string into SHA-256 hash
any | sha256  string

Converts a string into a SHA-256 hash. Non-string source values are turned into strings first. Based on a Liquid filter.

"my_value" | sha256 "bffdb4af5..."

Format filters
date
Format date string
string | date: <format>  string

Format date with given format. Formatting only works up to the accuracy of the source data - e.g. it's not possible to return hour of the day from a source values displaying just a date.

"2022-07-03" | date: 'm/d/Y' "07/03/2022"
"2022-07-03" | date: 'D M jS Y' "Sun Jul 3rd 2022"

Math filters
abs
Get absolute number
number | abs  number

Get absolute value from source number. Based on a Liquid filter.

-7 | abs 7
at_least
Minimum value for a number
number | at_least: <value>  number

Ensure the source value is at minimum the given number. Return value can be either an integer or a float. Based on a Liquid filter.

  • value number
    Required. Minimum number the value should be.
7 | at_least: 10' 10
15 | at_least: 10 15
at_most
Maximum value for a number
number | at_most: <value>  number

Ensure the source value is at maximum the given number. Return value can be either an integer or a float. Based on a Liquid filter.

  • value number
    Required. Maximum number the value should be.
7 | at_most: 10' 7
15 | at_most: 10 10
ceil
Round number up
number | ceil  int

Get integer, or next highest integer from a float source value with fractions. Based on a Liquid filter.

1.2 | ceil 2
divided_by
Divide a number
number | divided_by: <value>  number

Divide the source value by a given number. Depending on the outcome, return value can be either an integer or a float. Based on a Liquid filter.

  • value number
    Required. Number to divide by.
11 | divided_by: 2 5.5
floor
Round number down
number | floor  int

Get integer, or next lowest integer from a float source value with fractions. Based on a Liquid filter.

1.2 | floor 1
minus
Subtract a number
number | minus: <value>  number

Subtract a number from the source value. Depending on the outcome, return value can be either an integer or a float. Based on a Liquid filter.

  • value number
    Required. Number to subtract from source value.
6 | minus: 10 -4
plus
Add a number
number | plus: <value>  number

Add a number to the source value. Depending on the outcome, return value can be either an integer or a float. Based on a Liquid filter.

  • value number
    Required. Number to add to source value.
6 | plus: 4 10
times
Multiply a number
number | times: <value>  number

Multiply the source value by a given number. Depending on the outcome, return value can be either an integer or a float. Based on a Liquid filter.

  • value number
    Required. Number to multiply source value with.
6 | times: 5 30

String filters
append
Append a string
any | append: <value>  string

Append a string to the end of the source value. Non-string source values are turned into strings first. Based on a Liquid filter.

  • value string
    Required. String to append.
"My" | append: ' value' "My value"
7 | append: ' items' "7 items"
capitalize
Uppercase first letter in string
any | capitalize  string

Uppercase first letter from the source value. Non-string source values are turned into strings first. Based on a Liquid filter.

"campaign" | capitalize "Campaign"
downcase
Lowercase string
any | downcase  string

Turn all characters in the source value into lowercase. Non-string source values are turned into strings first. Based on a Liquid filter.

"Campaign" | downcase "campaign"
prepend
Prepend a string
any | prepend: <value>  string

Prepend a string to the beginning of the source value. Non-string source values are turned into strings first. Based on a Liquid filter.

  • value string
    Required. String to prepend.
"value" | prepend: 'My ' "My value"
7 | prepend: 'Items: ' "Items: 7"
regexp_extract
Extract a regular expression match from a string
any | regexp_extract: <pattern>, <group>  string

Replace source value with a matched group from a regular expression pattern. If no match is found, an empty string is used. Non-string source values are turned into strings first.

  • pattern string
    Required. Regular expression (PCRE) pattern to look for, with enclosing delimiters.
  • group int
    Optional. Index of which matched group should replace the source value. Defaults to 1 for the first matched group.
"cmp_ABC" | regexp_extract: '/^cmp_(.*?)$/' "ABC"
"ad_ABC" | regexp_extract: '/^cmp_(.*?)$/' ""
regexp_remove
Remove strings with a regular expression
any | regexp_remove: <pattern>  string

Find and remove all occurrences of regular expression pattern matches from the source value. Non-string source values are turned into strings first.

  • pattern string
    Required. Regular expression (PCRE) pattern to look for, with enclosing delimiters.
"CAMPAIGN" | regexp_remove: '/^Camp/i' "AIGN"
regexp_replace
Replace strings with a regular expression
any | regexp_replace: <pattern>, <replace>  string

Find and replace all occurrences of regular expression pattern matches in the source value with another string. Non-string source values are turned into strings first.

  • pattern string
    Required. Regular expression (PCRE) pattern to look for, with enclosing delimiters.
  • replace string
    Required. String to replace with.
"Campaign ABC" | regexp_replace: '/c$/i', 'X' "Campaign ABX"
remove
Find and remove strings
any | remove: <value>  string

Find and remove all occurrences of a given string from the source value. Searching is case-sensitive. Non-string source values are turned into strings first. Based on a Liquid filter.

  • value string
    Required. String to look for.
"Campaign" | remove: 'a' "Cmpign"
replace
Find and replace strings
any | replace: <find>, <replace>  string

Find and replace all occurrences of given string in the source value with another string. Searching is case-sensitive. Non-string source values are turned into strings first. Based on a Liquid filter.

  • find string
    Required. String to look for.
  • replace string
    Required. String to replace with.
"Campaign" | replace: 'a', 'A' "CAmpAign"
slice
Extract part from a string
any | slice: <offset>, <length>  string

Extract characters from the source value starting from a given offset position. Non-string source values are turned into strings first. Based on a Liquid filter.

  • offset int
    Required. Index to start from, 0-based.
  • length int
    Optional. Substring length. Defaults to 1.
"Campaign" | slice: 2 "m"
"Campaign" | slice: 2, 3 "mpa"
strip
Strip whitespace from a string
any | strip  string

Strip whitespace and new line characters from the beginning and from the end of the source value. Non-string source values are turned into strings first. Based on a Liquid filter.

"Campaign " | strip "Campaign"
truncate
Truncate a string into given length
string | truncate: <length>, <ellipsis>  string

When the source value exceeds given amount of characters, truncate string and append ellipsis to it. The length of the ellipsis is included to the truncation length. Unicode characters consisting of multiple bytes are measured as one character. Based on a Liquid filter.

  • length number
    Required. Number of characters to allow.
  • ellipsis string
    Optional. Custom ellipsis to append, defaults to "...".
"Campaign ABC" | truncate: 12 "Campaign ABC"
"Campaign ABC" | truncate: 8 "Campa..."
"Campaign ABC" | truncate: 8, "" "Campaign"
upcase
Uppercase a string
any | upcase  string

Turn all characters in the source value into uppercase. Non-string source values are turned into strings first. Based on a Liquid filter.

"Campaign" | upcase "CAMPAIGN"

Type filters
bool
Convert value into bool
any | bool  bool

Convert any non-boolean value into a boolean. Return null when conversion does not identify boolean intent from the value. Conversion understands different positive and negative values, such as words "yes" and "no".

null | bool null
"" | bool null
"7" | bool null
"1" | bool true
"0" | bool false
"Yes" | bool true
"No" | bool false
"True" | bool true
"False" | bool false
"On" | bool true
"Off" | bool false
"Enabled" | bool true
"Disabled" | bool false
float
Convert value into float
any | float  float

Convert integers and strings into a float number. Return null when conversion is not possible. When value is a string, recognize numeric strings formatted with a thousands separator, with a currency symbol, and with a percentage sign.

7 | float 7.0
"6.50" | float 6.5
"$7.25" | float 7.25
"15 %" | float 15
string
Convert value into string
any | string  string

Convert any value to into a string. Float values will loose unnecessary trailing decimals. Null values are turned into empty strings.

7.2500 | string "7.25"
7.0 | string "7"
null | string ""

Other filters
default
Set default for when value is empty
any | default: <value>  any

Use given default value when source value is null, false, 0 or an empty string. Based on a Liquid filter.

  • value any
    Required. Default value to use
"" | default: "none" "none"
null | default: 0 0

Errors

StatusErrorDescription
400SHORT_FILTER_NOT_FOUNDRequested transformation filter does not exist
400SHORT_FILTER_LINE_INVALIDProvided transformation syntax is invalid
400SHORT_FILTER_VALUE_INVALIDUnknown value used for transformation filter

Missing a filter?

If you find that we are missing the filter or functionality you absolutely need, please contact us or your Supermetrics representative, and let us know.

Last updated 2023-05-04 UTC.