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

使用限制

数据库用户功能为 Beta 功能，如需使用数据库用户连接，请联系提交工单或联系 ByteHouse 团队获取白名单权限。

安装

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/v<版本号>/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 支持通过 IAM 用户或数据库用户连接，您可按需操作。

使用 IAM 用户连接

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

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

示例如下：

bytehouse-cli --host tenant-{TENANT_ID}-{REGION}[-{ENVIRONMENT}]-public.bytehouse.volces.com --port 19000 --secure --token XXXXXXXXXXXXX

# 更多配置参数示例
bytehouse-cli --host tenant-{TENANT_ID}-{REGION}[-{ENVIRONMENT}]-public.bytehouse.volces.com --port 19000 --secure --token XXXXXXXXXXXXX --send_timeout=3600 --read_timeout=3600 --virtual_warehouse=warehouse1 --database=db1

参数说明如下，更多 flag 标志及缩写可以参考 CLI 配置参数文档。

使用数据库用户连接

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

bytehouse-cli --user {accountID_or_accountName}::{username}[::{envID}] --password {password} --host {HOST} --port 19000 --secure

示例如下：

bytehouse-cli --user 21XXXXXXXX::demodb::testenv --password XXXXXXXX--host tenant-{TENANT_ID}-{REGION}[-{ENVIRONMENT}]-public.bytehouse.volces.com --port 19000 --secure

参数说明如下，更多 flag 标志及缩写可以参考 CLI 配置参数文档。

非交互模式

有时可能由于正在编写 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