# 指标与指标树命令参考

来源：语雀《guancli 指标能力使用文档》

本文只记录当前 guancli 指标相关命令、参数和高频示例。使用时替换示例中的 ID 和 profile。

## 全局参数

适用于 `metric` 与 `metric_attribution` 命令：

| 参数 | 说明 |
| --- | --- |
| `--profile string` | 使用指定环境配置 |
| `-f, --format string` | 输出格式：`auto`、`csv`、`expanded`、`table`、`json`，默认 `auto` |
| `--raw` | 输出服务端原始 JSON，跳过 CLI 解析和格式化 |
| `--brief` | 轻量输出模式，省略部分高 token 内容 |
| `-v, --verbose` | 显示详细日志 |
| `-h, --help` | 查看帮助 |

## metric

入口：

```bash
guancli metric [command]
```

子命令：

| 子命令 | 功能 |
| --- | --- |
| `project` | 获取指标主题列表 |
| `search` | 搜索指标 |
| `get` | 获取指标详情 |
| `by-dataset` | 按数据集 ID 获取直接和下游关联指标 |
| `query` | 查询指标数据 |
| `tree` | 获取指标目录树 |
| `create` | 新建原子指标（JSON 文件驱动） |
| `edit` | 编辑原子指标（JSON patch / replace） |
| `delete` | 删除指标（先执行删除影响校验） |
| `public-dim` | 公共维度查询、新建、编辑、删除 |

### metric project

获取指标主题列表；传关键词时按主题名称做模糊过滤。

```bash
guancli metric project [keyword] [flags]
```

输出中的 `全部指标数` 为主题根目录及其所有子目录累计指标数量。

示例：

```bash
guancli metric project --profile default
guancli metric project 经营 --profile default
guancli metric project 经营 --profile default -f json
guancli metric project 经营 --profile default --raw
```

### metric search

搜索指标；传关键词时后台用 `%keyword%` 模糊匹配，不传关键词返回所有指标。

```bash
guancli metric search [keyword] [flags]
```

专属参数：

| 参数 | 说明 |
| --- | --- |
| `-d, --dir-id string` | 限定搜索主题 ID |

示例：

```bash
guancli metric search 订购 --profile default -d <metric_topic_id>
guancli metric search 订购 --profile default -f json
guancli metric search 订购 --profile default --raw
```

### metric get

获取指标详情，包括元数据、数据口径、数据集、权限、统计信息、自定义属性和血缘关系。

```bash
guancli metric get <metric_id> [flags]
```

示例：

```bash
guancli metric get <metric_id> --profile default
guancli metric get <metric_id> --profile default --brief
guancli metric get <metric_id> --profile default -f json
guancli metric get <metric_id> --profile default --raw
```

### metric by-dataset

按数据集 ID 获取关联指标。命令会跨指标主题扫描指标，并结合指标详情和指标血缘判断该数据集关联的指标；结果包含直接使用该数据集的原子指标，也包含继续引用这些指标的复合指标和衍生指标。

```bash
guancli metric by-dataset <ds_id> [flags]
```

专属参数：

| 参数 | 说明 |
| --- | --- |
| `-d, --dir-id string` | 限定搜索主题 ID |

示例：

```bash
guancli metric by-dataset <ds_id> --profile default
guancli metric by-dataset <ds_id> --profile default -f json
guancli metric by-dataset <ds_id> --profile default -d <metric_topic_id>
guancli metric by-dataset <ds_id> --profile default --raw
```

### metric query

查询指标数据，支持维度、筛选、排序、列筛选和行数限制。泛化查询参数见 `metric-generic-query.md`。

```bash
guancli metric query <metric_id> [flags]
```

专属参数：

| 参数 | 默认值 | 说明 |
| --- | --- | --- |
| `--limit int` | `50` | 数据行数限制 |
| `--dim strings` | 无 | 维度名称，可多次指定，也支持逗号、中文逗号、顿号分隔 |
| `--filter stringArray` | 无 | 筛选条件，格式：`"列名 操作符 值"`，可多次指定 |
| `--combine-type string` | `AND` | 多条件组合方式：`AND` 或 `OR` |
| `--sort-asc string` | 无 | 按列升序排序，与 `--sort-desc` 互斥 |
| `--sort-desc string` | 无 | 按列降序排序，与 `--sort-asc` 互斥 |
| `--columns strings` | 无 | 只显示指定列，逗号分隔，在 CLI 端执行 |
| `--precision int` | `6` | 数值最大小数位数；传 `-1` 保留原始精度 |

筛选操作符：

| 类型 | 操作符 |
| --- | --- |
| 比较 | `EQ`、`NE`、`LT`、`LE`、`GT`、`GE` |
| 区间 | `BT` |
| 集合 | `IN` |
| 空值 | `IS_NULL`、`NOT_NULL` |
| 字符串 | `CONTAINS`、`NOT_CONTAINS`、`STARTSWITH`、`NOT_STARTSWITH`、`ENDSWITH`、`NOT_ENDSWITH` |

