Skip to content

Commit 5b7c670

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

File tree

4 files changed

+1217
-0
lines changed

4 files changed

+1217
-0
lines changed

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

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
## Pinot CLI
2+
3+
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.
4+
5+
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).
6+
7+
## Requirements
8+
9+
- Java 11+ on PATH (Java 22+ recommended for performance)
10+
11+
## Build
12+
13+
From the repository root:
14+
15+
```bash
16+
./mvnw -DskipTests -pl pinot-clients/pinot-cli -am package
17+
```
18+
19+
Artifacts:
20+
21+
- `pinot-clients/pinot-cli/target/pinot-cli-*-executable.jar` (executable, recommended)
22+
- `pinot-clients/pinot-cli/target/pinot-cli-1.5.0-SNAPSHOT.jar` (thin)
23+
24+
## Running
25+
26+
### Interactive mode
27+
28+
```bash
29+
pinot-clients/pinot-cli/target/pinot-cli-*-executable.jar \
30+
-u jdbc:pinot://<controller-host>:<port>
31+
```
32+
33+
- Multi-line SQL is supported; end statements with `;` to execute.
34+
- Built-in commands: `help`, `clear`, `exit`, `quit`.
35+
- Default history file: `~/.pinot_history` (customize with `--history-file`).
36+
- Enable paging with a pager (e.g., `less`) via `--pager` or environment variables below.
37+
38+
### Batch mode
39+
40+
Execute a single statement:
41+
42+
```bash
43+
pinot-clients/pinot-cli/target/pinot-cli-*-executable.jar \
44+
-u jdbc:pinot://<controller-host>:<port> \
45+
--output-format=CSV_HEADER \
46+
--execute "SELECT * FROM myTable LIMIT 3;"
47+
```
48+
49+
Execute statements from a file:
50+
51+
```bash
52+
pinot-clients/pinot-cli/target/pinot-cli-*-executable.jar \
53+
-u jdbc:pinot://<controller-host>:<port> \
54+
--output-format=JSON \
55+
-f queries.sql
56+
```
57+
58+
## Options
59+
60+
- `-u, --url` JDBC URL. Example: `jdbc:pinot://controller:9000` or `jdbc:pinotgrpc://controller:9000` (required)
61+
- `-n, --user` Username
62+
- `-p, --password` Password
63+
- `--header` Extra request header `key=value` (repeatable), e.g., `--header Authorization=Bearer <token>`
64+
- `--set` Query/session option `key=value` (repeatable). Forwarded as connection properties
65+
- `-e, --execute` Execute SQL and exit
66+
- `-f, --file` Execute SQL from file and exit
67+
- `-o, --output` Legacy: `table|csv|json` (backward compatibility). Prefer the formats below
68+
- `--output-format` Batch output format
69+
- `--output-format-interactive` Interactive output format (default: `ALIGNED`)
70+
- `--pager` Pager program used in interactive mode (e.g., `less -SRFXK`). Empty disables pagination
71+
- `--history-file` Path to history file for interactive mode (default: `~/.pinot_history`)
72+
- `--config` Path to a properties file with defaults (see Configuration below)
73+
- `--debug` Print stack traces and timing diagnostics to stderr
74+
75+
### Output formats
76+
77+
Available values for `--output-format` and `--output-format-interactive` (case-insensitive):
78+
79+
- `CSV`, `CSV_HEADER`, `CSV_UNQUOTED`, `CSV_HEADER_UNQUOTED`
80+
- `TSV`, `TSV_HEADER`
81+
- `JSON` (one JSON object per line)
82+
- `ALIGNED` (ASCII table)
83+
- `VERTICAL` (record-oriented)
84+
- `AUTO` (chooses `ALIGNED` if it fits terminal width, otherwise `VERTICAL`)
85+
- `MARKDOWN` (Markdown table)
86+
- `NULL` (suppress normal results; useful for timing/error checks)
87+
88+
## Configuration
89+
90+
You can load defaults from a properties file using `--config` or via environment variables:
91+
92+
- `PINOT_CONFIG` (preferred)
93+
- `TRINO_CONFIG` (supported for parity)
94+
95+
Supported keys in the properties file (CLI flags take precedence):
96+
97+
- `server` (maps to `--url`)
98+
- `user`, `password`
99+
- `output-format`, `output-format-interactive`, `output`
100+
- `pager`, `history-file`, `debug`
101+
- `headers.*` (e.g., `headers.Authorization=Bearer <token>`) -> becomes extra headers
102+
- Any other key is forwarded as a session option (equivalent to `--set key=value`)
103+
104+
Example `pinot-cli.properties`:
105+
106+
```properties
107+
server=jdbc:pinot://localhost:9000
108+
user=alice
109+
output-format-interactive=AUTO
110+
pager=less -SRFXK
111+
history-file=/Users/alice/.pinot_history
112+
headers.Authorization=Bearer abc123
113+
debug=true
114+
timeoutMs=60000
115+
```
116+
117+
Run with:
118+
119+
```bash
120+
PINOT_CONFIG=/path/to/pinot-cli.properties \
121+
pinot-clients/pinot-cli/target/pinot-cli-*-executable.jar
122+
```
123+
124+
## Environment variables
125+
126+
- `PINOT_CONFIG` / `TRINO_CONFIG`: path to a config properties file
127+
- `PINOT_PAGER` / `TRINO_PAGER`: pager command for interactive mode (e.g., `less -SRFXK`)
128+
129+
## Examples
130+
131+
Interactive with AUTO format and pager:
132+
133+
```bash
134+
pinot-clients/pinot-cli/target/pinot-cli-*-executable.jar \
135+
-u jdbc:pinot://localhost:9000 \
136+
--output-format-interactive=AUTO \
137+
--pager "less -SRFXK"
138+
```
139+
140+
Batch to JSON:
141+
142+
```bash
143+
pinot-clients/pinot-cli/target/pinot-cli-*-executable.jar \
144+
-u jdbc:pinot://localhost:9000 \
145+
--output-format=JSON \
146+
--execute "SELECT col1, col2 FROM myTable LIMIT 3;"
147+
```
148+
149+
## Notes
150+
151+
- CLI arguments take precedence over config file values.
152+
- Pager is only used in interactive mode. Batch mode prints directly to stdout.
153+
154+

‎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)