@guandata/guancli 1.0.24 → 1.0.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/README.md +18 -0
  3. package/binaries/guancli-darwin-arm64 +0 -0
  4. package/binaries/guancli-darwin-x64 +0 -0
  5. package/binaries/guancli-linux-arm64 +0 -0
  6. package/binaries/guancli-linux-x64 +0 -0
  7. package/binaries/guancli-win32-x64.exe +0 -0
  8. package/package.json +3 -3
  9. package/skills/guancli/SKILL.md +17 -1
  10. package/skills/guancli/references/metric-commands.md +240 -0
  11. package/skills/guancli/references/metric-generic-query.md +195 -0
package/CHANGELOG.md CHANGED
@@ -1,5 +1,19 @@
1
1
  # Changelog
2
2
 
3
+ ## @guandata/guancli 1.0.26 - 2026-05-25
4
+
5
+ - 新增 `ds execute-sql` 命令，支持对一个或多个数据集执行 SQL 查询，并提供 JSON/CSV/表格等输出。
6
+ - `ds execute-sql` 支持旧版 public-api fallback，兼容未开放新接口的 BI 环境。
7
+ - 改进卡片预览写入 `/dev/stdout` 时的输出行为，避免混入非数据日志。
8
+ - 增强卡片表格输出的稳定性，排序时可处理不完整行数据。
9
+
10
+ ## @guandata/guancli 1.0.25 - 2026-05-21
11
+
12
+ - 指标查询能力增强，补充指标泛化查询、同环比、最近周期、占比、Top N 排名等参数说明和参考文档。
13
+ - 新增 `server-version` / `bi-version` 命令，可查看当前 BI 版本，并在指标泛化查询前进行版本兼容性检查。
14
+ - 登录流程补充隐私协议提示，便于首次授权时确认使用前提。
15
+ - 优化数据集字段信息解析能力，便于在筛选和指标相关场景中复用字段元数据。
16
+
3
17
  ## @guandata/guancli 1.0.24 - 2026-05-20
4
18
 
5
19
  - 新增卡片预览数据分页能力，提升大数据量预览时的可用性与稳定性。
package/README.md CHANGED
@@ -23,6 +23,10 @@ guancli etl tree
23
23
  guancli etl get <resource_id>
24
24
  guancli ds search <keyword>
25
25
  guancli ds preview <ds_id>
26
+ guancli ds execute-sql -inputs <ds_id> -sql "SELECT * FROM input1 LIMIT 20" # 需目标 BI 支持该接口并开启高级 SQL 查询
27
+ guancli ds execute-sql -inputs <ds_id> -sql "SELECT * FROM input1 LIMIT 20" -f json
28
+ guancli ds execute-sql -inputs <ds_id> -sql "SELECT * FROM input1 LIMIT 20" --raw
29
+ # 旧版 public-api fallback 不支持 disable-cache；--limit 在非 raw 输出渲染前本地截断，--raw 保持后端原始响应
26
30
  guancli page get <page_id>
27
31
  guancli card preview <card_id>
28
32
  guancli chatbi query --theme-name "经营主题" --message "最近30天营业收入是多少？"
@@ -30,6 +34,20 @@ guancli chatbi query --theme-name "经营主题" --message "最近30天营业收
30
34
 
31
35
  ## 版本更新
32
36
 
37
+ ### 1.0.26
38
+
39
+ - 新增 `ds execute-sql` 命令，支持对一个或多个数据集执行 SQL 查询，并提供 JSON/CSV/表格等输出。
40
+ - `ds execute-sql` 支持旧版 public-api fallback，兼容未开放新接口的 BI 环境。
41
+ - 改进卡片预览写入 `/dev/stdout` 时的输出行为，避免混入非数据日志。
42
+ - 增强卡片表格输出的稳定性，排序时可处理不完整行数据。
43
+
44
+ ### 1.0.25
45
+
46
+ - 指标查询能力增强，补充指标泛化查询、同环比、最近周期、占比、Top N 排名等参数说明和参考文档。
47
+ - 新增 `server-version` / `bi-version` 命令，可查看当前 BI 版本，并在指标泛化查询前进行版本兼容性检查。
48
+ - 登录流程补充隐私协议提示，便于首次授权时确认使用前提。
49
+ - 优化数据集字段信息解析能力，便于在筛选和指标相关场景中复用字段元数据。
50
+
33
51
  ### 1.0.24
