How to Use NeuronSearchLab Rules to Boost, Pin, Filter, and Diversify Results

Recommendation systems should learn from behaviour, but most production teams also need direct operational control.

A merchandiser may need to feature a seasonal collection. A marketplace operator may need to hide unavailable supply. A media team may want to avoid ten articles from the same topic in a single rail. A product team may want to test a new ranking policy for one segment without changing the entire recommendation stack.

That is the role of rules in NeuronSearchLab. Rules let you shape served results around business constraints, editorial judgment, eligibility requirements, and diversity goals while still using the platform’s retrieval, ranking, analytics, contexts, segments, and experiments.

This guide is written for a technical operator or developer who wants to configure rules today. It covers prerequisites, setup steps, verification, troubleshooting, and where to go next in the NeuronSearchLab documentation.

If you are new to the platform, start with the NeuronSearchLab docs, the getting started guide, and the product overview on features. If you do not have an account yet, you can sign up at console.neuronsearchlab.com/signup.

Prerequisites: what you need before configuring rules

Before rules can produce useful results, the recommendation runtime needs enough structure to apply them safely. At a minimum, confirm that the following are in place.

1. A NeuronSearchLab workspace and console access
   You need access to the NeuronSearchLab admin console. This is the operator-facing control plane where teams manage contexts, ranking pipelines, rules, segments, experiments, integrations, credentials, analytics, and explainability views.

   If you do not have credentials yet, create an account at console.neuronsearchlab.com/signup. After signing in, use the console security or SDK credentials area to create or manage the credentials your application will use.

2. A connected catalogue
   Rules are most useful when your catalogue contains the fields you want to act on, such as category, brand, availability, price band, region, content type, freshness, or editorial tags.

   If your catalogue is not connected yet, follow How to connect catalog and events.

3. Event tracking
   Rules can be applied even in early deployments, but recommendation quality improves when the system has behavioural signals. Make sure your application is sending relevant events, such as views, clicks, add-to-cart actions, purchases, reads, saves, or other domain-specific interactions.

4. At least one recommendation context
   A context describes where and why recommendations are being served, for example a home page module, product detail page rail, search-adjacent discovery surface, article recommendation block, or post-purchase experience.

   If you are setting up a new use case, follow How to launch a new context.

5. An application integration path
   Your backend should request recommendations through the hosted runtime using the Core API or official SDKs. For implementation details, see the SDK introduction and How to serve recommendations. If you operate recommendations through an AI or agent workflow, review the MCP SDK docs.

Rules are configured in the NeuronSearchLab control plane, while your application continues to request recommendations from the runtime. That separation matters: developers do not need to redeploy application code every time an operator adjusts a boost, pin, filter, or diversification policy.

Decide what each rule should do

Before creating rules, define the operational intent. The four common rule patterns are boost, pin, filter, and diversify. They solve different problems and should not be used interchangeably.

| Rule pattern | Use it when | Example intent | Main risk | | --- | --- | --- | --- | | Boost | Some eligible items should receive more exposure | Promote new arrivals, high-margin products, local inventory, or preferred content | Over-boosting can reduce relevance | | Pin | A specific item or set of items must appear in a specific position or area | Put a campaign item in the first slot of a module | Excessive pinning can make the rail feel static | | Filter | Some items should not be eligible | Remove unavailable items, unsafe content, wrong-region items, or already-consumed content | Over-filtering can shrink candidate pools | | Diversify | Results should not be too concentrated | Avoid showing only one brand, category, author, supplier, or topic | Too much diversification can weaken personal relevance |

A useful rule design starts with a sentence:

• “For the holiday campaign context, boost items tagged holiday for logged-in users in the gift-buyer segment.”
• “For product detail recommendations, filter out the current product and unavailable variants.”
• “For the home page news rail, diversify by topic so one theme does not dominate.”
• “For a sponsored editorial campaign, pin the lead item in the first slot for a defined time window.”

The important part is to preserve the distinction between eligibility, ranking influence, and placement.

Filters decide what can appear. Boosts influence how eligible items compete. Pins reserve specific placements. Diversification reshapes the final set so the user sees a healthier mix.

When these concerns are separated, the system is easier to debug. If an item did not appear, you can ask: was it filtered out, not retrieved, out-ranked, displaced by a pin, or reduced by a diversity constraint?

Setup steps: configure rules in NeuronSearchLab

