--- title: "Transformation filters" slug: "transformation-filters" updated: 2025-09-14T22:24:05Z published: 2025-09-14T22:24:05Z stale: true --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.supermetrics.com/llms.txt > Use this file to discover all available pages before exploring further. # Transformation filters Transformation filters are a simple way to alter your query results in Supermetrics API using [Liquid filter](https://shopify.dev/api/liquid/filters) syntax. ```plaintext "fields": [  {"id":"campaign_name", "transform":"downcase | replace: 'number', '#'"},  {"id":"impressions", "transform":"times: 100"} ] ``` For more complex use cases, please consider using [custom fields](/v1/docs/about-supermetrics-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": ```plaintext 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** ```plaintext string | country_code:  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** ```plaintext string | country_name:  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** ```plaintext number | currency:  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**](https://supermetrics.com/docs/product-api-field-data-services#currency_conversion) for additional details. - **symbol**string *Required*. Target currency symbol. Case-insensitive. See [**fixer.io/symbols**](http://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**](https://supermetrics.com/docs/product-api-support-options) of any issues you might encounter. **percent Multiply number by 100** ```plaintext 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** ```plaintext 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** ```plaintext ``` - | | | | --- | --- | **hmac_sha256 Convert string into keyed SHA-256 hash** ```plaintext ``` - | | | | --- | --- | **md5 Convert string into MD5 hash** ```plaintext ``` | | | | --- | --- | **sha1 Convert string into SHA-1 hash** ```plaintext ``` | | | | --- | --- | **sha256 Convert string into SHA-256 hash** ```plaintext ``` | | | | --- | --- | ##### Format filters **date Format date string** ```plaintext ``` - | | | | --- | --- | | | | ##### Math filters **abs Get absolute number** ```plaintext ``` | | | | --- | --- | **at_least Minimum value for a number** ```plaintext ``` - | | | | --- | --- | | | | **at_most Maximum value for a number** ```plaintext ``` - | | | | --- | --- | | | | **ceil Round number up** ```plaintext ``` | | | | --- | --- | **divided_by Divide a number** ```plaintext ``` - | | | | --- | --- | **floor Round number down** ```plaintext ``` | | | | --- | --- | **minus Subtract a number** ```plaintext ``` - | | | | --- | --- | **plus Add a number** ```plaintext ``` - | | | | --- | --- | **times Multiply a number** ```plaintext ``` - | | | | --- | --- | ##### String filters **append Append a string** ```plaintext any | append:  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**](https://shopify.dev/api/liquid/filters#append). - **value**string *Required*. String to append. | "My" \| append: ' value' | "My value" | | --- | --- | | 7 \| append: ' items' | "7 items" | **capitalize Uppercase first letter in string** ```plaintext any | capitalize  string ``` Uppercase first letter from the source value. Non-string source values are turned into strings first. Based on a [**Liquid filter**](https://shopify.dev/api/liquid/filters#capitalize). | "campaign" \| capitalize | "Campaign" | | --- | --- | **downcase Lowercase string** ```plaintext 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**](https://shopify.dev/api/liquid/filters#downcase). | "Campaign" \| downcase | "campaign" | | --- | --- | **prepend Prepend a string** ```plaintext any | prepend:  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**](https://shopify.dev/api/liquid/filters#prepend). - **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** ```plaintext any | regexp_extract: ,  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** ```plaintext any | regexp_remove:  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** ```plaintext any | regexp_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** ```plaintext any | remove:  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**](https://shopify.dev/api/liquid/filters#remove). - **value**string *Required*. String to look for. | "Campaign" \| remove: 'a' | "Cmpign" | | --- | --- | **replace Find and replace strings** ```plaintext any | 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**](https://shopify.dev/api/liquid/filters#replace). - **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** ```plaintext any | slice: ,  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**](https://shopify.dev/api/liquid/filters#slice). - **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** ```plaintext 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**](https://shopify.dev/api/liquid/filters#strip). | "Campaign " \| strip | "Campaign" | | --- | --- | **truncate Truncate a string into given length** ```plaintext string | truncate: ,  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**](https://shopify.dev/api/liquid/filters#truncate). - **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** ```plaintext 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**](https://shopify.dev/api/liquid/filters#upcase). | "Campaign" \| upcase | "CAMPAIGN" | | --- | --- | ##### Type filters **bool Convert value into bool** ```plaintext ``` | | | | --- | --- | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | **float Convert value into float** ```plaintext ``` | | | | --- | --- | | | | | | | | | | **string Convert value into string** ```plaintext ``` | | | | --- | --- | | | | | | | ##### Other filters **default Set default for when value is empty** ```plaintext ``` - | | | | --- | --- | | | | ## 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](/v1-api/apidocs/support) or your Supermetrics representative, and let us know.