34
52
 
35
53
  - 新增卡片预览数据分页能力，提升大数据量预览时的可用性与稳定性。
package/binaries/guancli-darwin-arm64 CHANGED
Binary file
package/binaries/guancli-darwin-x64 CHANGED
Binary file
package/binaries/guancli-linux-arm64 CHANGED
Binary file
package/binaries/guancli-linux-x64 CHANGED
Binary file
package/binaries/guancli-win32-x64.exe CHANGED
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@guandata/guancli",
3
- "version": "1.0.24",
3
+ "version": "1.0.26",
4
4
  "description": "观远 BI 命令行工具 - 通过 API 操作 ETL、数据集、页面、表单等资源，并提供 ChatBI 问数/洞察能力",
5
5
  "bin": {
6
6
  "guancli": "bin/run.js"
@@ -35,7 +35,7 @@
35
35
  "node": ">=14"
36
36
  },
37
37
  "publishConfig": {
38
- "access": "public",
39
- "registry": "https://app.mayidata.com/nexus/repository/guandata-web/"
38
+ "registry": "https://registry.npmjs.org/",
39
+ "access": "public"
40
40
  }
41
41
  }
package/skills/guancli/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: guancli
3
- description: 当用户要分析观远 BI / Guandata 的 ETL、数据集、页面/仪表板、卡片、血缘、节点 SQL、资源树、目录、表单填报数据，或给出 ETL ID、dsId、page ID、card ID 想看现有内容时，主动使用这个 skill。即使用户只说"看一下这个 page""贴一下这个 ETL 的 SQL""搜个叫 X 的数据集""这个数据集长啥样""页面卡片用了哪些 ds"，也要触发。它直接调用 BI HTTP API 拉数据并整理成 AI 友好的中文结论，定位是只读分析（Form 表单填报例外，支持 CRUD）。修改 ETL 走 guanetl；新建/改 Card/Page 走 guanvis；数据源/数据集 CRUD/增量/调度走 guands；页面 PNG 视觉验证走 guanvis screenshot；管理员级 SVC SQL / 动态码走 guanadmin。若用户希望直接分析 BI 项目而不是手工点页面，或希望直接通过 ChatBI 进行主题问数/洞察分析，也应优先使用这个 skill。
3
+ description: 当用户要分析观远 BI / Guandata 的 ETL、数据集、页面/仪表板、卡片、血缘、节点 SQL、资源树、目录、表单填报数据、指标 metric、指标树归因 metric_attribution、指标泛化查询参数，或给出 ETL ID、dsId、page ID、card ID、metric ID、metric tree ID 想看现有内容/查询数据时，主动使用这个 skill。即使用户只说"看一下这个 page""贴一下这个 ETL 的 SQL""搜个叫 X 的数据集""这个数据集长啥样""页面卡片用了哪些 ds""帮我查这个指标""生成指标泛化查询命令"，也要触发。它直接调用 BI HTTP API 拉数据并整理成 AI 友好的中文结论，定位是只读分析（Form 表单填报例外，支持 CRUD）。修改 ETL 走 guanetl；新建/改 Card/Page 走 guanvis；数据源/数据集 CRUD/增量/调度走 guands；页面 PNG 视觉验证走 guanvis screenshot；管理员级 SVC SQL / 动态码走 guanadmin。若用户希望直接分析 BI 项目而不是手工点页面，或希望直接通过 ChatBI 进行主题问数/洞察分析，也应优先使用这个 skill。
4
4
  compatibility: Requires Node.js 14+. Install via npm install -g @guandata/guancli.
5
5
  ---
6
6
 
@@ -14,6 +14,7 @@ compatibility: Requires Node.js 14+. Install via npm install -g @guandata/guancl
14
14
  - 用户在排查 BI 资源配置、页面卡片定义、接口返回或 lineage 关系。
