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:

  1. Sales count — number of purchases in the last 30 days
  2. Revenue — total revenue from purchases in the last 30 days
  3. Click-through rate (CTR) — clicks / views over the last 30 days
  4. Conversion rate — purchases / clicks over the last 30 days
  5. View count — number of views in the last 7 days
  6. Recency — how recently the document had any interaction

The formula:

text
composite = sales_count × 0.30
         + revenue         × 0.20
         + ctr             × 0.20
         + conversion_rate × 0.15
         + view_count      × 0.10
         + recency         × 0.05

Each 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.

Event prerequisites
Scoring requires behavioral events to be sent via 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:

text
await idx.updateSettings({
  scoring: {
    enabled: true,
    ranking_weight: 0.10,
  },
});
text
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.

ParameterTypeDescription
sales_count optionalnumberWeight for purchase count over the last 30 days.
Default: 0.30
revenue optionalnumberWeight for total revenue over the last 30 days.
Default: 0.20
ctr optionalnumberWeight for click-through rate over the last 30 days.
Default: 0.20
conversion_rate optionalnumberWeight for purchase-to-click conversion rate.
Default: 0.15
view_count optionalnumberWeight for view count over the last 7 days.
Default: 0.10
recency optionalnumberWeight for document recency.
Default: 0.05
text
// 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):

text
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.
Start conservative
Begin with the default 0.10 and increase gradually. Monitor search quality in the dashboard analytics to find the right balance for your index.

API Endpoints

Four endpoints let you inspect and manage scoring:

Get scoring overview

text
const overview = await idx.getScoring();
// { settings: { enabled, weights, ranking_weight }, stats: { total_scored, average_score, last_computed_at } }

Get top documents by score

text
const top = await idx.getTopScores({ limit: 20 });
// DocumentScore[] with composite_score, sales_count, revenue, ctr, etc.

Get a single document's score

text
const score = await idx.getDocumentScore('product_123');

Trigger immediate recompute

text
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:

text
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.