コンテンツにスキップ
machbase-neo
TQL
読み取りAPIとして使用

読み取りAPIとして使用

例を実行する前に、以下のSQLでテーブルとデータを準備してください。
CREATE TAG TABLE IF NOT EXISTS EXAMPLE (
    NAME VARCHAR(20) PRIMARY KEY,
    TIME DATETIME BASETIME,
VALUE DOUBLE SUMMARIZED);

INSERT INTO EXAMPLE VALUES('TAG0', TO_DATE('2021-08-12'), 10);
INSERT INTO EXAMPLE VALUES('TAG0', TO_DATE('2021-08-13'), 11);

TQLスクリプトを保存すると、エディターの右上に アイコンが表示されます。クリックすると、スクリプトのアドレスをコピーできます。

CSV

以下のコードを output-csv.tql として保存してください。

1
2

SQL( `select * from example limit 2` )
CSV()

curl コマンドでTQLを呼び出してください。

$ curl http://127.0.0.1:5654/db/tql/output-csv.tql
TAG0,1628694000000000000,10
TAG0,1628780400000000000,11

JSON

以下のコードを output-json.tql として保存してください。

1
2

SQL( `select * from example limit 2` )
JSON()

curl コマンドでTQLを呼び出してください。

$ curl http://127.0.0.1:5654/db/tql/output-json.tql
{
    "data": {
        "columns": [ "NAME", "TIME", "VALUE" ],
        "types": [ "string", "datetime", "double" ],
        "rows": [
            [ "TAG0", 1628694000000000000, 10 ],
            [ "TAG0", 1628780400000000000, 11 ]
        ]
    },
    "success": true,
    "reason": "success",
    "elapse": "770.078µs"
}

NDJSON

以下のコードを output-ndjson.tql として保存してください。

1
2

SQL( `select * from example limit 2` )
NDJSON( )

curl コマンドでTQLを呼び出してください。

$ curl http://127.0.0.1:5654/db/tql/output-ndjson.tql
{ "NAME": "TAG0", "TIME": 1628694000000000000, "VALUE": 10 }↵
{ "NAME": "TAG0", "TIME": 1628780400000000000, "VALUE": 11 }↵
↵

MARKDOWN

以下のコードを output-markdown.tql として保存してください。

1
2

SQL( `select * from example limit 2` )
MARKDOWN()

curl コマンドでTQLを呼び出してください。

$ curl http://127.0.0.1:5654/db/tql/output-markdown.tql
|NAME|TIME|VALUE|
|:-----|:-----|:-----|
|TAG0|1628694000000000000|10.000000|
|TAG0|1628780400000000000|11.000000|

HTML

HTML() 関数は、テンプレート言語を使って結果をHTML文書として出力します。
クエリ結果に合わせて、HTMLの構造とスタイルを自由に構成できます。

{{ .V.column_name }} のようにカラム値を読み取ったり、{{ if .IsFirst }}、{{ if .IsLast }} の条件で最初と最後の行に応じてテンプレートを制御したりできます。TQLスクリプトだけで、表やレポートなどのさまざまなHTML表現を生成できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

SQL(`select name, time, value from example limit 5`)
HTML({
{{ if .IsFirst }}
    <html>
    <body>
        <h2>HTML Template Example</h2>
        <hr>
        <table>
{{ end }}
    <tr>
        <td>{{ .V.name }}</td>
        <td>{{ .V.time }}</td>
        <td>{{ .V.value }}</td>
    </tr>
{{ if .IsLast }}
    </table>
        <hr>
        Total: {{ .Num }}
    </body>
    </html>
{{ end }}
})

CHART

TQLファイルの保存

以下のコードを output-chart.tql として保存してください。

1
2
3
4
5
6
7
8

SQL(`select time, value from example where name = ? limit 2`, "TAG0")
CHART(
    chartOption({
        xAxis: { data: column(0) },
        yAxis: {},
        series: { type:"bar", data: column(1) }
    })
)

HTTP GET

Webブラウザーで http://127.0.0.1:5654/db/tql/output-chart.tql を開いてください。

従来の CHART_LINE()、CHART_BAR()、CHART_SCATTER() 系の関数は、新しい CHART() 関数に置き換えられました。
例は CHART() を参照してください。

chartJson()の使用

TQLファイルの保存

以下のコードを output-chart.tql として保存してください。

