Ranking expressions

A ranking expression computes a score for each activity, and the feed is ordered by that score, highest first. This page is the reference for what an expression or interest ranking can use: activity fields, data types, functions, operators, constants and decay functions. For how to configure ranking on a feed group or feed view, see Ranking.

Activity data

It's not possible to access all fields of an ActivityResponse inside the ranking context. Below you'll find the list of supported fields:

Every field the expression references that isn't a built-in field, such as custom.*, external.*, metrics.* and selector_source, needs a default value in defaults. The default is used for activities that don't have the field, and creating or updating a feed group or feed view without it fails with expression references fields without defaults: <field>. Write defaults as nested objects ({ "custom": { "foo": 0 } }), not dotted keys ("custom.foo"). Built-in fields such as popularity or share_count can't have defaults.

from getstream.models import ActivitySelectorConfig, RankingConfig

client.feeds.create_feed_group(
    id="myid",
    activity_selectors=[ActivitySelectorConfig(type="following")],
    ranking=RankingConfig(
        type="expression",
        score="popularity * (custom.isBoosted ? 1.5 : 1)",
        defaults={"custom": {"isBoosted": False}},
    ),
)

Data types

The following data types are supported in the ranking expression context:

Functions

The following functions can be used in ranking expressions:

Operators

The following operators can be used in ranking expressions:

• Arithmetic operators: +, -, *, /, % (modulus), ^, ** (exponent)

• Logical operators: not/!, &&/ and, ||/or

• Conditional: x ? y : z, ??, if/else

• Comparison: ==, !=, <, >, <=, >=

• Control order of evaluation with parentheses ()

• Array/map operators: [] (index), ., ?., in (checks if an array/map has an item/key)

• String operators: + (concatenation), contains, startsWith, endsWith

This lets you construct a scoring algorithm like this:

"score":"(a > 2 || (b > 4 && c > 3)) ? 1 : -1"

Constants

The following constants and helpers are also available to use in ranking expressions:

Decay & Ranking

Stream supports linear, exponential, and Gaussian decay. The built-in decay_linear(t), decay_exp(t) and decay_gauss(t) take one argument and always use the default parameters below (origin now, scale 5 days, no offset, decay 0.5); extra arguments are ignored. To change the parameters, define your own function under functions with a base of decay_linear, decay_exp or decay_gauss, and call it by name in score. All parameter values are strings.

Parameters

The example below defines a simple_gauss with the following parameters:

• scale: 5 days

• offset: 1 day

• decay: 0.3

This means that an activity younger than 1 day (the offset) will return a score of 1. An activity that is exactly 6 days old (offset + scale) will get a score of 0.3 (the decay factor).

The example also defines a popularity_gauss that scores activities with a popularity of 100 or more as 1 (origin: "100" with direction: "right"), and lowers the score of less popular activities. A function applied to something other than time needs an origin, because the default origin is the current time. The full example:

from getstream.models import ActivitySelectorConfig, DecayFunctionConfig, RankingConfig

client.feeds.create_feed_group(
    id="myid",
    activity_selectors=[ActivitySelectorConfig(type="following")],
    ranking=RankingConfig(
        type="expression",
        score="simple_gauss(time)*popularity_gauss(popularity)",
        functions={
            "simple_gauss": DecayFunctionConfig(
                base="decay_gauss",
                scale="5d",
                offset="1d",
                decay="0.3",
            ),
            "popularity_gauss": DecayFunctionConfig(
                base="decay_gauss",
                origin="100",
                direction="right",
                scale="100",
                offset="5",
                decay="0.5",
            ),
        },
    ),
)

Ranking by Selector Source

When using multiple activity selectors, each activity is tagged with a selector_source field indicating which selector provided it. This enables you to prioritize activities from specific sources in your ranking expressions.

from getstream.models import ActivitySelectorConfig, RankingConfig

# Example 1: Simple boost - following activities get 2x multiplier
client.feeds.create_feed_group(
    id="selector_timeline",
    activity_selectors=[
        ActivitySelectorConfig(type="following"),
        ActivitySelectorConfig(type="popular", min_popularity=1),
    ],
    ranking=RankingConfig(
        type="expression",
        score='selector_source == "following" ? popularity * 2 : popularity',
        # Required when using selector_source in expressions
        defaults={"selector_source": ""},
    ),
)

# Example 2: Multiple selectors with different bonuses
client.feeds.create_feed_group(
    id="multi_selector_timeline",
    activity_selectors=[
        ActivitySelectorConfig(type="following"),
        ActivitySelectorConfig(type="interest"),
        ActivitySelectorConfig(type="popular", min_popularity=1),
    ],
    ranking=RankingConfig(
        type="expression",
        score=(
            '(selector_source == "following" ? 10 : 0) + '
            '(selector_source == "interest" ? 5 : 0) + '
            "popularity"
        ),
        defaults={"selector_source": ""},
    ),
)

Important notes:

• Defaults required: You must provide selector_source in the defaults map (typically as an empty string "")
• Duplicate activities: If an activity matches multiple selectors, it keeps a single selector_source. following takes precedence over the other selectors
• Valid sources: following, popular, interest, query, proximity, current_feed, follow_suggestion