Skip to main content
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:
TypeUse when the target attribute is…
value_mappingA primitive (array, boolean, double, long, string, timestamptz)
object_mappingAn object, with one expression per property
cached_mappingResolved 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. For the UI and end-to-end workflow, see Mapping schemas.

​
value_mapping

A single SQL expression that produces the target value from each row of the source dataset.
​
type
string
required
Must be "value_mapping".
​
expression
string
required
A SQL expression evaluated against the source dataset.
{
  "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.
​
type
string
required
Must be "object_mapping".
​
property_mappings
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
{
  "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.
​
type
string
required
Must be "cached_mapping".
​
cache_dataset_id
integer
required
ID of the cache dataset to look up against. The dataset must already exist and be owned by the same company.
​
input_expressions
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.
{
  "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

Cached mappings are subject to additional validation. Requests that violate these rules are rejected at create time.
  • 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

Mapping schemas

Walk through the UI and API for creating mappings.

Transformation functions

Functions available in mapping expressions.

How Rosetta Stone works

Background on attributes, mappings, and normalization.

Attribute types

The target shapes a mapping can produce.