Custom Ranking

Stream allows you to configure your own ranking method. You can add multiple ranking methods to a given Flat feed group.

An example ranking config is shown below:

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

Available Functions

Operators

The scoring algorithm has support for simple control flows and logical operators.

• Logical operators && and ||

• Ternary conditional x ? y : z

• Control order of evaluation with parens ()

This lets you construct a scoring algorithm like this

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

Adding Activities

Below is an example of how to add activities with custom ranking:

// Instantiate a feed object
var userFeed1 = client.Feed("user", "1");

// Add an activity to the feed, where actor, object and target are references to objects - adding your ranking method as a parameter (in this case, "popularity"):
var activity = new Activity("User:2", "pin", "Place:42")
{
  Target = "Board:1"
};
activity.SetData("popularity", 5);

var activityResponse = await userFeed1.AddActivityAsync(activity)

// Server-Side: Instantiate a feed using feed class 'user' and user id '1'
const user1 = client.feed('user', '1');

// Client-Side: Instantiate a feed for feed group 'user', user id '1' and a security token generated server side
const user1 = client.feed('user', '1', token);

// Add an activity to the feed - adding your ranking method as a parameter (in this case, "popularity"):
const activity = { "actor": "User:2", "verb": "pin", "object": "Place:42", "target": "Board:1", "popularity": 5 };

// Add Activity 
await user1.addActivity(activity);

# Instantiate a feed object
user_feed_1 = client.feed('user', '1')

# Add an activity to the feed, where actor, object and target are references to objects - adding your ranking method as a parameter (in this case, "popularity"):
activity_data = { "actor": "User:2", "verb": "pin", "object": "Place:42", "target": "Board:1", "popularity": 5 }

activity_response = user_feed_1.add_activity(activity_data)

# Instantiate a feed object
user_feed_1 = client.feed('user', '1')

# Add an activity to the feed - where actor, object, and target are references to objects - adding your ranking method as a parameter (in this case, "popularity"):
activity_data = { :actor => "User:2", :verb => "pin", :object => "Place:42", :target => "Board:1", :popularity => 5 }

activity_response = user_feed_1.add_activity(activity_data)

// Instantiate a feed object
$userFeed1 = $client->feed('user', '1');

// Add an activity to the feed, where actor, object and target are references to objects - and adding your ranking method as a parameter (in this case, "popularity"):
$data = [
  "actor" =>"User:2",
  "verb" =>"pin",
  "object" =>"Place:42",
  "target" =>"Board:1",
  "popularity" => 5,
];

$userFeed1->addActivity($data);

// Add an activity to the feed, where actor, object and target are references to objects - adding your ranking method as a parameter (in this case, "popularity"):
Activity activity = Activity.builder()
    .actor("User:1")
    .verb("pin")
    .object("place:42")
    .target("board:1")
    .extraField("popularity", 5)
    .build();
userFeed.addActivity(activity).join();

// Instantiate a feed object
	userFeed, err := client.FlatFeed("user", "42")
	if err != nil {
		panic(err)
	}

	// Add an activity to the feed, where actor, object and target are references to objects - adding your ranking method as a parameter (in this case, "popularity"):
	activity := stream.Activity{
		Actor: "user:42",
		Verb:  "pin",
		Object: "place:42",
		Target: "board:1",
		Extra: map[string]any{
			"popularity": 5,
		},
	}
	_, err = userFeed.AddActivity(context.TODO(), activity)
	if err != nil {
		panic(err)
	}

let user1 = client.flatFeed(feedSlug: "user", userId: "1")
let activity = Activity(actor: "User:1", verb: "pin", object: "Place:42")

user1.add(activity) { result in
  if case .success(let activity) = result {
    // Added activity
    print(activity.id)
  }
}

// Server-Side: Instantiate a feed using feed class 'user' and user id '1'
final user1 = client.flatFeed('user', '1');

// Client-Side: Instantiate a feed for feed group 'user', user id '1' and a security token generated server side
final user1 = client.flatFeed('user', '1', token);

// Add an activity to the feed - adding your ranking method as a parameter (in this case, "popularity"):
final activity2 = Activity(actor: 'User:2', verb: 'pin', object: 'Place:42', target: 'Board:1', extraData: {'popularity': 5});

