Catalogs

Catalogs help you store and manage business data for marketing automation. This guide explains the types of catalogs available and how to use catalog data in campaigns and recommendations.

What are catalogs

A catalog is a lookup table with one primary key item_id that stores and manages business data for marketing automation. Ecommerce websites typically use catalogs to store products and related information, while publishing businesses use catalogs for articles and section details.

Catalog types

Bloomreach offers two types of catalogs:

General catalogs

A flexible lookup table for your project where item_id is the only required attribute as the primary key. Define all other attributes based on your business needs.

Product catalogs

Designed to store ecommerce product information with a predefined data structure that helps Bloomreach identify key product details for recommendations, inventory management, and stock level calculations.

Create and manage catalogs

The way you create and manage catalogs depends on your integration. Non-Data hub integrations use the legacy catalogs system.

Data hub integrations

Catalogs include the following:

Product catalogs

If your project has Data hub enabled, manage product data in a product item type in an item collection. When you connect the item type to your project as a destination, Data hub creates the catalog, and it appears in your catalogs listing.

Product catalogs with context data

Product and variant catalogs created from a product item type can store context data, such as store-specific values. In Data & Assets > Catalogs, you can't edit these catalogs' data or schema. To see a catalog's items for one context value, open the catalog and select the value in the Items tab. General catalogs from custom item types don't have context data.

Only the catalog view uses context data. Other features, such as scenarios and campaigns, use base items. To decide whether contexts fit your Marketing use case, contact your Customer Success Manager (CSM).

General catalogs

Create general catalogs directly within the Catalogs application. General catalogs with Data hub integrations offer features including mutable schemas and searchable settings that you can modify after creation.

You can also manage a general catalog through Data hub. Add a custom item type to an item collection and connect it to a Marketing destination. Data hub then creates the catalog in your project.

📘

Note

You can't convert an existing general catalog into a custom item type. To manage that data in Data hub, import it or send it through the API to a custom item type and connect the item type to a Marketing destination. Data hub creates a new catalog. The existing catalog stays as it is, so update any campaigns and catalog triggers that use it.

Non-Data hub integrations

Create and manage both product and general catalogs directly in the project using imports and the Catalog API. For non-Data hub integrations, you can’t change the catalog schema or searchable attributes after creation.

Key differences

Learn about the key differences in capabilities between the Data hub catalogs and legacy catalogs.

Recommended reserved product catalog attributes

The table below lists the recommended reserved product catalog attributes. These attributes have special meaning in Bloomreach and enable features such as recommendations and inventory management.

Reserved attribute names for Data hub item collections

You can use the following names as custom attributes. Since Marketing reserves these names, it adds a main. prefix to the attribute (for example, main.height). To reference the attribute in Marketing, use the prefixed name main.height instead of the original name height. This applies to product item types only. General catalogs from custom item types keep the attribute names set in Data hub, without the prefix.

active, brand, capacity, category_ids, category_path, category_paths, category_level_1 through category_level_20, color, color_group, condition, cost_per_unit, country, date_added, default_variant, depth, description, discount_percentage, discount_value, exclude_from_apps, flags, gender, height, high_confidence_terms, image, keywords, large_image, launch_date, lead_time, original_price, original_price_range, price, price_range, product_class, product_id, promotions, returned_products, reviews, size, stock_level, stores, supplier, swatch_image, thumb_image, title, url, variant_options, and width.

Many of these names have an equivalent Data hub system attribute. If you want to reference the attribute in Marketing without the main. prefix, set up the closest system attribute instead.

Data mapping

Non-Data hub integrations

• If your workspace isn’t Data hub enabled, ensure you map the catalog attributes during the initial catalog import in Data & Assets > Imports.
• Then, use Data & Assets > Data manager > Mapping to choose the required main catalog and map the reserved attributes.

See the legacy catalogs setup guide.

Data hub integrations

If your account has Data hub enabled, how you configure catalog attributes depends on the catalog type.

Product catalogs

If you manage your main product catalog through a product item type in a Data hub item collection:

Map product attributes in Data hub

• Open the product item type's Schema tab to configure how record fields map to item attributes, including system attributes. See Configure schema.
• Set item identifier. This corresponds to the item_id.

Choose main catalog and control searchable fields in Marketing destination

• After you create a Marketing destination for the product item type, Data hub keeps the product catalog in sync.
• Use Data & Assets > Data manager > Mapping to choose the required main catalog.
• To change which attributes can be used as filters in recommendations and campaigns, go to Data & Assets > Catalogs > [The product catalog] > Attributes and adjust the Searchable settings. Update these at any time without recreating the catalog. See the Data hub catalogs setup guide.

Required mappings for product-based use cases

When setting up use cases or recommendations that reference product data, confirm that the reserved attributes reference the Data hub system attribute listed below.

General catalogs (Data hub catalogs)

If you use general catalogs:

• Created directly in the Catalogs application: Go to Data & Assets > Catalogs and create a catalog with type General. Configure schema and searchable fields using the catalog’s Schema tab to define attributes and choose which ones are searchable. Change these settings at any time without recreating the catalog. See the Data hub catalogs setup guide.
• Created from a custom item type in Data hub: Configure the schema on the item type's Schema tab in Data hub. See Configure schema. To manage searchability settings, go to Data & Assets > Catalogs, open the catalog, and click the Attributes tab.

User access

Manage catalog permissions through roles in Access Management > Roles. Assign appropriate roles to perform catalog operations.

Full catalog management

With the Project Developer/Admin, Imports Admin, or Campaigns Editor/Admin roles, you have complete control over catalogs.

Permissions

• Create, delete, and modify catalogs along with their records, configuration, and schema.
• Create, modify, run, and delete catalog imports.
• View all catalog components, including items, records, schema, jobs, and imports.

These roles don't let you edit the data or schema of catalogs that you manage through a Data hub item type. Manage those in Data hub.

View-only access

With the Campaigns Viewer, Weblayers Viewer/Editor/Publisher, Email Campaigns Viewer/Editor/Publisher, SMS Campaigns Viewer/Editor/Publisher, Scenarios Viewer/Editor/Publisher, Customers Viewer/Editor/Consent Editor, Managed Endpoints Viewer/Editor/Publisher, or Recommendation Viewer/Editor roles, you can view all catalogs and their components.

Permissions

View catalog items, item attributes, records, record fields, configuration, schema, jobs, and imports.

Limitations

• Number of catalogs per project: The limit is 50 catalogs per project, regardless of catalog version. Data hub catalogs enforce this limit. Legacy catalogs don't enforce this limit.
• Searchable attributes per catalog: 40 maximum.
• Items per project: 6,000,000 maximum for both legacy and Data hub catalogs.
• Items per Data hub catalog: 1,000,000 maximum.
• Catalog item value length: 28,672 bytes maximum (legacy catalogs). If you exceed this, shorten the value or split the property into two shorter ones.
• Attributes per catalog or item: 260 maximum. This applies to both legacy and Data hub catalogs.

To request an increase to any of these limits, contact your Customer Success Manager (CSM).

Downloading and exporting catalogs isn't possible.

📘

Note

Catalogs with no usage in the previous 90 days (no access from the application and no import) are automatically deleted. All respective scenarios remain editable.

Personally identifiable information

Catalogs should never contain personally identifiable information (PII) such as emails or phone numbers.