How do I paginate a Stream ranked feed?

I was pretty deep into integrating Stream into my existing pagination implementation (which is also used for paginating non-activity data stored in MySQL) when I came across this line in the Stream documentation under "Custom Ranking":

Please note: offset and id_lt cannot be used to read ranked feeds. Use score_lt for pagination instead.

This seems to be the only mention of score_lt in the docs. I can't find it discussed anywhere else, nor can I find an example of what its value should be. Should it be the same UUID I would use for id_lt if I were paginating a non-ranked feed? Or is it meant to be a score value of some kind that would be returned only by a ranked feed?

Normally I'd just try it and see, but ranked feeds are only available to paid plans and I'm still evaluating Stream.

This could have significant implications for how I implement pagination though, since I do want to be able to use ranked feeds in the future if I move forward with Stream.

Solution

When retrieving activities from a ranked feed using a specific ranking config, each activity will include a score attribute. You can use the score_lt to paginate through the items in the ranked feed (along with the limit parameter).

(When paginating through items on non-ranked feeds, we usually recommend using the id_lt parameter, which will just return activities by creation date, in chronological order from most-recent to least-recent. However, since older content in a ranked feed might be ranked higher than newer content, we have to paginate and order via the score attribute.)

Whenever you create a ranked feed, you'll create at least one ranked feed config. I'm going to name my ranked feed config ranked-feed-config-one (you can have as many as you'd like) which will look something like this:

{
    "score": "decay_linear(time) * popularity ^ 0.5",
    "defaults": {
        "popularity": 1
    }
}

Whenever you send a new activity into stream, you'll also provide an optional popularity parameter. (If you don't provide one, popularity will default to 1.)

Then, whenever you retrieve activities from the ranked feed, you can specify what ranking config you'd like to use (ranked-feed-config-one), like this:

someFeed.get({ ranking: 'ranked-feed-config-one' })

Each activity will be returned with (and ordered by) a score attribute. You'll save the last score attribute, and use that when supplying the score_lt parameter for future pagination calls.

Hopefully that helps clear things up! Let me know if there's anything else I can help answer for you.