Ranking helpers

hlquery exposes rank_signal (plus optional popularity_score/hit_log) so you can boost popular documents without changing core ranking.

Data model

1. Store counters every time a document is opened:
   • popularity_score: total opens
   • hit_log: batch log for recent opens or quality signals
   • rank_signal: precomputed boost that combines log + linear terms (the helper below does the math)
2. Update those fields whenever the front end reports new hits (see POST /collections/{collection}/documents in each client).
3. When searching, sort by rank_signal:desc (the helpers below will append that sort clause for you).

Client helpers

Every API client now ships the same ranking helpers so you can recompute rank_signal and attach the sort clause in a consistent way.

Language	Helper	Usage
PHP	Hlquery\Ranker::computeRankSignal / attachRankSort()	Ranker::computeRankSignal($popularity, $hitLog); Ranker::attachRankSort($params);
Python	hlquery.utils.compute_rank_signal / attach_rank_sort()	params = {'q':'search'}; params['rank_signal'] = compute_rank_signal(popularity_score, hit_log); attach_rank_sort(params)
Node	hlquery.Utils.Ranker.computeRankSignal / attachRankSort()	const {Ranker} = client.Utils; params.rank_signal = Ranker.computeRankSignal(...); Ranker.attachRankSort(params);
Go	ComputeRankSignal() / AttachRankSort()	params["rank_signal"] = fmt.Sprintf("%f", ComputeRankSignal(...)); AttachRankSort(params, "rank_signal", "desc")
Java	Ranker.computeRankSignal() / Ranker.attachRankSort()	params.put("rank_signal", Ranker.computeRankSignal(...)); Ranker.attachRankSort(params, "rank_signal", "desc");
Rust	compute_rank_signal() / attach_rank_sort()	params.insert("rank_signal".to_string(), compute_rank_signal(...).to_string()); attach_rank_sort(&mut params, "rank_signal", "desc");
C++	hlquery::Ranker::ComputeRankSignal / AttachRankSort	params["rank_signal"] = std::to_string(Ranker::ComputeRankSignal(...)); Ranker::AttachRankSort(params);

Best practices

• Keep popularity_score/hit_log as numeric fields in your schema.
• Store the computed rank_signal whenever you update either counter, so you can sort without additional math on the server.
• Always include rank_signal in your search payload (as a field and in sort_by) to leverage the boost.
• Combine the helper with client-side conflict handling so different backends can compute and push updates safely.