数据与执行命令

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

HQL 表达式

本页的 data-model query、metric、measure 等命令广泛使用 HQL (Hengshi Query Language) 表达式来定义聚合、计算字段和查询条件。HQL 支持聚合函数（SUM、AVG、COUNT 等）、时间函数（YEAR、MONTH、PERIODCOMPARE 等）和条件逻辑。完整的函数列表请参考 HQL 函数参考。

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

最小可用示例：

hbi connection list --output 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 浏览：

# 只列出 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

最小可用示例：

hbi dataset list --app 4812 --output 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

最小可用示例：

hbi data-model query --app 4812 --dataset 3 "SUM({amount})" --output 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

最小可用示例：

hbi metric list --app 4812 --dataset 3 --output 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

最小可用示例：

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

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

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

创建或更新业务指标时，可以同时定义限定条件和时间轴：

• -w, --where <HQL>：限定条件 HQL；参数可重复，多个条件按 AND 组合。
• --time-dimension <FIELD>：时间轴字段名。
• --time-granularity <GRANULARITY>：时间粒度，可选值为 year、qoy、quarter、moy、month、week、dom、dow、day。

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

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 \
  --where "{amount} > 0" \
  --time-dimension order_date \
  --time-granularity day

典型输出：

[
  {
    "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

最小可用示例：

hbi pipeline list --output 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

最小可用示例：

hbi notebook list --output 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

最小可用示例：

hbi data-alert list 4812 --output 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

最小可用示例：

hbi data-agent config get --output 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。