Transformation filters

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.

defaultstring
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.

defaultstring
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.

symbolstring
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

hmac_sha256

Convert string into keyed SHA-256 hash

md5

Convert string into MD5 hash

sha1

Convert string into SHA-1 hash

sha256

Convert string into SHA-256 hash

Format filters

date

Format date string

Math filters

abs

Get absolute number

at_least

Minimum value for a number

at_most

Maximum value for a number

ceil

Round number up

divided_by

Divide a number

floor

Round number down

minus

Subtract a number

plus

Add a number

times

Multiply a number

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.

valuestring
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.

valuestring
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.

patternstring
Required. Regular expression (PCRE) pattern to look for, with enclosing delimiters.
groupint
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.

patternstring
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.

patternstring
Required. Regular expression (PCRE) pattern to look for, with enclosing delimiters.
replacestring
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.

valuestring
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.

findstring
Required. String to look for.
replacestring
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.

offsetint
Required. Index to start from, 0-based.
lengthint
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.

lengthnumber
Required. Number of characters to allow.
ellipsisstring
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

float

Convert value into float

string

Convert value into string

Other filters

default

Set default for when value is empty

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.