Query Elevation
Query Elevation gives you editorial control over your search results. It lets you manually pin specific results to the top for a given search query, or hide results that should not appear. Think of it as the ability to hand-pick what shows up first when someone searches for a particular term. For a step-by-step tutorial, see the Query Elevation guide in the knowledge base.
How Query Elevation Works
Normally, search results are ranked purely by relevance — the best-matching documents appear first. But sometimes, you know better than the algorithm. Maybe your most important product page is not ranking #1 for its own name, or maybe an outdated page keeps appearing and confusing users.
With Query Elevation, you can override the automatic ranking for specific queries:
What Is Query Elevation in Plain English?
Imagine you run a shoe store and someone searches for "returns." The algorithm might show a random blog post first, but you know that the most helpful result is your Returns Policy page. With Query Elevation, you simply pin the Returns Policy to the top whenever someone searches for "returns."
You can also hide results. If someone searches for "returns" and an archived, outdated returns policy from 2019 keeps showing up, you can exclude it so users only see the current, correct information.
Each rule applies to a specific query. Pinning the Returns Policy for "returns" does not affect any other search query. Every query can have its own set of pinned and excluded results.
How to Enable Query Elevation
Query Elevation is a feature you turn on per index. Follow these steps:
- Open Index Settings — go to your Opensolr dashboard and click on the index you want to configure.
- Find the Elevation Toggle — in the index settings panel, locate the Query Elevation option. It is a simple on/off toggle.
- Turn It On — flip the toggle to enable elevation. This activates the elevation feature for this index and shows the elevation controls on your search page.
If you turn off Query Elevation after setting up pinned and excluded results, all your elevation rules will be permanently deleted. You cannot undo this action. If you turn it back on, you will need to recreate your rules from scratch.
Managing Elevation Rules
Elevation rules are managed directly from the search page, not from the admin panel. This means you work with real search results in real time, which makes it easy to see exactly what you are pinning or excluding.
Pinning Results
Pinning a result forces it to appear at the very top of the results list whenever someone searches for that specific query. Here is how:
- Search for the query — go to your search page and type the query you want to create a rule for (e.g., "returns policy").
- Find the result to promote — scroll through the results until you find the page you want to appear first.
- Click the Pin icon — click the pin/arrow-up button on that result. It will immediately move to the top of the results.
- Verify — search for the same query again. The pinned result should now appear as #1, with a visual indicator showing it is pinned.
You can pin multiple results for the same query. If you pin 3 results, they will occupy positions #1, #2, and #3, in the order you pinned them. The remaining results follow in their natural ranking order.
Excluding Results
Excluding a result removes it from the search results for that specific query. The document still exists in your index, and it will still appear for other queries where it is relevant. It is only hidden for the query you create the exclusion rule on.
- Search for the query — type the query where the unwanted result appears.
- Find the result to hide — locate the document you want to remove from this query's results.
- Click the Exclude icon — click the X/hide button on that result. It will disappear from the results.
Per-Query Rules
Every elevation rule is tied to a specific search query. This means:
- Pinning a result for "pricing" does not affect the results for "plans" or "cost."
- Excluding a result for "refunds" does not hide it from "returns" or "money back."
- You can create completely different pin/exclude rules for every query.
- Queries are matched exactly — "pricing plans" and "pricing plan" (without the s) are treated as different queries.
If you toggle Query Elevation off in your index settings, every pin and exclusion rule you have created will be permanently deleted. This cannot be undone. Only disable elevation if you are sure you no longer need any of your rules.
Common Use Cases
Here are some real-world scenarios where Query Elevation shines:
Promoting Important Pages
Pin your most critical pages to the top. For example, pin your "Contact Us" page for queries like "contact," "help," "support," and "phone number." This ensures users always find the right page on the first try.
Hiding Outdated Content
Exclude old pages that are no longer accurate but have not been removed from your site yet. A 2019 pricing page or a deprecated API docs page should not confuse your users. Hide it from relevant queries until you can properly archive or delete it.
Seasonal Promotions
During a Black Friday sale, pin your sale landing page for queries like "deals," "discount," and "sale." When the promotion ends, simply remove the pin and the results go back to their natural order.
Fixing Relevance Gaps
Sometimes the search algorithm cannot figure out that a page is relevant for a particular query (especially if the page uses different terminology). Pin it manually to fill the gap until the content or search tuning can be improved.
How It Works Behind the Scenes
You do not need to understand the technical details to use Query Elevation, but here is a quick overview for the curious:
- Elevation rules are stored in a special configuration file within your Opensolr index.
- Each rule maps a query string to a list of document IDs to pin or exclude.
- When a search is performed, Opensolr checks if any elevation rules exist for that exact query. If they do, the pinned documents are moved to the top and excluded documents are filtered out — all before the results are returned to the user.
- Elevation happens after relevance scoring, so pinned results override the natural ranking but excluded results are simply removed.
Tips for Effective Elevation
Elevation is for specific, high-value queries. If you find yourself pinning results for dozens of queries, consider adjusting your Search Tuning settings instead — see the Search Tuning reference for all available controls. Good relevance tuning reduces the need for manual overrides.
Content changes over time. A page you pinned 6 months ago may no longer be the best result. Check your elevation rules regularly, especially after major content updates on your website.
Check your Analytics and Click Analytics & CTR data to find queries with high search volume but low click-through rates. Those are queries where users are not finding what they need, and elevation can help.
Elevation rules match queries exactly. If you pin a result for "returns," it will not apply to "return" (singular) or "return policy." Create separate rules for important variations.
Elevation works alongside Facet Filters. A pinned result will still appear at the top even when the user applies filters, as long as the pinned document passes those filter criteria.
Only exclude results that are genuinely harmful or misleading. If a result is simply "not ideal," improving the content or search tuning is usually a better long-term solution than hiding it.