Ballista Command-line Interface¶
The Ballista CLI allows SQL queries to be executed against a Ballista cluster, or in standalone mode in a single process.
Use Cargo to install:
cargo install ballista-cli
Usage¶
USAGE:
ballista-cli [OPTIONS]
OPTIONS:
-c, --batch-size <BATCH_SIZE> The batch size of each query, or use Ballista default
-f, --file <FILE>... Execute commands from file(s), then exit
--format <FORMAT> [default: table] [possible values: csv, tsv, table, json,
nd-json]
-h, --help Print help information
--host <HOST> Ballista scheduler host
-p, --data-path <DATA_PATH> Path to your data, default to current directory
--port <PORT> Ballista scheduler port
-q, --quiet Reduce printing other than the results and work quietly
-r, --rc <RC>... Run the provided files on startup instead of ~/.ballistarc
--tui Enables terminal user interface (requires `tui` feature)
-V, --version Print version information
Example¶
Create a CSV file to query.
$ echo "1,2" > data.csv
Run Ballista CLI in Distributed Mode¶
The CLI can connect to a Ballista scheduler for query execution.
ballista-cli --host localhost --port 50050
Run Ballista CLI in Standalone Mode¶
It is also possible to run the CLI in standalone mode, where it will create a scheduler and executor in-process.
$ ballista-cli
Ballista CLI v52.0.0
> CREATE EXTERNAL TABLE foo (a INT, b INT) STORED AS CSV LOCATION 'data.csv';
0 rows in set. Query took 0.001 seconds.
> SELECT * FROM foo;
+---+---+
| a | b |
+---+---+
| 1 | 2 |
+---+---+
1 row in set. Query took 0.017 seconds.
Cli commands¶
Available commands inside Ballista CLI are:
Quit
> \q
Help
> \?
ListTables
> \d
DescribeTable
> \d table_name
QuietMode
> \quiet [true|false]
list function
> \h
Search and describe function
> \h function_table
Terminal User Interface (TUI)¶
When Ballista CLI is built with the tui feature, you can launch an interactive terminal user interface
that provides a visual overview of the Ballista cluster.
Launching the TUI¶
There are two ways to start the TUI:
Directly via command-line flag:
ballista-cli --tui
From within the Ballista CLI interactive shell:
ballista-cli
> \tui
TUI Features¶
The TUI provides the following views:
Executors: Lists all registered executors with their host, port, task slots, memory usage, and last seen time. Supports sorting by any column.
Executor details: Select an executor and press
Enterto show extra details about it.Jobs: Displays active and completed jobs with their status, start time, and duration. Supports sorting, job search (
/), and shows job details on selection.Job Stages: When viewing a job, press
Enterto see its execution stages with input/output rows, elapsed compute, and task percentiles.Stage Tasks & Plan: Within the Job Stages view, press
Enterto see individual task details orpto view the stage execution plan.Job Plans: For completed jobs, press
pto view the Stage, Physical, or Logical query plans.Job Stages Graph: Press
gto visualize the job’s stage execution graph.Metrics: Fetches and displays Prometheus metrics from the scheduler, including query execution statistics.
Scheduler Info: Shows the current scheduler state and configuration.
TUI Screenshots¶
TUI Configuration¶
The TUI reads its configuration from a YAML file located at the platform-specific config directory:
Platform |
Example Path |
|---|---|
Linux |
|
macOS |
|
Windows |
|
Create the file manually if it does not exist. The following settings are available:
tick_interval_ms: 2000
job:
stage:
plan:
tree: false
scheduler:
url: http://localhost:50050
http:
timeout: 2000
tick_interval_ms: How often the TUI refreshes data from the scheduler (milliseconds).job.stage.plan.tree: Whether to show the stage execution plan as a tree.scheduler.url: The Ballista scheduler HTTP endpoint.http.timeout: HTTP request timeout in milliseconds.
Environment variables prefixed with BALLISTA_ also override these values. For example:
BALLISTA_SCHEDULER_URL=http://localhost:50051 ballista-cli --tui
The TUI connects to the scheduler via HTTP and refreshes data automatically every few seconds.