The exact configuration you choose depends on your catalogue fields, recommendation context, and business goal. The workflow below is the safest way to implement rules without losing observability.

1. Choose the context you want to control

Start in the NeuronSearchLab console and select the recommendation context where the rule should apply. Keep the scope narrow at first.

Good first contexts include:

• A single home page recommendation rail
• A product detail page “related items” module
• A category discovery surface
• A logged-in user recommendation block
• A newsletter or content recommendation context

Avoid starting with a global rule that affects every surface. Rules are easier to verify when they are attached to a specific context with known traffic and clear expected behaviour.

If you need a new serving surface, create the context first using How to launch a new context.

2. Confirm the catalogue fields required by the rule

Check that your items contain the attributes your rule will use.

For example:

• Boosts may depend on tags, collection names, freshness, margin bands, or campaign labels.
• Pins require stable item identifiers.
• Filters often depend on availability, region, language, safety status, inventory, or lifecycle state.
• Diversification usually depends on a grouping field, such as category, brand, author, supplier, topic, or content type.

If the required fields are missing or inconsistent, fix the catalogue feed before configuring the rule. Rules are only as reliable as the item metadata they operate on.

For catalogue setup, use How to connect catalog and events.

3. Add eligibility filters first

Filters should normally be configured before boosts and pins, because they define the valid candidate set.

Common filters include:

• Exclude unavailable or inactive items
• Exclude items that cannot ship to the user’s region
• Exclude items the user has already purchased or consumed
• Exclude the item currently being viewed
• Exclude content that does not match policy, language, or age requirements

Keep filters explicit and auditable. If a filter represents a hard business rule, such as “do not show out-of-stock items,” it should be treated differently from a soft preference, such as “prefer premium inventory.”

A practical test: if showing the item would be wrong, use a filter. If showing the item is acceptable but less preferred, use ranking or boost logic instead.

4. Add boosts for controlled promotion

After eligibility is clear, add boosts for items that should receive more exposure while still competing with other relevant candidates.

Boosts are useful for:

• Seasonal campaigns
• New launches
• Local inventory
• Fresh content
• Strategic categories
• Items with strong availability
• Editorially selected collections

Use boosts carefully. A boost should change the ranking pressure, not replace relevance entirely. If every campaign receives a large boost, the recommender becomes difficult to reason about and users may see results that feel less personal.

A good operating pattern is to start with a limited boost, apply it to one context or segment, and compare performance before widening scope.

5. Add pins only when placement is intentional

Pinning is stronger than boosting. A pinned item is not simply favoured, it is placed intentionally.

Use pins when the position itself matters:

• A launch item must appear first in a campaign rail.
• A publisher wants the lead story fixed in the first slot.
• A marketplace wants a sponsored or contractual item placed in a defined position.
• A curated experience needs a specific hero item.

Because pins can override the natural behaviour of a recommender, keep them limited, time-bound, and visible to operators. If you pin too many slots, there may be little room left for personalised ranking.

A useful internal convention is to document why each pin exists, who requested it, when it should end, and which context or segment it affects.

6. Add diversification to protect result quality

Diversification helps prevent repetitive result sets. It is especially useful when the highest-scoring candidates are clustered around one attribute.

Examples:

• Do not show ten products from the same brand in one carousel.
• Mix topics in a news rail.
• Avoid too many items from the same seller.
• Spread recommendations across categories.
• Balance content types in a media feed.

Diversification should reflect the user experience you want. For some contexts, concentration is acceptable. A “more like this” rail may reasonably show similar items. A home page discovery rail usually benefits from broader coverage.

Configure diversification after filters, boosts, and pins, then verify that it improves the final set without making the recommendations feel random.

7. Use segments and experiments when rollout risk is high

If a rule may affect conversion, engagement, revenue, or user trust, avoid an immediate global rollout.

NeuronSearchLab supports segments, experiments, A/B testing, analytics, and explainability views. Use those capabilities to test rule changes with a defined audience before expanding them.

Examples:

• Test a boost for new arrivals with 10 percent of traffic.
• Apply a diversity rule only to returning users.
• Compare a pinned campaign rail against a fully ranked rail.
• Evaluate whether stricter availability filters reduce empty or poor-quality results.

For serving integration details, see How to serve recommendations. For broader platform capabilities, see features and pricing.

Verify the rule before and after launch

Verification should happen at three levels: configuration, serving output, and business impact.

