Time grains

When a dataset has a timeKey, you can use .by(grain) on metrics to aggregate by time periods.

const revenue = Orders.metric('revenue', { measure: 'revenue' });
const monthlyRevenue = revenue.by('month');

await analytics.execute(monthlyRevenue, {
  dimensions: ['country'],
});

Supported grains:

• day
• week
• month
• quarter
• year

Time key and timestamp dimensions

timeKey names the physical timestamp column used for time bucketing. It does not create a selectable dimension by itself.

If you also want callers to select, filter, or group by that timestamp through the dataset API, add a timestamp dimension that maps a semantic name to the same column:

const Orders = dataset('orders', {
  source: 'orders',
  timeKey: 'created_at',
  dimensions: {
    createdAt: dimension.timestamp({ column: 'created_at' }),
    country: dimension.string(),
  },
  measures: {
    revenue: measure.sum('amount'),
  },
});

With that setup, .by('month') buckets on created_at, while dataset queries can still use the semantic dimension name createdAt.