💡 Prerequisites

Knowledge Prerequisites
We recommend reading the following guides before starting:

Catalogs application: This guide introduces you to the Catalogs application.

Access Prerequisites
Catalogs application should always be accessed via tools.bloomreach.com and not via tools-staging.bloomreach.com. The only exception to this is if the account is not accessible via tools.bloomreach.com and is accessible via tools-staging.bloomreach.com.

Both Production and Staging versions of Catalogs are available on tools.bloomreach.com. Accessing Catalogs application via tools-staging.bloomreach.com for a non-staging-only account may have edge cases where functionality may not work as it isn't a supported use case.

EU/UK-based Merchants: EU/UK-based merchants should access via tools.bloomreach.co.uk and not via tools-staging.bloomreach.co.uk. The only exception to this is if the account is not accessible via tools.bloomreach.co.uk and is accessible via tools-staging.bloomreach.co.uk.

Both Production and Staging versions of Catalogs are available on tools.bloomreach.co.uk. Accessing Catalogs application via tools-staging.bloomreach.co.uk for a non-staging-only account may have edge cases where functionality may not work as it isn't a supported use case.

📔 Glossary

Feed: A file containing the current set of all records in the catalog. You will have a separate product and content feed if you have both products and content on your site.
Catalog: Catalog contains a set of product or content data for a single language. Catalog contains:
- a unique name identifier like catalog_name or domain_key
- a configuration
- a set and type of raw data (product or content records)
- a set of transformed data (documents)
- a collection name (describes how a catalog relates to another catalog)
A catalog can power a single site or multiple sites.
Record: A record is a piece of raw and unmodified information that you send to Bloomreach. This raw information can include details like the product ID, attributes, variants, and views.
Document: Documents comprise product records that have been transformed according to catalog configurations and stored in Bloomreach.

Understanding the Feed

Navigation path: Catalogs application can be viewed in the Discovery dashboard under the path Setup -> Catalogs.

Catalog Listing

Catalog Name: This is the unique identifier for the Catalog and is used nearly throughout all API calls and pixel events. In certain Search APIs, this is also the value of the domain_key parameter
Catalog Language
Specification whether it is a Product or Content Catalog
Catalog Versions: The Production and Staging environment versions available for that Catalog

Note: Catalogs are an account-level resource, so when you select a specific site in the dashboard dropdown, the parent account of the site selected will be used.

Catalog Versions High-Level Details

Each Catalog version contains high-level details such as:

1. The last time the Catalog's index was updated

This indicator helps you know if your Catalog is up to date.

2. Number of Documents in that Catalog

In the standard scenario, this is the total count of unique items and item variations in a Catalog as sent in the feed and currently indexed

Inclusive of variants
Inclusive of availability
Inclusive of invalid items like invalid price, missing title, or URL

This count represents documents in Production. Note that in the Staging environment, the documents cannot exceed 1.5 times the licensed amount used in Production.

In a multi-view override scenario, the number of documents represent the uniqueness of a product grouped into views. Suppose the product price varies across views. The price in views 1, 2, 3 is $10.99, and the price in views 4, 5, 6, is $11.99. In this case, we would generate 2 documents, one for each unique grouping of views based on the product data.

3. Byte size of data in the Catalog

This shows the cumulative amount of customer data across all the documents in the Catalog's index. This is nearly equivalent to taking each document, turning it into a JSON object, and summing the byte size of all the objects.

Note: If you’d like to add an additional Catalog to the account, Bloomreach Support can help set it up for you. Please provide the language and name, and specify if it's a Product or Content Catalog.

Catalog Feed (Feed Tab)

On clicking a Catalog, you’ll be taken to the Feed tab. Under the Feed tab, you can search for raw feed records, view all feed data, and see the overall record counts. A catalog's feed contains the current state of the data records that have been sent in or modified via our Feed API from the source system powering this catalog.

When you're investigating data-related issues, this is your go-to spot. The Feed section allows you to:

View the current state of the feed
Understand what data Bloomreach has received from your source system
Confirm if we have all the attributes you expect for your data.

If you don't see data in the Catalog's feed and the index is up to date, then you won’t see this data in our search results or other API responses.

Records List

The Records list view will show all products and items. Records are specific to the feed and shouldn't be confused with documents. Feed records are turned into documents based on the catalog configuration at index update time during indexing.

The records shown remain in their raw form without any modification from the source system.

When viewing, you’ll see up-to-date records received through any full or delta feed jobs that have been successfully processed. There may be a slight delay between success and data showing in the UI, but it is minimal.

The feed records shown here are only available and reflected in search results and API responses once the catalog's index is updated. Typically, the source system will update the index by performing our Update Index API call.

Understanding Product Details in the Records

Every record will show the following details for a specific product or item:

Product or item identifier (Product ID)

Product ID is not an attribute of the record. In the feed, it can be found as part of the path property, eg. if in the path property "/products/123", the product ID is 123. Bloomreach doesn't generate an ID for a record, it is always specified in the feed by the customer.

Attributes

Each record lists the attributes related to that product or item. Initially, you’ll see a set of 4 attributes in each product record. To view the complete list of attributes, click on the Show all attributes dropdown.

