ByteHouse CLI 是一个命令行应用程序，用于以最直接的方式与 ByteHouse 服务交互，您可以直接使用秘钥对连接 ByteHouse CLI 并执行资源创建管理、SQL 查询等操作。本文将介绍如何安装和使用 ByteHouse CLI。

准备工作

• 已开通 ByteHouse 云数仓版服务，详情请参见快速入门。
• 本操作基于 Node.js 环境部署 ByteHouse CLI，执行操作前请预先完成 Node.js 环境安装。

:::tip
推荐部署版本：Node.js 22.x 与 24.x LTS。
:::

• 已完成公网配置，详情请参见步骤二：配置网络信息。
• 如需使用 ByteHouse CLI 管理 ByteHouse 资源，请先完成 ByteHouse 服务的创建。
• 如需使用多模态向量化检索功能，请先开通火山方舟服务，详情请参见开通模型服务。

安装

通过终端执行以下命令，安装 ByteHouse CLI：

# 第一步：全局安装 ByteHouse CLI
npm install -g @bytehouse/cli

# 第二步：校验安装结果，输出版本号即为成功 
bytehouse-cli --version

连接到 ByteHouse

通过终端操作

init 命令会以对话的形式，引导用户逐步填写配置信息，适合首次使用，流程更直观。

bytehouse-cli init

需要用户提供如下配置信息：
参数说明

| | | \

参数	说明
ByteHouse版本（必填）	固定为 CDW，代表 ByteHouse 云数仓版
ByteHouse Base URL（必填）	集群的访问地址。您可以在 ByteHouse 控制台的租户管理 > 基本信息 > 网络信息中查看网络组配置，详情请参见步骤二：配置网络信息。
	
ByteHouse API Key（必填）	集群的访问密钥。您可登录 ByteHouse 控制台，在 租户管理 > 连接信息页面中，单击 API Key 表单下的”＋ 新建“按钮来创建 API Key。
	:::warning
	* API Key 创建后无法再次查看，建议将秘钥下载到本地保存。
	* 最多可以创建 2 个 API Key。
	:::
ByteHouse 用户名 （必填）	您在火山引擎控制台的用户名称，固定为：bytehouse。
大模型服务（按需）	如需使用多模态向量化检索功能，请填写火山方舟 URL、API Key和火山方舟模型 ID。
	获取方式：
	1. 登录火山方舟控制台，在左侧导航栏选择模型广场，选择已开通的多模态模型，点击API 接入。
	
	2. 在快捷 API 接入页面中，获取 API Key、火山方舟模型 ID 和火山方舟 URL。
	

通过Agent操作

用户可以通过 Agent（例如 TRAE）调用 ByteHouse CLI 的能力，将自然语言意图转化为具体命令并执行。Agent 能够基于上下文自动完成多步命令的组合与执行，例如逐步探查库表结构、构建查询语句并获取结果。将如下参数提供给 Agent 执行，Agent 会自动完成连接。

操作实践指导

基础查询

ByteHouse CLI 可以支持开发者或 Agent 直接在终端中完成数据探查，快速了解数据全貌。

执行查询类 SQL 语句

命令格式

bytehouse-cli query <SQL 查询语句>

用途说明
用于执行 SQL 查询语句，例如 SELECT、SHOW 。通常会返回结果集。
使用示例

bytehouse-cli query "SELECT * FROM default.user_info LIMIT 10"

使用建议

• 需要查看数据结果时优先用 query。
• 不建议用它执行建表、删表、写入等变更类 SQL。

执行操作列 SQL 语句

命令格式

bytehouse-cli exec <SQL 操作语句>

用途说明
用于执行会改动数据或结构的 SQL 操作语句，例如 INSERT、CREATE、ALTER、UPDATE、DELETE 等。
使用示例

bytehouse-cli exec "CREATE TABLE default.test_table (id UInt64, name String) ENGINE=CnchMergeTree ORDER BY id"

使用建议

• 只要 SQL 会改数据或改结构，就优先使用 exec。
• 生产环境执行前建议先确认 SQL 内容，避免误操作。

查看集群状态

命令格式

