Example: Create a time series through the wire listener

This example shows how to create, load, and query a time series with the MongoDB API or the REST API through the wire listener.

Before you begin

Before you start this example, ensure these tasks are complete:

  • Connect to a database in which to create the time series table. You run all methods in the database.
  • Configure the wire listener for the MongoDB API or the REST API. For more information, see Configuring the wire listener for the first time.
  • Define a dbspace that is named dbspace1. For more information, see Dbspaces.

About this task

In this example, you create a time series that contains sensor readings about the temperature and humidity in a house. Readings are taken every 10 minutes. The following table lists the time series properties that are used in this example.
Table 1. Time series properties used in this example
Time series propertyDefinition
Timepoint size10 minutes
When timepoints are validEvery 10 minutes
Data in the time seriesThe following data:
  • Timestamp
  • A float value that represents temperature
  • A float value that represents humidity
Time series tableThe following columns:
  • A meter ID column of type INTEGER
  • A TimeSeries data type column
Origin2014-01-01 00:00:00.00000
RegularityRegular
Where to store the dataIn a container that you create
How to load the dataThrough a virtual table
How to access the dataThrough a virtual table

Procedure

To create a time series with the MongoDB API mongo shell or the REST API:
  1. Create a time series calendar. The time series calendar is named ts_10min, with a calendar and pattern start date of 2014-01-01 00:00:00, a calendar pattern that is defined with intervals of minutes, and data is recorded in 10 minute increments after the origin.
    MongoDB API
    Add to the predefined system.timeseries.calendar collection.
    db.system.timeseries.calendar.insert({"name":"ts_10min", 
 "calendarStart":"2014-01-01 00:00:00",
 "patternStart":"2014-01-01 00:00:00", 
 "pattern":{"type":"minute", 
          "intervals":[{"duration":"1","on":"true"}, 
                     {"duration":"9","on":"false"}]}})
    REST API
    Request:
    Specify the POST method and the system.timeseries.calendar collection:
    POST /stores_demo/system.timeseries.calendar
    Data:
    Specify the calendar attributes:
    {"name":"ts_10min", 
 "calendarStart":"2014-01-01 00:00:00",
 "patternStart":"2014-01-01 00:00:00", 
 "pattern":{"type":"minute", 
          "intervals":[{"duration":1,"on":true}, 
                     {"duration":9,"on":false}]}}
    Response:
    The following response indicates that the operation was successful:
    [{"ok":true}]
  2. Create a TimeSeries row type. The row type is named reading and includes fields for timestamp, temperature, and humidity.
    MongoDB API
    Add to the predefined system.timeseries.rowType collection.
    db.system.timeseries.rowType.insert({"name":"reading",
"fields":[{"name":"tstamp","type":"datetime year to fraction(5)"},
        {"name":"temp","type":"float"},
        {"name":"hum","type":"float"}]})
    REST API
    Request:
    Specify the POST method and the system.timeseries.rowType collection:
    POST /stores_demo/system.timeseries.rowType
    Data:
    Specify the row type attributes:
    {"name":"reading",
"fields":[{"name":"tstamp","type":"datetime year to fraction(5)"},
        {"name":"temp","type":"float"},
        {"name":"hum","type":"float"}]}
    Response:
    The following response indicates that the operation was successful:
    [{"ok":true}]
  3. Create a container. The container is named c_0 and is created in the dbspace1 dbspace, in the reading time series row, with a first extent size of 1000, and with growth increments of 500.
    MongoDB API
    Add to the predefined system.timeseries.container collection.
    db.system.timeseries.container.insert({"name":"c_0",
 "dbspaceName":"dbspace1",
 "rowTypeName":"reading",
 "firstExtent":1000,
 "nextExtent":500})
    REST API
    Request:
    Specify the POST method and the system.timeseries.container collection:
    POST /stores_demo/system.timeseries.container
    Data:
    Specify the container attributes:
    {"name":"c_0",
 "dbspaceName":"dbspace1",
 "rowTypeName":"reading",
 "firstExtent":1000,
 "nextExtent":500}
    Response:
    The following response indicates that the operation was successful:
    [{"ok":true}]
  4. Create a time series table. The time series table is named ts_data1 and includes id and ts columns.
    MongoDB API
    Create the ts_data1 time series table:
    db.runCommand({"create":"ts_data1",
 "columns":[{"name":"id","type":"int","primaryKey":"true","notNull":"true"},
          {"name":"ts","type":"timeseries(reading)"}]})
    REST API
    Request:
    Specify the GET method:
    GET /stores_demo/$cmd?query={create:"ts_data1",
 		"columns":[{"name":"id","type":"int","primaryKey":true,"notNull":true},
          {"name":"ts","type":"timeseries(reading)"}]}
    Data:
    None.
    Response:
    The following response indicates that the operation was successful:
    [{"ok":true}]
  5. Create a virtual table. The virtual table is named ts_data1_v and is based on the time series table that is named ts_data1 and its timeseries column ts, using the ts_10min calendar, starting on 2014-01-01 00:00:00.00000, in the time series container c_0, with the virtualTableMode parameter set to 0 (default).
    MongoDB API
    Create the ts_data1_v virtual table:
    db.runCommand({"create":"ts_data1_v",
 "timeseriesVirtualTable":
         {"baseTableName":"ts_data1",
          "newTimeseries":"calendar(ts_10min),origin(2014-01-01 00:00:00.00000),container(c_0)", 
          "virtualTableMode":0,
          "timeseriesColumnName":"ts"}})
    REST API
    Request:
    Specify the GET method:
    GET /stores_demo/$cmd?query={"create":"ts_data1_v",
 "timeseriesVirtualTable":
         {"baseTableName":"ts_data1",
          "newTimeseries":"calendar(ts_10min),
                         origin(2014-01-01 00:00:00.00000),
                         container(c_0)", 
                         "virtualTableMode":0,
                         "timeseriesColumnName":"ts"}}
    Data:
    None.
    Response:
    The following response indicates that the operation was successful:
    [{"ok":true}]
  6. Load records into the time series by inserting documents into the ts_data1_v virtual table.

    Because this time series is regular, you are not required to include the time stamp. The first record is inserted for the origin of the time series, 2014-01-01 00:00:00.00000. The second record has the time stamp 2014-01-01 00:10:00.00000, and the third record has the time stamp 2014-01-01 00:20:00.00000.

    MongoDB API
    Add documents to the ts_data1_v virtual table:
    db.ts_data1_v.insert([{"id":1,"temp":15.0,"hum":20.0},	{"id":1,"temp":16.2,hum:19.0},{id:1,temp:16.5,hum:22.0}])
    REST API
    Request:
    Specify the POST method:
    POST /stores_demo/ts_data1_v
    Data:
    Specify the documents to load:
    [{"id":1,"temp":15.0,"hum":20.0},
{"id":1,"temp":16.2,"hum":19.0},
{"id":1,"temp":16.5,"hum":22.0}]
    Response:
    The following response indicates that the operation was successful:
    {"ok":true}
  7. Query the time series data by using the ts_data1_v virtual table.
    MongoDB API
    Query the ts_data1_v virtual table:
    db.ts_data1_v.find()

Results:
> db.ts_data1_v.find()
{"id":1,"tstamp":ISODate("2014-01-01T06:00:00Z"),"temp":15,"hum":20}
{"id":1,"tstamp":ISODate("2014-01-01T06:10:00Z"),"temp":16.2,"hum":19}
{"id":1,"tstamp":ISODate("2014-01-01T06:20:00Z"),"temp":16.5,"hum":22}
    REST API
    Request:
    GET /stores_demo/ts_data1_v
    Data:
    None.
    Response:
    The following response indicates that the operation was successful:
    [{"id":1,"tstamp":{"$date":1388556000000},"temp":15.0,"hum":20.0},
 {"id":1,"tstamp":{"$date":1388556600000},"temp":16.2,"hum":19.0},
 {"id":1,"tstamp":{"$date":1388557200000},"temp":16.5,"hum":22.0}]