15
15
  - 用户需要对表单填报(Form)数据进行 CRUD 操作（查询/插入/更新/删除）。
16
16
  - 用户要直接用 ChatBI 主题做 L1 问数或 L2 洞察，而不是打开网页手工操作。
17
+ - 用户要搜索指标、获取指标详情、查询指标数据、查看指标目录、执行指标树归因，或让你生成/解释指标泛化查询命令。
17
18
 
18
19
  如果用户只想生成页面 PNG 截图成品，不要用本 skill，改用 `guanvis screenshot`。页面截图不要再走 `guanexport`；移动端页面/卡片导出仍暂用 `guanexport` legacy 功能。
19
20
 
@@ -95,6 +96,19 @@ guancli 是 BI 资源的**只读分析入口**（Form 表单填报例外）。
95
96
  4. 信息不全时先 `tree` 或 `search`，拿到 ID 后再 `get`。
96
97
  5. `tree` 和 `search` 语义不同：目录名能出现在 `ds tree`，不代表同词一定能命中 `ds search`。
97
98
 
99
+ ## 指标命令参考
100
+
101
+ 当任务涉及指标、指标树归因、`metric query`、泛化查询、同比/环比、XTD、最近 N 周期、占比、Top N 排名或 `adv-calc-json` 时，先按需读取引用文件，避免把全部命令塞进主 skill：
102
+
103
+ - 指标与指标树全量命令：`references/metric-commands.md`
104
+ - 指标泛化查询参数与示例：`references/metric-generic-query.md`
105
+
106
+ 关键规则：
107
+
108
+ - 普通指标数据查询用 `guancli metric query <metric_id>`，可加 `--dim`、`--filter`、排序、列筛选、输出格式等。
109
+ - 只要传入 `--compare`、`--compare-value`、`--xtd`、`--last`、`--recent`、`--recent-base`、`--percentage`、`--percentage-dim`、`--rank-top`、`--rank-order`、`--rank-dim`、`--adv-calc-json` 任一参数，就进入指标泛化查询模式。
110
+ - 泛化查询要求 BI 版本 `>= 8.2.1`；如需确认环境版本，先执行 `guancli server-version --profile <profile>`。
111
+
98
112
  ## 标准分析流程
99
113
 
100
114
  ### 1. 拉取目录树
@@ -139,6 +153,8 @@ guancli page get <resource_id> # 页面详情（含卡片列表、血缘
139
153
  guancli ds preview <ds_id> # 预览数据集数据 (表格格式)
140
154
  guancli ds preview <ds_id> --limit 20 # 限制预览行数
141
155
  guancli ds preview <ds_id> --raw # 输出原始 JSON