bytehouse-cli cluster <action> [参数]

用途说明
用于查看集群状态、排查运行问题。
参数说明

| | | \

命令	说明
cluster test	测试集群连接。用于确认 CLI 与目标集群是否可正常通信。新环境/新账号建议先跑一次。
cluster parts	查询集群数据分区。用于查看数据分区（parts/partition）信息，常用于巡检或排查数据分布异常。
	参数详解：
	```Bash
	bytehouse-cli cluster parts --limit
	```
	* --limit ：限制返回数量，默认值为20。
cluster mutation	查询 Mutation 状态。用于检查异步变更任务状态，适合排查“已提交变更但效果未生效”。
cluster nodes	查询集群节点状态。用于查看各节点运行情况，适合日常巡检与故障定位。

使用示例

bytehouse-cli cluster parts --limit 50

查看数据库信息

命令格式

bytehouse-cli database <action> [参数]

用途说明
用于查看数据库列表、数据库详情，以及数据库下的表和视图。
参数说明

| | | \

参数	说明
database list	列出所有数据库。支持按名称过滤与分页获取。数据库很多时建议配合 --filter/--limit/--offset。
	参数详解：
	```Bash
	bytehouse-cli database list [--filter ] [--limit ] [--offset ]
	```
	* --filter <filter>：数据库名称过滤。
	* --limit <limit>：返回数量限制，默认值为 100。
	* --offset <offset>：分页偏移量，默认值为 0。
database detail	获取数据库详情。用于查看数据库的详细信息（图片中未给出额外参数）。
database tables	列出库下所有表（不含视图）。默认查看 default 库；如需查看其他库，使用 --database 指定。
	参数详解：
	```Bash
	bytehouse-cli database tables [--database ]
	```
	* --database <database>：数据库名称，默认值为 default。
database tables-views	列出库下所有表和视图。适合做库对象盘点，需要把视图也一起列出来时使用。

使用示例

bytehouse-cli database list --limit 20 --offset 40

查看表详情

命令格式

bytehouse-cli table detail --database <database> --table <table>  

用途说明
用于查看指定表的详细信息。
参数说明

| | | \

参数	说明
--database <database>	数据库名称，默认值为default。
--table <table>	表名称，必填。

使用示例

bytehouse-cli table detail --table user_info  

智能分析

ByteHouse CLI 支持通过自然语言驱动数仓操作，无需编写复杂 SQL 查询语句即可完成数据分析，例如：自然语言自动转 SQL、自动执行查询、自动返回分析结果等。

智能问答

直接提问 ByteHouse 产品相关问题，例如：“ByteHouse 云数仓版怎么计费？”、“ByteHouse 怎么管理用户权限？”、“ByteHouse 的向量检索怎么使用？”
命令格式

bytehouse-cli agent chat --message <message>

用途说明
智能问答，可查询 ByteHouse 知识库内容。它更像一个产品知识助手，适合问概念、功能、能力边界和产品使用问题。
参数说明

| | | \

参数	说明
-message <message>	问题描述。

使用示例

bytehouse-cli agent chat --message 'ByteHouse云数仓版是什么'

使用建议
单次咨询仅提交单一问题，并配套完整必要背景信息，包含产品版本、部署形态（云数仓版 / 自建版）、故障报错原文或复现现象。

自然语言转 SQL（不执行）

将用自然语言描述的业务问题转换为 SQL 语句，支持指定一个或多个表用于查询。
命令格式

bytehouse-cli agent text2sql --query <query> --tables <tables>

用途说明
把自然语言描述转换成 SQL 语句，但不直接执行。
参数说明

| | | \

参数	说明
--query <query>	自然语言查询描述。
--tables <tables>	可供查询的表集合，逗号分隔，例如 default.table1,default.table2。

使用示例

bytehouse-cli agent text2sql --query '统计用户下单最多的三个城市' --tables 'ecommerce.orders'

自然语言转 SQL 并执行

从自然语言问题出发，自动完成 SQL 转换并执行，直接返回查询结果。
命令格式

bytehouse-cli agent query --query <query> --tables <tables>

