Scoring
Document scoring automatically ranks products by popularity using behavioral signals like purchases, clicks, and views. Skirre aggregates these events into a composite score per document, then blends it into search ranking so popular items surface higher.
Overview
When scoring is enabled, Skirre runs a background job every 6 hours that aggregates behavioral events (sent via the Events API) into per-document popularity scores. These scores are then blended into search ranking alongside BM25 relevance and optional semantic similarity.
The scoring pipeline is fully self-contained — all required data comes from the events already stored in Skirre. No external data sources are needed.
How It Works
The composite score for each document is computed from six behavioral signals, each normalized to a 0–1 range within the index using min-max scaling:
- Sales count — number of purchases in the last 30 days
- Revenue — total revenue from purchases in the last 30 days
- Click-through rate (CTR) — clicks / views over the last 30 days
- Conversion rate — purchases / clicks over the last 30 days
- View count — number of views in the last 7 days
- Recency — how recently the document had any interaction
The formula:
composite = sales_count × 0.30
+ revenue × 0.20
+ ctr × 0.20
+ conversion_rate × 0.15
+ view_count × 0.10
+ recency × 0.05Each signal is min-max normalized per index, so a score of 1.0 means the document has the highest value for that signal in the entire index.
POST /v1/events. Without
events, all scores will be zero. See the Events API to start
tracking user behavior.Enabling Scoring
Scoring is disabled by default. Enable it via the index settings:
await idx.updateSettings({ scoring: { enabled: true, ranking_weight: 0.10, }, });
curl -X PUT https://search.example.com/v1/indices/products/settings \ -H "Authorization: Bearer sk_search_live_..." \ -H "Content-Type: application/json" \ -d '{ "scoring": { "enabled": true, "ranking_weight": 0.10 } }'
Once enabled, scores are recomputed every 6 hours automatically. You can also trigger an immediate recomputation via the API.
Tuning Signal Weights
The default weights work well for most e-commerce use cases, but you can adjust them to match your business priorities. Weights should sum to approximately 1.0.
| Parameter | Type | Description |
|---|---|---|
| sales_count optional | number | Weight for purchase count over the last 30 days. Default: 0.30 |
| revenue optional | number | Weight for total revenue over the last 30 days. Default: 0.20 |
| ctr optional | number | Weight for click-through rate over the last 30 days. Default: 0.20 |
| conversion_rate optional | number | Weight for purchase-to-click conversion rate. Default: 0.15 |
| view_count optional | number | Weight for view count over the last 7 days. Default: 0.10 |
| recency optional | number | Weight for document recency. Default: 0.05 |
// Revenue-focused scoring — prioritize high-value products await idx.updateSettings({ scoring: { enabled: true, ranking_weight: 0.15, weights: { sales_count: 0.20, revenue: 0.35, ctr: 0.15, conversion_rate: 0.15, view_count: 0.10, recency: 0.05, }, }, });
Ranking Weight
The ranking_weight controls how much the composite popularity score influences
the final search ranking. It's blended with the relevance score (BM25 + optional semantic):
final_score = relevance × (1 - ranking_weight) + popularity × ranking_weight
- 0.00: Popularity has no effect — pure relevance ranking (default behavior when scoring is disabled).
- 0.10 (default): A gentle boost for popular items. Best sellers surface slightly higher without overwhelming relevance.
- 0.25: Significant popularity influence. Good for broad queries where relevance alone doesn't differentiate well.
- 0.50 (max): Heavy popularity bias. Use with caution — less relevant but popular items may outrank precise matches.
API Endpoints
Four endpoints let you inspect and manage scoring:
Get scoring overview
const overview = await idx.getScoring(); // { settings: { enabled, weights, ranking_weight }, stats: { total_scored, average_score, last_computed_at } }
Get top documents by score
const top = await idx.getTopScores({ limit: 20 }); // DocumentScore[] with composite_score, sales_count, revenue, ctr, etc.
Get a single document's score
const score = await idx.getDocumentScore('product_123');
Trigger immediate recompute
const result = await idx.recomputeScores(); // { status: "ok", documents_scored: 369 }
Best Practices
Accumulate events first
Scoring works best with sufficient event data. Wait until your index has at least a few hundred events before enabling scoring, otherwise all documents will have near-zero scores and the ranking boost will have little effect.
Send quality events
Include query_id from search responses in your click and purchase events. This
allows Skirre to compute accurate CTR and conversion rates. Events without a query_id still
contribute to sales and view counts.
Include revenue metadata
For purchase events, include revenue in the metadata object. Without it, the
revenue signal will be zero for all documents:
await skirre.sendEvents({ events: [{ type: 'purchase', index_uid: 'products', document_id: 'product_123', query_id: 'q_abc', metadata: { revenue: 49.99 }, }], });
Monitor score distribution
Use the dashboard analytics page or the getTopScores() API to monitor the score
distribution. If all scores cluster near 0 or 1, your weights may need adjustment, or you may
need more diverse event data.