hyperdb-downsampling

Tiered time series downsampling for HyperDB using d3. Show recent data in full detail, older data progressively aggregated.

Install

npm install hyperdb-downsampling

Usage

import { downsample } from 'hyperdb-downsampling'

Simple downsampling

Aggregate all data into hourly averages:

const result = downsample(data, {
  field: 'value',
  tiers: [
    { label: 'hourly', to: Infinity, interval: 'hour' }
  ]
})

Tiered downsampling

Show raw data for the last 10 seconds, 10-second averages up to 1 minute, and minute averages up to 5 minutes:

const result = downsample(data, {
  field: 'value',
  tiers: [
    { label: 'raw', to: 10_000 },
    { label: '10s_avg', from: 10_000, to: 60_000, interval: '10s' },
    { label: '1min_avg', from: 60_000, to: 300_000, interval: 'minute' },
  ]
})

Custom aggregation

Each tier defaults to mean, but you can choose min, max, median, or sum:

const result = downsample(data, {
  field: 'value',
  tiers: [
    { label: 'raw', to: 10_000 },
    { label: '10s_max', from: 10_000, to: 60_000, interval: '10s', aggregate: 'max' },
    { label: '1min_min', from: 60_000, to: 300_000, interval: 'minute', aggregate: 'min' },
  ]
})

API

downsample(data, options)

data — Array of objects with a timestamp field and one or more numeric fields.

options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | field | string | — | The numeric field to aggregate | | tiers | Tier[] | — | Array of tier configurations | | timestampField | string | 'timestamp' | Name of the timestamp field |

Tier configuration:

| Option | Type | Default | Description | |--------|------|---------|-------------| | label | string | — | Name for this tier (included in output) | | from | number | 0 | Min age in ms (inclusive) | | to | number | — | Max age in ms (exclusive) | | interval | string | — | Aggregation interval. Omit for raw data | | aggregate | string | 'mean' | One of mean, min, max, median, sum |

Available intervals: 5s, 10s, 30s, second, minute, hour, day, week, month

Output

Returns a sorted array of objects:

[
  { date: Date, value: 14.2, tier: 'raw' },
  { date: Date, value: 15.1, tier: '10s_avg' },
  { date: Date, value: 14.8, tier: '1min_avg' },
]

Example with HyperDB

import { downsample } from 'hyperdb-downsample'

const all = await db.find('@collection/readings').toArray()

const result = downsample(all, {
  field: 'value',
  tiers: [
    { label: 'raw', to: 10_000 },
    { label: '10s_avg', from: 10_000, to: 60_000, interval: '10s' },
    { label: '1min_avg', from: 60_000, to: 300_000, interval: 'minute' },
  ]
})

License

ISC