用途说明
把自然语言转换成 SQL 后直接执行，并返回查询结果。
参数说明

| | | \

参数	说明
--query <query>	自然语言查询描述。
--tables <tables>	可供查询的表集合，逗号分隔，例如 default.table1,default.table2。

使用示例

bytehouse-cli agent query --query '近三个月销售量最高的3件商品及其销售渠道' --tables 'ecommerce.products'

使用建议

• 如果查询逻辑比较复杂，建议先用 text2sql 看 SQL 是否符合预期

智能诊断

命令格式

bytehouse-cli agent smart_diagnosis --query <query>

用途说明
通过自然语言执行集群或查询任务诊断。
参数说明

| | | \

参数	说明
--query <query>	自然语言描述的诊断问题。

使用示例

bytehouse-cli agent smart_diagnosis --query "为什么最近查询明显变慢"

多模数据处理与混合检索分析

在实际场景中，很多企业数据并不只存在于结构化表中，还包括文档、报告、图片、视频、日志等多种形式。用户可以通过 ByteHouse CLI 快速完成从原始数据到向量化，再到结构化+非结构检索分析的完整流程。
:::warning
使用多模态能力前，请确保在初始化配置中已填写方舟 Ark Base URL、Ark API Key 和 Ark Model 信息。
:::

多模态向量化

通过 Embedding 能力，将文本/图片/视频等多模原始数据转化为向量表示，实现非结构化数据的可计算化。
命令格式

bytehouse-cli volcengine embedding [--text <text> | --image <url> | --video <url>] [参数]

用途说明
执行多模态向量化，支持文本、图片、视频三种输入。
参数说明

| | | \

参数	说明
--text <text>	输入待向量化的文本内容。
--image <url>	输入待向量化的图片 URL。
--video <url>	输入待向量化的视频 URL。
--ark-base-url <url>	ARK Base URL。
--ark-api-key <key>	ARK API Key。
--ark-model <model>	向量化模型名称。默认值为 doubao-embedding-vision-251215。
--instruction <instruction>	自定义指令，用于提升检索精度。
--dimensions <dimensions>	向量维度，取值为 1024 或 2048 ，默认值为2048。

使用示例

  bytehouse-cli volcengine embedding \
  --text "一只戴着围巾的猫" \
  --ark-api-key "<ARK_API_KEY>" \
  --ark-base-url "<ARK_BASE_URL>" \
  --ark-model "doubao-embedding-vision-251215" \
  --dimensions 2048

使用建议

• 三种输入通常只选一种，不建议同时传。
• 如果长期使用，建议把 arkBaseUrl、arkApiKey、arkModel 写入配置，避免每次重复输入。
• 检索场景下可以配合--instruction <instruction> 提升召回质量。

全文检索

:::tip
执行全文检索前，请先为目标字段创建倒排索引。
:::
命令格式

bytehouse-cli volcengine hybrid_search fulltext --table-name <table> --query <query> [参数]

用途说明
按关键词做全文检索。
参数说明

| | | \

参数	说明
--table-name <tableName>	表名，默认是 default 库，跨库须写完整路径。
--query <query>	查询关键词。
--content-field <contentField>	全文检索内容字段。默认值为 content。
--fields <fields>	返回字段，多个字段逗号分隔。默认值为 content。
--top-k <topK>	返回结果数量。默认值为 20。
--include-content	是否返回完整 content。默认值为 false。

使用示例

  bytehouse-cli volcengine hybrid_search fulltext \
  --table-name default.docs \
  --query "向量检索" \
  --fields "title,content" \
  --top-k 10

向量检索

命令格式

bytehouse-cli volcengine hybrid_search vector --table-name <table> --query <query> [参数]

用途说明
先将查询文本转成向量，再做向量相似度检索。
参数说明

| | | \

参数	说明
--table-name <tableName>	目标表名。
--query <query>	查询文本。
--fields <fields>	返回字段。默认值为 content。
--vector-score <vectorScore>	相似度阈值。默认值为 0.8。
--top-k <topK>	返回结果数量。默认值为 20。
--ark-api-key <key>	ARK API Key。
--ark-base-url <url>	ARK Base URL。
--ark-model <model>	向量化模型名称。
--instruction <instruction>	自定义指令。
--dimensions <dimensions>	向量维度。默认值为 2048。
--include-content	是否返回完整 content。默认值为 false。

