Basics

Primitive types

TQL has three types for primitive string, number and boolean.

string

Define constant strings as like traditional programming languages with quation marks, single(’), double (") and backtick(`). The backtick’ed string is usuful when you need to define a string in multiple lines including quation marks inside such as long SQL statement.

Example) Escaping single quote with backslash(\')

1
2

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

Example) Use multi-lines sql statement without escaping by backtick(`)

1
2
3
4
5

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

There is a user convenient way specifying JSON string in a TQL script by using double braces. It doesn’t require quotation marks escaping.

1
2
3
4
5
6
7
8
9

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

number

TQL treats all numberic constants as 64bit floating number.

1
2

QUERY( 'value', from('example', 'temperature'), limit(10))
CSV()

1
2

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

boolean

true and false

1
2

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

Statements

Every statement in TQL should be a function call except the literal constants of string, number and boolean.

// A comment line starts with '//'

// Each statement should start from first column.
QUERY(
    'value',
    from('example', 'temperature'),
    limit(10)
)
CSV()

SRC and SINK

Every .tql script should start with one source statement which can generates a record or records. For example, SQL(), QUERY() and SCRIPT() that generates records with yield(), yieldKey() can be a source. And the last statement should be a sink statement that encode the result or write into the database. For example, APPEND(), INSERT() and all CHART_XXX functions can be a sink.

MAP functions

There may be zero or more map functions between source and sink statements. The names of all map functions are with capital letters, in contrast lower case camel notation functions are used as arguments of the other map functions.

1
2
3
4
5
6
7
8

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

Query Param

When external applications call a *.tql script via HTTP it can provide arguments as query parameters. The function param() is purposed to retrieve the values from query parameters in TQL script.

If the script below saved as ‘hello2.tql’, applications can call this script by HTTP GET method with http://127.0.0.1:5654/db/tql/hello2.tql?name=temperature&count=10. Then param('name') returns “temperature”, param('count') is 10, as expected.

1
2
3
4
5
6

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

Query Param - Example

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

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

Operator ??

?? operator takes left and right operand. if left operand is defined it returns value of it, if left operand is not defined it returns right operand instead. The example below shows the common use case of the ?? operator. If caller did not provide query param variables, the right side operand will be taken as a default value.

1
2
3
4
5
6

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

Operator ?? - Example

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