GuanDS 使用指南

更新时间：2026-08-06 16:40:40

产品概述

GuanDS 是什么

GuanDS 是观远 BI 的数据源、数据集和填报表单管理工具。它与 GuanCLI 共用登录状态，支持管理连接账号、从数据库或文件创建数据集、维护数据和字段、设置更新调度，以及管理填报表单。

配合 AI Agent 使用时，用户无需记忆具体命令，只需要描述业务目标，Agent 会根据需求调用 GuanDS 完成资源查询、方案生成、操作预览和执行。

例如：“从分析库的 orders 表创建抽取数据集，先预览，不要发布到生产目录。”Agent 会先查询资源和环境，再生成计划、执行预览，并在确认后写入。

建议先在测试环境或个人目录试用。涉及生产数据、覆盖数据、删除字段或删除资源时，先确认目标环境、资源 ID、影响范围和恢复方案。

说明

目前产品处于公测阶段，可以免费使用所有功能，公测后需要获得商业授权才能继续使用，如仍需体验请联系观远数据商务人员或客户成功经理（通常是贵公司当前的服务交流负责人）。

适用场景

优先使用 GuanDS 处理以下任务：

• 管理数据连接：查看连接器类型、测试连接、创建连接账号、原地改名、原地更新 host/端口/库名/账号/密码/schema。
• 浏览源端结构：查看账号下的 schema、表、字段，预览表数据或 SQL 查询结果。
• 创建数据集：从数据库表、自定义 SQL、CSV、Excel、填报表单创建数据集。
• 维护数据集：搜索、查看详情、查看字段、查看被哪些卡片使用、重命名、移动、另存、删除。
• 维护数据内容：替换文件数据集数据、追加数据、按条件清理数据、按主键去重追加。
• 同步数据结构：源端加列、删列、改名、改类型后，通过 sync-schema 生成计划并原地应用。
• 配置更新策略：设置增量 SQL、preClean 先删后插、去重主键、自动同步新增列、定时更新。
• 管理计算字段：新建、更新、删除和批量新建数据集级计算字段。
• 查看权限影响：查询数据集行列权限配置和关联权限模板，查看数据集被哪些卡片引用。
• 管理任务：查询、等待、取消更新任务，查看近期失败任务辅助诊断。
• 管理填报表单：创建表单、导出表单 DSL、原地更新表单、重命名、移动表单、管理表单目录。

使用边界

GuanDS 不适合承担以下工作：

需求	推荐工具	说明
页面、卡片、仪表板的生成和发布	GuanVis	偏可视化产物
ETL 流程的创建、编辑、保存、发布和运行	GuanETL	偏 ETL 节点和流程编排
复杂血缘分析、数据集预览、页面详情、ETL 详情等只读诊断	GuanCLI	偏只读分析和定位
行列权限的设置或修改	BI 网页端	guands dataset permission get 只负责读取展示
文件上传数据集的结构变更保留 dsId	暂无通用 CLI 方案	replace-data 只替换数据，不改变字段结构
MongoDB、SAP、FTP、服务器文件、对象存储等非标准 host/port 表单连接器的原地更新	BI 网页端	这些连接器的 account update 能力有限
表单 TABLE 子表的原地结构编辑	BI 网页端	子表支持创建，但原地编辑结构暂不支持

高风险操作

以下操作会影响线上数据或引用关系，执行前必须确认目标环境、资源 ID、预览结果和影响范围：

• account delete、dataset delete、dir delete、form folder delete
• dataset replace-data、dataset append-data、dataset clear-data
• dataset sync-schema apply --mode reset
• dataset primary-key set/clear
• dataset calc-field delete
• form update 中删除已有字段

删除、清空、删除计算字段等命令必须显式传 --yes。不确定时先使用 --dry-run、--preview 或 plan。

常见资源 ID

说明 GuanDS 操作过程中会使用资源 ID。

ID	含义	示例
acId	连接账号 ID	数据库连接账号
dsId	数据集 ID	销售订单数据集
fdId	字段 ID	金额字段
dirId	数据集目录 ID	销售分析目录
fmId	填报表单 ID	门店巡检表

资源名称可能重复。 不要根据名称猜测 ID。 执行修改操作前，应先通过 Agent 或查询命令确认资源 ID。

前提条件

安装 GuanDS 前，请确认电脑已安装 Node.js、npm 和 GuanCLI，并已完成 guancli auth login。安装和登录方式请参考 GuanCLI 使用指南。

安装 GuanDS

方式一：通过 npm 命令全局安装

# 首次安装
npm install -g @guandata/guands

# 验证安装
guands version

# 让 AI Agent 识别 GuanDS
guands install-skill

升级时执行：

npm install -g @guandata/guands@latest
guands install-skill

guands install-skill 会安装 GuanDS 的工具说明，让 AI 知道何时使用它；该命令不替代 GuanCLI 登录。

