Search Refinement Buckets

If you create a search refinement without buckets, then every separate value for refinement appears. Without buckets, the number of separate values can easily become overwhelming for a user.

For example, customers typically search for basic colors, such as red, green, or blue. The merchant can define buckets that group colors.

Bucket Values
Red Crimson, Garnet, Ruby, Maroon, Cherry, Rouge
Blue Sky Blue, Navy, Cerulean, Cobalt

Bucketing Types

For a specific refinement, the options available for the customer to query on are referred to as buckets. For example, for a color refinement, you might create red, blue, and brown buckets. You can assign value buckets for each refinement directly or have the buckets created automatically based on value name, value count, or category. If you assign buckets, you can create a group of values that are all included in the bucket. The example below includes search refinements with and without buckets.

Bucket by Value:

You can create custom bucket names or icons and manually assign specific values to them. Examples of this type of bucket include color or style indicators (retro, modern, etc). For example, the same color (#CC0033) can appear in the red-orange bucket in the Men's category, the pink-red bucket in Women's category, and the Red bucket in the Unisex category.

The buckets shown to the customer are those of the deepest common category for the search result set. To determine the deepest common category, use the Storefront Toolkit Search Information tool. To access this information, click the Search information icon in your application header.

Note: You must rebuild the search index if you move refinement definitions from one category to another. Such changes are not covered by incremental indexing and therefore require a full index rebuild. If you do not, the search refinement definitions might not work as expected.

Although different categories can have different buckets, the same category can't have different buckets for the same attribute in subcategories. For example, you can't create an Age refinement that gets more specific with every category level.

Setting Up Buckets for Value Refinements:

When setting up buckets, please be aware that all refinements, regardless of their location, are used to improve search results. More specifically, search finds any values contained in refinements and maps each value to its bucket's label, therefore, it is important to set up buckets with labels describing a concept more specific than its values.

For example, it makes sense to include "tan" and "beige" in a "brown" bucket, as they are related and it is a kind-of relationship (tan is a kind-of brown).

The same would apply to "striped" as a kind of "multicolor", or to "jeans" as a kind of "trousers". If this pattern is followed, there should never exist a situation in which two buckets in different categories have a conflicting set of values.

Expanding on that logic, you may set up the value "black striped" to be included in a "black" bucket, a "multi-color" bucket, and a "striped" bucket, as all of these are generalizations of this value.

Avoid setting up the same term in a contradictory manner across different categories.

For example, in a "Denim" category, do not violate the above by setting up a "Jeans" bucket that contains the term "trousers" even though you may be certain that all trousers in this category are jeans trousers.

Bucket by Value Count:

A value count bucket lets you assign different values to specific buckets. Examples of this type of bucket include sizes, weights, and other group-able options. For example, you might want a bucket for small sizes that includes 1X, size 2, and size 2 petite. You might also want to reduce the number of refinements to those that are the most commonly used. For example, you might want to create buckets for laptops that are: under 1 kg, 1 kg - 3 kg, and over 4kg.

Bucket by Price Threshold:

You can choose to create price buckets that include a range of prices. If you use this option, you don't have to manually assign values to the buckets. This is very efficient when creating search refinements for prices.

Bucket by Period

You can choose to create period buckets for ranges of dates related to the product. For example, how new the product is, when it's available for sale, or other seasonal information. . If you use this option, you don't have to manually assign values to the buckets. This is very efficient when creating search refinements by date.

Bucket for All Values

Although customers can de-select search refinement values, you might want to create a bucket for "All" values so that it's clear to customers that they can broaden as well as refine their search.

Allowed Characters for Bucket Values

You can include commas or backslashes in bucket definitions by escaping them with a backslash ('\').

For example, to create a bucket value as follows:

one each of pure white, blueberry, brown

Enter the following:

one each of pure white\, blueberry\, brown

in order for the text to be processed as single refinement value. Otherwise, each color is included as a separate bucketing value.

Unbucketed Value Display

If you have some values that are not bucketed, you decide whether to include all unbucketed values in a single bucket, as single values, or not show them at all. For example, for a color refinement, you might have some items that are not a single color, but multi-color. You can have a multi-color bucket that contains all unbucketed values, you can have each unbucketed value, such as blue/brown or red/black appear independently, or you can hide all multi-color items, assuming that a customer using the color refinement is looking for an item of a specific color.

Relaxing Refinements

You can let users remove a search refinement in several ways. For buckets with values by assignment, the easiest way to do this is to create an "All" bucket that the user can select. For buckets that are assigned by name or value count, you can create links that let the user relax the refinement. You can use the ProductSearchModel or ContentSearchModel canRelax() methods to determine whether the search can be expanded. If the search can be relaxed, there are several methods you can use to relax the search. There are different methods for relaxing a category refinement, folder refinement, or an attribute refinement.

For an example of relaxing a search, see the productsearchrefinebar.isml templates in the SiteGenesis application (in the SiteGenesis Storefront Core cartridge in search\components.

Variation Products in Refinements

If you refine on an attribute value, any variation products with that value are included in the search refinement, if the attribute is a slicing attribute for the product. For example, if you have a T-shirt in several colors and are using color as a slicing attribute, so that the T-shirt appears in the storefront in several colors, if you refined by 'red', then the red T-shirt variation appears in the search results.

Product Sets in Refinements

Product sets are included in refinements if any items in the set match the refinement. For example, if a product set for an outfit includes a red T-shirt, then the outfit is included in the search results.

Testing Tips

If you use bucketing and the value list changes, or you have updated the catalog, remember to refresh the index, and view the buckets to make sure that all changes have been made correctly. Repeat this after every catalog update.


If you want to use localized bucket labels, supply a localized label for the bucket values for attribute refinements.

If the attribute used for the refinement is defined as localizable, the values provided in the bucket value list are as well. For localized refinement attributes, one value list must be supported per active locale (for example, "Red" = "Dark Red" and "Rot" = "Dunkelrot"). If the attribute used for refinement is non-localized, only one bucket value list is necessary.

Price Refinements

Bucket definitions for price refinements capture the following information:

The localized bucket label can be used to render the price range independently of the actual numerical bounds (for example, 'Inexpensive' as the label for price bucket <= $10).

X Privacy Update: We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used. By continuing to use this site you are giving us your consent to do this. Privacy Policy.