MODE 時系列データベースの使い方 (Collection 編)

エンジニアの野本です。先日時系列データベース (以下 TSDB) の新バージョンリリースをお知らせしました。

「MODE Core Platform」における時系列データベースの新バージョンリリースのお知らせ

主なアップデートとして「多次元データ対応」あげられています。これは Collection という機能として提供しているもので、この記事中でもあるように次元数の多いデータを今までより簡単に扱えるようにする機能です。今回は Collection がどのようなものか、どのように使えるのかを簡単に紹介します。

Collection で何が変わったの?

以前のブログ記事で TSDB の基本的な使い方を紹介しました。今までは時系列データを 1 次元でのみ扱え、Series ID をキーとして 1 データポイント当たり 1 つの値のみ保持することが可能でした。

Series ID	日時	値
series-01	2020/06/01 00:00:42	4.88
series-01	2020/06/01 00:01:42	4.94
series-01	2020/06/01 00:02:42	4.94
series-02	2020/04/22 10:00:30	60
series-02	2020/04/22 10:02:22	-24

これが Collection により、1 データポイントが Collection として管理され、複数の値を保持出来るようになりました。

Collection ID: collection-01

日時	値:v1	値:v2	値:v3	タグ:version	タグ:ID
2020/06/01 00:00:42	4.88	24	1	V1	0001
2020/06/01 00:01:42	4.94	12	0	V1	0002
2020/06/01 00:02:42	4.94	35	1	V2	1001

Collection ID: collection-02

日時	値:temperature	値:co2	タグ:density
2020/06/01 00:00:42	30.88	800.2	normal
2020/06/01 00:01:42	29.94	880.2	normal
2020/06/01 00:02:42	28.94	1400.4	high

主な違いとして以下が上げられます

Series ID に変わり Collection ID でデータの集合を管理
各 Collection ごとに値の数や値の名称を設定出来る
データポイントに対し付加情報をタグとして付与出来る
- データ参照時にタグ情報も取得することで、取得したデータをタグで分類するようなことが可能
- タグも値と同様 Collection ごとに可変で名称を設定可能

このように、データポイントに対し柔軟に複数のデータを格納することが出来るようになりました。XYZ 軸がある加速度センサーや緯度経度を持つ位置情報など次元数の多いセンサーのデータを同時に扱うことが簡単になることが分かると思います。

Collection データの取得方法

基本的には先に紹介した Series ID により管理されたデータとほぼ同じ方法で格納されたデータを取得出来ます。Collection 固有のパラメータやどのような形式でデータを取得出来るのかを紹介します。Collection の API も詳細は公式ドキュメントに記載されているので参考にしてみて下さい。

Collection 一覧

現在格納されている Collection の一覧は以下のように確認出来ます。Collection に値やタグがどのようなキー名で保存されているかの情報も確認出来ます。

$ curl -X GET -H 'Authorization: ModeCloud [PROJECT_API_KEY]' https://api.tinkermode.com/homes/123/smartModules/tsdb/collections

[
  {
    "homeId": 123,
    "id": "collection1",
    "moduleId": "tsdb",
    "timeZone": "Asia/Tokyo",
    "tagNames": [
      "density",
    ],
    "valueNames": [
      "temperature",
      "co2"
    ]
  },
  {
    "homeId": 123,
    "id": "collection2",
    "moduleId": "tsdb",
    "timeZone": "Asia/Tokyo",
    "tagNames": [
      "tag1",
      "tag2",
      "tag3"
    ],
    "valueNames": [
      "v1",
      "v2",
      "v3",
      "v4"
    ]
  }
]

期間内データの取得

Collection ID をキーに期間指定してデータを取得します。期間指定や集約の種類の指定は Series データ取得時と同様です。Collection では 1 つのデータポイントに複数の値が格納されています。取得したい値の名称を selectValues パラメータにて指定します。複数の値を取得したい場合はカンマ区切リで指定します。期間による集約の解像度は Series データと同じです。

curl -X GET -H 'Authorization: ModeCloud [PROJECT_API_KEY]'  https://api.tinkermode.com/homes/123/smartModules/tsdb/collection/collection1/data\?begin\=2020-06-01T00:00:00.000Z\&end\=2020-06-30T00:59:59.999Z\&aggregation\=avg\&selectValues\=temperature,co2

