基礎

基本型

TQLは、文字列（string）、数値（number）、ブール値（boolean）、時刻（time）型をサポートします。

文字列（string）

文字列は、単一引用符（’）、二重引用符（"）、バッククォート、中括弧で囲めます。バッククォートは、複数行の文字列や引用符を含む長いSQL文に便利です。

複数行のテキストにバッククォートや中括弧（{、}）が含まれ、区切り文字と衝突する場合は、タグ付きリテラルを使用できます。

• タグ付きバッククォート：`<<TAG ... TAG`
• タグ付き中括弧：({<<TAG ... TAG})

どちらも内容をrawテキストとして扱い、終了行のタグで閉じます。

SQL( 'select * from example where name=\'temperature\' limit 10' )
CSV()

SQL( "select * from example where name='temperature' limit 10" )
CSV()

SQL( `select *
      from example
      where name='temperature'
      limit 10` )
CSV()

SCRIPT(`<<JS
// '{' を返す関数
function a () { return '{' }
JS`)
CSV()

MARKDOWN({<<MD
```mermaid
erDiagram
    CUSTOMER ||--o{ ORDER :places
```
MD})

二重中括弧（{{ }}）を使うと、引用符をエスケープせずにJSON文字列を記述できます。

STRING({{
    "name": "Connan",
    "hired": true,
    "company": {
        "name":"acme",
        "employee": 123
    }
}})
CSV()

バッククォートでJSONを記述する例です。

1
2
3
4
5
6
7
8
9

STRING(`{ 
    "name": "Connan",
    "hired": true,
    "company": {
        "name":"acme",
        "employee": 123
    }
}`)
CSV()

数値（number）

すべての数値リテラルは64ビット浮動小数点数として処理されます。

SQL_SELECT('time', 'value', from('example', 'temperature'), limit(10))
CSV()

FAKE( oscillator( freq(12.34, 20), range("now", "1s", "100ms")) )
CSV()

ブール値（boolean）

ブール定数は true と false です。

FAKE( linspace(0, 1, 1))
CSV( heading(false) )

時刻（time）

time()、parseTime() 関数で生成するか、SQLの結果の DATETIME カラムから取得できます。

タイムゾーン（timeZone）

tz() 関数でタイムゾーンを指定できます。例：tz('UTC')、tz('Local')、tz('Asia/Seoul')

リスト（list）

list() 関数で値の配列を生成します。例：list(1, 2, 3)

辞書（dictionary）

dict() 関数は、文字列のキーと値のペアからなる辞書を生成します。例：dict("name", "pi", "value", 3.14)

文の記述規則

文字列、数値、ブール値のリテラルを除き、すべての文は関数呼び出しの形式で記述します。

// コメントは '//' で記述します。
SQL_SELECT(
    'time', 'value',
    from('example', 'temperature'),
    limit(10)
)
CSV()

SRCとSINK

.tql スクリプトは、データを生成する**ソース（SRC）関数で始める必要があります。SQL()、SQL_SELECT()、SCRIPT() などが該当します。最後の文は、結果を出力または保存するシンク（SINK）**関数である必要があります。代表例は CSV()、JSON()、APPEND()、CHART() です。

MAP関数

ソースとシンクの間には、0個以上のMAP関数を配置できます。MAP関数名は大文字で始まり、内部のオプションは小文字で始まるキャメルケースの関数で指定します。

SQL_SELECT(
    'time', 'value',
    from('example', 'temperature'),
    limit(10)
)
DROP(5)
TAKE(5)
CSV()

パラメーター（param）

HTTPで .tql スクリプトを呼び出す際にクエリパラメーターを渡し、param() 関数で値を読み取れます。

SQL_SELECT(
    'time', 'value',
    from('example', param('name')),
    limit( param('count') )
)
CSV()

たとえば、ファイルを hello2.tql として保存し、http://127.0.0.1:5654/db/tql/hello2.tql?name=temperature&count=10 で呼び出すと、param('name') は "temperature"、param('count') は文字列 "10" を返します。

SQL( `select * from example where name = ?`, param('name'))
CSV()

curl "http://127.0.0.1:5654/db/tql/param.tql?name=TAG0"

演算子

算術演算子

+、-、*、/ の4つの算術演算をサポートします。

1
2
3

