Decay functions for relevance scoring

5 min

Decay functions boost content closer to a target value, commonly a date. More recent content ranks higher in results. Use decay functions when recency affects relevance, such as in news feeds, blog listings, or activity streams.

Decay functions influence relevance scoring, not filtering. All matching items display in the results. The scoring system ranks items closer to the target value higher.

Apply date-based decay

Pass a DecayOptions object to a .Where() clause to apply decay to a date field. Content closer to the Origin value receives a higher relevance score. Content further away loses relevance based on the decay rate.

var result = await client
    .QueryContent<BlogPostPage>()
    .Where(x => x.StartPublish, new Optimizely.Graph.Cms.Query.Abstractions.DecayOptions
    {
        Origin = DateTime.UtcNow,
        Rate   = 0.3f,
        Scale  = 100
    })
    .GetAsContentAsync();

In this example, the query boosts blog posts closer to the current date.

DecayOptions parameters

The DecayOptions object defines how the scoring changes relative to the target value.

Parameter	Type	Description
Origin	DateTime	The reference value used to calculate distance. Items closest to this value receive the highest relevance score.
Rate	float	The rate at which relevance decreases as distance from Origin increases. Higher values cause faster decay.
Scale	int	The distance at which the score decays by the specified Rate. For date fields, the distance is measured in days.

Decay affects the relevance score, not the result set. All matching items are returned. They are just ranked with recency taken into account. To sort purely by date instead, use .OrderBy() and skip decay.

Combine decay with other query operations

Decay functions work alongside filters, search, and pagination. Combine them with other query methods to refine results while boosting recent content.

var result = await client
    .QueryContent<BlogPostPage>()
    .Where(x => x.BlogCategory == "News")
    .Where(x => x.StartPublish, new DecayOptions
    {
        Origin = DateTime.UtcNow,
        Rate   = 0.5f,
        Scale  = 30
    })
    .Limit(20)
    .GetAsContentAsync();

Decay versus sorting

Decay functions affect the relevance score, which influences ranking in search results. To sort results strictly by a field value, use .OrderBy() instead.

To sort strictly by publication date:

var result = await client
    .QueryContent<BlogPostPage>()
    .OrderBy(x => x.StartPublish, OrderDirection.Descending)
    .GetAsContentAsync();

Use decay when recency should influence ranking alongside other relevance signals, such as search matches or filters.