{
  "aggregation": "avg",
  "begin": "2020-06-01T00:00:00Z",
  "collectionId": "collection1",
  "data": [
    [
      "2020-06-01T09:00:00+09:00",
      19.5,
      1289.7
    ],
    [
      "2020-06-01T09:00:15+09:00",
      18.7,
      849.2
    ],
    [
      "2020-06-01T09:01:15+09:00",
      17.3,
      1343.05
    ],
    ...
    [
      "2020-06-01T09:55:45+09:00",
      19.3,
      89.98
    ],
    [
      "2020-06-01T09:56:45+09:00",
      20.8,
      557.01
    ],
    [
      "2020-06-01T09:59:15+09:00",
      21.0,
      1503.12
    ]
  ],
  "end": "2020-06-01T00:59:59.999Z",
  "resolution": "15sec"
}

data キーの各データポイントの情報の配列です。各データポイントの情報も配列になっており、先頭がタイムスタンプ、以降は selectValues で指定した値が順番に入っています。

生のデータポイントの取得

Series データと同様、ts パラメータで開始日時を、 limit で取得最大件数を指定して生の Collection データを取得出来ます。期間による取得と同様 selectValues パラメータにて取得する値の設定が必要です。また、生のデータにはタグ情報も格納されているので selectTags パラメータにより取得したいタグ名を設定しタグの値も取得出来ます。

$ curl -X GET -H 'Authorization: ModeCloud [PROJECT_API_KEY]' https://api.tinkermode.com/homes/123/smartModules/tsdb/collections/collection1/data\?t\s=2020-06-01T00:00:00.000Z\&limit\=100\&selectValues\=temperature,co2\&selectTags\=density

{
  "collectionId": "collection1",
  "data": [
    [
      "2020-06-01T09:00:00+09:00",
      22.1,
      1881.01,
      "high"
    ],
    [
      "2020-06-01T09:00:09+09:00",
      17.0,
      698.57,
      "normal"
    ],
    [
      "2020-06-01T09:00:21+09:00",
      18.7,
      849.27,
      "normal"
    ],
    [
      "2020-06-01T09:01:16+09:00",
      19.3,
      1343.05,
      "high"
    ],
    [
      "2020-06-01T09:05:41+09:00",
      20.3,
      313.03,
      "normal"
    ],
    ...
  ],
  "limit": 100,
  "ts": "2020-06-01T00:00:00Z"

data キーの内容は期間指定のデータとほぼ同じで、selectTags で指定したタグ情報が値の次に格納されています。

データのエクスポート

Series データ同様 csv 形式でファイルをダウンロード出来ます。

$ payload=$(cat <<EOF
{
    "begin": "2020-04-01T00:00:00Z",
    "end": "2020-04-01T23:59:59Z",
    "collectionds": ["collection1"]
}
EOF)

$ curl -X POST -H 'Authorization: ModeCloud [PROJECT_API_KEY]' -d '${payload}' https://api.tinkermode.com/homes/123/smartModules/tsdb/export

2020/06/01 00:00:00,22.1,1881.01,high
2020/06/01 00:00:09,17.1,698.57,normal
2020/06/01 00:00:21,18.7,849.27,normal
2020/06/01 00:01:16,19.3,1343.05,high
2020/06/01 00:05:41,17.3,313.03,normal
2020/06/01 00:10:52,19.2,604.4,normal
2020/06/01 00:12:37,16.0,1030.42,high
2020/06/01 00:14:04,14.2,761.31,normal
...

まとめ

Collection として次元数の多いデータを扱えるようになったことにより今まで以上に幅広いセンサーや機器のデータを簡単に格納し、より柔軟に扱えるようになりました。ちなみに今までの 1 次元のデータも引き続き使うことが出来るので収集したいシンプルなセンサーは従来の方法で利用し続けたりデータの種類によって使い分けることが出来ます。次元数の多いデータのセンサーのデータを同時にうまく扱ったシステムを検討している方は是非一度ご利用をご検討してみて下さい!

MODE JAPAN Blog

IoTを活用したデジタルトランスフォーメーションのための情報、開発の現場から技術的な情報や取り組みについてお届けします。