---
url: /v6.2/cli-reference-data.md
---
# 数据与执行命令

这一页覆盖数据接入、建模、指标、执行和智能能力，和 `hbi-data`、`hbi-data-modeling`、`hbi-pipeline`、`hbi-notebook`、`hbi-data-alert`、`hbi-data-agent` 等 skills 最接近。每个命令域都提供最小可用示例与典型输出，让你第一次就能照着跑。

> \[!TIP] HQL 表达式
> 本页的 `data-model query`、`metric`、`measure` 等命令广泛使用 [HQL (Hengshi Query Language)](https://api.hengshi.com/function_reference.html) 表达式来定义聚合、计算字段和查询条件。HQL 支持聚合函数（SUM、AVG、COUNT 等）、时间函数（YEAR、MONTH、PERIODCOMPARE 等）和条件逻辑。完整的函数列表请参考 [HQL 函数参考](https://api.hengshi.com/function_reference.html)。

## `connection`

**用途**：管理数据连接、浏览库表、测试连通性。

**常见子命令**：

* 连接本体：`types` `list` `show` `test` `create` `delete` `update`
* 内部授权规则：`auth-rules` `auth-rule-get` `auth-rule-create` `auth-rule-update` `auth-rule-delete`
* 继承控制：`auth-inherit-get` `auth-inherit-update`
* 数据浏览：`browse` `query`

**最小可用示例**：

```bash
hbi connection list --output json
```

**典型输出**：

```json
[
  {
    "id": 39774,
    "title": "analytics-db",
    "accessCount": 273,
    "options": {
      "type": "postgresql",
      "maxConnNum": 10,
      "metaConfig": {
        "dbMajorVersion": 13,
        "dbMinorVersion": 11,
        "dbProductName": "PostgreSQL"
      }
    },
    "createdAt": "2022-10-27 13:54:24",
    "visible": true
  }
]
```

**下一步常见动作**：

* 查看连接详情：`hbi connection show 39774 --output json`
* 测试连通性：`hbi connection test 39774`
* 浏览库表：`hbi connection browse 39774 --output json`

**按 schema/path 浏览**：

```bash
# 只列出 schema/path 层级
hbi connection browse 39774 --schemas --output json

# 精确列出 public schema 下的所有表
hbi connection browse 39774 --schema public --output json

# 多层 path 重复传入 --schema；--query 只在选中的子树内过滤
hbi connection browse 39774 --schema hive --schema default --query orders --output yaml
```

`--schema` 每次接收一个 path 层级，可重复且保留顺序。不要把多层 path 拼成 `catalog.schema`，因为层级名称本身可能包含点号。`--schema` 与 `--query` 同时使用时是 AND 关系；不传 `--schema` 时，`--query` 仍按名称做模糊过滤。

## `dataset`

**用途**：管理数据集、字段、粒度、预览和导入导出。

**常见子命令**：

* 生命周期：`list` `show` `update` `replace` `delete` `duplicate` `import`
* 预览与状态：`preview` `status` `schedule` `lineage` `export`
* 知识增强：`knowledge` `example`
* 创建路径：`create` `create-from-file` `upload` `create-custom-sql` `create-api` `create-reference`
* 数据加工：`create-union` `create-fusion` `create-aggregate` `create-pivot` `create-unpivot`
* 字段与表达式：`fields` `expression-rewrite` `column-create` `column-update` `column-delete`
* 字段补充：`column-values` `column-geo` `column-geo-role` `column-geo-role-reset`
* 粒度：`granularity-list` `granularity-create` `granularity-update` `granularity-delete`

**最小可用示例**：

```bash
hbi dataset list --app 4812 --output json
```

**典型输出**：

```json
[
  {
    "id": 3,
    "title": "销售订单明细",
    "appId": 4812,
    "connectionId": 39774,
    "createdAt": "2025-01-10 09:00:00",
    "updatedAt": "2026-05-20 16:30:00",
    "status": "ready"
  }
]
```

**下一步常见动作**：

* 预览数据：`hbi dataset preview --app 4812 --dataset 3 --limit 10 --output json`
* 查看字段：`hbi dataset fields --app 4812 --dataset 3 --output json`
* 查看数据集状态：`hbi dataset status --app 4812 --dataset 3 --output json`

## `data-model`

**用途**：管理数据模型与联表关系。

**常见子命令**：

* `list` `show` `preview` `query`
* `lineage` `tree`
* `suggest-joins`
* `join-add` `join-list` `join-delete`

**最小可用示例**：

```bash
hbi data-model query --app 4812 --dataset 3 "SUM({amount})" --output json
```

**典型输出**：

```json
{
  "result": [
    {
      "SUM({amount})": 1234567.89
    }
  ],
  "executionTime": 234
}
```

**下一步常见动作**：

* 按维度分组：`hbi data-model query --app 4812 --dataset 3 "SUM({amount})" --by "group({region})" --output json`
* 查看模型树：`hbi data-model tree --app 4812 --dataset 3 --output json`
* 推荐联表：`hbi data-model suggest-joins --app 4812 --dataset 3 --output json`

## `metric`

**用途**：管理原子指标。

**常见子命令**：

* `create` `delete` `update`
* `list` `show`
* `query`

**最小可用示例**：

```bash
hbi metric list --app 4812 --dataset 3 --output json
```

**典型输出**：

```json
[
  {
    "id": 101,
    "name": "销售总额",
    "expression": "SUM({amount})",
    "datasetId": 3,
    "createdAt": "2025-02-10 10:00:00"
  }
]
```

**下一步常见动作**：

* 查看指标详情：`hbi metric show --app 4812 --dataset 3 c1 --output json`
* 查询指标数据：`hbi metric query --app 4812 --dataset 3 c1 --output json`

## `measure`

**用途**：管理业务指标。

**常见子命令**：

* `create` `delete` `update`
* `list` `show`
* `query`

**最小可用示例**：

```bash
hbi measure list --app 4812 --dataset 3 --output json
```

`measure show` 的最后一个参数可以是业务指标的字段名（如 `m1`）或显示名（如 `月度已支付销售额`）。使用显示名时，CLI 会在指定数据集内做精确匹配；如果显示名重名，命令会列出候选字段名，请改用字段名查询。`measure update` 和 `measure delete` 仍只接受字段名。

```bash
hbi measure show --app 4812 --dataset 3 "月度已支付销售额" --output json
```

创建或更新业务指标时，可以同时定义限定条件和时间轴；更新时还可以替换或清空分析维度：

* `-w, --where <HQL>`：限定条件 HQL；参数可重复，多个条件按 `AND` 组合。
* `-D, --dimension <FIELD_OR_LABEL>`：替换分析维度；可重复，也可以用逗号分隔。字段名优先于显示名，显示名按精确匹配解析。
* `--clear-dimensions`：清空全部分析维度，不能与 `--dimension` 同时使用。
* `--time-dimension <FIELD>`：时间轴字段名。
* `--time-granularity <GRANULARITY>`：时间粒度，可选值为 `year`、`qoy`、`quarter`、`moy`、`month`、`week`、`dom`、`dow`、`day`。

`--time-dimension` 和 `--time-granularity` 必须成对使用。`measure update` 显式传入限定条件或时间轴时，会使用这些参数定义的自定义分析语境，不再沿用已有的数据集粒度配置。

```bash
hbi measure create --app 4812 --dataset 3 \
  --label "月度已支付销售额" \
  --expression "SUM({amount})" \
  --where "{status} = 'paid'" \
  --time-dimension order_date \
  --time-granularity month

hbi measure update --app 4812 --dataset 3 m1 \
  --dimension region \
  --dimension "商品类别,订单日期" \
  --where "{amount} > 0" \
  --time-dimension order_date \
  --time-granularity day

hbi measure update --app 4812 --dataset 3 m1 --clear-dimensions
```

**典型输出**：

```json
[
  {
    "id": 201,
    "name": "月度销售增长率",
    "expression": "PERCENTCHANGE(SUM({amount}), month({date}))",
    "datasetId": 3,
    "createdAt": "2025-03-15 11:00:00"
  }
]
```

**下一步常见动作**：

* 查看业务指标详情：`hbi measure show --app 4812 --dataset 3 m1 --output json`
* 搜索业务指标：`hbi measure query --app 4812 --query "销售" --output json`

## `pipeline`

**用途**：管理数据集成流程和节点。

**常见子命令**：

* 流程本体：`list` `show` `create` `update` `delete` `duplicate`
* 运行状态：`status` `errors` `schedule`
* 节点读写：`node` `edit`

**最小可用示例**：

```bash
hbi pipeline list --output json
```

**典型输出**：

```json
[
  {
    "id": 450,
    "title": "日报数据汇总",
    "createdAt": "2025-04-01 08:00:00",
    "updatedAt": "2026-05-25 10:00:00",
    "status": "success"
  }
]
```

**下一步常见动作**：

* 查看流程详情：`hbi pipeline show 450 --output json`
* 查看执行状态：`hbi pipeline status 450 --output json`
* 编辑节点：`hbi pipeline edit add 450 --help`

`edit` 是最常见的下一层入口，常见子命令包括：

* `add`
* `remove`
* `connect`

## `notebook`

**用途**：管理 Notebook、段落和执行相关配置。

**常见子命令**：

* Notebook 本体：`list` `show` `create` `update` `delete`
* 段落：`paragraphs` `add-paragraph` `update-paragraph` `execute` `delete-paragraph`
* 连接：`connections` `add-connection` `authorize-connection` `revoke-connection` `remove-connection`
* 其他：`schedule` `languages`

**最小可用示例**：

```bash
hbi notebook list --output json
```

**典型输出**：

```json
[
  {
    "id": 350,
    "title": "数据分析笔记",
    "createdAt": "2025-05-10 14:00:00",
    "updatedAt": "2026-06-01 09:30:00"
  }
]
```

**下一步常见动作**：

* 查看 Notebook 详情：`hbi notebook show 350 --output json`
* 列出段落：`hbi notebook paragraphs 350 --output json`
* 执行段落：`hbi notebook execute 350 para_123`

## `data-alert`

**用途**：管理数据预警。

**常见子命令**：

* `list` `show`
* `create` `update` `delete`
* `enable` `disable`
* `validate`

**最小可用示例**：

```bash
hbi data-alert list 4812 --output json
```

**典型输出**：

```json
[
  {
    "id": 520,
    "title": "日销售额预警",
    "enabled": true,
    "createdAt": "2025-06-01 10:00:00"
  }
]
```

**下一步常见动作**：

* 查看预警详情：`hbi data-alert show 4812 520 --output json`
* 启用预警：`hbi data-alert enable 4812 520`
* 禁用预警：`hbi data-alert disable 4812 520 --dry-run`

## `data-agent`

**用途**：管理 Data Agent / ChatBI 后台配置。

**常见子命令**：

* `config`
* `prompt`
* `vector`

**最小可用示例**：

```bash
hbi data-agent config get --output json
```

**典型输出**：

```json
{
  "enabled": true,
  "model": "gpt-4",
  "basePrompt": "你是一个数据分析助手",
  "updatedAt": "2026-05-30 16:00:00"
}
```

**下一步常见动作**：

* 查看 prompt 列表：`hbi data-agent prompt list --output json`
* 查看向量化状态：`hbi data-agent vector status --output json`

## 继续下钻建议

| 场景 | 先进入哪层命令树 |
| --- | --- |
| 数据连接、库表浏览、连通性测试 | `connection` |
| 数据集生命周期、预览、字段与粒度 | `dataset` |
| 联表关系与模型查询 | `data-model` |
| 数据集成流程本体 | `pipeline` |
| 节点增删改连线 | `pipeline edit` |
| Notebook、段落与连接 | `notebook` |
| 预警定义与启停 | `data-alert` |
| Data Agent 配置、Prompt 与向量状态 | `data-agent` |

需要具体参数和示例时，再在终端查看对应层级的 `--help`。