You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Timeplus Enterprise provides a command-line interface (CLI) to run SQL commands via `timeplusd client`. The `timeplusd` executable is available in the `timeplus/bin` folder of [the bare metal packages](/release-downloads) and in the `PATH` of the `timeplus/timeplusd` Docker image.
3
+
`timeplusd client` is the native CLI for Timeplus Enterprise. It ships in the
4
+
`timeplus/bin` folder of [the bare-metal package](/release-downloads) and is on
5
+
`PATH` in the `timeplus/timeplusd` Docker image.
6
+
4
7
:::info
5
-
In the Docker/Kubernetes environments, you can also run `timeplusd-client` command, which will call `timeplusd client` command.
8
+
In Docker and Kubernetes environments the alias `timeplusd-client` is also
9
+
available and forwards to `timeplusd client`.
6
10
:::
7
11
8
-
Different client and server versions are compatible with one another, but some features may not be available in older clients. We recommend using the same version of the client as the server app. When you try to use a client of the older version, then the server, `timeplusd client` displays the message:
12
+
Client and server versions are cross-compatible, but newer server features may
13
+
be unavailable in older clients — keep them in sync when possible. A version
14
+
skew prints:
9
15
10
16
```
11
17
Timeplus client version is older than Timeplus server. It may lack support for new features.
12
18
```
13
19
14
20
## Usage {#cli_usage}
15
21
16
-
The client can be used in interactive and non-interactive (batch) mode. To use batch mode, specify the ‘query’ parameter, or send data to ‘stdin’ (it verifies that ‘stdin’ is not a terminal), or both. Similar to the HTTP interface, when using the ‘query’ parameter and sending data to ‘stdin’, the request is a concatenation of the ‘query’ parameter, a line feed, and the data in ‘stdin’. This is convenient for large INSERT queries.
22
+
The client runs in two modes:
23
+
24
+
-**Interactive** — started when no query is supplied. Enter queries at the
25
+
prompt, press Enter to submit (terminate with `;` when `--multiline` / `-m`
26
+
is set). Append `\G` to a query to force Vertical output (MySQL-style).
27
+
Ctrl+C cancels a running query; Ctrl+D, `exit`, `quit`, or `:q` exits the
28
+
shell. History is kept in `~/.timeplusd-client-history`.
29
+
-**Batch** — triggered by `--query` / `-q` and/or piping data to `stdin`.
30
+
The request sent to the server is the query, a newline, then `stdin` —
31
+
convenient for large `INSERT`s. Default output format is `PrettyCompact`;
32
+
override with `--format` / `-f`, `--vertical` / `-E`, or a `FORMAT` clause.
33
+
34
+
By default only a single statement runs per batch invocation. Use
35
+
`--multiquery` / `-n` to send several semicolon-separated statements in one
36
+
request (not supported for `INSERT`).
37
+
38
+
### Executing SQL {#executing-sql}
39
+
40
+
```bash
41
+
# interactive
42
+
timeplusd client -h 127.0.0.1 --ask-password
43
+
44
+
# one-shot
45
+
timeplusd client -q "SELECT version()"
46
+
timeplusd client -d mydb -q "SELECT count() FROM events"
47
+
48
+
# multiple statements (INSERT excluded)
49
+
timeplusd client -n -q "
50
+
CREATE STREAM IF NOT EXISTS demo(id int);
51
+
SELECT count() FROM demo;
52
+
"
53
+
54
+
# run a script file
55
+
timeplusd client --multiquery < statements.sql
56
+
timeplusd client --queries-file ./statements.sql
57
+
58
+
# diagnostics
59
+
timeplusd client --time -q "..."# elapsed time to stderr
-q "SELECT {col:identifier} FROM {db:identifier}.{tbl:identifier} LIMIT 10"
27
77
28
-
$ cat file.csv | timeplusd client --database=test --query="INSERT INTO test FORMAT CSV";
78
+
# tuples and other structured types work the same way
79
+
timeplusd client --param_t="(10, ('dt', 10))" \
80
+
-q "SELECT * FROM stream WHERE val = {t:tuple(uint8, tuple(string, uint8))}"
29
81
```
30
82
31
-
In batch mode, the default data format is TabSeparated. You can set the format in the FORMAT clause of the query.
83
+
Parameters can also be set inside a session:
32
84
33
-
By default, you can only process a single query in batch mode. To make multiple queries from a script, use the `--multiquery` parameter. This works for all queries except INSERT. Query results are output consecutively without additional separators. Similarly, to process a large number of queries, you can run ‘timeplusd client’ for each query. Note that it may take tens of milliseconds to launch the ‘timeplusd client’ program.
In interactive mode, you get a command line where you can enter queries.
89
+
See [Data types](/datatypes) for the full list of supported parameter types.
36
90
37
-
If ‘multiline’ is not specified (the default): To run the query, press Enter. The semicolon is not necessary at the end of the query. To enter a multiline query, enter a backslash `\` before the line feed. After you press Enter, you will be asked to enter the next line of the query.
91
+
## Loading Data {#loading-data}
38
92
39
-
If multiline is specified: To run a query, end it with a semicolon and press Enter. If the semicolon was omitted at the end of the entered line, you will be asked to enter the next line of the query.
93
+
`INSERT ... FORMAT <fmt>` reads rows from `stdin` in the named format. The
94
+
examples below assume:
40
95
41
-
Only a single query is run, so everything after the semicolon is ignored.
96
+
```sql
97
+
CREATE STREAM events (id uint64, name string, ts datetime64(3));
98
+
```
42
99
43
-
You can specify `\G` instead of or after the semicolon. This indicates Vertical format. In this format, each value is printed on a separate line, which is convenient for wide tables. This unusual feature was added for compatibility with the MySQL CLI.
100
+
### Text formats {#loading-text}
44
101
45
-
The command line is based on ‘replxx’ (similar to ‘readline’). In other words, it uses the familiar keyboard shortcuts and keeps a history. The history is written to `~/.timeplusd-client-history`.
102
+
```bash
103
+
# CSV, no header
104
+
cat <<EOF | timeplusd client -q "INSERT INTO events FORMAT CSV"
105
+
1,alice,2026-04-20 10:00:00.000
106
+
2,bob,2026-04-20 10:00:01.000
107
+
EOF
46
108
47
-
By default, the format used is PrettyCompact. You can change the format in the FORMAT clause of the query, or by specifying `\G` at the end of the query, using the `--format` or `--vertical` argument in the command line, or using the client configuration file.
109
+
# CSV with header — column order comes from the file
110
+
timeplusd client -q "INSERT INTO events FORMAT CSVWithNames"< events.csv
48
111
49
-
To exit the client, press Ctrl+D, or enter one of the following instead of a query: “exit”, “quit”, “logout”, “exit;”, “quit;”, “logout;”, “q”, “Q”, “:q”.
112
+
# tab-separated variants
113
+
timeplusd client -q "INSERT INTO events FORMAT TabSeparated"< events.tsv
114
+
timeplusd client -q "INSERT INTO events FORMAT TSVWithNames"< events_h.tsv
50
115
51
-
When processing a query, the client shows:
116
+
# NDJSON — inline or from a file
117
+
cat <<EOF | timeplusd client -q "INSERT INTO events FORMAT JSONEachRow"
timeplusd client -q "INSERT INTO events FORMAT JSONEachRow"< events.ndjson
122
+
```
52
123
53
-
1. Progress, which is updated no more than 10 times per second (by default). For quick queries, the progress might not have time to be displayed.
54
-
2. The formatted query after parsing, for debugging.
55
-
3. The result in the specified format.
56
-
4. The number of lines in the result, the time passed, and the average speed of query processing.
124
+
### Columnar formats {#loading-columnar}
57
125
58
-
You can cancel a long query by pressing Ctrl+C. However, you will still need to wait for a little for the server to abort the request. It is not possible to cancel a query at certain stages. If you do not wait and press Ctrl+C a second time, the client will exit.
126
+
```bash
127
+
timeplusd client -q "INSERT INTO events FORMAT Parquet"< events.parquet
128
+
timeplusd client -q "INSERT INTO events FORMAT ORC"< events.orc
129
+
timeplusd client -q "INSERT INTO events FORMAT Arrow"< events.arrow
130
+
```
59
131
60
-
The command-line client allows passing external data (external temporary tables) for querying. For more information, see the section “External data for query processing”.
132
+
### Values and pipelines {#loading-misc}
61
133
62
-
### Queries with Parameters {#cli-queries-with-parameters}
134
+
```bash
135
+
# inline literals
136
+
timeplusd client -q "INSERT INTO events VALUES (100,'eve','2026-04-20 10:10:00.000')"
63
137
64
-
You can create a query with parameters and pass values to them from client application. This allows to avoid formatting query with specific dynamic values on client side. For example:
138
+
# remote source
139
+
curl -sS https://example.com/events.csv \
140
+
| timeplusd client -q "INSERT INTO events FORMAT CSVWithNames"
65
141
66
-
```bash
67
-
$ timeplusd client --param_parName="[1, 2]"-q "SELECT * FROM stream WHERE a = {parName:array(uint16)}"
68
-
```
142
+
# server-to-server copy — Native is the fastest binary format
143
+
timeplusd client -h src -q "SELECT * FROM events FORMAT Native" \
144
+
| timeplusd client -h dst -q "INSERT INTO events FORMAT Native"
69
145
70
-
It is also possible to set parameters from within an interactive session:
71
-
```bash
72
-
$ timeplusd client -nq "
73
-
SET param_parName='[1, 2]';
74
-
SELECT {parName:array(uint16)}"
146
+
# tolerate up to 10 malformed rows (or use --input_format_allow_errors_ratio=R)
Format a query as usual, then place the values that you want to pass from the app parameters to the query in braces in the following format:
153
+
Pick the output format with `-f` or a trailing `FORMAT` clause and redirect
154
+
`stdout`. Wrap the stream with `table(...)` so the query is bounded — a plain
155
+
`SELECT ... FROM <stream>` is streaming and never returns.
80
156
81
-
```sql
82
-
{<name>:<data type>}
83
-
```
84
-
85
-
-`name` — Placeholder identifier. In the console client it should be used in app parameters as `--param_<name> = value`.
86
-
-`data type` — [Data type](/datatypes) of the app parameter value. For example, a data structure like `(integer, ('string', integer))` can have the `tuple(uint8, tuple(string, uint8))` data type (you can also use another integer types). It's also possible to pass table, database, column names as a parameter, in that case you would need to use `identifier` as a data type.
157
+
### Text formats {#dumping-text}
87
158
88
-
#### Example {#example}
159
+
```bash
160
+
# the two styles are equivalent — pick either the -f flag or a trailing FORMAT clause
161
+
timeplusd client -f CSVWithNames -q "SELECT * FROM table(events)"> events.csv
162
+
timeplusd client -q "SELECT * FROM table(events) FORMAT CSVWithNames"> events.csv
89
163
90
-
```bash
91
-
$ timeplusd client --param_tuple_in_tuple="(10, ('dt', 10))" -q "SELECT * FROM stream WHERE val = {tuple_in_tuple:tuple(uint8, tuple(string, uint8))}"
timeplusd client -q "SELECT * FROM table(events) FORMAT TSVWithNames"> events.tsv
165
+
timeplusd client -q "SELECT * FROM table(events) FORMAT JSON"> events.json # meta + data
166
+
timeplusd client -q "SELECT * FROM table(events) FORMAT JSONEachRow"> events.ndjson
167
+
timeplusd client -q "SELECT * FROM table(events) FORMAT SQLInsert"> events.sql # replayable INSERTs
93
168
```
94
169
95
-
## Configuration {#interfaces_cli_configuration}
96
-
97
-
You can pass parameters to `timeplusd client` (all parameters have a default value) using:
98
-
99
-
- From the Command Line
170
+
### Columnar formats {#dumping-columnar}
100
171
101
-
Command-line options override the default values and settings in configuration files.
172
+
```bash
173
+
timeplusd client -q "SELECT * FROM table(events) FORMAT Parquet"> events.parquet
174
+
timeplusd client -q "SELECT * FROM table(events) FORMAT ORC"> events.orc
175
+
timeplusd client -q "SELECT * FROM table(events) FORMAT Arrow"> events.arrow
176
+
```
102
177
103
-
- Configuration files.
178
+
For large exports, prefer `Native` or `Parquet` over CSV/JSON — faster and
179
+
schema-preserving.
104
180
105
-
Settings in the configuration files override the default values.
181
+
### Terminal output {#dumping-pretty}
106
182
107
-
### Command Line Options {#command-line-options}
183
+
```bash
184
+
timeplusd client -q "SELECT * FROM table(events) LIMIT 5 FORMAT PrettyCompact"
185
+
timeplusd client -q "SELECT * FROM table(events) LIMIT 1 FORMAT Vertical"# one column per line
186
+
```
108
187
109
-
-`--host, -h` – The server name, ‘localhost’ by default. You can use either the name or the IPv4 or IPv6 address.
110
-
-`--port` – The port to connect to. Default value: 8463. Note that the HTTP interface and the native interface use different ports.
111
-
-`--user, -u` – The username. Default value: default.
112
-
-`--password` – The password. Default value: empty string.
113
-
-`--ask-password` - Prompt the user to enter a password.
114
-
-`--query, -q` – The query to process when using non-interactive mode. You must specify either `query` or `queries-file` option.
115
-
-`--queries-file` – file path with queries to execute. You must specify either `query` or `queries-file` option.
116
-
-`--database, -d` – Select the current default database. Default value: the current database from the server settings (‘default’ by default).
117
-
-`--multiline, -m` – If specified, allow multiline queries (do not send the query on Enter).
118
-
-`--multiquery, -n` – If specified, allow processing multiple queries separated by semicolons.
119
-
-`--format, -f` – Use the specified default format to output the result.
120
-
-`--vertical, -E` – If specified, use the Vertical format by default to output the result. This is the same as `–format=Vertical`. In this format, each value is printed on a separate line, which is helpful when displaying wide tables.
121
-
-`--time, -t` – If specified, print the query execution time to ‘stderr’ in non-interactive mode.
122
-
-`--stacktrace` – If specified, also print the stack trace if an exception occurs.
123
-
-`--config-file` – The name of the configuration file.
124
-
-`--secure` – If specified, will connect to server over secure connection (TLS). You might need to configure your CA certificates in the [configuration file](#configuration_files). (../operations/server-configuration-parameters/settings.md#server_configuration_parameters-openssl).
125
-
-`--history_file` — Path to a file containing command history.
126
-
-`--param_<name>` — Value for a [query with parameters](#cli-queries-with-parameters).
127
-
-`--hardware-utilization` — Print hardware utilization information in progress bar.
0 commit comments