# 指标泛化查询参考

来源：语雀《guancli 指标泛化查询使用文档》

泛化查询统一入口：

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

## 进入泛化模式的参数

只要传入以下任一参数，CLI 就会进入泛化查询模式：

- `--compare`
- `--compare-value`
- `--xtd`
- `--last`
- `--recent`
- `--recent-base`
- `--percentage`
- `--percentage-dim`
- `--rank-top`
- `--rank-order`
- `--rank-dim`
- `--adv-calc-json`

泛化查询要求 BI 版本 `>= 8.2.1`。如果用户不确定环境版本，先执行：

```bash
guancli server-version --profile <profile>
```

## 通用参数

| 参数 | 说明 |
| --- | --- |
| `--profile string` | 使用指定环境 |
| `--dim strings` | 查询维度，可多次传，也支持逗号、中文逗号、顿号分隔 |
| `--filter stringArray` | 筛选条件，格式：`"列名 操作符 值"` |
| `--combine-type string` | 多条件组合方式：`AND` 或 `OR` |
| `--sort-asc string` | 按列升序排序 |
| `--sort-desc string` | 按列降序排序 |
| `--columns strings` | 只显示指定列 |
| `--limit int` | 返回行数限制 |
| `--precision int` | 数值最大小数位数，`-1` 表示原始精度 |
| `-f, --format string` | 输出格式：`auto`、`table`、`csv`、`expanded`、`json` |
| `--raw` | 输出服务端原始 JSON |
| `-v, --verbose` | 显示详细日志 |

筛选操作符：`EQ`、`NE`、`LT`、`LE`、`GT`、`GE`、`BT`、`IN`、`IS_NULL`、`NOT_NULL`、`CONTAINS`、`NOT_CONTAINS`、`STARTSWITH`、`NOT_STARTSWITH`、`ENDSWITH`、`NOT_ENDSWITH`。

## 参数值

### `--compare`

| 值 | 含义 |
| --- | --- |
| `yoy` | 同比，和去年同期相比 |
| `mom` | 月环比，和上个月同期相比 |
| `qoq` | 季环比，和上个季度同期相比 |
| `wow` | 周环比，和上周同期相比 |
| `dod` | 日环比，和前一天相比 |

### `--compare-value`

| 值 | 含义 |
| --- | --- |
| `value` | 对比值，返回绝对值变化结果 |
| `rate` | 对比率，返回变化比例或增长率 |
| `rawdata` | 原始对比值，返回对比计算所需的原始值 |

### `--xtd`

| 值 | 含义 |
| --- | --- |
| `ytd` | 年累计 |
| `qtd` | 季累计 |
| `mtd` | 月累计 |
| `wtd` | 周累计 |
| `dtd` | 日累计 |

### `--recent`

格式：`数字 + d/w/m/q/y`，如 `7d`、`4w`、`3m`、`2q`、`2y`。

`--recent-base YYYY-MM-DD` 指定最近 N 个周期向前回看的基准日期，仅和 `--recent` 一起使用。

### 排名

| 参数 | 说明 |
| --- | --- |
| `--rank-top int` | Top N 数量 |
| `--rank-order string` | `asc` 或 `desc` |
| `--rank-dim string` | 排名范围维度名 |

## 主计算互斥

结构化泛化参数当前只支持一次指定一个主高级计算，请在以下几类中选择一种：

- `--compare`
- `--xtd`
- `--last`
- `--recent`
- `--percentage`
- `--rank-top`
- `--adv-calc-json`

`--compare-value` 必须和 `--compare` 一起使用；`--percentage-dim` 必须和 `--percentage` 一起使用；`--rank-dim` / `--rank-order` 必须和 `--rank-top` 一起使用；`--recent-base` 必须和 `--recent` 一起使用。

## 示例

### 同比 / 环比

```bash
guancli metric query <metric_id> --profile default --dim 日期 --compare yoy --limit 10
guancli metric query <metric_id> --profile default --dim 日期 --compare mom --limit 10
guancli metric query <metric_id> --profile default --dim 日期 --compare yoy --compare-value rate --limit 10
guancli metric query <metric_id> --profile default --dim 省份 --compare yoy --filter "省份 EQ 河南省" --limit 10
```

### 累计 XTD

```bash
guancli metric query <metric_id> --profile default --dim 日期 --xtd ytd --limit 10
guancli metric query <metric_id> --profile default --dim 日期 --xtd qtd --limit 10
guancli metric query <metric_id> --profile default --dim 日期 --xtd mtd --limit 10
guancli metric query <metric_id> --profile default --dim 日期 --xtd wtd --limit 10
guancli metric query <metric_id> --profile default --dim 日期 --xtd dtd --limit 10
```

### 期末值

```bash
guancli metric query <metric_id> --profile default --dim 日期 --last --limit 10
guancli metric query <metric_id> --profile default --dim 省份 --last --limit 10
```

### 最近 N 个周期

```bash
guancli metric query <metric_id> --profile default --dim 日期 --recent 7d --limit 10
guancli metric query <metric_id> --profile default --dim 日期 --recent 4w --limit 10
guancli metric query <metric_id> --profile default --dim 日期 --recent 3m --limit 10
guancli metric query <metric_id> --profile default --dim 日期 --recent 2y --limit 10
guancli metric query <metric_id> --profile default --dim 日期 --recent 3m --recent-base 2026-04-30 --limit 10
```

### 占比

```bash
guancli metric query <metric_id> --profile default --dim 城市 --percentage --percentage-dim 城市 --limit 10
guancli metric query <metric_id> --profile default --dim 省份 --percentage --percentage-dim 省份 --limit 10
guancli metric query <metric_id> --profile default --dim 城市 --percentage --percentage-dim 城市 --sort-desc 订购数量_percentage --limit 10
```

### 排名 / Top N

```bash
guancli metric query <metric_id> --profile default --dim 城市 --rank-top 5 --rank-order desc --rank-dim 城市 --limit 5
guancli metric query <metric_id> --profile default --dim 省份 --rank-top 10 --rank-order desc --rank-dim 省份 --limit 10
guancli metric query <metric_id> --profile default --dim 城市 --rank-top 5 --rank-order asc --rank-dim 城市 --limit 5
```

### 原始高级计算 JSON

```bash
guancli metric query <metric_id> \
  --profile default \
  --dim 日期 \
  --adv-calc-json '{"advType":"COMPARATIVE","advValue":{"advType":"COMPARATIVE","dateFdId":"<date_fd_id>","valueType":"VALUE","offset":1,"offsetType":"YEAR","granularity":"YEAR"}}' \
  --limit 10

guancli metric query <metric_id> \
  --profile default \
  --dim 日期 \
  --adv-calc-json '{"advType":"RECENT_X","advValue":{"advType":"RECENT_X","dateFdId":"<date_fd_id>","granularity":"DAY","baselineOffset":[6,0]}}' \
  --limit 10
```

### 输出格式

```bash
guancli metric query <metric_id> --profile default --dim 日期 --compare yoy -f json
guancli metric query <metric_id> --profile default --dim 日期 --xtd ytd -f csv
guancli metric query <metric_id> --profile default --dim 日期 --recent 7d --raw
```

### 常用组合

```bash
guancli metric query <metric_id> --profile default --dim 省份 --compare yoy --filter "省份 EQ 河南省" --limit 5
guancli metric query <metric_id> --profile default --dim 日期 --recent 7d --columns "日期,订购数量_recent_7d" --limit 10
guancli metric query <metric_id> --profile default --dim 城市 --rank-top 5 --rank-order desc --rank-dim 城市 -f json
```