getTimeSeries

A Time Series model is a data model that represents series of labeled numerical values, grouped into equally sized time intervals, such as days or years. Suitable for rendering time series charts.

Usage

const formula = await dataSource.getTimeSeries({
    column: 'column_A',
    ticks: 5,
    operation: 'count'
    // + base options...
});

Options

The getTimeSeries model inherits all options from the base options, plus:

export interface TimeSeriesRequestOptions extends BaseRequestOptions {
  column: string;
  stepSize: 'year' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
  stepMultiplier?: number;
  operation: 'count' | 'avg' | 'min' | 'max' | 'sum';
  operationColumn?: string | '*';
  operationExp?: string;
  splitByCategory?: string;
  splitByCategoryLimit?: number;
  splitByCategoryValues?: string[];
}

• column: the name of the column that will be used to get the time intervals. It must be a date/time column.

• stepSize: the time interval that the time series will use for grouping data. Accepted values are: year, month, week, day, hour, minute, and second.

• stepMultiplier (optional): use this multiplier to increase the bin that will be used within the step size. For example, a stepSize: day, stepMultiplier: 10 will return values in blocks of 10 days each. By default it's 1.

• operation: the statistical operation that will be performed on the operationColumn to get the numerical value for each time interval. Accepted values are: count, avg, min, max, and sum.

• operationColumn (optional): the name of the column that will be used to calculate the numerical value for each time interval. When using count, you can also use * to calculate total row count. Required when using an operation other than custom.

• operationExp (optional): a valid SQL expression to perform a custom aggregation. For example sum(sales)/sum(area) . Only applicable when using a custom operation.

You can generate multiple series in the same model by using the splitByCategory parameters

• splitByCategory (optional): the name of the column that will be used to group the values into multiple series.

• splitByCategoryLimit (optional): this is the maximum number of series (values in the splitByCategory ) column that the model will return. Unless specific values are requested in splyByCategoryValues, the model will return the top highest values for the entire time range, based on the operation used.

• splitByCategoryValues (optional): this is a list of specific values from the splitByCategory column that will be returned as time series in the model. No other values will be returned.

Response

The response is composed of two items:

• rows: A list of rows, where each row is an object that includes the time interval (name) and the associated value for that interval.

  • If using categories, it also includes the category for that row.

• categories: A list containing the requested categories.

Without categories

type TimeSeriesModelResponse = {
  rows: {name: string; value: number}[];
  categories: undefined;
};
/* example response 
  {
    rows: [
      { name: 1724976000, value: 389},
      { name: 1725062400, value: 647},
      { name: 1725148800, value: 478},
      { name: 1725235200, value: 120}
    ],
    categories: undefined
  }
*/    

With categories

type TimeSeriesModelResponse = {
  rows: {name: string; category: string; value: number}[];
  categories: string[];
};
/* example response 
  {
    rows: [
      { name: 1724976000, category: 'A', value: 389},
      { name: 1724976000, category: 'B', value: 738},
      { name: 1725062400, category: 'A', value: 647},
      { name: 1725062400, category: 'B', value: 1234},
      { name: 1725148800, category: 'A', value: 478},
      { name: 1725148800, category: 'B', value: 982},
      { name: 1725235200, category: 'A', value: 120},
      { name: 1725235200, category: 'B', value: 928}
    ],
    categories: ['A','B']
  }
*/    

The response can be then mapped to any HTML element, but more commonly it will be mapped to a a charting library to create time series charts.