Skip to content

Commit b14df23

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

File tree

4 files changed

+1316
-0
lines changed

4 files changed

+1316
-0
lines changed

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

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

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