Configuration checks

Before sending traffic, confirm:

• The rule is attached to the intended context.
• The rule uses catalogue fields that actually exist.
• The rule scope is correct, including segment, context, and any rollout constraints.
• Filters do not remove too many candidates.
• Pins reference valid item identifiers.
• Boosts are limited to the intended item set.
• Diversification uses the correct grouping field.

If the rule depends on fresh catalogue data, confirm the relevant items have been ingested before testing.

Serving checks

Use your application integration, SDK-based test harness, or operational workflow to request recommendations for known users or test cases.

Check the result set for expected behaviour:

• Filtered items are absent.
• Boosted items appear more often or higher, where relevant.
• Pinned items appear in the intended placement.
• Diversified results are less concentrated by the selected field.
• The response still contains enough items for the UI.

Developers should test through the same runtime path the application uses, not through admin-only routes. The official SDKs talk to the hosted runtime. Start from the SDK introduction if you are wiring this into your backend.

If you use AI-assisted operations, the MCP documentation explains the MCP integration path.

Analytics and explainability checks

After launch, use NeuronSearchLab analytics and explainability views to review how the rule is affecting recommendation activity.

Look for:

• Reduced empty result rates
• Stable or improved engagement
• No unexpected concentration in one item group
• No sudden drop in relevant catalogue coverage
• Campaign exposure that matches the intended scope
• Segment-level differences in performance

Do not judge a rule only by whether it “worked” mechanically. A pin can appear in the right place and still hurt the experience. A filter can remove the right items but shrink the candidate set too aggressively. Verification should include both correctness and outcome quality.

Troubleshooting common rule problems

“My boosted items are not appearing”

Possible causes:

• The items are filtered out before ranking.
• The items are not in the relevant catalogue feed.
• The context is using a candidate pool where those items are not retrieved.
• The boost is scoped to a different segment or context.
• The items are eligible but still not competitive enough.

Start by confirming eligibility and scope. Then test with a narrow context and known item identifiers.

“My pinned item is missing”

Check that:

• The item identifier is correct.
• The item is active and available.
• The item has been ingested into the catalogue.
• The pin is attached to the context being requested.
• A hard filter is not excluding it.
• The UI has enough slots to display the pinned position.

Pins are placement controls, but they still depend on valid item data and correct context configuration.

“The filter removed too many results”

This usually means the rule is too broad or the catalogue field is sparse.

Review:

• Whether the field is populated consistently.
• Whether the filter should be limited to a segment or context.
• Whether a soft ranking preference would be better than a hard exclusion.
• Whether fallback inventory exists for the context.

Hard filters are powerful. Use them for true eligibility constraints, not general preferences.

“Diversification made results less relevant”

Diversification can reduce repetition, but if configured too aggressively it may push strong candidates down too far.

Try:

• Applying it only to broad discovery contexts.
• Using a grouping field that matches user perception.
• Reducing the strength or scope of the diversity policy.
• Testing it with an experiment before full rollout.

A user may appreciate category diversity on a home page but expect similarity on a product detail page.

“The rule works in one place but not another”

Rules are usually scoped by context, segment, pipeline configuration, or experiment setup. Confirm that the application is requesting the expected context and that the rule is attached to that context.

If you recently created a new context, revisit How to launch a new context and How to serve recommendations.

FAQ

Should I use a boost or a pin?

Use a boost when you want eligible items to receive more ranking pressure while still competing with other candidates. Use a pin when a specific item must appear in a specific placement. Pins are stronger and should be used more sparingly.

Should business rules replace learned ranking?

Usually, no. Rules are best used to express constraints, campaign needs, editorial control, and diversity requirements around the learned system. The strongest setup combines machine-learned retrieval and ranking with clear operator controls.

Can I test a rule before rolling it out broadly?

Yes. NeuronSearchLab supports contexts, segments, experiments, A/B testing, analytics, and explainability workflows. For meaningful changes, test rules with a defined audience or context before applying them broadly.

What should I do if I do not have API credentials yet?

Sign up at console.neuronsearchlab.com/signup, then use the console security or SDK credentials area to create credentials for your application. Start with Getting Started, the docs, and the SDK introduction.

Where should I go next?

If you are implementing recommendations for the first time, read How to connect catalog and events, then How to launch a new context, and finally How to serve recommendations. If you want to understand the broader platform, review features and pricing.