コンテンツにスキップ
machbase-neo
TQL
TQLの概要

TQLの概要

Machbase Neoは、Transforming Query Language（TQL）と、その実行用APIを提供します。

一般的なアプリケーション開発では、データベースから取得した表形式の結果を必要なデータ構造に変換し、加工してからJSON、CSV、チャートなどで出力します。
TQLでは、この処理を数行のスクリプトで実装できます。作成したTQLをHTTPエンドポイントとして公開し、APIのように呼び出すこともできます。

TQLとは

TQL（Transforming Query Language）は、データ変換用のDSLです。
データストリームの流れを定義します。各データ単位（レコード）は、key と value で構成されます。

  • key：通常は自動増加する整数（クエリ結果のROWNUMに相当）
  • value：実際のデータを格納するタプル

tql_records

TQLスクリプトは、データを取得する SRC 関数で始まり、変換結果を出力する SINK 関数で終わります。
その間に必要な数の MAP 関数を挿入し、データを必要な形式に変換できます。

tql_flow_min

tql_flow

SRC

  • SQL()：Machbase Neo、またはブリッジで接続した外部DBでSQLを実行してレコードを生成
  • FAKE()：テスト用の仮想データを生成
  • CSV()：CSVファイルを読み取り
  • BYTES()：ファイルシステム、HTTPリクエスト、MQTTペイロードからバイナリデータを読み取り

tql_src

SINK

  • INSERT()：レコードをMachbase Neoのテーブルに書き込み
  • CHART()：レコードをチャートとして描画
  • JSON()、CSV()：データをそれぞれJSON、CSV形式にエンコード

tql_sink

MAP

MAP 関数は、データを別の形式に変換するための主要なツールです。
数学演算、文字列処理、形式変換、外部システムとの連携などを実行できます。

tql_map

TQLの実行

Web UIに接続する

ブラウザーで http://127.0.0.1:5654/ にアクセスし、アカウント（sys / manager）でログインしてください。

新しいTQLを作成する

上部の「New…」ページで「TQL」を選択してください。

サンプルコードを実行する

サンプルTQLコードをエディターに貼り付け、左上の ▶︎ アイコンをクリックしてください。
以下の例は、周波数1.5Hz、振幅1.0の波形をチャートに出力します。

FAKE( oscillator(freq(1.5, 1.0), range('now', '3s', '10ms')) )
CHART_SCATTER()

さまざまな出力形式

  • CSV：スプレッドシートなど、CSVファイルを読み取るツールとの連携に適しています。
  • JSON：WebアプリケーションやAPIと連携しやすい構造です。

TQLで形式を簡単に変更できます。

FAKE( oscillator(freq(1.5, 1.0), range('now', '3s', '10ms')) )
JSON()

APIとして使用する

右上の保存アイコンをクリックして、コードを hello.tql として保存してください。
その後、http://127.0.0.1:5654/db/tql/hello.tql にアクセスするか、curl で呼び出してデータを取得できます。

アイコン説明
スクリプトを保存すると右上にリンクアイコンが表示されます。クリックすると、スクリプトのアドレスをコピーできます。
curl -o - http://127.0.0.1:5654/db/tql/hello.tql
$ curl -o - -v http://127.0.0.1:5654/db/tql/hello.tql
...
< HTTP/1.1 200 OK
< Content-Type: text/csv
<
1686787739025518000,-0.238191
1686787739035518000,-0.328532
...

HTTPヘッダーを含むCSVレスポンスの例です。

$ curl -o - -v http://127.0.0.1:5654/db/tql/hello.tql
...omit...
>
< HTTP/1.1 200 OK
< Content-Type: text/csv
< Transfer-Encoding: chunked
<
1686787739025518000,-0.238191
1686787739035518000,-0.328532
1686787739045518000,-0.415960
1686787739055518000,-0.499692
1686787739065518000,-0.578992
...omit...

JSON()に変更する

CSV() を JSON() に変更して保存し、再度呼び出すと、JSON形式で結果を取得できます。

curl -o - http://127.0.0.1:5654/db/tql/hello.tql

HTTPヘッダーを含むJSONレスポンスの例です。

$ curl -o - -v http://127.0.0.1:5654/db/tql/hello.tql
...omit...
< HTTP/1.1 200 OK
< Content-Type: application/json
< Transfer-Encoding: chunked
<
{
"data": {
    "columns": [ "time", "value" ],
    "types": [ "datetime", "double" ],
    "rows": [
    [ 1686788907538618000, 0.9344920354538058 ],
    [ 1686788907548618000, 0.8968436523101743 ],
    ...omit...
},
"success": true,
"reason": "success",
"elapse": "956.291µs"
}

transpose()を指定したJSON()

データ可視化アプリケーションを開発する場合、 TQLのJSON出力では結果を行単位から列単位に転置できることを覚えておくと便利です。 JSON( transpose(true) ) を指定して再度呼び出すと、結果のJSONに cols 配列が含まれます。

$ curl -o - -v http://127.0.0.1:5654/db/tql/hello.tql
...omit...
< HTTP/1.1 200 OK
< Content-Type: application/json
< Transfer-Encoding: chunked
<
{
"data": {
    "columns": [ "time", "value" ],
    "types": [ "datetime", "double" ],
    "cols": [
        [ 1686789517241103000, ...omit..., 1686789520231103000],
        [ -0.7638449771082523, ...omit..., 0.8211935584502427]
    ]
},
"success": true,
"reason": "success",
"elapse": "1.208166ms"
}

この機能を使うと、他のアプリケーションからデータにアクセスするRESTful APIを簡単に作成できます。

INSERT

CSV() を INSERT("time", "value", table("example"), tag("temperature")) に変更して再実行します。

テーブルを検索する 

SQL('select * from tag limit 10')
CSV()
最終更新日
基礎