Liquid Templates
Census uses the Liquid template language to give you extra control over the data you send.
These are tiny programs that let you change the format of data using a simple snippet of code. For example, you can use Liquid to...
Add prefixes or suffixes
Change to upper or lower case
Format dates
Combine columns together
Conditionally use alternate values
Build JSON objects or arrays
Liquid is easy to learn and also very powerful. We look forward to seeing the templates you build!
Census supports the full standard set of Liquid 5.4 template features, filters, and tags (with the minor exception of the include
and render
tags for external files).
Census does not support any Shopify- or Jekyll-specific extensions to Liquid templates, so be sure you're referencing the standard docs at shopify.github.io/liquid.
Getting started
Your most basic operation in Liquid is to reference a record column, like this:
You can add text before or after a variable reference by putting it outside the {{
and }}
markers:
By using two variable references in one template, you can combine columns together:
Another very common job for Liquid is transforming text. Liquid filters are activated with the |
(pipe) symbol:
Column references
All of the columns on your source record are available using the record['COLUMN_NAME']
syntax. When Census sees this syntax, it knows this column is required from the source.
The exact column name must be used in the record
property accessor.
For example, if your source column name is COMPANY_ID
, then you must use record['COMPANY_ID']
in your Liquid template. Any other variations such as company_id
, companyid
, or companyID
will be raised as validation errors.
Any columns not explicitly referenced are not retrieved from the source, which ensures that syncs using Liquid templates run just as fast as all your other syncs on Census.
Standard Filters
There are over 40 standard Liquid filters to be found in the left sidebar in the official documenation. Here are a few common ones...
Convert text to lowercase:
Convert text to uppercase:
Substitute all example text with the provided result text:
Remove space characters from the start and end of the text:
Format a timestamp as a text date:
Census Filters
Census also includes a number of custom filters specifically designed to help you with data transforms...
json
Encode a value into JSON syntax:
This can be useful when working with APIs or structured data.
except
Get a subset of an object with some keys removed:
Often used together with json. Also accepts an array or an object as a single argument.
only
Get a subset of an object containing just some keys:
Often used together with json. Also accepts an array or an object as a single argument.
keys
Get all of the keys of an object:
sha256
Get the SHA-256 hash of a value and return the hex representation:
Can be helpful for generating hashed identifiers for advertising destinations like Google Ads or LinkedIn.
base64
Encode a value using Base64:
May be useful to work around fields that don't allow some special characters.
Validation
As you write your Liquid templates, it's possible that you may make a typo or don't quite have the right syntax. Census will catch all these errors as you type, and you'll know about them well before your sync starts running.
Here are some invalid template examples that will be caught by Census:
{{ record['ID' }}
→ Liquid syntax error: Expected close_square but found end_of_string in "{{ record['ID' }}"{{ record['NAMEE'] }}
→ Column being referenced in template can't be found in data source [NAMEE]{% assign category = record['CAT'] %}{{ categoryy.ratio | times: 100 }}
→ [categoryy.ratio | times: 100] unknown variable `categoryy`
Compared to some other implementations of Liquid, Census runs using strict parsing and rendering. This means that invalid templates won't run, and any errors encountered when running a valid template won't cause bad data to be sent to your destination.
Advanced
The examples above just scratch the surface of what can be done with Liquid templates. The language exposes enough capabilities to define complex conditions, process structured data, and do some really advanced data manipulation.
Custom variables
If you're writing advanced expression and want to store an intermediate result, you can create your own Liquid variables to help (official docs).
Make a new variable from a value:
Make a new variable from captured text:
This is great for text variables that combine multiple columns or make use of multiple Liquid filters or tags.
Conditionals
You can build advanced conditional code with Liquid, for example, to use one variable or another, or to "translate" values for your destination (official docs).
Construct a condition using boolean operators:
Construct conditions based on matching values:
Looping
You can also iterate over arrays to build text with repeating elements (official docs).
Generate text for each item:
Commonly used in JSON mode and with batched records.
Whitespace
If you're using spaces in a complex template and notice your output now includes unwanted spaces, this is a sign that you need to use Liquid whitespace control syntax.
Liquid is basically text building engine. You can think of {{ ... }}
and {% ... %}
as "insertion points" into a text file...
The code inside the brackets will get run by Liquid, and it doesn't make a difference if there's whitespace inside the code, only the code's output will be inserted.
On the other hand, any whitespace outside of those insertion points will be preserved by Liquid, just like any other text.
Preserved whitespace won't be an issue for text formats like HTML and JSON where whitespace is collapsed or ignored, but for many other use cases, whitespace is significant and causes problems.
To deal with this, Liquid uses the -
(hyphen) symbol for whitespace control, stripping out whitespace at the insertion point where the symbol is used (official docs).
Here are a few examples of whitespace inside vs. outside Liquid code blocks (using {id: 1}
as the record data)...
Notes:
Whitespace inside code has no effect
Whitespace outside code is preserved
No whitespace between tags gives no result whitespace
Whitespace between tags is preserved
Whitespace control symbol strips whitespace around variable
Whitespace control symbol strips whitespace inside tags
Whitespace includes single spaces, line breaks, and tabs—any of the blank spaces you see in your template code.
JSON mode
One special use for Liquid templates is to build JSON documents. This can be great for advanced API usage with templated fields or even building custom integrations with the HTTP Request destination.
Two special features get activated when in JSON mode:
Escaped strings
JSON strings are escaped by default, which means that you don't need to worry about source data causing JSON syntax errors.
This behavior can be overridden using either the json
filter (to encode a value into valid JSON) or the raw
filter (when your source data is already valid JSON).
Flexible syntax
When generating JSON data using for loops, this process will often leave a ,
after the last item in an array or object, which is invalid JSON.
Instead of triggering an error, Census allows this syntax and converts it into valid JSON. It does this by parsing the template output as YAML, which is a strict superset of JSON (allows all valid JSON) that accepts these "trailing commas".
If you want, you're free to use any other YAML features, like block-style collections, and the result will still be converted to valid JSON:
Last updated