Records
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.
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 typically represents a product or product variant, 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 product information 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.
Record states
Records can exist in different states depending on your configuration:
- Staging: Records exist but haven't been processed into items yet. This state allows you to review and validate data before transformation.
- Published: Records automatically create or update items through schema transformation. Most implementations use auto-publish mode, where record ingestion immediately triggers item creation.
For most use cases, auto-publish mode provides the simplest workflow. Advanced scenarios may require staging records for review before publishing.
Format, send, and update records
Review the guides on sending and updating records through API integration.
View and explore records
Review the detailed setup guide to view, search, and manage records in your item collection.
FAQs
What's the difference between records and products?
Records are your raw source data before any transformation occurs. Products (items) are built from records based on your schema configuration. Records contain flexible fields that don't yet have meaning to Bloomreach, while products are structured data with validated attributes that Bloomreach can use.
Can records have different fields across products?
Yes. Records are schema-less, meaning each product 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.
Next steps
Now that you understand records, explore how they transform into structured data:
Updated 15 days ago