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
Open the source dataset
Navigate to the source dataset users will query and click Edit.
Columns step
Go to the Columns step and click Add Translation Columns.
- Select reference dataset — choose the lookup dataset.
- Source column (join key) — column in the source dataset to match (for example,
country_code).
- Reference column (join key) — corresponding column in the reference dataset (for example,
alpha_2_code).
- 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:
| Parameter | Result |
|---|
translate=true | Returns enriched/translated values from attached lookups. |
translate=false | Returns raw source data only. |
df = liberator.get_dataframe(liberator.query(
name="transactions",
symbols=["AAPL"],
back_to="2026-01-01",
as_of="2026-01-31",
translate=True,
))
translate in other clients.
Conflict and missing-value behavior
| Situation | Behavior |
|---|
| No match in the lookup table | Output column is null; the row is still returned. |
| Multiple entries for the same key | The entry with the most recent timestamp wins. |
| Multiple lookup tables | All lookups resolve in one query pass. |
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.