156
+ guancli ds execute-sql -inputs <ds_id> -sql "SELECT * FROM input1 LIMIT 20" # 用 SQL 查询数据集（需目标 BI 支持该接口并开启高级 SQL 查询）
157
+ `execute-sql` 的旧版 public-api fallback 不支持 disable-cache；`--limit` 在非 raw 输出渲染前本地截断，`--raw` 保持后端原始响应。
142
158
  ```
143
159
 
144
160
  数据集 ID (dsId) 可通过 `ds tree` 或 `ds search` 获取。
package/skills/guancli/references/metric-commands.md ADDED
@@ -0,0 +1,240 @@
1
+ # 指标与指标树命令参考
2
+
3
+ 来源：语雀《guancli 指标能力使用文档》
4
+
5
+ 本文只记录当前 guancli 指标相关命令、参数和高频示例。使用时替换示例中的 ID 和 profile。
6
+
7
+ ## 全局参数
8
+
9
+ 适用于 `metric` 与 `metric_attribution` 命令：
10
+
11
+ | 参数 | 说明 |
12
+ | --- | --- |
13
+ | `--profile string` | 使用指定环境配置 |
14
+ | `-f, --format string` | 输出格式：`auto`、`csv`、`expanded`、`table`、`json`，默认 `auto` |
15
+ | `--raw` | 输出服务端原始 JSON，跳过 CLI 解析和格式化 |
16
+ | `--brief` | 轻量输出模式，省略部分高 token 内容 |
17
+ | `-v, --verbose` | 显示详细日志 |
18
+ | `-h, --help` | 查看帮助 |
19
+
20
+ ## metric
21
+
22
+ 入口：
23
+
24
+ ```bash
25
+ guancli metric [command]
26
+ ```
27
+
28
+ 子命令：
29
+
30
+ | 子命令 | 功能 |
31
+ | --- | --- |
32
+ | `search` | 搜索指标 |
33
+ | `get` | 获取指标详情 |
34
+ | `query` | 查询指标数据 |
35
+ | `tree` | 获取指标目录树 |
36
+
37
+ ### metric search
38
+
39
+ 搜索指标；传关键词时后台用 `%keyword%` 模糊匹配，不传关键词返回所有指标。
40
+
41
+ ```bash
42
+ guancli metric search [keyword] [flags]
43
+ ```
44
+
45
+ 专属参数：
46
+
47
+ | 参数 | 说明 |
48
+ | --- | --- |
49
+ | `-d, --dir-id string` | 限定搜索主题 ID |
50
+
51
+ 示例：
52
+
53
+ ```bash
54
+ guancli metric search 订购 --profile default -d <metric_topic_id>
55
+ guancli metric search 订购 --profile default -f json
56
+ guancli metric search 订购 --profile default --raw
57
+ ```
58
+
59
+ ### metric get
60
+
61
+ 获取指标详情，包括元数据、数据口径、数据集、权限、统计信息、自定义属性和血缘关系。
62
+
63
+ ```bash
64
+ guancli metric get <metric_id> [flags]
65
+ ```
66
+
67
+ 示例：
68
+
69
+ ```bash
70
+ guancli metric get <metric_id> --profile default
71
+ guancli metric get <metric_id> --profile default --brief
72
+ guancli metric get <metric_id> --profile default -f json
73
+ guancli metric get <metric_id> --profile default --raw
74
+ ```
75
+
76
+ ### metric query
77
+
78
+ 查询指标数据，支持维度、筛选、排序、列筛选和行数限制。泛化查询参数见 `metric-generic-query.md`。
79
+
80
+ ```bash
81
+ guancli metric query <metric_id> [flags]
82
+ ```
83
+
84
+ 专属参数：
85
+
86
+ | 参数 | 默认值 | 说明 |
87
+ | --- | --- | --- |
88
+ | `--limit int` | `50` | 数据行数限制 |
89
+ | `--dim strings` | 无 | 维度名称，可多次指定，也支持逗号、中文逗号、顿号分隔 |
90
+ | `--filter stringArray` | 无 | 筛选条件，格式：`"列名 操作符 值"`，可多次指定 |
91
+ | `--combine-type string` | `AND` | 多条件组合方式：`AND` 或 `OR` |
92
+ | `--sort-asc string` | 无 | 按列升序排序，与 `--sort-desc` 互斥 |
93
+ | `--sort-desc string` | 无 | 按列降序排序，与 `--sort-asc` 互斥 |
94
+ | `--columns strings` | 无 | 只显示指定列，逗号分隔，在 CLI 端执行 |
95
+ | `--precision int` | `6` | 数值最大小数位数；传 `-1` 保留原始精度 |
96
+
97
+ 筛选操作符：
98
+
99
+ | 类型 | 操作符 |
100
+ | --- | --- |
101
+ | 比较 | `EQ`、`NE`、`LT`、`LE`、`GT`、`GE` |
102
+ | 区间 | `BT` |
103
+ | 集合 | `IN` |
104
+ | 空值 | `IS_NULL`、`NOT_NULL` |
105
+ | 字符串 | `CONTAINS`、`NOT_CONTAINS`、`STARTSWITH`、`NOT_STARTSWITH`、`ENDSWITH`、`NOT_ENDSWITH` |
106
+
107
+ 示例：
108
+
109
+ ```bash
110
+ guancli metric query <metric_id> --profile default
111
+ guancli metric query <metric_id> --profile default --dim 省份 --limit 10
112
+ guancli metric query <metric_id> --profile default --dim "省份、城市" --limit 20
113
+ guancli metric query <metric_id> --profile default --dim 省份 --filter "省份 EQ 河南省"
114
+ guancli metric query <metric_id> --profile default --dim 省份 --filter "省份 EQ 河南省" --filter "省份 EQ 青海省" --combine-type OR
115
+ guancli metric query <metric_id> --profile default --dim 省份 --sort-desc 订购数量
116
+ guancli metric query <metric_id> --profile default --dim 省份 --columns "省份,订购数量"
117
+ guancli metric query <metric_id> --profile default --dim 省份 -f csv
118
+ guancli metric query <metric_id> --profile default --dim 省份 --raw
119
+ ```
120
+
121
+ ### metric tree
122
+
123
+ 获取指标目录树。默认输出树形结构，最外层展示指标主题。
124
+
125
+ ```bash
126
+ guancli metric tree [flags]
127
+ ```
128
+
129
+ 示例：
130
+
131
+ ```bash
132
+ guancli metric tree --profile default
133
+ guancli metric tree --profile default --brief
134
+ guancli metric tree --profile default -f json
135
+ guancli metric tree --profile default --raw
136
+ ```
137
+
138
+ ## metric_attribution
139
+
140
+ 入口：
141
+
142
+ ```bash
143
+ guancli metric_attribution [command]
144
+ ```
145
+
146
+ 子命令：
147
+
148
+ | 子命令 | 功能 |
149
+ | --- | --- |
150
+ | `tree` | 获取指标树目录树 |
151
+ | `search` | 搜索指标树 |
152
+ | `get` | 获取指标树详情 |
153
+ | `query` | 查询指标树贡献数据 |
154
+
155
+ ### metric_attribution tree
156
+
157
+ 获取指标树目录树。
158
+
159
+ ```bash
160
+ guancli metric_attribution tree --profile test43
161
+ guancli metric_attribution tree --profile test43 --brief
162
+ guancli metric_attribution tree --profile test43 -f json
163
+ guancli metric_attribution tree --profile test43 --raw
164
+ ```
165
+
166
+ ### metric_attribution search
167
+
168
+ 搜索指标树；不传关键词返回所有指标树。
169
+
170
+ ```bash
171
+ guancli metric_attribution search [keyword] [flags]
172
+ ```
173
+
174
+ 示例：
175
+
176
+ ```bash
177
+ guancli metric_attribution search 贡献率 --profile test43
178
+ guancli metric_attribution search --profile test43
179
+ guancli metric_attribution search 贡献率 --profile test43 -f json
180
+ guancli metric_attribution search 贡献率 --profile test43 --raw
181
+ ```
182
+
183
+ ### metric_attribution get
184
+
185
+ 获取指标树详情，包括指标树元数据、根指标、时间对比配置、维度拆解配置和指标拆解配置。
186
+
187
+ ```bash
188
+ guancli metric_attribution get <resource_id> [flags]
189
+ ```
190
+
191
+ 示例：
192
+
193
+ ```bash
194
+ guancli metric_attribution get <metric_tree_id> --profile test43
195
+ guancli metric_attribution get <metric_tree_id> --profile test43 -f json
196
+ guancli metric_attribution get <metric_tree_id> --profile test43 --raw
197
+ ```
198
+
199
+ ### metric_attribution query
200
+
201
+ 对指定指标树执行贡献分析，支持指标拆解、单维度拆解和全维扫描。
202
+
203
+ ```bash
204
+ guancli metric_attribution query <metric_tree_id> [flags]
205
+ ```
206
+
207
+ 专属参数：
208
+
209
+ | 参数 | 默认值 | 适用 target | 说明 |
210
+ | --- | --- | --- | --- |
211
+ | `--target string` | `index` | 全部 | 分析目标：`index`、`dim`、`scan` |
212
+ | `--dim string` | 无 | `dim` | 指定维度名 |
213
+ | `--scan-dim strings` | 无 | `scan` | 指定扫描维度，可多次传入 |
214
+ | `--exclude-dim strings` | 无 | `scan` | 排除扫描维度，可多次传入 |
215
+ | `--period string` | 使用指标树配置 | 全部 | 本期时间，格式 `YYYY-MM-DD` |
216
+ | `--last-period string` | 使用指标树配置 | 全部 | 上期时间，格式 `YYYY-MM-DD` |
217
+ | `--time-comparison-json string` | 无 | 全部 | 原始时间对比配置 JSON，优先级高于默认配置 |
218
+ | `--sort string` | `desc` | 全部 | 排序方式：`asc` 或 `desc` |
219
+ | `--limit int` | 无 | `index`、`dim` | 返回条数限制 |
220
+ | `--group-limit int` | `5` | `scan` | scan 模式下每个维度返回 Top N |
221
+ | `--filter stringArray` | 无 | 全部 | 筛选条件，格式：`"列名 操作符 值"`，可多次指定 |
222
+
223
+ 示例：
224
+
225
+ ```bash
226
+ guancli metric_attribution query <metric_tree_id> --profile test43 --target index
227
+ guancli metric_attribution query <metric_tree_id> --profile test43 --target index --limit 5
228
+ guancli metric_attribution query <metric_tree_id> --profile test43 --target dim --dim 业务员
229
+ guancli metric_attribution query <metric_tree_id> --profile test43 --target dim --dim 业务员 --limit 10
230
+ guancli metric_attribution query <metric_tree_id> --profile test43 --target scan
231
+ guancli metric_attribution query <metric_tree_id> --profile test43 --target scan --scan-dim 业务员 --scan-dim 商品名称
232
+ guancli metric_attribution query <metric_tree_id> --profile test43 --target scan --exclude-dim 客户编号
233
+ guancli metric_attribution query <metric_tree_id> --profile test43 --target scan --group-limit 3
234
+ guancli metric_attribution query <metric_tree_id> --profile test43 --target dim --dim 业务员 --period 2023-07-01 --last-period 2023-06-01
235
+ guancli metric_attribution query <metric_tree_id> --profile test43 --target scan --filter "业务员 EQ Lela Kemmer"
236
+ guancli metric_attribution query <metric_tree_id> --profile test43 --target dim --dim 业务员 --sort asc
237
+ guancli metric_attribution query <metric_tree_id> --profile test43 --target dim --dim 业务员 -f json
238
+ guancli metric_attribution query <metric_tree_id> --profile test43 --target scan -f csv
239
+ guancli metric_attribution query <metric_tree_id> --profile test43 --target dim --dim 业务员 --raw
240
+ ```
package/skills/guancli/references/metric-generic-query.md ADDED
@@ -0,0 +1,195 @@
1
+ # 指标泛化查询参考
2
+
3
+ 来源：语雀《guancli 指标泛化查询使用文档》
4
+
5
+ 泛化查询统一入口：
6
+
7
+ ```bash
8
+ guancli metric query <metric_id> [flags]
9
+ ```
10
+
11
+ ## 进入泛化模式的参数
12
+
13
+ 只要传入以下任一参数，CLI 就会进入泛化查询模式：
14
+
15
+ - `--compare`
16
+ - `--compare-value`
17
+ - `--xtd`
18
+ - `--last`
19
+ - `--recent`
20
+ - `--recent-base`
21
+ - `--percentage`
22
+ - `--percentage-dim`
23
+ - `--rank-top`
24
+ - `--rank-order`
25
+ - `--rank-dim`
26
+ - `--adv-calc-json`
27
+
28
+ 泛化查询要求 BI 版本 `>= 8.2.1`。如果用户不确定环境版本，先执行：
29
+
30
+ ```bash
31
+ guancli server-version --profile <profile>
32
+ ```
33
+
34
+ ## 通用参数
35
+
36
+ | 参数 | 说明 |
37
+ | --- | --- |
38
+ | `--profile string` | 使用指定环境 |
39
+ | `--dim strings` | 查询维度，可多次传，也支持逗号、中文逗号、顿号分隔 |
40
+ | `--filter stringArray` | 筛选条件，格式：`"列名 操作符 值"` |
41
+ | `--combine-type string` | 多条件组合方式：`AND` 或 `OR` |
42
+ | `--sort-asc string` | 按列升序排序 |
43
+ | `--sort-desc string` | 按列降序排序 |
44
+ | `--columns strings` | 只显示指定列 |
45
+ | `--limit int` | 返回行数限制 |
46
+ | `--precision int` | 数值最大小数位数，`-1` 表示原始精度 |
47
+ | `-f, --format string` | 输出格式：`auto`、`table`、`csv`、`expanded`、`json` |
48
+ | `--raw` | 输出服务端原始 JSON |
49
+ | `-v, --verbose` | 显示详细日志 |
50
+
51
+ 筛选操作符：`EQ`、`NE`、`LT`、`LE`、`GT`、`GE`、`BT`、`IN`、`IS_NULL`、`NOT_NULL`、`CONTAINS`、`NOT_CONTAINS`、`STARTSWITH`、`NOT_STARTSWITH`、`ENDSWITH`、`NOT_ENDSWITH`。
52
+
53
+ ## 参数值
54
+
55
+ ### `--compare`
56
+
57
+ | 值 | 含义 |
58
+ | --- | --- |
59
+ | `yoy` | 同比，和去年同期相比 |
60
+ | `mom` | 月环比，和上个月同期相比 |
61
+ | `qoq` | 季环比，和上个季度同期相比 |
62
+ | `wow` | 周环比，和上周同期相比 |
63
+ | `dod` | 日环比，和前一天相比 |
64
+
65
+ ### `--compare-value`
66
+
67
+ | 值 | 含义 |
68
+ | --- | --- |
69
+ | `value` | 对比值，返回绝对值变化结果 |
70
+ | `rate` | 对比率，返回变化比例或增长率 |
71
+ | `rawdata` | 原始对比值，返回对比计算所需的原始值 |
72
+
73
+ ### `--xtd`
74
+
75
+ | 值 | 含义 |
76
+ | --- | --- |
77
+ | `ytd` | 年累计 |
78
+ | `qtd` | 季累计 |
79
+ | `mtd` | 月累计 |
80
+ | `wtd` | 周累计 |
81
+ | `dtd` | 日累计 |
82
+
83
+ ### `--recent`
84
+
85
+ 格式：`数字 + d/w/m/q/y`，如 `7d`、`4w`、`3m`、`2q`、`2y`。
86
+
87
+ `--recent-base YYYY-MM-DD` 指定最近 N 个周期向前回看的基准日期，仅和 `--recent` 一起使用。
88
+
89
+ ### 排名
90
+
91
+ | 参数 | 说明 |
92
+ | --- | --- |
93
+ | `--rank-top int` | Top N 数量 |
94
+ | `--rank-order string` | `asc` 或 `desc` |
95
+ | `--rank-dim string` | 排名范围维度名 |
96
+
97
+ ## 主计算互斥
98
+
99
+ 结构化泛化参数当前只支持一次指定一个主高级计算，请在以下几类中选择一种：
100
+
101
+ - `--compare`
102
+ - `--xtd`
103
+ - `--last`
104
+ - `--recent`
105
+ - `--percentage`
106
+ - `--rank-top`
107
+ - `--adv-calc-json`
108
+
109
+ `--compare-value` 必须和 `--compare` 一起使用；`--percentage-dim` 必须和 `--percentage` 一起使用；`--rank-dim` / `--rank-order` 必须和 `--rank-top` 一起使用；`--recent-base` 必须和 `--recent` 一起使用。
110
+
111
+ ## 示例
112
+
113
+ ### 同比 / 环比
114
+
115
+ ```bash
116
+ guancli metric query <metric_id> --profile default --dim 日期 --compare yoy --limit 10
117
+ guancli metric query <metric_id> --profile default --dim 日期 --compare mom --limit 10
118
+ guancli metric query <metric_id> --profile default --dim 日期 --compare yoy --compare-value rate --limit 10
119
+ guancli metric query <metric_id> --profile default --dim 省份 --compare yoy --filter "省份 EQ 河南省" --limit 10
120
+ ```
121
+
122
+ ### 累计 XTD
123
+
124
+ ```bash
125
+ guancli metric query <metric_id> --profile default --dim 日期 --xtd ytd --limit 10
126
+ guancli metric query <metric_id> --profile default --dim 日期 --xtd qtd --limit 10
127
+ guancli metric query <metric_id> --profile default --dim 日期 --xtd mtd --limit 10
128
+ guancli metric query <metric_id> --profile default --dim 日期 --xtd wtd --limit 10
129
+ guancli metric query <metric_id> --profile default --dim 日期 --xtd dtd --limit 10
130
+ ```
131
+
132
+ ### 期末值
133
+
134
+ ```bash
135
+ guancli metric query <metric_id> --profile default --dim 日期 --last --limit 10
136
+ guancli metric query <metric_id> --profile default --dim 省份 --last --limit 10
137
+ ```
138
+
139
+ ### 最近 N 个周期
140
+
141
+ ```bash
142
+ guancli metric query <metric_id> --profile default --dim 日期 --recent 7d --limit 10
143
+ guancli metric query <metric_id> --profile default --dim 日期 --recent 4w --limit 10
144
+ guancli metric query <metric_id> --profile default --dim 日期 --recent 3m --limit 10
145
+ guancli metric query <metric_id> --profile default --dim 日期 --recent 2y --limit 10
146
+ guancli metric query <metric_id> --profile default --dim 日期 --recent 3m --recent-base 2026-04-30 --limit 10
147
+ ```
148
+
149
+ ### 占比
150
+
151
+ ```bash
152
+ guancli metric query <metric_id> --profile default --dim 城市 --percentage --percentage-dim 城市 --limit 10
153
+ guancli metric query <metric_id> --profile default --dim 省份 --percentage --percentage-dim 省份 --limit 10
154
+ guancli metric query <metric_id> --profile default --dim 城市 --percentage --percentage-dim 城市 --sort-desc 订购数量_percentage --limit 10
155
+ ```
156
+
157
+ ### 排名 / Top N
158
+
159
+ ```bash
160
+ guancli metric query <metric_id> --profile default --dim 城市 --rank-top 5 --rank-order desc --rank-dim 城市 --limit 5
161
+ guancli metric query <metric_id> --profile default --dim 省份 --rank-top 10 --rank-order desc --rank-dim 省份 --limit 10
162
+ guancli metric query <metric_id> --profile default --dim 城市 --rank-top 5 --rank-order asc --rank-dim 城市 --limit 5
163
+ ```
164
+
165
+ ### 原始高级计算 JSON
166
+
167
+ ```bash
168
+ guancli metric query <metric_id> \
169
+ --profile default \
170
+ --dim 日期 \
171
+ --adv-calc-json '{"advType":"COMPARATIVE","advValue":{"advType":"COMPARATIVE","dateFdId":"<date_fd_id>","valueType":"VALUE","offset":1,"offsetType":"YEAR","granularity":"YEAR"}}' \
172
+ --limit 10
173
+
174
+ guancli metric query <metric_id> \
175
+ --profile default \
176
+ --dim 日期 \
177
+ --adv-calc-json '{"advType":"RECENT_X","advValue":{"advType":"RECENT_X","dateFdId":"<date_fd_id>","granularity":"DAY","baselineOffset":[6,0]}}' \
178
+ --limit 10
179
+ ```
180
+
181
+ ### 输出格式
182
+
183
+ ```bash
184
+ guancli metric query <metric_id> --profile default --dim 日期 --compare yoy -f json
185
+ guancli metric query <metric_id> --profile default --dim 日期 --xtd ytd -f csv
186
+ guancli metric query <metric_id> --profile default --dim 日期 --recent 7d --raw
187
+ ```
188
+
189
+ ### 常用组合
190
+
191
+ ```bash
192
+ guancli metric query <metric_id> --profile default --dim 省份 --compare yoy --filter "省份 EQ 河南省" --limit 5
193
+ guancli metric query <metric_id> --profile default --dim 日期 --recent 7d --columns "日期,订购数量_recent_7d" --limit 10
194
+ guancli metric query <metric_id> --profile default --dim 城市 --rank-top 5 --rank-order desc --rank-dim 城市 -f json
195
+ ```