1
2
3
4
5
6
7
8
9

SQL(`select time, value from example where name = ? limit 2`, "TAG0")
CHART(
    chartJson(true),
    chartOption({
        xAxis: { data: column(0) },
        yAxis: {},
        series: { type:"bar", data: column(1) }
    })
)

HTTP GET

Webブラウザーで http://127.0.0.1:5654/db/tql/output-chart.tql を開いてください。

{
  "chartID":"MzM3NjYzNjg5MTYxNjQ2MDg_", 
  "jsAssets": ["/web/echarts/echarts.min.js"],
  "jsCodeAssets": ["/web/api/tql-assets/MzM3NjYzNjg5MTYxNjQ2MDg_.js"],
  "style": {
      "width": "600px",
      "height": "600px"	
  },
  "theme": "white"
}

chartID()の使用

TQLファイルの保存

以下のコードを output-chart.tql として保存してください。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

SQL(`select time, value from example where name = ? limit 2`, "TAG0")
CHART(
    chartID("myChart"),
    chartJson(true),
    chartOption({
        xAxis: { data: column(0) },
        yAxis: {},
        series: { type:"bar", data: column(1) }
    })
)

HTTP GET

Webブラウザーで http://127.0.0.1:5654/db/tql/output-chart.tql を開いてください。

{
  "chartID":"myChart", 
  "jsAssets": ["/web/echarts/echarts.min.js"],
  "jsCodeAssets": ["/web/api/tql-assets/myChart.js"],
  "style": {
      "width": "600px",
      "height": "600px"	
  },
  "theme": "white"
}

この方法は、DOM文書に <div id='myChart'></div> がある場合に便利です。

... HTML内 ...
<div id='myChart'></div>
<script>
    fetch('http://127.0.0.1:5654/db/tql/output-chart.tql').then( function(rsp) {
        return rsp.json();
    }).then( function(c) {
        c.jsAssets.concat(c.jsCodeAssets).forEach((src) => {
            const sScript = document.createElement('script');
            sScript.src = src;
            sScript.type = 'text/javascript';
            document.getElementsByTagName('head')[0].appendChild(sScript);
        })
    })
</script>
... omit ...

結果データのキャッシュ

Since v8.0.43

以下のように、CSV()、JSON()、NDJSON()、HTML() シンクに cache() オプション関数を指定できます。

SQL( "select * from example limit ?, 1000",  param("offset") ?? 0 )
JSON( cache( param("offset") ?? "0", "60s" ) )

cache() オプションは、必須の CACHE_KEY と TTL、省略可能な r を受け取ります。

構文: cache(CACHE_KEY string, TTL string, [r float])

  1. 最初のパラメーター CACHE_KEY は、キャッシュデータの登録と検索に使用します。キーは [filename] + [source_code_hash] + [CACHE_KEY] で構成されます。 そのため、同じTQL（同じファイル名とコード）を同じ CACHE_KEY で実行すると、 キーは同じになり、後から実行した結果が既存のキャッシュデータを上書きします。
  2. 2番目のパラメーター TTL は、指定した期間後にキャッシュを自動削除します。 TTLの経過後に受け取ったリクエストは、実際のDBを検索して結果データを返し、 その結果を再びキャッシュに登録します。
  3. 3番目の省略可能なパラメーター r は、先行キャッシュ更新率（preemptive-cache-update-ratio）です。 0より大きく1.0未満の値を指定します。 r * TTL から TTL の間に受け取った最初のリクエストには、 現在のキャッシュデータを返してからクエリを実行し、キャッシュを更新します。 後続のリクエストは、更新済みの結果をキャッシュから取得します。 これにより、頻繁に要求される CACHE_KEY のキャッシュデータをバックグラウンドで継続的に更新できます。

コードを変更すると source_code_hash が変わるため、キャッシュミスになります。 TTLが経過してキャッシュが自動削除された場合も、キャッシュミスになります。 いずれの場合もリクエストを実行し、その結果をキャッシュに登録します。

この動作は、シンク関数に cache() オプションを指定した場合にのみ適用されます。 cache() を指定していないTQLは、キャッシュを検索しません。

注意：キャッシュを過度に使用すると、メモリが不足する可能性があります。 たとえば、数十億件のレコードをSELECTするTQLでcache()を使用する場合などです。

最終更新日
書き込みAPIとして使用SRC