示例：

```bash
guancli metric query <metric_id> --profile default
guancli metric query <metric_id> --profile default --dim 省份 --limit 10
guancli metric query <metric_id> --profile default --dim "省份、城市" --limit 20
guancli metric query <metric_id> --profile default --dim 省份 --filter "省份 EQ 河南省"
guancli metric query <metric_id> --profile default --dim 省份 --filter "省份 EQ 河南省" --filter "省份 EQ 青海省" --combine-type OR
guancli metric query <metric_id> --profile default --dim 省份 --sort-desc 订购数量
guancli metric query <metric_id> --profile default --dim 省份 --columns "省份,订购数量"
guancli metric query <metric_id> --profile default --dim 省份 -f csv
guancli metric query <metric_id> --profile default --dim 省份 --raw
```

### metric tree

获取指标目录树。默认输出树形结构，最外层展示指标主题。

```bash
guancli metric tree [flags]
```

示例：

```bash
guancli metric tree --profile default
guancli metric tree --profile default --brief
guancli metric tree --profile default -f json
guancli metric tree --profile default --raw
```

### metric create

新建原子指标。写入流程先读 `metric-mutation.md` 和 `metric-common-fields.md`，原子字段、问询流程和 JSON 模板见 `metric-atomic-mutation.md`。复合指标和衍生指标创建当前使用 `guancli fetch POST /api/metric-platform/metrics/<type>-metrics --stdin`，分别见 `metric-composite-mutation.md` 和 `metric-derived-mutation.md`。

```bash
guancli metric create --profile default --file atomic_metric.json --dry-run
guancli metric create --profile default --file atomic_metric.json -f json
```

专属参数：

| 参数 | 说明 |
| --- | --- |
| `--file string` | 指标请求体 JSON 文件 |
| `--stdin` | 从 stdin 读取指标请求体 JSON |
| `--set key=value` | 覆盖字段；支持点路径；可重复 |
| `--dry-run` | 只输出请求方法、路径和请求体，不提交 |

### metric edit

编辑原子指标。默认先读取现有详情，再将 JSON 文件/stdin 和 `--set` 作为 patch 合并；`--replace` 直接提交输入 JSON。复合指标和衍生指标编辑当前使用 `guancli fetch POST /api/metric-platform/metrics/<type>-metrics/<metric_id> --stdin`，写入流程先读 `metric-mutation.md` 和 `metric-common-fields.md`，再按类型读取对应细节文档。

```bash
guancli metric edit <metric_id> --profile default --file patch.json --dry-run
guancli metric edit <metric_id> --profile default --set name=新名称
guancli metric edit <metric_id> --profile default --file full.json --replace
```

专属参数：

| 参数 | 说明 |
| --- | --- |
| `--file string` | 指标 patch/full JSON 文件 |
| `--stdin` | 从 stdin 读取指标 patch/full JSON |
| `--set key=value` | 覆盖字段；支持点路径；可重复 |
| `--replace` | 直接提交输入 JSON，不先读取现有详情并合并 |
| `--dry-run` | 只输出请求方法、路径和请求体，不提交 |

### metric delete

删除指标。命令与 Web 删除弹窗一致：先调用删除影响校验；如果存在下游指标或卡片，则阻断删除并输出影响列表。未传 `--confirm` 时只输出校验结果，不真实删除。详细流程见 `metric-delete-mutation.md`。

```bash
guancli metric delete <metric_id> --profile default
guancli metric delete <metric_id> --profile default --confirm
guancli metric delete <metric_id> --profile default --confirm --dry-run
```

专属参数：

| 参数 | 说明 |
| --- | --- |
| `--confirm` | 确认删除；未设置时只执行删除影响校验 |
| `--dry-run` | 只输出将执行的删除校验和删除请求，不提交 |

### metric public-dim

公共维度相关操作。详细字段、问询流程和 JSON 模板见 `metric-public-dimension.md`。

```bash
guancli metric public-dim list [keyword]
guancli metric public-dim get <public_dim_id>
guancli metric public-dim fd-map <ds_id>
guancli metric public-dim create --file public_dim.json --dry-run
guancli metric public-dim edit <public_dim_id> --file patch.json
guancli metric public-dim owner <public_dim_id> --business-owner <user_id>
guancli metric public-dim delete <public_dim_id>
guancli metric public-dim delete <public_dim_id> --confirm
```

别名：

```bash
guancli metric public-dimension ...
guancli metric pubdim ...
```

常用参数：

