Mapping configuration

During the Publish and Synchronization (P&S) process, a unique key is generated for each published resource. This key is used to store the resource’s denormalized data in storage, enabling efficient data retrieval later. By default, Spryker generates these keys using the database ID of the corresponding record to ensure uniqueness.

Example: Abstract product key

For an abstract product, the storage key might look like this:

kv:product_abstract:de:de_de:100

You can query Redis using this key to retrieve the stored product data.

Reasons to use mappings

The default key generation may not be suitable in cases such as the following:

• You only know the product SKU, not its ID

• Avoid exposing internal database IDs externally

• Your project needs a more flexible lookup strategy

Mappings

Mappings enable you to associate a resource’s internal ID with an alternative, unique identifier–for example, SKU. A mapping creates an additional storage record that links this identifier to the resource ID using a dedicated key. This key does not include the database ID.

Mappings are configured in the Propel schema and used during the P&S process.

Defining mappings

Mappings are defined in the synchronization behavior of a Propel schema.

For example, SKU can be mapped to ID for abstract products in spy_product_abstract_storage:

<table name="spy_product_abstract_storage">
  <behavior name="synchronization">
      <parameter name="mappings" value="sku:id_product_abstract"/>
      ...
  </behavior>
</table>

sku is the source (alternative key), and id_product_abstract is the destination (resource ID).

These values must match keys in the resource payload.

After rebuilding the Propel entity and re-syncing, a new record is stored in Redis. Example:

{"id":1,"_timestamp":1599741494.2676899} 

Key example:

kv:product_abstract:de:de_de:sku:001

This enables Redis lookups using sku:001 instead of the database ID.

Retrieve data using a mapping

To retrieve data using a mapping, take the following steps:

1. To get the product ID, query the mapping key–for example, sku:001.

2. Construct the final storage key using the retrieved ID.

3. Query storage again using the full key–for example kv:product_abstract:de:de_de:100.

This adds one extra lookup step but has minimal performance impact, especially when using Redis.

Multiple mappings

Spryker supports multiple mappings per resource. Define them using the same mappings parameter, separated by a configurable delimiter (; by default):

<table name="spy_product_abstract_storage">
<behavior name="synchronization">
    <parameter name="mappings" value="sku:id_product_abstract;foo:bar"/>
    ...
</behavior>

Each mapping results in a separate key in storage. After making changes, regenerate the Propel entity classes.

To change the delimiter, override \Spryker\Zed\SynchronizationBehavior\SynchronizationBehaviorConfig::MAPPINGS_DELIMITER.