This will display a list of all the product or item level attributes with their values. Values that begin and end in double quotes are string values; otherwise, they are the literal JSON value supplied in the feed. Values of the data can be easily copied to use elsewhere.

Variants

The record also lists the variants of the specific product/item. You can see a variants dropdown under each record. Click on the dropdown to view each variant's attributes and identifiers. On clicking the dropdown, you get a grid view of all unique attributes in that product or item like Variant ID, Color, Color Family, Color Group, Default SKU, and Integer SKUID.

You can also click any product variant and view all of its attributes.

Search for Products/Product Variant using Product ID/ Variant ID

You can use the search bar to search the feed data for a specific product ID. The same search feature is available for finding a specific variant in the list of variants. Please note that the Product/Variant ID used here must be an exact match.

Configuring Attributes (Attributes tab)

This section allows you to

View the list of all configurations applied to custom attributes: The list of custom attribute configurations helps you understand how custom attributes function and behave in our Search and Suggest APIs.
Change the custom attributes configurations: Based on your understanding of the current custom attributes configurations, you can choose a different setting as per your needs.

By modifying the properties, you can control how the attribute behaves in our APIs. Suppose you have a custom attribute in your data called "display_value1" and you would like that attribute to show up in our API responses. You would first need to make a custom attribute configuration for "display_value1" and tell Bloomreach that the attribute should be "displayable." After that change is saved and the index is updated, you can query our APIs and request that "display_value1" is returned in the response. When the index is updated, the feed data will be applied to this list of custom attribute configurations, and documents will be generated accordingly.

Custom attributes may be sent in the feed before configuration and will be visible in the Feed tab; however, they will not be usable until they have been configured.

There are certain enterprise accounts where default configured behavior may be defined differently for attributes that do not have an explicit custom configuration. It's important to know your default account setting to understand how all your custom attributes will be treated during indexing.

You can specify the following for each custom attribute configuration:

Configuration	Description	Available Options
Level	Specify the level at which this attribute appears in your Product Data - either it's in the basic Product attributes (Product), or it's reported in the variants / SKUs section and is a (Variant) attribute instead. Please note that this setting does not change where a value is stored.	Actions associated with dropdown options: Product: Specify that the attribute appears at the product level in the associated product documents Variant: Specify that the attribute appears at the variant level in the associated variant documents
Facetable	Specify whether the attribute and its value may be used for faceting, filtering, sorting, and merchandising rules. This also controls whether Bloomreach should treat the attribute as part of our dynamic facet feature. If an attribute is specified as a dynamic facet attribute, Bloomreach will determine if the attribute should be returned as a facet in the API response algorithmically. Note: We do not support the pipe character "\|" in facet name.	Actions associated with dropdown options: Dynamic: Corresponds to Search features ON Dynamic facet ON Manual: Corresponds to Search features ON Dynamic facet OFF Manual implies that you can use this attribute in facet management and manually work with it. Off: Corresponds to Search features OFF Dynamic facet OFF
Displayable	Specify whether the attribute may be returned in API responses so that it can be displayed in your frontend. When returning a result set, Product ID(pid) is the only attribute returned in each document by default. You can explicitly request additional parameters in the Search API call using the`fl` parameter. However, the additional attribute must be configured as displayable first.	Checking this returns the attribute in the API response if used in the fl parameter. Unchecking this prevents returning the attribute in the API response.
Searchable	Specify whether the attribute's value will be used when matching products or items during a keyword search. It affects only recall, not ranking.	Checking this allows the attribute to be used as part of the searchable keyword text. Checking for a large-sized or a multi-value attribute can decrease the recall set relevance of a keyword search. Unchecking this blocks the attribute from being used as part of searchable keyword text.
Multi-valued	Specify whether the attribute's value should be returned and treated as an array or a single value. Make sure to align this with the feed format in nearly all circumstances.	Checking the box returns this attribute as a multi-valued array in the associated documents. If a record is scalar and this box is checked, the value will be an array of the single value. Unchecking the box returns the attribute as a scalar. If a record is an array and this box is unchecked, the first value of the record array will be the scalar value of the attribute.
Data type	Specify whether the attribute's value should be returned and treated as text or number. This should align with the feed format in nearly all circumstances.	Actions associated with dropdown options: Text: Choose this for a text-type attribute Number: Choose this for a number-type attribute

Setting New Attribute Configurations

Click on Add an Attribute Configuration to configure a new attribute.
This displays a new attribute field. Here, you can specify the attribute name and select the desired configurations.

Catalog Configuration Changes

This visual shows the process of making changes to the existing attribute configurations of the attribute sample_field_name_11. The process of changing existing attribute settings is simple. You can rename, select/deselect existing configurations or choose the options provided in the dropdown lists to get the desired changes. To revert the changes, click the Revert symbol.

After configuring attributes, proceed with this guide to push the changes to production.

Points to remember

You can hover over each configuration property to reveal a quick tooltip on what it does.
Duplicate attribute names are not allowed.
Bloomreach Reserved Attribute names cannot be used as attribute names.
To edit or promote configuration changes, you need a role with the appropriate catalog permissions to modify catalogs.