Skip to content
MACHHUB MACHHUB MACHHUB
Contribute to this page

Historian (Time-Series)

The Historian stores all time-series tag readings for historical analysis and trending. Use it instead of Collections for time-series data. The sdk.historian namespace exports historized readings — with optional bucketing and aggregation — as a gzipped CSV Blob.

Exporting data as CSV

Section titled “Exporting data as CSV”

getHistoricalDataAsCSV exports one or more topics as a gzipped CSV Blob. With multiple topics the result is merged into a single CSV with columns [Timestamp, topic1, topic2, ...]. Optional time bucketing (sampleRate) and aggregation reduce the row count.

getHistoricalDataAsCSV(
  topics: string[],
  startDate: Date,
  endDate: Date,
  timezone?: string,
  sampleRate?: string,
  aggregation?: 'mean' | 'sum' | 'min' | 'max' | 'median' | 'none',
  mapping?: Record<string, string>,
): Promise<Blob>
ParameterTypeRequiredDescription
topicsstring[]YesTopic strings to export
startDateDateYesStart of the data range
endDateDateYesEnd of the data range
timezonestringNoIANA timezone, e.g. "Asia/Kuala_Lumpur"
sampleRatestringNoBucket interval in underscore format, e.g. "5_second", "1_minute", "1_hour"
aggregation'mean'|'sum'|'min'|'max'|'median'|'none'NoAggregation applied within each bucket
mappingRecord<string, string>NoRename topic columns in the CSV header

sampleRate format

Section titled “sampleRate format”

The bucket interval uses an underscore format: <count>_<unit>.

ValueMeaning
"5_second"5-second buckets
"1_minute"1-minute buckets
"15_minute"15-minute buckets
"1_hour"1-hour buckets
"1_day"Daily buckets

Examples

Section titled “Examples”
import { getOrInitializeSDK } from './sdk.service';


const sdk = await getOrInitializeSDK();


// Single topic, full resolution
const blob = await sdk.historian.getHistoricalDataAsCSV(
  ['Sensor/Temperature'],
  new Date('2024-01-01'),
  new Date('2024-01-31')
);


// Multiple topics, timezone + renamed columns
const renamed = await sdk.historian.getHistoricalDataAsCSV(
  ['Sensor/Temperature', 'Sensor/Humidity', 'Sensor/Pressure'],
  new Date('2024-01-01'),
  new Date('2024-01-31'),
  'Asia/Kuala_Lumpur',
  undefined,
  undefined,
  {
    'Sensor/Temperature': 'Temp °C',
    'Sensor/Humidity': 'Humidity %',
    'Sensor/Pressure': 'Pressure hPa',
  }
);


// Hourly average
const hourly = await sdk.historian.getHistoricalDataAsCSV(
  ['production/line1', 'production/line2'],
  new Date('2024-01-01'),
  new Date('2024-01-07'),
  'UTC',
  '1_hour',
  'mean'
);

Trigger a browser download

Section titled “Trigger a browser download”

The export is a Blob, so download it with an object URL — and revoke the URL when done.

const blob = await sdk.historian.getHistoricalDataAsCSV(
  ['Sensor/Temperature'],
  startDate,
  endDate,
  'Asia/Kuala_Lumpur',
  '1_minute',
  'mean'
);


const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = 'sensor_data.csv.gz';
a.click();
URL.revokeObjectURL(url);

Checklist

Section titled “Checklist”
  • Time-series data stored in the Historian (not Collections).
  • Time ranges bounded to what you need.
  • Aggregation / sampleRate used to reduce volume for large ranges.
  • Object URLs revoked after CSV downloads.

Next

Section titled “Next”