# Ranking

Stream allows you to configure your own ranking method to determine the order of activities inside a feed.

An example ranking config is shown below:

<partial id="activity-feeds/v3-latest/_default/_partials/ranking-example"></partial>

### Available Functions

<admonition type="info">

obs: functions are parsed in lowercase

</admonition>

| name                           | description                                                                                                                                                                                                                                                                                                 |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Basic Arithmetic               | The following are supported: + - \* / ( ) ^                                                                                                                                                                                                                                                                 |
| ln(x)                          | Log Function natural base                                                                                                                                                                                                                                                                                   |
| log(x)                         | Log Function base 10                                                                                                                                                                                                                                                                                        |
| sin(x)                         | Trigonometric sine function                                                                                                                                                                                                                                                                                 |
| cos(x)                         | Trigonometric cosine function                                                                                                                                                                                                                                                                               |
| tan(x)                         | Trigonometric tangent function                                                                                                                                                                                                                                                                              |
| abs(x)                         | Absolute value                                                                                                                                                                                                                                                                                              |
| min(a,b)                       | Minimum value                                                                                                                                                                                                                                                                                               |
| max(a,b)                       | Maximum value                                                                                                                                                                                                                                                                                               |
| trunc(x)                       | Truncates to the nearest integer value                                                                                                                                                                                                                                                                      |
| round(x)                       | Rounds to the nearest integer value                                                                                                                                                                                                                                                                         |
| decay_linear(t)                | Linear Decay                                                                                                                                                                                                                                                                                                |
| decay_exp(t)                   | Exponential Decay                                                                                                                                                                                                                                                                                           |
| decay_gauss(t)                 | Gauss Decay                                                                                                                                                                                                                                                                                                 |
| rand_normal()                  | Returns a normally distributed number in the range [-inf, +inf] with standard normal distribution (stddev = 1, mean = 0)                                                                                                                                                                                    |
| rand_normal(a,b,σ,µ)           | Returns a normally distributed number in the range [a, b] with specific normal distribution (stddev = σ, mean = µ)                                                                                                                                                                                          |
| rand()                         | Returns a random number in the range [0, 1.0)                                                                                                                                                                                                                                                               |
| rand(a,b)                      | Returns a random number in the range [a, b)                                                                                                                                                                                                                                                                 |
| to_unix_timestamp(t)           | Converts a time value to a unix timestamp                                                                                                                                                                                                                                                                   |
| dist(lat1,lng1,lat2,lng2,unit) | Returns the distance between the two points given by (lat1,lng1) and (lat2,lng2) . By default the unit is in kilometers, but the unit can also be M for miles or N nautical miles. This function can be combined with the external ranking parameters to rank activities based on a users distance to them. |

### 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

<codetabs>

<codetabs-item value="none" label="None">

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

</codetabs-item>

</codetabs>

### Adding Activities

Below is an example of how to add activities with custom data that you can use for ranking as well:

<codetabs>

<codetabs-item value="javascript" label="JavaScript">

```js
const activity = await feed.addActivity({
  type: "post",
  text: "Great content",
  custom: {
    quality_score: 0.95,
    engagement_prediction: 0.8,
  },
});
```

</codetabs-item>

<codetabs-item value="nodejs" label="Node">

```js
const activity = await client.feeds.addActivity({
  fids: [feed.fid],
  type: "post",
  text: "Great content",
  custom: {
    quality_score: 0.95,
    engagement_prediction: 0.8,
  },
  user_id: "<user id>",
});
```

</codetabs-item>

</codetabs>

### Retrieving Activities

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

<codetabs>

<codetabs-item value="javascript" label="JavaScript">

```js
const feed = client.feed("user", "sara");

// Reads feed with the default view configured for the given feed group (user group in this case)
const response = await feed.getOrCreate();
// Provide a custom view when reading the feed
const response = await feed.getOrCreate({ view: "myview" });
```

</codetabs-item>

<codetabs-item value="nodejs" label="Node">

```js
const feed = client.feeds.feed("user", "sara");

// Reads feed with the default view configured for the given feed group (user group in this case)
const response = await feed.getOrCreate({ user_id: "sara" });
// Provide a custom view when reading the feed
const response = await feed.getOrCreate({ user_id: "sara", view: "myview" });
```

</codetabs-item>

</codetabs>

<admonition type="info">

You can only use  **limit**  and  **offset**  for pagination with custom ranking.

</admonition>

Configuring ranking can be complex. Feel free to reach out to [support](https://getstream.io/contact/support/) if you have questions.

## More visibility into ranking variables

The `score` field of an activity contains the result of the ranking algorithm.

<codetabs>

<codetabs-item value="javascript" label="JavaScript">

```js
const feed = client.feed("user", "sara");
const response = await feed.getOrCreate();

console.log(response.activities[0].score);
```

</codetabs-item>

<codetabs-item value="nodejs" label="Node">

```js
const feed = client.feeds.feed("user", "sara");
const response = await feed.getOrCreate({ user_id: "sara" });

console.log(response.activities[0].score);
```

</codetabs-item>

</codetabs>

## 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.

![](https://getstream.imgix.net/images/docs/decay_explainer.png?auto=compress&fit=clip&w=800&h=600)

### Parameters

| name      | description                                                                                                                                              | default |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| origin    | The best possible value. If the value is equal to the origin the decay function will return 1.                                                           | now     |
| scale     | Determines how quickly the score drops from 1.0 to the decay value. If the scale is set to "3d" the score will be equal to the decay value after 3 days. | 5d      |
| offset    | Values below the offset will start to receive a lower score.                                                                                             | 0       |
| decay     | The score that a value at scale distance from the origin should receive.                                                                                 | 0.5     |
| direction | left, right or both. If right is specified only apply the decay for the right part of the graph.                                                         | both    |

<admonition type="info">

You can use s, m, h, d and w to specify seconds, minutes, hours, days and weeks respectively.

</admonition>

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:

<codetabs>

<codetabs-item value="nodejs" label="Node">

```json
{
  "type": "expression",
  "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"
}
```

</codetabs-item>

</codetabs>

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.

<admonition type="info">

Custom ranking is only working on the last 1000 activities of the feed.

</admonition>

Configuring ranking can be complex. Feel free to reach out to [support](https://getstream.io/contact/support/) if you have questions!

## Analytics & Reaction Counts

<admonition type="info">

Analytics and Reaction Counts can be used in ranking easily, contact support to get them enabled.

</admonition>

<codetabs>

<codetabs-item value="nodejs" label="Node">

```js
{
  "type": "expression",
  "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)"
}
```

</codetabs-item>

</codetabs>

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.

<admonition type="info">

Reaction counts are cached for 30 minutes. Therefore, when using this as a ranking criteria, you can anticipate a small delay between when a new reaction is added / removed and the recalculation of the score of the activity.

</admonition>

---

This page was last updated at 2025-08-15T14:14:10.324Z.

For the most recent version of this documentation, visit [https://getstream.io/activity-feeds/docs/react-native/custom_ranking/](https://getstream.io/activity-feeds/docs/react-native/custom_ranking/).