如果已成功安装但终端提示找不到 guands，检查 npm 全局命令目录是否已加入系统 PATH：

npm prefix -g

方式二：通过 Agent 辅助安装

将以下内容发送给 AI Agent：

请检查当前电脑是否已安装 Node.js、GuanCLI 和 GuanDS。
如果 GuanDS 未安装，请执行 npm install -g @guandata/guands，确认 guands version 可以正常执行，
再执行 guands install-skill。不要修改 BI 中的任何资源。

登录 BI 环境

GuanDS 使用 GuanCLI 的认证配置。只要 guancli auth login 登录成功，GuanDS 会自动复用当前环境和账号。详细配置可参考 登录 GuanCLI。

执行写操作前，先检查环境：

guancli auth status
guancli auth list

多环境场景下，请确认当前 profile 正确。不要将其他环境的 acId、dsId、dirId 或 fmId 用于当前环境。

使用 GuanDS 管理数据资产

通常不需要手动执行每一条命令。建议先让 Agent 查询资源和影响范围，再预览写操作；确认结果后再创建、更新或删除。

下面每个步骤提供两种操作方式：

• AI Agent 调用示例：适合希望通过自然语言完成操作的用户；
• CLI 命令参考：适合技术用户直接调用 GuanDS。

第一步：检查环境和资源

请检查当前 GuanCLI 登录的 BI 环境，并搜索名称包含“销售”的数据集。
列出名称、ID、目录、数据来源和最近更新状态。只查询，不做修改。

如果需要管理连接账号，可以这样说：

请列出当前环境可用的连接器和数据库连接账号。不要显示密码，也不要修改配置。

第二步：从数据库或文件创建数据集

从数据库建集前，先让 Agent 测试连接、查看表和字段，再选择抽取或直连模式：

请用 GuanDS 查看“分析库”中的 orders 表结构，并在测试目录创建一个名为“订单明细测试”的抽取数据集。
先展示将执行的命令和目标目录；确认字段、目录和环境后再创建，并等待首次抽取任务完成。

从 CSV 或 Excel 建集时，先预览文件：

请预览 ./sales.xlsx 的 Sheet 和字段。确认“销售明细”Sheet 的表头和字段类型后，导入为测试数据集；先不要覆盖任何已有数据集。

对应命令：

# 浏览数据库结构
guands connector list
guands account list
guands account tables <acId> --schema public
guands account columns <acId> --table orders --schema public

# 从数据库表或 SQL 创建数据集
guands dataset create-db --ac-id <acId> --tables "orders" --ds-names "订单表"
guands dataset create-query --ac-id <acId> --name "用户订单汇总" --sql "SELECT customer_id, SUM(amount) AS total_amount FROM orders GROUP BY customer_id"

# 预览和导入文件
guands dataset import ./sales.csv --preview
guands dataset import ./sales.xlsx --sheet "销售明细"

Excel 有多个 Sheet 时必须指定 --sheet。CSV 第一行必须是表头；需要指定编码、分隔符或字段类型时，先使用 --preview 核对。

第三步：更新已有数据集

更新已有数据集时，优先原地修改，保留 dsId 及其卡片、ETL、权限和调度引用。可以把具体需求直接描述给 Agent：

请用 GuanDS 将 ./fixed.csv 替换到数据集 <dsId>。先查看该数据集的引用卡片和权限配置，
再执行 --dry-run 预览行数变化；确认目标环境和影响范围后再正式替换。

请用 GuanDS 将 ./daily.csv 追加到数据集 <dsId>，先 --dry-run 预览。
如果存在重复主键，请使用 --distinct-by 去重并保留新数据。

请用 GuanDS 清理数据集 <dsId> 中“日期 < 2024-01-01”的数据。
这是高风险操作，先 --dry-run 预览要删除的行数，确认后再执行。

对应命令：

# 替换或追加文件数据
guands dataset replace-data <dsId> ./fixed.csv --dry-run
guands dataset append-data <dsId> ./daily.csv --dry-run

# 按条件清理数据；真正执行需要 --yes
guands dataset clear-data <dsId> --where "日期 < 2024-01-01"
guands dataset clear-data <dsId> --where "日期 < 2024-01-01" --yes

# 查看引用和权限
guands dataset cards <dsId>
guands dataset permission get <dsId>

注意

不要用“删除旧数据集再新建同名数据集”代替编辑。这样会改变 ID，导致下游引用断裂。

第四步：同步结构、字段和计算字段

当数据库源表新增列、删列、改名或改类型后，先让 Agent 生成 schema 同步计划。字段改名时，在计划中映射新字段名，以保留原字段 fdId：

数据库源表结构已变更，请用 GuanDS 为数据集 <dsId> 生成 schema 同步计划。
展示 addedNew、unmappedOrig 和可映射字段；先 --dry-run 核对后再应用。
对于改名字段，请映射新字段名以保留原 fdId。

请在数据集 <dsId> 中新增一个名为“利润率”的计算字段，公式为 [利润]/[销售额]。
先展示将要执行的命令和字段类型，确认后再创建。

