HomeData hubOther resources
Guides

Configure schema

Suggest Edits

👍

Welcome note

Data hub is our new upgraded platform, which we rolled out in August 2025. It offers a single unified integration for passing your data through to your Bloomreach products.

You have access to Data hub if you've implemented with Bloomreach after August 2025.

Customers who have implemented before August 2025 should follow the existing documentation for Engagement, Discovery, and Clarity.

Map your raw record fields to meaningful attributes so the system can create items from them.

Prerequisites

Knowledge

  • Understanding of item collection concepts.
  • Understanding of which record fields should map to product-level vs. variant-level attributes.
  • Knowledge of appropriate data types for your attributes (string, number, boolean, array).
  • Knowledge of schema mapping.

Process

Steps to configure schema

The following steps apply to both product and variant attribute mappings. 

  1. Go to Data hub > Items in your Bloomreach workspace. 

  2. Locate and open the existing item collection from the item collections listing page.

  3. Click the Schema tab.

  4. Set the item identifier. This defaults to record ID, but you can choose a custom record field as item ID. When you choose the custom option:

    1. Field name: Enter the name of your custom field.

    2. Record level: Select which level (product or variant) of your data hierarchy contains this field. 

    3. Fallback behavior: Choose what happens when the specified field value is missing:

      1. Fallback to record ID (default): Uses the record ID if your custom field is empty.

      2. Skip updates for related item: Ignores records without the custom field value.

      3. Stop job execution (job failure): Fails the job if any record is missing the field value.

        Item identifier mapping dialog in Bloomreach Data hub, showing options to select record ID or a custom record field as the item identifier.

  5. Click + New attribute and select the attribute type.

    The Schema tab in a Bloomreach Data hub item collection, displaying a list of schema attributes and options to add new attributes.

System attributes

Select and map system attributes to source fields from your records (like title, price, url). Click Apply selection.

The Add system attributes dialog in Bloomreach Data hub, listing available system attributes such as color, price, and launch date.

Custom attributes

Map custom attributes for any fields unique to your business (like color_family or custom_level). Select the source field, choose a data type, and save changes.

The custom attribute definition dialog in Bloomreach Data hub, showing fields for attribute name, type, data type, and source field mapping.

Custom attributes namespacing

When custom attributes have the same name as system attributes, they receive a namespace prefix to prevent collisions when they sync with destinations.

Example

Schema: Custom attribute named color

Engagement catalog: Appears as main.color

Discovery catalog: Appears as main.color

The main namespace ensures your custom color attribute doesn't conflict with any system color attribute. System attributes map directly without the namespace prefix.

  1. Click Save changes. Repeat the same process for variant attributes by clicking the Variant tab. 

Data hub reprocesses your data to generate items based on the new mappings. Wait for the items update job to complete.

Next step

Verify items.

Updated 7 days ago