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 -v

升级

如果要升级您的 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 发布地址 中获取最新发布版本的链接，并参考下面的代码操作。

# 请从上面的发布地址中获取最新链接，或替换下面代码中的版本号
# 使用最新发布版本替换下面的第一行内容
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 

# 将这个二进制可执行文件作为别名添加到 ~/.bashrc 文件中，或者添加到 ~/.zshrc 文件中
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} 

示例如下：

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

# 更多配置参数示例
bytehouse-cli --host bytehouse-cn-beijing.volces.com --port 19000 --secure --token XXXXXXXXXXXXX --send_timeout=3600 --receive_timeout=3600 --virtual_warehouse=warehouse1 --database=db1

参数说明：

• {HOST}：在 ByteHouse 控制台租户管理>基本信息>网络信息中获取到租户专用的集群连接{HOST}地址（私网或公网地址）。
• --secure：定义是否要用 Secure TCP 连接。如果是连接到火山引擎托管的 ByteHouse，则 --secure 为必选字段。
• {API_KEY} ：请访问 ByteHouse 控制台租户管理>连接信息页面，新建并获取 API Key 信息。
• 通过命令行连接时，可以通过增加标志--<flag> 指定对应的配置参数，如 --user fred。更多 flag 标志及缩写可以参考 CLI 配置参数文档。
• 其他可选字段，如不指定则使用默认值：
  • --receive_timeout 默认值：300，即 5 分钟。
  • --send_timeout 默认值：300，即 5 分钟。
  • --virtual_warehouse 默认值为用户默认数仓，如存在。
  • --database 默认值为用户默认数据库，如存在。

非交互模式

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

使用查询标志

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

bytehouse-cli --host {HOST} --port 19000 --secure --token {API_KEY} -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-cli 的路径。

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 可以显示所有支持的标志。

#显示所有标志及其别名
bytehouse-cli -h