Reduce

Overview

The reduce system takes key:value pairs as input from the Map operation. When the input meets defined conditions, the reduce produces a new set of key:value pairs using a defined operation.

The reduce operation can be min, max, count or sum. The output of the reduce operation is a summary of all processed inputs transformed into an array of all the reduce operations.

Reduce definition example

{
  "version": "1.7.0",
  "event": {
    "game": {
      "reductions": [
        {
          "id": "changeColor",
          "where": {"key": ["changeColor", "<name>", "<color>"]},
          "key": ["<name>", "<color>"],
          "value": ["$count"],
          "period": 250
        },
        {
          "id": "cheer",
          "where": {"key": ["cheer", "<name>"]},
          "key": ["<name>"],
          "value": ["$sum"],
          "period": 250,
          "publishers": [
            "genvid://game",
            "genvid://notifications"
          ]
        }
      ]
    }
  }
}

Reduce Schema

id

A unique string that refers to the reduce.

where

A schema defining the conditions that trigger producing a new key:value pair. See Where clause content for more information.

period

The frequency of the reduction in milliseconds (ms). For example, a 250ms period means that the game would receive the reduce output 4 times per second.

key

An array of strings representing the new key. Each string can be:

  • Alphanumeric string: A plain literal value.

  • <anyText>: A named value taken from the input key.

value

An array of operations which merges the inputs and generates the outputs. Note that even though an operation is specified, all operations are currently returned into each reduce.

Possible operations are:

  • $min: Returns the minimum value among all inputs.

  • $max: Returns the maximum value among all inputs.

  • $count: Returns the number of times the key was encountered.

  • $sum: Returns the sum of all input values added together.

publishers

An array of URLs representing where the reduction will be published. Currently, only two value is possible:

  • genvid://game: The reduction will be sent to the game, and can be retrieve through the Native API. See Genvid_Subscribe() function for more information.

  • genvid://notifications: The value will be sent to the Notifications system and can be retrieved through the onNotificationsReceived callback. The notification id is on the format events.summaries.reduction id, and the notification data contains a JSON object like this:

    {
   "id":"playerlike",
   "results": [
      {
         "key":["like", "player1"],
         "value":
         {
            "count": 1,
            "sum": 1,
         }
      },
      {
         "key":["like", "player2"],
         "value":
         {
            "count": 3,
            "sum": 3,
         }
      },
   ]
}

    New in version 1.43.0.

reset

When do the reduction counters get reset. This object is composed of two properties:

mode

The mode of reset. Can be either periodic or on-demand. The default value of periodic means that the value will be reset at the end of one or multiple of the reduction periods. The mode on-demand will not reset the events unless a call to POST /reduction/{id} be done with an action reset.

count

The number of periods before reset. The default is 1 and it means that the reset will happens everytime the reduction is sending a summary. A value of 5 for example will mean the reduction will accumulate for 4 reduction, and will be reset at the 5th one. Ignored if the mode is on-demand.

New in version 1.47.0.

Reduce Example

The Reduce operation takes key:value pairs as input and transforms them into another set of key:value pairs, but merged together to have fewer of them.

Like the mapping step, Genvid uses JSON for the reduction step.

{
  "id": "playerlike",
  "where": {
    "key": ["like", "<playerName>"]
  },
  "key": ["like", "<playerName>"],
  "value": ["$count"],
  "period": 1000,
  "reset": {
    "mode": "periodic",
    "count": 1
  }
}

During the reduction step, the operation looks for any key starting with "like"`while ignoring the second parameter. (The second parameter matched will be referable as the token ``playerName` in later steps.)

The operation merges the matching key:value will then be merged, and the resulting valuepairs and assigns the number of times it encountered the original key to the value. Genvid uses this result to transmit the event data.

For example, we receive the following results from the Map function:

[
   { "key": ["like", "player1"], "value": { "count": 1 } },
   { "key": ["like", "player1"], "value": { "count": 1 } },
   { "key": ["like", "player2"], "value": { "count": 1 } },
   { "key": ["like", "player1"], "value": { "count": 1 } }
]

The Reduce function merges them into the following:

[
  {"key": ["like", "player1"], "value": { "count": 3 } },
  {"key": ["like", "player2"], "value": { "count": 1 } }
]

Important

Due to some past bug, the current values always contains all operations, even if they weren’t requested in the configuration. Future version could fix it.