ByteHouse CLI

ByteHouse CLI (command-line interface) is the most direct way to interact with ByteHouse services.

Installation

Get the latest version of ByteHouse CLI.

macOS

To install ByteHouse CLI on macOS, you’ll need to have Homebrew installed on your machine. Then, run the following commands:


brew tap bytehouse-cloud/homebrew-core
brew install bytehouse-cli

To upgrade the ByteHouse CLI, run the following command:


brew upgrade bytehouse-cli

Linux


curl -o bytehouse-cli -L https://github.com/bytehouse-cloud/cli/releases/download/v1.5.21/bytehouse-linux-amd64
chmod +x bytehouse-cli 

# Add this binary executable to your `~/.bashrc` as alias, or `~/.zshrc`l
echo “alias bytehouse-cli=\”$(pwd)/bytehouse-cli\"" > ~/.bashrc

Windows

Download the latest installer bytehouse-vX.X.XX.X-windows-amd64

Getting started

Credentials

To get started, you’ll need:

Account name
Username
Password
Region

This is the same as the info needed to log in with Web UI.

If you are unsure, you can also check your details on the top right corner of the web console.

Using the CLI

The easiest way to start the application is to run it from the command line or in PowerShell.

With flags

The format for specifying flag and its value when starting the application:

--<flag> value , eg --user mary

Flags also have aliases. Here’s an example of starting bytehouse-cli:


bytehouse-cli --user <user name> --account <account name> --password <password> --region <region name> --secure

# Example
$ bytehouse-cli --user bob --account AWSXXX --password coolbob --region cn-north-1 --secure

Note: --secure flag is needed when connecting to ByteHouse’s public domain.

With configuration file

Sometimes, it’s more manageable to keep all flags in a configuration file. You can also specify query settings in it. Use the -cf flag with the path to configuration file as value.

An example of a configuration file and its usage is shown below:


$ cat bytehouse_conf.toml

# Settings for connection
account = “AWSXXXXX”
user = “bob”
password = “coolbob”
region = “cn-north-1”
secure = true

# Settings for query Settings
ansi_sql = true 
$ bytehouse-cli -cf bytehouse_conf.toml

Non-interactive mode

While writing shell script, it could be impractical to get into interactive mode. ByteHouse CLI allows the user to execute an SQL command and exit automatically.

With query flag

If you launch bytehouse-cli with -q or --query flag, that SQL statement will be executed and bytehouse-cli will exit immediately after the execution.


$ bytehouse-cli -q “select 1”

With stdin

Users can also allow bytehouse-cli to take input from stdin.


$ echo “select 1” | bytehouse-cli

Scripting

To write an SQL script and pipe the input to bytehouse-cli:

Queries should be separated by ;
Queries will be run sequentially
Further execution is stopped if a previous query execution returns an error


$ cat example.sql
CREATE DATABASE bob_db;
USE bob_db;
CREATE TABLE bob_numbers
(
   i Int32
)
ENGINE = CnchMergeTree
ORDER BY i;
SHOW CREATE TABLE bob_numbers;
$ bytehouse-cli < example.sql

# This is also accepted
$ cat example.sql | bytehouse-cli

Data insertion

It is very common to load data from a file, as shown below:

From query

Interactive mode


ByteHouse » INSERT INTO bob_db.bob_number VALUES (1), (2), (3)

Non-interactive mode


$ bytehouse-cli -q “INSERT INTO bob_db.bob_number VALUES (1), (2), (3)”

From a local file

Interactive mode


ByteHouse » INSERT INTO bob_db.bob_number FORMAT csv INFILE ‘path/to/data.csv’

Non-interactive mode


$ bytehouse-cli -q “INSERT INTO bob_db.bob_number FORMAT csv” < ‘path/to/data.csv’

Data export

You can use the INTO OUTFILE syntax after your query to save results to a local file.


ByteHouse » SELECT * FROM bob_db.bob_number INTO OUTFILE ‘out.csv’ format csv.

Version check

You can check the version of the ByteHouse CLI using the -v or --version flag. When the flag is specified, ByteHouse CLI does not start.


$ bytehouse-cli -v

v1.5.2

Help

You can display all the supported flags by using -h flag or --help.


#To display all options and their alias
bytehouse-cli -h