One of the high priority items on the Lens roadmap is the ability to support month over month calculations, described in that issue in user-facing terms. The architectural requirements are described here, including some sample tables. This issue will focus on the way we want to implement this feature in esaggs for use by Lens.

Defining the goal

We want to implement time offsets in esaggs using a top-level Filters aggregation. One filter will contain the dashboard context for the "Current time," and the other filter will contain dashboard context with the "offset time". Esaggs should combine the two filters into a single table. The table should be constructed by matching buckets from the current and offset values: if any of the buckets contain timestamps, they need to be aligned using moment. Missing matches need to apply a fitting function.

For our purposes in Lens, we only want to compare metric values, not buckets. If the buckets don't match then we can't build a reasonable comparison.

When using a time offset for display, there are three possible values for each metric. For example, if the metric is "Count", these are the three values:

• The count within the current time
• The count at the offset
• The percentage difference of current / offset

For example, this visualization shows "count at current time" with "percentage difference":

Defining the API

There are two kinds of APIs that could be acceptable for this. I would like feedback about which of these APIs we should use:

a. Automatically generate additional columns for each metric and add to the table. For example, esaggs offset="-4w" aggConfigs="[{ id: 'a', type: 'count' }]" would generate a table with three columns: ['a', 'a-offset', 'a-offset-percent']
b. Add an additional parameter to each metric which allows you to select between the three possible metrics with offset. For example, esaggs offset="-4w" aggConfigs="[{ id: 'a', type: 'count', offset: 'percent' }]" would return a single column instead of three columns.

In both APIs the offset is at the top level, because there is only one offset allowed. It does not make sense to build multiple time comparisons into the API.

cc @elastic/kibana-app-arch @lukeelmers