// Add Activity 
await user1.addActivity(activity);

Retrieving Activities

Below is an example of how to retrieve activities sorted by custom ranking:

// Get activities sorted by the ranking method labelled 'activity_popularity' (Ranked Feeds Enabled)
var result = await userFeed1.GetFlatActivitiesAsync(GetOptions.Default.WithLimit(5).WithRanking("activity_popularity"));

// Get activities sorted by the ranking method labelled 'activity_popularity' (Ranked Feeds Enabled)
const response = await user1.get({ limit:20, ranking:'activity_popularity'});

# Get activities sorted by the ranking method labelled 'activity_popularity' (Ranked Feeds Enabled)
result = user_feed_1.get(limit=5, ranking="activity_popularity")

# Get activities sorted by the ranking method labelled 'activity_popularity' (Ranked Feeds Enabled)
result = user_feed_1.get(:limit=>5, :ranking=>'activity_popularity')

// Get 5 activities - using limit, offset - and sorted by the ranking method labelled 'activity_popularity' (Ranked Feeds Enabled):
$options = ['ranking' => 'activity_popularity'];

$results = $userFeed1->getActivities(0, 5, $options);

// Get activities sorted by the ranking method labelled 'activity_popularity' (Ranked Feeds Enabled)
response = userFeed.getActivities(new Pagination().limit(5), "activity_popularity").join();

// Get activities sorted by the ranking method labelled 'activity_popularity' (Ranked Feeds Enabled)
	resp, err := userFeed.GetActivitiesWithRanking(
		context.TODO(),
		"activity_popularity",
		stream.WithActivitiesLimit(5),
	)
	if err != nil {
		panic(err)
	}
 
	for _, activity := range resp.Results {
		fmt.Println(activity)
		// ...
	}

// Get activities sorted by the ranking method labelled 'activity_popularity' (Ranked Feeds Enabled):
user1.get(ranking: "activity_popularity")

// Get activities sorted by rank (Ranked Feeds Enabled):
 final response = await userFeed.getActivities(limit: 5, ranking: "popularity");

Configuring ranking can be complex. Feel free to reach out to support if you have questions.

More visibility into ranking variables

If you need to inspect your ranking variables at runtime this can be achieved like so

result = user_feed_1.get(ranking="activity_popularity", limit=5, withScoreVars=True)

$results = $userFeed1->getActivities(0, 5, $options=['ranking' => 'activity_popularity', 'withScoreVars' => true]);

const response = await user1.get({ limit:20, ranking:'activity_popularity', withScoreVars: true });

Decay & Ranking

Stream supports a Linear, Exponential, and Gauss decay. For each decay function, we support 4 arguments: Origin, Scale, Offset, and Decay. You can pass either a timedelta string (such as 3d, 4w), or a numeric value.

Parameters

The example below defines a simple_gauss with the following params:

• scale : 5 days

• offset : 1 day

• decay : 0.3 day

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 full JSON config is shown below:

{
 "functions": {
  "simple_gauss": {
   "base":"decay_gauss",
   "scale":"5d",
   "offset":"1d",
   "decay":"0.3"
  },
  "popularity_gauss": {
   "base":"decay_gauss",
   "scale":"100",
   "offset":"5",
   "decay":"0.5"
  }
 },
 "defaults": {
   "popularity": 1
 },
 "score":"simple_gauss(time)*popularity"
}

You can specify defaults for the variables you use. The example above sets popularity to 1 if it’s missing from the activity. We highly recommend setting up defaults to prevent errors when retrieving activities without these variables.

Configuring ranking can be complex. Feel free to reach out to support if you have questions!

Analytics & Reaction Counts

{
 "defaults": {
   "analytics": {
    "view": 0
   },
   "reaction_counts": {
    "like": 0,
    "comment": 0
   }
 },
 "score":"simple_gauss(time)*(0.1*analytics.view+0.5*reaction_counts.like+reaction_counts.comment)"
}

In this example, we define defaults for activities that might be missing any analytics or reactions on it. Then, a linear combination of these numbers is adjusted according to passed time.