FAKE(linspace(1, 10, 5))
MAPVALUE( 1, value(0) * 100 )
CSV()

1,100
3.25,325
5.5,550
7.75,775
10,1000

剰余演算子

% で表す剰余演算子（モジュロ演算子）は、算術演算子です。 整数除算の余りを返します。

1
2
3

FAKE(arrange(1, 10, 1))
FILTER(value(0) % 3 == 0)
CSV()

3
6
9

文字列の連結

+ 演算子のオペランドが文字列の場合、連結した文字列を返します。

1
2
3
4
5

FAKE(json({
    ["hello", "world"]
}))
MAPVALUE(2, value(0) + " " + value(1) + "?")
CSV()

hello,world,hello world?

比較演算子

1
2
3

FAKE(linspace(1, 5, 5))
FILTER( value(0) >= 4 )
CSV()

4
5

論理演算子

論理演算子は、論理積、論理和、否定を実行します。

1
2
3

FAKE(linspace(1, 5, 5))
FILTER( value(0) > 0  && mod(value(0), 2) == 0 )
CSV()

2
4

IN演算子

A in (args...) は、argsに A が含まれる場合にtrue、それ以外の場合にfalseを返します。

1
2
3
4
5
6
7
8

FAKE(json({
    ["A", 1.0],
    ["B", 1.5],
    ["C", 2.0],
    ["D", 2.5]
}))
FILTER( value(0) in ("A", "C") )
CSV()

1
2
3
4
5
6
7
8

FAKE(json({
    ["A", 1.0],
    ["B", 1.5],
    ["C", 2.0],
    ["D", 2.5]
}))
FILTER( value(1) in (1.5, 2.5) )
CSV()

三項演算子

三項演算子 ? : は、他のプログラミング言語のif-else文に似ています。 if-else文と同じ手順で条件に応じた値を選択します。

• param(’name’) が定義されているかどうか

1
2
3
4
5
6
7
8

SQL_SELECT(
    'time', 'value',
    from('example',
        param('name') == NULL ? 'temperature' : param('name')
    ),
    limit( param('count') ?? 10 )
)
CSV()

• 条件に応じた値の変更

1
2
3

FAKE(linspace(1, 5, 5))
MAPVALUE(0, mod(value(0), 2) == 0 ? value(0)*10 : value(0))
CSV()

1
20
3
40
5

Nil合体演算子

?? 演算子は左右のオペランドを受け取ります。左辺が定義されている場合はその値を返し、未定義の場合は右辺の値を返します。 以下は ?? 演算子の一般的な使用例です。呼び出し元がクエリパラメーターを指定しなかった場合、右辺の値を既定値として使用します。

1
2
3
4
5
6

SQL_SELECT(
    'time', 'value',
    from('example', param('name') ?? 'temperature'),
    limit( param('count') ?? 10 )
)
CSV()

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

例

SQL( `select * from example limit ?`, param('limit') ?? 1)
CSV()

curl http://127.0.0.1:5654/db/tql/param-default.tql

TAG0,1628694000000000000,10

curl http://127.0.0.1:5654/db/tql/param-default.tql?limit=2

TAG0,1628694000000000000,10
TAG0,1628780400000000000,11

プラグマ

//+ name=value ディレクティブは、Machbase NeoによるTQLスクリプトの実行方法を指定します。

log-level

ログレベルを [TRACE | DEBUG | INFO | WARN | ERROR] のいずれかに設定します。 既定値は ERROR です。HTTPおよびMQTT APIから呼び出した場合、ほとんどのログメッセージを抑制します。

1
2
3
4

//+ log-level=TRACE
SQL(`select * from my_table where name = ?`, param("name"))
WHEN(true, doLog('hello world'))
CSV()

sql-thread-lock

このプラグマは、指定した SQL() を専用のネイティブスレッドで実行します。 スレッドはTQLスクリプトの終了時に終了します。 SRCの SQL() でのみ動作します。

100個のHTTPクライアントが同時にTQLファイルを実行する内部性能テストでは、 このオプションを有効にするとレスポンスのレイテンシーが35%増加しますが、メモリ解放の遅延が大幅に減少しました。

1
2
3
4

//+ sql-thread-lock
SQL(`select * from my_table where name = ?`, param("name"))
WHEN(true, doLog('hello world'))
CSV()