| 子命令 | 参数 | 说明 |
| --- | --- | --- |
| `list` | `--limit` | 返回条数，默认 50 |
| `list` | `--offset` | 分页偏移，默认 0 |
| `list` | `--order-by` | `utimeDesc` 或 `utimeAsc` |
| `create/edit` | `--file`、`--stdin`、`--set`、`--dry-run` | JSON 文件驱动写入 |
| `edit` | `--replace` | 直接提交输入 JSON，不读取详情合并 |
| `owner` | `--business-owner` | 新责任人用户 ID |
| `delete` | `--confirm` | 确认删除；未设置时只执行依赖检查 |
| `delete` | `--dry-run` | 输出依赖检查和删除请求，不提交 |

## metric_attribution

入口：

```bash
guancli metric_attribution [command]
```

子命令：

| 子命令 | 功能 |
| --- | --- |
| `tree` | 获取指标树目录树 |
| `search` | 搜索指标树 |
| `get` | 获取指标树详情 |
| `query` | 查询指标树贡献数据 |

### metric_attribution tree

获取指标树目录树。

```bash
guancli metric_attribution tree --profile test43
guancli metric_attribution tree --profile test43 --brief
guancli metric_attribution tree --profile test43 -f json
guancli metric_attribution tree --profile test43 --raw
```

### metric_attribution search

搜索指标树；不传关键词返回所有指标树。

```bash
guancli metric_attribution search [keyword] [flags]
```

示例：

```bash
guancli metric_attribution search 贡献率 --profile test43
guancli metric_attribution search --profile test43
guancli metric_attribution search 贡献率 --profile test43 -f json
guancli metric_attribution search 贡献率 --profile test43 --raw
```

### metric_attribution get

获取指标树详情，包括指标树元数据、根指标、时间对比配置、维度拆解配置和指标拆解配置。

```bash
guancli metric_attribution get <resource_id> [flags]
```

示例：

```bash
guancli metric_attribution get <metric_tree_id> --profile test43
guancli metric_attribution get <metric_tree_id> --profile test43 -f json
guancli metric_attribution get <metric_tree_id> --profile test43 --raw
```

### metric_attribution query

对指定指标树执行贡献分析，支持指标拆解、单维度拆解和全维扫描。

```bash
guancli metric_attribution query <metric_tree_id> [flags]
```

专属参数：

| 参数 | 默认值 | 适用 target | 说明 |
| --- | --- | --- | --- |
| `--target string` | `index` | 全部 | 分析目标：`index`、`dim`、`scan` |
| `--dim string` | 无 | `dim` | 指定维度名 |
| `--scan-dim strings` | 无 | `scan` | 指定扫描维度，可多次传入 |
| `--exclude-dim strings` | 无 | `scan` | 排除扫描维度，可多次传入 |
| `--period string` | 使用指标树配置 | 全部 | 本期时间，格式 `YYYY-MM-DD` |
| `--last-period string` | 使用指标树配置 | 全部 | 上期时间，格式 `YYYY-MM-DD` |
| `--time-comparison-json string` | 无 | 全部 | 原始时间对比配置 JSON，优先级高于默认配置 |
| `--sort string` | `desc` | 全部 | 排序方式：`asc` 或 `desc` |
| `--limit int` | 无 | `index`、`dim` | 返回条数限制 |
| `--group-limit int` | `5` | `scan` | scan 模式下每个维度返回 Top N |
| `--filter stringArray` | 无 | 全部 | 筛选条件，格式：`"列名 操作符 值"`，可多次指定 |

示例：

```bash
guancli metric_attribution query <metric_tree_id> --profile test43 --target index
guancli metric_attribution query <metric_tree_id> --profile test43 --target index --limit 5
guancli metric_attribution query <metric_tree_id> --profile test43 --target dim --dim 业务员
guancli metric_attribution query <metric_tree_id> --profile test43 --target dim --dim 业务员 --limit 10
guancli metric_attribution query <metric_tree_id> --profile test43 --target scan
guancli metric_attribution query <metric_tree_id> --profile test43 --target scan --scan-dim 业务员 --scan-dim 商品名称
guancli metric_attribution query <metric_tree_id> --profile test43 --target scan --exclude-dim 客户编号
guancli metric_attribution query <metric_tree_id> --profile test43 --target scan --group-limit 3
guancli metric_attribution query <metric_tree_id> --profile test43 --target dim --dim 业务员 --period 2023-07-01 --last-period 2023-06-01
guancli metric_attribution query <metric_tree_id> --profile test43 --target scan --filter "业务员 EQ Lela Kemmer"
guancli metric_attribution query <metric_tree_id> --profile test43 --target dim --dim 业务员 --sort asc
guancli metric_attribution query <metric_tree_id> --profile test43 --target dim --dim 业务员 -f json
guancli metric_attribution query <metric_tree_id> --profile test43 --target scan -f csv
guancli metric_attribution query <metric_tree_id> --profile test43 --target dim --dim 业务员 --raw
```