对应命令：

guands dataset sync-schema plan <dsId>
guands dataset sync-schema apply <dsId> --plan sync-schema-plan-<dsId>.json --mode schema-only --dry-run
guands dataset sync-schema apply <dsId> --plan sync-schema-plan-<dsId>.json --mode schema-only

# 修改字段展示名或计算字段
guands dataset alias <dsId> --fd-id <fdId> --alias "展示名"
guands dataset calc-field add <dsId> --name "利润率" --formula "[利润]/[销售额]"
guands dataset calc-field update <dsId> --fd-id <fdId> --formula "[利润]/[销售额]*100"

说明

--mode schema-only 只更新结构；--mode reset 会重置并全量覆写数据。直连数据集只能使用 reset，执行前应先确认影响范围。

第五步：设置更新与调度

数据集创建后，可让 Agent 配置增量更新、去重主键和定时任务：

请为数据集 <dsId> 配置时间窗口增量更新：增量 SQL 拉取近 7 天数据，
并使用 preClean 清理同一窗口内的旧数据。先展示 SQL 和规则，确认后再应用。

请为数据集 <dsId> 配置每天凌晨 2 点的定时更新任务，并执行一次 refresh --wait 验证任务能正常完成。

对应命令：

guands dataset update-setting <dsId> \
  --incremental \
  --incremental-sql "SELECT * FROM orders WHERE data_date >= '{{{today - 7 days}}}'" \
  --preclean \
  --preclean-rule "data_date >= '{{{today - 7 days}}}'"

guands dataset primary-key set <dsId> --columns "id" --dry-run
guands dataset schedule <dsId> --cron-type daily --hour 2 --minute 0
guands dataset refresh <dsId> --wait --timeout 600

说明

增量 SQL 和清理规则使用 BI 时间宏，例如 {{{yesterday}}} 或 {{{first day of this month}}}。不要依赖 NOW()、CURDATE() 等数据库时间函数。设置主键前，确认字段非空且唯一。

第六步：管理填报表单和任务

表单更新前先导出当前 DSL，在导出文件上修改，保留已有字段锚点：

请帮我导出 ID 为 <fmId> 的填报表单到 form.js，我修改后再用 GuanDS 原地更新。
更新前先用 --dry-run 核对字段变更，确保不删除已有字段。

数据集 <dsId> 最近更新可能失败了，请用 GuanDS 查看最近 24 小时的失败任务历史，
并展示任务 ID、错误信息和当前数据集状态。

对应命令：

guands form export <fmId> --out form.js
guands form validate form.js
guands form update <fmId> form.js --dry-run
guands form update <fmId> form.js

guands task status <taskId>
guands task wait <taskId> --timeout 600
guands task history --status FAILED --hours 24

表单和数据集是两类资源。要让填报数据进入下游 ETL，先创建对应的填报数据集。删除表单字段会删除历史列数据，必须先确认影响。

使用建议

• 缺少 ID 时先搜索，不要根据名称猜测。资源名称可能重复。
• 写操作先使用 --dry-run、--preview 或 plan，并在执行后回读验证。
• 删除、清空、覆盖、删除字段和 sync-schema --mode reset 属于高风险操作；确认对象、影响范围和授权后再执行。
• dataset refresh 已有进行中任务时不会重复提交。使用 --wait 等待已有任务结束。
• rowCount 是后端元数据快照，不是实时核数结果。验证数据量时应使用业务 SQL、抽样或下游查询。
• 时间窗口增量不会自动删除源端已删除的记录。需要删除语义时，设置合理的 preClean 窗口或周期性全量更新。

常见问题排查

问题一：找不到数据集、目录或连接账号

先确认当前环境：

guancli auth status
guands account list
guands dataset list 销售
guands dir tree

如果名称重复，请根据搜索结果指定资源 ID。

问题二：文件导入后字段不正确

先预览文件：

guands dataset import ./data.csv --preview

确认 CSV 表头、编码和分隔符，或确认 Excel 的 Sheet 与表头行。多 Sheet 的 Excel 必须显式指定 --sheet。

问题三：refresh 后数据量没有变化

先等待任务完成并查看状态：

guands dataset refresh <dsId> --wait --timeout 600
guands task history --status FAILED --hours 24

rowCount 可能尚未刷新；请使用业务查询或抽样核对实际数据，并检查增量 SQL 与清理规则。

问题四：AI 没有自动使用 GuanDS

在需求中明确说明：

请使用 GuanDS 管理这个数据集。先查询资源和影响范围，再预览写操作；没有我的确认不要执行覆盖、删除或清空。

并确认已执行：

guands install-skill

问题五：权限只能查看，不能修改

GuanDS 沿用观远 BI 的资源权限。先查看当前账号和数据集权限；如需修改行列权限，请在 BI 网页端处理。

guancli auth status
guands dataset permission get <dsId>