Time series collections and table formats

You can add, view, and remove documents from the time series collections with REST API and MongoDB API methods to create and manage your time series. You must use a specific format to create time series tables and virtual tables that are based on time series tables.

For the REST API, use the GET, POST, and DELETE methods to view, insert, or delete data in the time series collections.

For the MongoDB API, use the query, create, or remove methods to view, insert, or delete data in the time series collections.

The time series collections are virtual collections that are used to manage the objects that are required to store time series data in a database.

system.timeseries.calendar collection

The system.timeseries.calendar collection stores the definitions of predefined and user-defined calendars. A calendar controls the times at which time series data can be stored. The calendar definition embeds the calendar pattern definition. For details and restrictions about calendars, see Calendar data type. For a list of predefined calendars, see Predefined calendars.

Use the following format to add a calendar to the system.timeseries.calendar collection.

calendar

{ name : " calendar_name " , calendarStart : " start_date " , patternStart : " pattern_date " , pattern : { type : " interval " , intervals : [ { duration : " num_intervals " , on : { true | false } } ] } }
name
The name of the calendar.
calendarStart
The start date of the calendar.
patternStart
The start date of the calendar pattern.
pattern
The calendar pattern definition.
type
The time interval. Valid values for interval are: second, minute, hour, day, week, month, year.
intervals
The description of when to record data.
duration
The number of intervals, as a positive integer.
on
Whether to record data during the interval:
true = Recording is on.
false = Recording is off.

system.timeseries.rowType collection

The system.timeseries.rowType collection stores TimeSeries row type definitions. The TimeSeries row type defines the structure for the time series data within a single column in the database. For details and restrictions on TimeSeries row types, see TimeSeries data type.

Use the following format to add a TimeSeries row type to the system.timeseries.rowType collection.

{ name : " rowtype_name " , fields : [ { name : " field_name " , type : " data_type " } ] }
name
The rowtype_name is the name of the TimeSeries row type.
fields
name
The name of the field in the row data type. The field_name must be unique for the row data type. The number of fields in a row type is not restricted.
type
Must be datetime year to fraction(5) for the first field, which contains the time stamp.
The data type of the field. Most data types are valid for fields after the time stamp field.

system.timeseries.container collection

The system.timeseries.container collection stores container definitions. Time series data is stored in containers. For details and restrictions on containers, see TSContainerCreate procedure. Rolling window container syntax is not supported.

Use the following format to add a container to the system.timeseries.container collection.

{ name : " container_name " , dbspaceName : " dbspace_name " , rowTypeName : " rowtype_name " , firstExtent : extent_size , nextExtent : next_extent_size }
name
The container_name is the name of the container. The container name must be unique.
dbspaceName
The dbspace_name is the name of the dbspace for the container.
rowTypeName
The rowtype_name is the name of an existing TimeSeries row type in the system.timeseries.rowType collection.
firstExtent
The extent_size is a number that represents the first extent size for the container, in KB.
nextExtent
The next_extent_size is a number that represents the increments by which the container grows, in KB. The value must be equivalent to at least 4 pages.

Time series table format

A time series table must have a primary key column that does not allow null values. The last column in the time series table must be the TimeSeries column. For details and restrictions on time series tables, see Create the database table.

The following format describes the simplest structure of a time series table. You can include other options and columns in a time series table.

{ collection : " table_name " , options : { columns : [ { name : " col_name " , type : " data_type " , primaryKey : true , notNull : true } , { name : " col_name " , type : " timeseries ( rowtype_name ) " } ] } }
collection
The table_name is the name of the time series table.
options
The collection definition.
columns
The column definitions.
name
The col_name is the name of the column.
type
The data_type is the data type of the column.
For the TimeSeries column, the rowtype_name is the name of an existing TimeSeries row type in the system.timeseries.rowType collection.
primaryKey
true = The column is the primary key.
notNull
true = The column does not allow null values.

Virtual table format

You use a virtual table that is based on the time series table to insert and query time series data.

{ collection : " virtualtable_name " , options : { timeseriesVirtualTable : { baseTableName : " table_name " , newTimeSeries : " calendar ( calendar_name ) , origin ( origin ) , container ( container_name ) [ { , irregular | , regular } ] , virtualTableMode : mode , timeseriesColumnName : " col_name " } } }
collection
The virtualtable_name is the name of the virtual table.
options
timeseriesVirtualTable
The definition of the virtual table.
baseTableName
The table_name is the name of the time series table.
newTimeseries
The time series definition.
calendar
The calendar_name is the name of a calendar in the system.timeseries.calendar collection.
origin
The origin is the first time stamp in the time series. The data type is DATETIME YEAR TO FRACTION(5).
container
The container_name is the name of a container in the system.timeseries.container collection.
regular
Default. The time series is regular.
irregular
The time series is irregular.
virtualTableMode
The mode is the integer value of the TSVTMode parameter that controls the behavior and display of the virtual table for time series data. For the settings of the TSVTMode parameter, see The TSVTMode parameter.
timeseriesColumnName
The col_name is the name of the TimeSeries column.