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:-----------------------------> .-,---------------------------------------------------. V | >--[----{--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
- 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
- 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
- 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
- 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.