Records

👍
Data hub rollout
Data hub provides new unified API integration methods for sending data to multiple Bloomreach products. Access is being rolled out in phases. For new implementations, we recommend using Data hub where available. Existing product-specific integrations remain fully supported for Marketing, Search, and Conversational agent.

This guide introduces you to the concept of records.

What are records

Records are the raw, unstructured source data you ingest into an item collection. Each record belongs to one item type and represents a product, a variant, or other business data, such as an article, containing fields like title, price, color, or any other JSON-based data. Records store data in a flexible JSON format, eliminating the need for a predefined schema. This flexibility allows you to send business data exactly as it exists in your source system, whether that's an ecommerce platform, product information management system, or custom database.

Why are records important

Records serve as your source of truth before any transformation into structured items. By storing data in its raw form, you maintain a copy of what your source system provided. This separation between raw data (records) and transformed data (items) gives you the flexibility to change how data is structured and validated without affecting your source data. You can modify your schema mappings, test different attribute configurations, and reprocess data multiple times from the same record set.

Key features

Flexible JSON

Records can have any valid JSON fields (strings, numbers, arrays, objects).

Product and variant data

If your data contains product variants, each variant is stored as a separate record that is linked to its parent product record.

Records in an item type

Records belong to the item type, and a Full Records update replaces records in that item type only. Another item type can use the same record ID for a different record.

When records become items

An Items update processes records using the item type's schema. Imports start this processing automatically. By default, an API Records update changes only records. If using API, you can choose to start an Items update and a Destination items update after successful processing. See Automatic success triggers.

Override data

A record in a product item type can hold override data in a contexts object, with the values that differ for each context value. Data hub uses it once a context with the same name exists and the fields are mapped. To send it, follow Send context data in records.

Format, send, and update records

Review the guides on sending and updating records through API integration and using imports. Each request updates records in one item type. Use that item type's system name in the request path. The name doesn't have to be product.

View and explore records

Review the detailed setup guide to view, search, and manage records in your item collection. You can review records in the Data hub interface, but you change them through the API or an import.

FAQs

What's the difference between records and items?

Records are your raw source data before any transformation occurs. Items are built from records based on your schema configuration. Records contain flexible fields that don't yet have meaning to Bloomreach, while items are structured data with validated attributes that Bloomreach can use.

Can records have different fields across items?

Yes. Records are schema-less, meaning each record can have a completely different set of fields. Even field data types can vary between records—one product might have a color field as a string while another has it as an integer. The schema mapping process standardizes these differences when creating items.

Can variants under the same product have different fields?

Yes. Each variant record can have its own unique set of fields. Variant structures are completely flexible, allowing different products to model their variant data differently based on business needs.

Where do field names come from when mapping the schema?

Field names come directly from the data you send in your records. They're not predefined or configured in advance. When you map attributes in the schema, the system suggests fields by analyzing all the fields present across your record set. You can also manually enter field names that don't yet exist in your data but will be used when they arrive.

What happens if I send PII data in records?

Bloomreach recommends that you avoid sending personally identifiable information (PII) in item collections. Product catalogs are designed for product data like titles, prices, and descriptions, not customer information. If you do send PII data, it will be visible in your records.

How do I know who made changes to my records?

Record updates are tracked through the jobs system. Each record maintains a “created at” and “last updated at” timestamp along with the associated job ID that created or modified it. Use this job ID to trace back to the specific user or API key that made the change through standard audit log capabilities. For detailed audit information, contact the Bloomreach Support team.

Do records need to have the same identifier as items?

No. Items can be configured via schema to have a different identifier than the source system record identifiers. The identifier can come from field-level data in the record. This is useful when the business uses a different item identifier than the technical source system uses, allowing for easier integration. For an example, see Record IDs and item IDs.

Next steps

Now that you understand records, explore how they transform into structured data: