Skip to main content

​
Dataset field mapping

Dataset field mapping defines a relationship between a source dataset and one or more reference (lookup) datasets. When a user queries the source with translation enabled, Liberator enriches values from the reference data at query time. Source data is never modified. Example: A transactions dataset stores country codes (US, DE, JP). A reference dataset maps codes to English country names. With mapping configured, translate=true returns the country name automatically. You can attach multiple lookup tables to one source dataset (products, locations, employees, and so on) and resolve them in a single query.
Admin privileges or higher are required. The reference dataset must already exist in Liberator before you map it.

​
Step 1 — Prepare the reference dataset

Onboard lookup data as a standard dataset (CSV, database table, etc.). Include at least:
  • A key column to match on (for example, country_code)
  • One or more output columns (for example, english_name)

​
Step 2 — Add translation columns

1

Open the source dataset

Navigate to the source dataset users will query and click Edit.
2

Columns step

Go to the Columns step and click Add Translation Columns.

​
Step 3 — Configure the mapping

In the Add Translation Columns dialog:
  1. Select reference dataset — choose the lookup dataset.
  2. Source column (join key) — column in the source dataset to match (for example, country_code).
  3. Reference column (join key) — corresponding column in the reference dataset (for example, alpha_2_code).
  4. Output column(s) — reference columns to surface in results (for example, english_name).
Click Add. Repeat for additional lookup tables.

​
Step 4 — Save and query

Save the dataset. When querying, pass the translate parameter:
See Query parameters for translate in other clients.

​
Conflict and missing-value behavior

​
Maintenance

  • Edit mappings from Edit → Columns on the source dataset.
  • Changes take effect on the next query.
  • Deleting a mapping entry causes affected output columns to return null.

​
Tips

  • Keep reference datasets small and focused on mapping data only.
  • Split large flat mapping tables into per-topic lookup datasets when possible.
  • Test with translate=true on a narrow date range before rolling out to users.