使用示例

  bytehouse-cli volcengine hybrid_search fulltext \
  --table-name 'default.test_hybrid_index' \
  --query 'ByteHouse' \
  --fields 'title, content'

混合检索

命令格式

bytehouse-cli volcengine hybrid_search search --table-name <table> --query <query> [参数]

用途说明
执行混合检索，结合全文检索、向量检索和 RRF 重排。
参数说明

| | | \

参数	说明
--table-name <tableName>	目标表名。默认default库下，其他库请指定完整路径。
--query <query>	查询文本。
--content-field <contentField>	全文检索字段。默认值为 content。
--fields <fields>	返回字段。默认值为 content。
--vector-score <vectorScore>	相似度阈值。默认值为 0.8。
--top-k <topK>	最终结果数量。默认值为 10。
--recall-k <recallK>	每路召回数量。默认值为 20。
--rrf-k <rrfK>	RRF 算法 k 参数。默认值为 60。
--ark-api-key <key>	ARK API Key。
--ark-base-url <url>	ARK Base URL。
--ark-model <model>	向量化模型名称。
--instruction <instruction>	自定义指令。
--dimensions <dimensions>	向量维度。默认值为 2048。
--include-content	是否返回完整 content。默认值为 false。

使用示例

  bytehouse-cli volcengine hybrid_search search \
  --table-name default.docs \
  --query "ByteHouse 向量检索怎么使用" \
  --fields "title,content" \
  --top-k 5 \
  --recall-k 20 \
  --rrf-k 60

集群诊断与运维

提供集群健康检查与问题排查能力，包括节点状态、查询执行情况、系统表完整性等。可通过bytehouse-cli diagnostics命令查询，并自动生成记录诊断结果的JSON文件。

集群诊断

命令格式

bytehouse-cli diagnostics [--full] [--limit <limit>] [--query-duration <ms>] [--time-range <hours>]

用途说明
执行 ByteHouse 集群诊断，适合排查慢查询、分区、最近一段时间的运行问题。
参数说明

| | ||| \

参数	说明
--full	是否运行完整诊断。适合做一次全量健康检查。默认值为 true。
--limit <limit>	查询限制条数。用于限制诊断时查询的记录规模。默认值为 20。
--query-duration <ms>	慢查询阈值。默认值为 1000，单位通常为毫秒，表示关注超过该阈值的查询。
--time-range <hours>	时间范围。默认值为 1，单位通常为小时，用于限定查询历史窗口。

使用示例

bytehouse-cli diagnostics \
  --query-duration 2000 \
  --time-range 2 \
  --limit 50

使用建议
适用于数据库性能排查：查询响应缓慢、疑似存在慢 SQL，需快速查看分区、语句耗时与时段异常指标。

计算组管理查询

提供计算组（Virtual Warehouse）信息查询能力，包括计算组列表、详细信息及配置查看等。
命令格式

bytehouse-cli virtual-warehouse <操作>

用途说明
执行 ByteHouse 集群诊断，适合排查慢查询、分区、最近一段时间的运行问题。
参数说明

| | | \

参数	说明
list	查看所有计算组列表，支持分页查询。
	参数详解：
	```Bash
	bytehouse-cli virtual-warehouse list [--limit ] [--offset ]
	```
	* --limit <limit>：返回的计算组数量限制，默认值为100。
	* --offset <offset>：返回的计算组偏移量，默认值为0。
detail	查看指定计算组详情。
	参数详解：
	```Bash
	bytehouse-cli virtual-warehouse detail --name
	```
	* --name <name>：计算组名称。
config	查看计算组配置。
	参数详解：
	```Bash
	bytehouse-cli virtual-warehouse config [--limit ] [--offset ]
	```
	* --limit <limit>：返回的计算组数量上限， 默认值为10。
	* --offset <offset> ：返回的计算组分页偏移量 ，默认值为0。