Feed arrangement

Feed arrangement changes the order of a ranked feed without changing any scores. Ranking decides how good each activity is. Arrangement decides where each activity goes, for placement rules that a score can't express, such as "show 4 sports activities for every 1 news activity".

You configure it with arrange on the ranking config of a feed group or feed view. Each arrange config uses exactly one mode. The only mode available today is blend, and more modes will be added later.

Blend mode

Blend mode interleaves activities from several sources at target ratios. A source is all activities that share a value of the key field, for example all activities of type sports.

The config below serves 4 sports activities for every 1 news activity, and keeps at least 2 other activities between two news activities:

{
  "ranking": {
    "type": "expression",
    "score": "decay_linear(time) * popularity",
    "arrange": {
      "mode": "blend",
      "key": "type",
      "blend": {
        "weights": { "sports": 80, "news": 20 },
        "min_gap": { "news": 2 }
      }
    }
  }
}

The feed then reads like this, where the exact positions vary from feed to feed:

sports, sports, news, sports, sports, sports, news, sports, sports, news, ...

Within each source, activities keep their ranking order: the best sports activity comes first among the sports activities, and so on. Scores are never changed.

How activities are placed

• Weights are relative. They are normalized, so 80/20, 0.8/0.2 and 4/1 produce the same order.
• Shares hold across the feed. While every source still has activities, the whole feed follows the weights, and in any run of 10 or more consecutive activities each source is typically within 2 activities of its target count.
• The pattern is not fixed. Positions are chosen with controlled randomness, so the feed doesn't repeat a predictable pattern, and different feeds get different patterns.
• min_gap is exact while every weighted source still has activities. A min_gap of 2 means at least 2 other activities sit between two activities of that source.
• When a source runs out, the remaining sources share the rest of the feed according to their weights. From that point on, ratios and gaps are best effort, and the feed never has empty slots or repeats.
• A source without any activities takes no part, and the sources that are present split the feed by their weights. As when a source runs out, gaps among the remaining sources are then best effort.

Activities without a weight

Activities whose key value has no entry in weights are placed after the blended activities, in score order.

To blend them too, add the catch-all source "*". It collects every key value without its own weight and blends them as one source. This is useful with "key": "user_id", where you can't list every author:

{
  "arrange": {
    "mode": "blend",
    "key": "user_id",
    "blend": {
      "weights": { "editorial-team": 30, "*": 70 },
      "min_gap": { "editorial-team": 1 }
    }
  }
}

Here about 30% of the feed comes from the editorial-team user, never twice in a row, and the remaining 70% from everyone else.

Giving every source enough candidates

Blending works on the candidates that your activity selectors return, after ranking. Each selector returns up to 1000 activities. If one source writes far more activities than another, the newest 1000 can hold only a few activities of the smaller source, which then runs out early.

To give each source its own pool of candidates, use one selector per source, for example by tagging activities with filter_tags when you write them:

{
  "activity_selectors": [
    {
      "type": "current_feed",
      "filter": { "filter_tags": { "$in": ["sports"] } }
    },
    { "type": "current_feed", "filter": { "filter_tags": { "$in": ["news"] } } }
  ]
}

Moving low-scoring activities to the end

Set tail_below to move activities that score strictly below a value to the very end of the feed, in score order. They are not blended, and they come after everything else. 0 is a valid value.

This works well together with exclude_below. For example, a score expression can return -2 for activities to hide and -1 for activities to show last:

{
  "ranking": {
    "type": "expression",
    "score": "...",
    "exclude_below": -1.5,
    "arrange": {
      "mode": "blend",
      "key": "type",
      "tail_below": 0,
      "blend": {
        "weights": { "sports": 80, "news": 20 }
      }
    }
  }
}

The steps run in this order:

1. Activities are scored and sorted.
2. Activities below exclude_below are removed.
3. Activities below tail_below are set aside for the end.
4. The remaining activities are blended.

The final feed is the blended activities, then the activities without a weight, then the activities below tail_below.

tail_below must be greater than exclude_below when both are set, because otherwise nothing would ever reach the end section.

Configuration reference

arrange

blend

Combining weights and gaps

A source with a gap of g needs g other activities between two of its own, so it can fill at most 1 in g + 1 positions. Each source therefore has to satisfy the rule below, where min_gap is the source's own entry or default_min_gap:

weight × (min_gap + 1) ≤ sum of all weights

For example, { "a": 2, "b": 1 } with min_gap: { "b": 2 } is valid (1 × 3 ≤ 3), but { "a": 1, "b": 1 } with the same gap is not (1 × 3 > 2).

Gaps on several sources can also conflict with each other even when every source passes this check on its own. Stream checks the whole combination when you save the feed group or view, and rejects combinations that can't be met.

Scores, pagination and caching

• The score returned for each activity is still its ranking score. An arranged feed is therefore not sorted by score.
• The order is stable for a given set of activities, so paginating through the feed is consistent. The order changes when activities are added or removed.
• After you add or remove arrange, a pagination cursor from before the change can be rejected with pagination token expired, please refresh the feed, or the next page can repeat or skip activities. Restart from the first page. Changing weights or gaps doesn't invalidate cursors and takes effect when cached results refresh.
• After changing the config, cached ranked results can take up to about 60 seconds to reflect it, or up to 10 minutes for some shared ranked feeds.
• Arranged feeds can be served from the hot feed cache, including with external ranking.

Validation errors

Creating or updating a feed group or feed view with an invalid arrange config returns a 400 error: