Configuration guide

This guide walks through configuring search boosts in Brightspot CMS.

Accessing boost settings

Global configuration (default for all sites)

1. From the left navigation, under Admin, click Plugins.
2. Select CMS Search Boost and click New Plugin.
3. Configure the Default Configuration section with boost rules that apply to all sites.

Site-specific configuration

1. From the left navigation, under Admin, click Sites & Settings.
2. Select your site.
3. Go to the Plugins tab.
4. Under Configs click Add and create a new CMS Search Boost Configuration.
5. Configure the Boost Configuration section with boost rules for this specific site.
6. Save the new CMS Search Boost Configuration, apply it to the Configs field, and save the site.

Configuration hierarchy

The plugin uses a fallback system:

1. Site-specific configuration — If a site has a CMS Search Boost Configuration in its Plugins tab, those rules are used.
2. Plugin default configuration — Sites without their own configuration inherit from the CMS Search Boost plugin's Default Configuration.
3. No configuration — If neither exists, CMS search uses default relevance ranking.

This allows you to set sensible defaults at the plugin level while customizing specific sites as needed.

Creating boost rules

Step 1: Select configuration type

In the Boost Configuration dropdown, select Custom. This reveals the boost rules list.

Step 2: Add a boost

Click Add to create a new boost rule. You'll see a dropdown with available boost types:

• Exact Match — Field value equals the entire search query
• Partial Match — Field contains any of the query terms
• Starts With Match — Field value begins with the query
• Content Type — Prioritize a specific content type
• Newest — Prioritize recent content by date
• Oldest — Prioritize older content by date
• Semantic Match — Match phonetically similar terms

Step 3: Configure the boost

Each boost type has specific configuration options:

For index-based boosts (Exact Match, Partial Match, Starts With, Newest, Oldest)

1. Types (optional) — Select one or more content types. On text matching boosts this restricts which content the boost lifts; on all index-based boosts it filters the Index dropdown to that type's fields plus global fields. Leave empty to see global indexed fields and boost content of any type. On Newest/Oldest boosts the selection only filters the field choices — see the boost types reference.
2. Index — Select the indexed field to match against. The dropdown shows fields appropriate for the boost type (text fields for text matching, date fields for date boosts).
3. Current Weight — Set the boost strength (0-100).

For every boost (optional targeting)

1. Search Surfaces — Limit the boost to the main CMS search, selector/typeahead searches, or both. Leave empty to apply everywhere.
2. Applied To Searches — Gate the boost by the types a search targets: All Searches, Only Searches For Specific Types, or All Searches Except For Specific Types. See the boost types reference for the exact semantics.

For content type boost

1. Content Type — Select which content type to prioritize.
2. Current Weight — Set the boost strength (0-100).

For semantic match boost

1. Content Type — Select the content type to boost when terms match.
2. Keywords — Add terms that should trigger this boost when phonetically matched.
3. Current Weight — Set the boost strength (0-100).

Step 4: Set the weight

The Current Weight field controls how strongly this boost affects results:

Weight Range	Effect
0-20	Subtle influence
20-50	Noticeable prioritization
50-80	Strong prioritization
80-100	Dominant (use sparingly)

Step 5: Save

Click Save to apply your configuration. Changes take effect immediately for all CMS searches on the configured site.

Managing multiple boosts

You can add multiple boost rules to a configuration. They are applied in order, with each boost contributing to the final relevance score.

Combining boosts effectively

A well-balanced configuration typically includes:

1. One or two text matching boosts — To prioritize results that match the query
2. A content type boost (optional) — To surface preferred content types
3. A date boost (optional) — To factor in recency

warning

Avoid adding too many boosts or using very high weights on multiple boosts. This can make results unpredictable.

Reordering and removing boosts

• Drag boost entries to reorder them
• Click the remove button (X) to delete a boost rule

Common configurations

Prioritize title matches

For sites where exact title matches should appear first:

Boost Type	Field	Weight
Exact Match	cms.content.searchableText	75
Partial Match	cms.content.searchableText	35

News site (fresh content first)

For sites where recent content is most relevant:

Boost Type	Field/Type	Weight
Newest	cms.content.publishDate	60
Content Type	Article	40
Partial Match	cms.content.searchableText	30

Product catalog (exact SKU matching)

For e-commerce sites where users search by product codes:

Boost Type	Field	Weight
Exact Match	sku	90
Starts With Match	productName	50
Partial Match	cms.content.searchableText	25

Troubleshooting

Boosts not taking effect

1. Check configuration location — Ensure the site has a CMS Search Boost Configuration in its Plugins tab, or that the CMS Search Boost plugin has a Default Configuration set.
2. Verify field selection — Confirm the selected index field exists and contains data.
3. Check weight values — Weights of 0 have no effect.

Results not as expected

1. Review weight balance — If one boost has weight 90 and others have 20, the high-weight boost will dominate.
2. Consider boost order — Multiple boosts of similar weights interact; experiment with different orderings.
3. Test with specific queries — Some boosts only apply when specific conditions are met (e.g., exact match requires the full query to match).

Field not appearing in dropdown

1. Check the Type filter — The field might be type-specific; try selecting the appropriate content type.
2. Verify the field is indexed — Only indexed fields appear in the dropdown.
3. Check field type compatibility — Date boosts only show date fields; text boosts only show text fields.

Index field removed from the codebase

If the field or content type backing a configured Index is later removed from the codebase, Brightspot CMS skips that boost at search time instead of failing the search.

The next time the configuration loads or saves, Brightspot CMS also removes the stale boost automatically and displays a message listing which boosts were removed. The removal becomes permanent the next time the configuration is saved.

Install the cms-search-boost-health-check module to receive an alert when this happens instead of discovering it by opening the configuration. See Health check.