chore(search): Tune Algolia ranking to favor title and relevance#17825
Merged
coolguyzone merged 3 commits intoMay 27, 2026
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
@coolguyzone approved, but looks like a rebase is needed. Not blocking, but adding this note, just in case tweaking is possible in this way: If I was being nitty about building logic around our search, I would say default to this on every search bar, except when /platforms/ is selected. Because if I'm in the SDKs section, it may be nice to bias toward SDK doc results as the top, especially if it prioritizes showing me the platform/framework I have selected. Search does that today, it just does that no matter where I am in docs. And it's just clearly broken on the home page. |
Override the index settings pushed by scripts/algolia.ts so search results lean on titles and textual relevance instead of SDK popularity. - Add `title` as the first searchable attribute. Previously only `section`, `keywords`, and `text` were searched, so page titles like "Tracing" didn't contribute to matching unless they happened to also be a heading on the page. - Move `asc(popularity)` to the last position in the ranking criteria. It was running ahead of `attribute`, `exact`, and `proximity`, which meant a popular SDK page with a "Tracing" heading would outrank the Tracing product page on a "Tracing" query. Textual relevance now decides first; popularity is a final tiebreaker. Co-Authored-By: Claude <noreply@anthropic.com>
Pages outside `platforms/` previously fell back to `MAX_SAFE_INTEGER` for the popularity field, so they always lost the `asc(popularity)` ranking tiebreaker to any SDK page. That meant queries like "Tracing" or "Sentry CLI" surfaced random SDK pages instead of the product or CLI docs that match the query subject more directly. Treat product/concept/CLI/guides/integrations pages as the most popular non-platform group by giving them popularity 0 (better than every individual SDK). The platform `optionalFilters` boost still runs ahead of popularity in the ranking pipeline, so users who have a platform selected keep getting platform-relevant results first. Co-Authored-By: Claude <noreply@anthropic.com>
coolguyzone
force-pushed
the
coolguyzone/chore/tune-algolia-search-ranking
branch
from
0d65a7d to
0e10bf0
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
DESCRIBE YOUR PR
Tune Algolia docs search so it leans on titles and textual relevance over SDK popularity, and so SDK-agnostic product docs surface above individual SDK pages on broad queries.
Commit 1 — Ranking and searchable-attributes override
Override the index settings pushed by
scripts/algolia.tson top of the defaults from@sentry-internal/global-search:titleas the first searchable attribute. The package's defaultsearchableAttributesonly includessection,keywords, andtext— so page titles never contributed to matching unless they happened to also be a heading on the page. Withtitlefirst, title matches outrank section and body matches via Algolia'sattributeranking criterion.asc(popularity)to the last position in therankingarray. It was running ahead ofattribute,exact, andproximity, which meant a popular SDK page with a## Tracingheading would outrank the actual Tracing product page on a "Tracing" query. Textual relevance now decides first; popularity is a final tiebreaker.Commit 2 — Boost SDK-agnostic product docs
Pages outside
platforms/previously fell back toNumber.MAX_SAFE_INTEGERfor thepopularityfield, so they always lost theasc(popularity)tiebreaker to any SDK page. Pages whose slug starts withproduct/,concepts/,cli/,guides/, orintegrations/now getpopularity: 0— better than every individual SDK — so they surface above SDK pages on broad queries.This composes correctly with platform filtering: the platform
optionalFiltersboost runs at thefiltersranking criterion, which sits ahead ofasc(popularity). So a user with Python selected still gets Python-relevant pages first; product pages come second (and only beat non-matching SDK pages).Left
attributeForDistinct: 'section'unchanged for now — the above should be enough on its own, and changing distinct behavior is a bigger behavior shift worth testing separately if needed.IS YOUR CHANGE URGENT?
Help us prioritize incoming PRs by letting us know when the change needs to go live.
SLA
Thanks in advance for your help!
PRE-MERGE CHECKLIST
Make sure you've checked the following before merging your changes:
Testing note
The ranking-settings override (commit 1) only takes effect when
scripts/algolia.tsruns at deploy time against the production Algolia index, so a Vercel preview won't exercise it — preview deploys point at the existing index. To validate before merge, either tweak the index's "Searchable attributes" and "Ranking and Sorting" settings directly in the Algolia dashboard (non-destructive, easy to revert) or stand up a one-off staging index by overridingDOCS_INDEX_NAME.The popularity boost (commit 2) changes per-record data, so it'll only fully take effect after the next full reindex on master.