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

# Mapping types

> API reference for the mapping types accepted by the Mappings endpoints

A mapping connects a source dataset to a Rosetta Stone attribute. The Mappings API accepts three mapping types, distinguished by the `type` field on the request body:

| Type             | Use when the target attribute is...                                                          |
| ---------------- | -------------------------------------------------------------------------------------------- |
| `value_mapping`  | A primitive (`array`, `boolean`, `double`, `long`, `string`, `timestamptz`)                  |
| `object_mapping` | An `object`, with one expression per property                                                |
| `cached_mapping` | Resolved by joining the source dataset against a precomputed **cache dataset** at query time |

Dependencies are computed server-side from each expression; clients do not provide them on create or update.

For background on how mappings fit into the normalization layer, see [How Rosetta Stone works](/concepts/rosetta-stone/how-it-works). For the UI and end-to-end workflow, see [Mapping schemas](/guides/rosetta-stone/mapping-schemas).

## value\_mapping

A single SQL expression that produces the target value from each row of the source dataset.

<ParamField body="type" type="string" required>
  Must be `"value_mapping"`.
</ParamField>

<ParamField body="expression" type="string" required>
  A SQL expression evaluated against the source dataset.
</ParamField>

```json theme={null}
{
  "type": "value_mapping",
  "expression": "LOWER(email)"
}
```

## object\_mapping

A set of `property_mappings`, one per property of the target object attribute. Required properties of the attribute must be covered.

<ParamField body="type" type="string" required>
  Must be `"object_mapping"`.
</ParamField>

<ParamField body="property_mappings" type="array" required>
  One entry per target property. Each entry has:

  * `path` — dotted path into the target object (e.g. `product.id.value`)
  * `expression` — SQL expression evaluated against the source dataset
</ParamField>

```json theme={null}
{
  "type": "object_mapping",
  "property_mappings": [
    { "path": "product.brand",    "expression": "itemBrand" },
    { "path": "product.category", "expression": "itemCategory" },
    { "path": "product.id.type",  "expression": "'SKU'" },
    { "path": "product.id.value", "expression": "itemID" }
  ]
}
```

## cached\_mapping

A `cached_mapping` does not compute the attribute value from each source row. Instead, NQL joins the source dataset to a separate **cache dataset** at query time and reads the precomputed value out of the cache's `output` column.

Use a cached mapping when the transformation is expensive, depends on data outside the source dataset, or is produced by a workflow that writes its results into a dedicated cache dataset.

<ParamField body="type" type="string" required>
  Must be `"cached_mapping"`.
</ParamField>

<ParamField body="cache_dataset_id" type="integer" required>
  ID of the cache dataset to look up against. The dataset must already exist and be owned by the same company.
</ParamField>

<ParamField body="input_expressions" type="array" required>
  One or more SQL expressions evaluated against the source dataset to build the join key. Multi-column keys are concatenated with a separator at query time, so the cache dataset's `input` column must use the same encoding.
</ParamField>

```json theme={null}
{
  "type": "cached_mapping",
  "cache_dataset_id": 789,
  "input_expressions": ["LOWER(email)"]
}
```

### Cache dataset requirements

The dataset referenced by `cache_dataset_id` must:

* Be owned by the same company creating the mapping.
* Expose an `input` column that holds the join key (matching the encoding produced by `input_expressions`).
* Expose an `output` column whose type matches the target attribute. NQL reads the attribute value directly from this column.

### Constraints

<Warning>
  Cached mappings are subject to additional validation. Requests that violate these rules are rejected at create time.
</Warning>

* **Company scope only.** `cached_mapping` is only accepted on the company-scoped create endpoint (`POST /mappings/companies/{company_id}`). Global mapping endpoints do not accept it.
* **Forbidden attributes.** Cached mappings cannot target attributes used by the opt-out pipeline: `data_privacy_request_identifier`, `unique_id`, or `identifier_relation`.
* **No materialized fields.** You cannot create a materialized field (`Attr` or `AttrSample`) on top of a cached mapping, and you cannot convert an existing mapping to a cached mapping while an active materialized field references it.
* **No DELETE filters.** `DELETE` statements whose `WHERE` clause references an attribute backed by a cached mapping return `UnsupportedQuery: DELETE on cached mappings not yet supported`.
* **Preview is empty.** `POST /mappings/test` returns `{ "records": [] }` for cached mappings — there is no per-source-row preview because the lookup is resolved at query time.

## Testing a mapping

`POST /mappings/test` accepts the same request shape as create and returns sampled, mapped output. For `value_mapping` and `object_mapping` the response includes one entry per sampled source row with both the original `input` and the transformed `output`. For `cached_mapping` the response is always `{ "records": [] }`.

## Related content

<Columns cols={2}>
  <Card title="Mapping schemas" icon="diagram-project" href="/guides/rosetta-stone/mapping-schemas">
    Walk through the UI and API for creating mappings.
  </Card>

  <Card title="Transformation functions" icon="function" href="/reference/rosetta-stone/transformation-functions">
    Functions available in mapping expressions.
  </Card>

  <Card title="How Rosetta Stone works" icon="gears" href="/concepts/rosetta-stone/how-it-works">
    Background on attributes, mappings, and normalization.
  </Card>

  <Card title="Attribute types" icon="shapes" href="/reference/rosetta-stone/attribute-types">
    The target shapes a mapping can produce.
  </Card>
</Columns>