Skip to content

Commit 5555a6a

Browse files
xiangfu0xiangfu0
committed
Add pinot-cli module to provide a terminal cli for pinot
1 parent f4bc04d commit 5555a6a

File tree

4 files changed

+1283
-0
lines changed

4 files changed

+1283
-0
lines changed

‎pinot-clients/pinot-cli/README.md‎

Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
<!--
2+
3+
Licensed to the Apache Software Foundation (ASF) under one
4+
or more contributor license agreements. See the NOTICE file
5+
distributed with this work for additional information
6+
regarding copyright ownership. The ASF licenses this file
7+
to you under the Apache License, Version 2.0 (the
8+
"License"); you may not use this file except in compliance
9+
with the License. You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing,
14+
software distributed under the License is distributed on an
15+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16+
KIND, either express or implied. See the License for the
17+
specific language governing permissions and limitations
18+
under the License.
19+
20+
-->
21+
## Pinot CLI
22+
23+
An interactive and batch command-line client for Apache Pinot. It supports a rich interactive REPL, multiple output formats, history, pagination, configuration files, and batch execution.
24+
25+
Features are modeled after the Trino CLI for familiarity and ergonomics. See the Trino CLI docs for reference: [Trino CLI documentation](https://trino.io/docs/current/client/cli.html).
26+
27+
## Requirements
28+
29+
- Java 11+ on PATH (Java 22+ recommended for performance)
30+
31+
## Build
32+
33+
From the repository root:
34+
35+
```bash
36+
./mvnw -DskipTests -pl pinot-clients/pinot-cli -am package
37+
```
38+
39+
Artifacts:
40+
41+
- `pinot-clients/pinot-cli/target/pinot-cli-*-executable.jar` (executable, recommended)
42+
- `pinot-clients/pinot-cli/target/pinot-cli-1.5.0-SNAPSHOT.jar` (thin)
43+
44+
## Running
45+
46+
### Interactive mode
47+
48+
```bash
49+
pinot-clients/pinot-cli/target/pinot-cli-*-executable.jar \
50+
-u jdbc:pinot://<controller-host>:<port>
51+
```
52+
53+
- Multi-line SQL is supported; end statements with `;` to execute.
54+
- Built-in commands: `help`, `clear`, `exit`, `quit`.
55+
- Default history file: `~/.pinot_history` (customize with `--history-file`).
56+
- Enable paging with a pager (e.g., `less`) via `--pager` or environment variables below.
57+
58+
### Batch mode
59+
60+
Execute a single statement:
61+
62+
```bash
63+
pinot-clients/pinot-cli/target/pinot-cli-*-executable.jar \
64+
-u jdbc:pinot://<controller-host>:<port> \
65+
--output-format=CSV_HEADER \
66+
--execute "SELECT * FROM myTable LIMIT 3;"
67+
```
68+
69+
Execute statements from a file:
70+
71+
```bash
72+
pinot-clients/pinot-cli/target/pinot-cli-*-executable.jar \
73+
-u jdbc:pinot://<controller-host>:<port> \
74+
--output-format=JSON \
75+
-f queries.sql
76+
```
77+
78+
## Options
79+
80+
- `-u, --url` JDBC URL. Example: `jdbc:pinot://controller:9000` or `jdbc:pinotgrpc://controller:9000` (required)
81+
- `-n, --user` Username
82+
- `-p, --password` Password
83+
- `--header` Extra request header `key=value` (repeatable), e.g., `--header Authorization=Bearer <token>`
84+
- `--set` Query/session option `key=value` (repeatable). Forwarded as connection properties
85+
- `-e, --execute` Execute SQL and exit
86+
- `-f, --file` Execute SQL from file and exit
87+
- `-o, --output` Legacy: `table|csv|json` (backward compatibility). Prefer the formats below
88+
- `--output-format` Batch output format
89+
- `--output-format-interactive` Interactive output format (default: `ALIGNED`)
90+
- `--pager` Pager program used in interactive mode (e.g., `less -SRFXK`). Empty disables pagination
91+
- `--history-file` Path to history file for interactive mode (default: `~/.pinot_history`)
92+
- `--config` Path to a properties file with defaults (see Configuration below)
93+
- `--debug` Print stack traces and timing diagnostics to stderr
94+
95+
### Output formats
96+
97+
Available values for `--output-format` and `--output-format-interactive` (case-insensitive):
98+
99+
- `CSV`, `CSV_HEADER`, `CSV_UNQUOTED`, `CSV_HEADER_UNQUOTED`
100+
- `TSV`, `TSV_HEADER`
101+
- `JSON` (one JSON object per line)
102+
- `ALIGNED` (ASCII table)
103+
- `VERTICAL` (record-oriented)
104+
- `AUTO` (chooses `ALIGNED` if it fits terminal width, otherwise `VERTICAL`)
105+
- `MARKDOWN` (Markdown table)
106+
- `NULL` (suppress normal results; useful for timing/error checks)
107+
108+
## Configuration
109+
110+
You can load defaults from a properties file using `--config` or via environment variables:
111+
112+
- `PINOT_CONFIG` (preferred)
113+
- `TRINO_CONFIG` (supported for parity)
114+
115+
Supported keys in the properties file (CLI flags take precedence):
116+
117+
- `server` (maps to `--url`)
118+
- `user`, `password`
119+
- `output-format`, `output-format-interactive`, `output`
120+
- `pager`, `history-file`, `debug`
121+
- `headers.*` (e.g., `headers.Authorization=Bearer <token>`) -> becomes extra headers
122+
- Any other key is forwarded as a session option (equivalent to `--set key=value`)
123+
124+
Example `pinot-cli.properties`:
125+
126+
```properties
127+
server=jdbc:pinot://localhost:9000
128+
user=alice
129+
output-format-interactive=AUTO
130+
pager=less -SRFXK
131+
history-file=/Users/alice/.pinot_history
132+
headers.Authorization=Bearer abc123
133+
debug=true
134+
timeoutMs=60000
135+
```
136+
137+
Run with:
138+
139+
```bash
140+
PINOT_CONFIG=/path/to/pinot-cli.properties \
141+
pinot-clients/pinot-cli/target/pinot-cli-*-executable.jar
142+
```
143+
144+
## Environment variables
145+
146+
- `PINOT_CONFIG` / `TRINO_CONFIG`: path to a config properties file
147+
- `PINOT_PAGER` / `TRINO_PAGER`: pager command for interactive mode (e.g., `less -SRFXK`)
148+
149+
## Examples
150+
151+
Interactive with AUTO format and pager:
152+
153+
```bash
154+
pinot-clients/pinot-cli/target/pinot-cli-*-executable.jar \
155+
-u jdbc:pinot://localhost:9000 \
156+
--output-format-interactive=AUTO \
157+
--pager "less -SRFXK"
158+
```
159+
160+
Batch to JSON:
161+
162+
```bash
163+
pinot-clients/pinot-cli/target/pinot-cli-*-executable.jar \
164+
-u jdbc:pinot://localhost:9000 \
165+
--output-format=JSON \
166+
--execute "SELECT col1, col2 FROM myTable LIMIT 3;"
167+
```
168+
169+
## Notes
170+
171+
- CLI arguments take precedence over config file values.
172+
- Pager is only used in interactive mode. Batch mode prints directly to stdout.
173+
174+

‎pinot-clients/pinot-cli/pom.xml‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
<?xml version="1.0"?>
2+
<!--
3+
4+
Licensed to the Apache Software Foundation (ASF) under one
5+
or more contributor license agreements. See the NOTICE file
6+
distributed with this work for additional information
7+
regarding copyright ownership. The ASF licenses this file
8+
to you under the Apache License, Version 2.0 (the
9+
"License"); you may not use this file except in compliance
10+
with the License. You may obtain a copy of the License at
11+
12+
http://www.apache.org/licenses/LICENSE-2.0
13+
14+
Unless required by applicable law or agreed to in writing,
15+
software distributed under the License is distributed on an
16+
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17+
KIND, either express or implied. See the License for the
18+
specific language governing permissions and limitations
19+
under the License.
20+
21+
-->
22+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
23+
<modelVersion>4.0.0</modelVersion>
24+
<parent>
25+
<artifactId>pinot-clients</artifactId>
26+
<groupId>org.apache.pinot</groupId>
27+
<version>1.5.0-SNAPSHOT</version>
28+
</parent>
29+
<artifactId>pinot-cli</artifactId>
30+
<name>Pinot CLI</name>
31+
<url>https://pinot.apache.org/</url>
32+
<properties>
33+
<pinot.root>${basedir}/../..</pinot.root>
34+
</properties>
35+
36+
<dependencies>
37+
<dependency>
38+
<groupId>org.apache.pinot</groupId>
39+
<artifactId>pinot-jdbc-client</artifactId>
40+
</dependency>
41+
<dependency>
42+
<groupId>org.jline</groupId>
43+
<artifactId>jline</artifactId>
44+
</dependency>
45+
<dependency>
46+
<groupId>info.picocli</groupId>
47+
<artifactId>picocli</artifactId>
48+
</dependency>
49+
<dependency>
50+
<groupId>org.slf4j</groupId>
51+
<artifactId>slf4j-api</artifactId>
52+
</dependency>
53+
<dependency>
54+
<groupId>org.slf4j</groupId>
55+
<artifactId>slf4j-simple</artifactId>
56+
<scope>runtime</scope>
57+
</dependency>
58+
</dependencies>
59+
60+
<build>
61+
<plugins>
62+
<plugin>
63+
<groupId>org.apache.maven.plugins</groupId>
64+
<artifactId>maven-compiler-plugin</artifactId>
65+
<configuration>
66+
<source>${jdk.version}</source>
67+
<target>${jdk.version}</target>
68+
</configuration>
69+
</plugin>
70+
<plugin>
71+
<groupId>org.apache.maven.plugins</groupId>
72+
<artifactId>maven-shade-plugin</artifactId>
73+
<executions>
74+
<execution>
75+
<phase>package</phase>
76+
<goals>
77+
<goal>shade</goal>
78+
</goals>
79+
<configuration>
80+
<shadedArtifactAttached>true</shadedArtifactAttached>
81+
<shadedClassifierName>executable</shadedClassifierName>
82+
<transformers>
83+
<transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
84+
<mainClass>org.apache.pinot.cli.PinotCli</mainClass>
85+
</transformer>
86+
</transformers>
87+
</configuration>
88+
</execution>
89+
</executions>
90+
</plugin>
91+
<plugin>
92+
<groupId>org.skife.maven</groupId>
93+
<artifactId>really-executable-jar-maven-plugin</artifactId>
94+
<configuration>
95+
<flags>-Xmx1G --enable-native-access=ALL-UNNAMED -XX:+IgnoreUnrecognizedVMOptions</flags>
96+
<classifier>executable</classifier>
97+
</configuration>
98+
<executions>
99+
<execution>
100+
<goals>
101+
<goal>really-executable-jar</goal>
102+
</goals>
103+
<phase>package</phase>
104+
</execution>
105+
</executions>
106+
</plugin>
107+
</plugins>
108+
</build>
109+
</project>
110+
111+

0 commit comments

Comments
 (0)