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
- Encoding filters
- Format filters
- Math filters
- String filters
- Type filters
- Other 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.
-
format
string
Required. Date format, expecting PHP date format characters.
"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
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
Status | Error | Description |
400 | SHORT_FILTER_NOT_FOUND | Requested transformation filter does not exist |
400 | SHORT_FILTER_LINE_INVALID | Provided transformation syntax is invalid |
400 | SHORT_FILTER_VALUE_INVALID | Unknown 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.