> ## Documentation Index
> Fetch the complete documentation index at: https://knowledge.cloudquant.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dataset Field Mapping

> Map source dataset columns to reference lookup tables and enrich query results with translate=true

# 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.

<Note>
  Admin privileges or higher are required. The reference dataset must already exist in Liberator before you map it.
</Note>

## 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

<Steps>
  <Step title="Open the source dataset">
    Navigate to the source dataset users will query and click **Edit**.
  </Step>

  <Step title="Columns step">
    Go to the **Columns** step and click **Add Translation Columns**.
  </Step>
</Steps>

## 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:

| Parameter         | Result                                                    |
| ----------------- | --------------------------------------------------------- |
| `translate=true`  | Returns enriched/translated values from attached lookups. |
| `translate=false` | Returns raw source data only.                             |

```python theme={null}
df = liberator.get_dataframe(liberator.query(
    name="transactions",
    symbols=["AAPL"],
    back_to="2026-01-01",
    as_of="2026-01-31",
    translate=True,
))
```

See [Query parameters](/api-reference/concepts/query-parameters) for `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.