Mapping Data

Overview

In Hightouch, Mapping refers to the establishment of a one-to-one relationship between a column or field in your model and a record's property or field in a destination. Depending on your sync’s destination, you can map your data with either the basic mapper, which does column-based mapping, or the advanced mapper, which gives the additional options of mapping with static values, with variables, or with Liquid templating.

Basic mapper

Column Mapping

Column in your source	Field in your destination
email	hs_email
first_name	hs_firstName
last_name	hs_lastName
company_name	hs_company

With the basic mapper, you tell Hightouch which columns in your source should get fed into which fields in your destination. In column mapping, it is expected that every row has different values for each column.

Click ‘suggest mappings’ to auto-complete a column-based mapping based on column and field titles. Auto-completion works by searching for matching and near matching column and field titles. You should confirm that the auto-completion has made the correct selections:

Advanced Mapper

For destinations where the Advanced Mapper is enabled, you have the additional capability to create mappings that include a static value, a sync-based variable value, or complex values using the Liquid templating language. We are in the process of rolling out our Advanced Mapper to all existing destinations, and any new destinations will automatically be released with this new capability. Please let our CS team know if there’s a specific destination or use case that is a high priority for you to leverage this!

Static Mapping

With static mapping, you can specify a constant value to include in the mapping. Select ‘static value’, the value’s data type, and enter the value in the field provided. Click ‘apply’.

In this example, we are mapping the string ‘EMEA’ to the ‘region’ field in our destination. ‘EMEA’ will be inserted into every record’s ‘region’ field:

Variable Mapping

With variable mapping, you can include a variable with meta-data about your sync and send it to a field in your destination. Select ‘variable value’, the variable you would like to include, and click ‘apply’:

In this example, we are mapping the current time to the ‘Time sent’ field in our destination. An ISO timestamp (YYYY-MM-DD) will be inserted into every record’s ‘Time sent’ field:

Template Mapping

With template mapping, you can create more complex mappings using our library of Liquid-inspired functions as well as standard functions of the Liquid templating language. Please visit Liquid's documentation for more information on usage.

Select ‘template’, then select a variable and a function. The function's code will automatically appear in the editor window:

In this example, we are checking if a row’s ‘last_name’ column includes the string ‘Stark’. If it does, the row is processed. If it doesn’t, the row is rejected.

Liquid Templating

The template mapper can also implement all of Liquid’s regular functionality (see the Liquid Reference), beyond the Liquid-inspired functions we have provided for you in the UI.

Variables follow this format:

{{ row['company'] }}

The double-handlebars enclose a Liquid snippet that is generating output. The name of the column should go in between the single quotes inside the square brackets (akin to array field notation).

Functions follow this format:

{{ row['last_name'] | includes : 'Stark' }}

A single pipe comes after the variable, then the name of the function and any necessary parameters. See the Liquid Reference or Liquid Cheatsheet for a full list of available functions.

Liquid Variables in the Advanced Mapper

$ <column_name>
$ Model Name
$ Timestamp

All of the model’s column names will have a corresponding variable. You also have access to a variable for the name of the model and the timestamp for the sync’s run:

Liquid-Inspired Functions in the Advanced Mapper

Function	Syntax	Description
base64_decode	`row['email']\|b64_decode`	Base64 decode input
base64_encode	`row['email']\|b64_encode`	Base64 encode input
cast	`row['phone']\|cast:'string'`	Cast input to specified type. Allowable types are ‘string’, ‘number’, ‘boolean’
includes	`row[‘last_name’]\|includes:‘Stark’`	Check input for a substring. Row will be rejected if substring is not found
parse	`row['first_name']\|parse`	Parse input to JSON
JSON_construct	`\| json_construct: 'city', row['city'], 'state', row['state_province']`	Construct JSON object
regex_replace	`row['last_name']\|regex_replace: '<[a-zA-Z]>', '<replacement>'`	Search and replace substrings of input using RegEx
regex_test	`row['last_name']\|regex_test: '<[a-zA-Z]>'`	Check input for a RegEx match. Row will be rejected if no match is found using RegEx
sha256	`row['email']\|sha256`	Hash input using SHA-256
sha512	`row['email']\|sha512`	Hash input using SHA-512
to_date	`row[‘dob’]\|to_date`	Parse input and return a Date object (ISO 8601 format)
to_unix	`row[‘date_sent’]\|to_unix`	Convert input to Unix time
validate_email	`row['email']\|validate_email`	Reject emails that are not RFC 2822 compliant email addresses

Liquid Function Chaining

More than one Liquid function can be called on one input. Separate the functions with a single pipe:

Examples:

{{ row[‘full_name’] | camelcase | sha256 }}

{{ row['email'] | downcase | validate_email | sha256 }}

Extended Liquid and Use Cases

See the Liquid Reference or Liquid Cheatsheet for a full list of available functions.

Conditional Output

Use Liquid conditionals to specify output based on input. For example, this Liquid snippet

{% if row['title'] == "Awesome Shoes" %}
  These are awesome shoes!
{% elsif row['title'] == "Ugly Shoes" %}
  These are ugly shoes!
{% else %}
  No shoes selected!
{% endif %}

outputs the following result in the destination:

Math Functions

Use the abs function to send an absolute value:

{{ row['value'] | abs }}

Use the round function to round a value to the nearest integer or specified number of decimals:

{{ row['value'] | round: 2 }}

See Liquid Math Functions

String Functions

Use the capitalize function to capitalize the first letter of a string:

{{ row['title'] | capitalize }}

Use the strip function to remove all whitespace from the left and right sides of a string:

{{ row['title'] | strip }}

Use the append function to add a file extension to a string:

{{ row['file_name'] | append: '.png' }}

See Liquid String Functions

Template Mapping Use Cases

The Template Mapper is especially useful in situations where your chosen destination requires that your data be sent in a very specific format and you don't want to 'bake' this specificity into your model.

Webflow requires slugs to not have any special characters. Use regex_replace to remove them.
Enable lead routing in your destination using Liquid conditionals without touching your central dbt model.
Validate emails for Mailchimp.

Need help?

Our team is relentlessly focused on your success. We're ready to jump on a call to help unblock you.

Connection issues with your data warehouse?
Confusing API responses from destination systems?
Unsupported destination objects or modes?
Help with complex SQL queries?

Feature Requests?

If you see something that's missing from our app, let us know and we'll work with you to build it!

We want to hear your suggestions for new sources, destinations, and other features that would help you activate your data.