ByteHouse CLI 快速入门

ByteHouse CLI 是一个命令行应用程序，用于以最直接的方式与 Bytehouse 服务交互，您可以直接使用秘钥对连接 ByteHouse CLI 并执行资源创建管理、SQL 查询等操作。
您可以从 这里 获取最新的 ByteHouse CLI 发布版本。

安装

MacOS Homebrew 安装

安装

如果您的系统中安装了 Homebrew，可以直接运行如下命令安装 ByteHouse CLI。

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

升级

如果要升级您的 ByteHouse CLI 版本，可以运行下列命令。

brew upgrade bytehouse-cli

故障处理

如果您已经安装了 bytehouse-cli 并且在重新安装或升级时遇到一些错误，请尝试以下步骤。

1. 卸载 bytehouse cli 。

brew uninstall bytehouse-cli
brew untap bytehouse-cloud/homebrew-core

2. 执行下面的命令重新安装。

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

Linux 系统

对于 Linux 系统，请在 GitHub 发布地址 中获取最新发布版本的链接。
并参考下面的代码操作。

# 请从上面的发布地址中获取最新链接，或替换下面代码中的版本号
# Replace the first line below with the latest release version
curl -o bytehouse-cli.tar.gz -L https://github.com/bytehouse-cloud/cli/releases/download/<版本号>/bytehouse-cli_<版本号>_Linux_x86_64.tar.gz
mkdir -p ./bytehouse-cli/
tar -zxvf bytehouse-cli.tar.gz -C ./bytehouse-cli
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 系统

对于 Windows 系统，请选择 GitHub 地址 中的最新版本进行下载、解压及安装。
示例格式如下：bytehouse-cli_1.5.32_Windows_x86_64.zip

连接到 ByteHouse

可参考如下命令进行连接：

bytehouse-cli --host {HOST} --port 19000 --secure --token {API_KEY} 

# Example 
bytehouse-cli --host bytehouse-cn-beijing.volces.com --port 19000 --secure --token XXXXXXXXXXXXX

# Example with extra settings
bytehouse-cli --host bytehouse-cn-beijing.volces.com --port 19000 --secure --token XXXXXXXXXXXXX --send_timeout=3600 --receive_timeout=3600 --warehouse=warehouse1 --database=db1

1. 如果是连接到 火山引擎托管的ByteHouse，则--secure为必选字段；
2. {API_KEY} ：请访问 ByteHouse 控制台 租户管理-连接信息 页面，新建并获取 Access Token 信息。
3. {HOST}：火山引擎ByteHouse 集群连接信息请参考支持的地域及可用区；
4. 通过命令行连接时，可以通过增加标志--<flag> 指定对应的配置参数，如 --user fred。更多 flag 标志及缩写可以参考 CLI 配置参数文档；
5. 其他可选字段，如不指定则使用默认值：
   • receive_timeout (默认值：3600，即 1 小时)
   • send_timeout (默认值：3600，即 1 小时)
   • warehouse (默认值为用户默认数仓，如存在)
   • database (默认值为用户默认数据库，如存在)

非交互模式

有时可能由于正在编写 shell 脚本而无法进入交互模式。Bytehouse-cli 允许用户执行 SQL 命令并自动退出。

使用查询标志

如果使用 -q 或 --query 标志启动 bytehouse-cli，将会执行 sql 语句，并且 bytehouse-cli 会在执行后立即退出。

$ bytehouse-cli -q "select 1" 

使用 stdin

用户还可以允许 bytehouse-cli 使用 stdin 的输入。

$ echo "select 1" | bytehouse-cli

编写脚本

用户还可以编写 SQL 脚本并将输入通过管道传输到bytehouse cli

• 查询用 ; 分隔
• 查询将按顺序运行
• 如果第一次查询执行返回错误，请停止继续执行

$ cat example.sql
CREATE DATABASE bob_db;
USE bob_db;
CREATE TABLE bob_number
(
   i Int32
)
ENGINE = CnchMergeTree
ORDER BY i;
SHOW CREATE TABLE bob_number;

$ bytehouse-cli < example.sql

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

数据插入

从文件中加载数据是一种非常常见的做法，下面是一些操作示例。

从查询中插入数据

交互模式

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

非交互模式

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

从本地文件中插入数据

交互模式

Bytehouse » INSERT INTO bob_db.bob_number FORMAT csv INFILE 'path/to/data.csv'

非交互模式

$ bytehouse-cli -q "INSERT INTO bob_db.bob_number FORMAT csv" < 'path/to/data.csv'

数据导出

查询后用 INTO OUTFILE 语法可以将结果保存到本地文件。

Bytehouse » SELECT * FROM bob_db.bob_number INTO OUTFILE 'out.csv' format csv

如果需要保留查询结果的表头，则需要导出为 CSVWithNames 格式：

Bytehouse » SELECT * FROM bob_db.bob_number INTO OUTFILE 'out.csv' format CSVWithNames

版本检查

可以使用 -v 或 --version 标志检查 ByteHouse CLI 的版本。指定标志时，ByteHouse CLI 不启动

$ bytehouse-cli -v
v1.5.2

帮助

使用 -h 标志或 --help 可以显示所有支持的标志

#To display all option and its alias
bytehouse-cli -h