293 lines
13 KiB
Markdown
293 lines
13 KiB
Markdown
# 透视表 (pivot-table)
|
||
|
||
## 真对象硬约束
|
||
|
||
当用户要求"透视表 / 分组汇总 / 交叉分析 / 按 X 统计 Y"时，**必须**通过 `pivot-table create` 创建真实的透视表对象。**禁止**用 `SUMIFS` / `COUNTIFS` 等普通公式 + `csv-put` 在原表中拼一张"看起来像透视表的汇总表"来代替——静态公式无法随源数据动态更新，且失去交互能力。判断标准：交付后 `pivot-table list` 必须能返回该对象。
|
||
|
||
## 使用场景
|
||
|
||
读写透视表对象。本 reference 覆盖 4 个命令：
|
||
|
||
| 操作需求 | 使用命令 | 说明 |
|
||
|---------|---------|------|
|
||
| 查看已有透视表 | `pivot-table list` | 获取透视表的结构、数据源和配置 |
|
||
| 创建透视表 | `pivot-table create` | 创建透视表对象 |
|
||
| 更新透视表 | `pivot-table update` | 更新透视表配置（行/列/值/筛选字段） |
|
||
| 删除透视表 | `pivot-table delete` | 删除透视表 |
|
||
|
||
典型工作流：先读取现有透视表了解配置 -> 执行创建/更新/删除 -> 再次读取验证结果。
|
||
|
||
## 行/值字段映射（创建前必做）
|
||
|
||
创建透视表前先识别用户需求中的分组维度和聚合指标，**不要搞反**：
|
||
|
||
- **rows（行字段）** = 分组维度，即"按什么分组"。例：部门、地区、医生、产品类别
|
||
- **values（值字段）** = 聚合指标，即"统计什么数值"。例：销售额（`summarize_by: "sum"`）、订单数（`summarize_by: "count"`）
|
||
- **columns（列字段）** = 交叉维度（可选），即"再按什么横向展开"。例：月份、性别
|
||
|
||
| 用户说 | rows | values | columns |
|
||
|--------|------|--------|---------|
|
||
| "按部门统计人数" | 部门 | 姓名（`"count"`） | -- |
|
||
| "按医生统计费用和结余" | 主管医生 | 费用（`"sum"`）、结余（`"sum"`） | -- |
|
||
| "各部门男女人数" | 部门 | 姓名（`"count"`） | 性别 |
|
||
|
||
**常见配置错误（必须注意）**：
|
||
- **数据源范围必须精确**：透视表的数据源范围必须包含表头行，且精确覆盖全部数据行列。范围过大（包含空行/空列）或过小（遗漏数据列）都会导致透视表结果错误
|
||
- **行列字段选择要匹配用户意图**：用户说"按商品统计金额" -> 行字段=商品，值字段=金额（`summarize_by: "sum"`）。不要把行列字段搞反
|
||
- **聚合类型要匹配**：用户说"统计数量" -> `"count"`；"统计总额" -> `"sum"`；"统计平均" -> `"average"`
|
||
- **创建后必须验证**：调用 `pivot-table list` 确认透视表结构正确
|
||
|
||
## 命令详细参考
|
||
|
||
### 获取透视表
|
||
```
|
||
Usage:
|
||
dws sheet pivot-table list [flags]
|
||
Example:
|
||
# 列出所有透视表
|
||
dws sheet pivot-table list --node NODE_ID --sheet-id SHEET_ID
|
||
|
||
# 获取单个透视表详情
|
||
dws sheet pivot-table list --node NODE_ID --sheet-id SHEET_ID --pivot-table-id PT_ID
|
||
Flags:
|
||
--node string 表格文档 ID 或 URL (必填)
|
||
--sheet-id string 工作表 ID 或名称 (必填)
|
||
--pivot-table-id string 透视表 ID (可选，不传则返回全部)
|
||
```
|
||
|
||
### 创建透视表
|
||
```
|
||
Usage:
|
||
dws sheet pivot-table create [flags]
|
||
Example:
|
||
# 按部门统计销售额（默认自动新建工作表存放）
|
||
dws sheet pivot-table create --node NODE_ID \
|
||
--source "'Sheet1'!A1:D100" \
|
||
--properties '{
|
||
"rows": [{"field": "部门"}],
|
||
"values": [{"field": "销售额", "summarize_by": "sum"}],
|
||
"show_row_grand_total": true
|
||
}'
|
||
|
||
# 指定放置到已有工作表的特定位置
|
||
dws sheet pivot-table create --node NODE_ID \
|
||
--source "'Sheet1'!A1:E200" \
|
||
--target-sheet-id TARGET_SHEET_ID --target-position "A1" \
|
||
--properties '{
|
||
"rows": [{"field": "部门"}],
|
||
"values": [{"field": "销售额", "summarize_by": "sum"}]
|
||
}'
|
||
|
||
# 通过文件传入配置
|
||
dws sheet pivot-table create --node NODE_ID \
|
||
--source "'Sheet1'!A1:D50" --properties @pivot.json
|
||
Flags:
|
||
--node string 表格文档 ID 或 URL (必填)
|
||
--source string 数据源区域，A1 表示法含 sheet 前缀 (必填，如 "'Sheet1'!A1:D100")
|
||
--properties string 透视表配置 JSON (必填，含 rows/columns/values/filters)
|
||
--target-sheet-id string 目标工作表 ID 或名称 (可选，不传则自动新建工作表)
|
||
--target-position string 透视表放置位置 (可选，A1 格式单个 cell，如 "B5"，不传默认 A1)
|
||
```
|
||
|
||
### 更新透视表
|
||
```
|
||
Usage:
|
||
dws sheet pivot-table update [flags]
|
||
Example:
|
||
# 先获取现有配置
|
||
dws sheet pivot-table list --node NODE_ID --sheet-id SHEET_ID --pivot-table-id PT_ID
|
||
|
||
# 修改后回写
|
||
dws sheet pivot-table update --node NODE_ID --sheet-id SHEET_ID --pivot-table-id PT_ID \
|
||
--properties '{
|
||
"rows": [{"field": "部门"}],
|
||
"values": [
|
||
{"field": "销售额", "summarize_by": "sum"},
|
||
{"field": "订单号", "summarize_by": "count", "display_name": "订单数"}
|
||
],
|
||
"show_row_grand_total": true
|
||
}'
|
||
Flags:
|
||
--node string 表格文档 ID 或 URL (必填)
|
||
--sheet-id string 工作表 ID 或名称 (必填)
|
||
--pivot-table-id string 透视表 ID (必填，可通过 pivot-table list 获取)
|
||
--properties string 透视表配置 JSON (必填)
|
||
```
|
||
|
||
### 删除透视表
|
||
```
|
||
Usage:
|
||
dws sheet pivot-table delete [flags]
|
||
Example:
|
||
dws sheet pivot-table delete --node NODE_ID --sheet-id SHEET_ID --pivot-table-id PT_ID
|
||
Flags:
|
||
--node string 表格文档 ID 或 URL (必填)
|
||
--sheet-id string 工作表 ID 或名称 (必填)
|
||
--pivot-table-id string 透视表 ID (必填，可通过 pivot-table list 获取)
|
||
```
|
||
|
||
> [强制] 危险操作：删除不可恢复。必须先向用户展示操作摘要并获得明确同意，用户同意后才加 `--yes` 执行。
|
||
|
||
## `--properties` JSON Schema 速查
|
||
|
||
**顶层字段**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `rows` | object[] | 否 | 行字段数组（分组维度），详见下方「rows/columns 字段项」表 |
|
||
| `columns` | object[] | 否 | 列字段数组（交叉维度），结构同 rows |
|
||
| `values` | object[] | 是 | 值字段数组（聚合指标，至少一项），详见下方「values 字段项」表 |
|
||
| `filters` | object[] | 否 | 筛选字段数组，详见下方「filters 字段项」表 |
|
||
| `show_row_grand_total` | boolean | 否 | 是否显示行总计，默认 true |
|
||
| `show_col_grand_total` | boolean | 否 | 是否显示列总计，默认 true |
|
||
| `show_subtotals` | boolean | 否 | 是否显示分类小计，默认 true |
|
||
| `repeat_row_labels` | boolean | 否 | 是否显示重复项标签，默认 false |
|
||
| `collapse` | object | 否 | 行字段折叠状态：字段名 -> 要折叠的项目列表，如 `{"部门": ["A组", "B组"]}` |
|
||
|
||
**rows/columns 字段项**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `field` | string | 是 | 列名（表头文本），必须与数据源首行的列名完全匹配 |
|
||
| `display_name` | string | 否 | 显示名称（不传时使用 field 值） |
|
||
|
||
**filters 字段项**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `field` | string | 是 | 列名（表头文本），必须与数据源首行的列名完全匹配 |
|
||
| `display_name` | string | 否 | 显示名称（不传时使用 field 值） |
|
||
|
||
**values 字段项**：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `field` | string | 是 | 列名（表头文本），必须与数据源首行的列名完全匹配 |
|
||
| `summarize_by` | string | 否 | 聚合方式，默认 sum，详见下方枚举表 |
|
||
| `display_name` | string | 否 | 显示名称（不传时自动生成，如"求和 - 销售额"） |
|
||
| `show_data_as` | string | 否 | 值显示方式：`normal`/`percent_of_row_total`/`percent_of_col_total`/`percent_of_grand_total` |
|
||
|
||
**summarize_by 枚举值**：
|
||
|
||
| 值 | 说明 |
|
||
|----|------|
|
||
| `sum` | 求和（默认） |
|
||
| `count` | 计数 |
|
||
| `average` | 平均值 |
|
||
| `max` | 最大值 |
|
||
| `min` | 最小值 |
|
||
| `product` | 乘积 |
|
||
| `count_numbers` | 数值计数 |
|
||
| `std_dev` | 标准偏差 |
|
||
| `std_dev_p` | 总体标准偏差 |
|
||
| `var` | 方差 |
|
||
| `var_p` | 总体方差 |
|
||
| `distinct` | 去重计数 |
|
||
| `median` | 中位数 |
|
||
|
||
## `--source` 数据源格式
|
||
|
||
- 格式：`'SheetName'!StartCell:EndCell`
|
||
- 示例：`'Sheet1'!A1:D100`、`'销售数据'!A1:F500`
|
||
- 必须包含表头行（通常从第 1 行开始）
|
||
- sheet 名称用单引号包裹（含空格或特殊字符时必须）
|
||
- `source` 直接使用上述 A1 表示法，不要改写成其他结构
|
||
|
||
## 高级功能示例
|
||
|
||
```bash
|
||
# 含折叠 + show_data_as
|
||
dws sheet pivot-table create --node <NODE_ID> \
|
||
--source "'Sheet1'!A1:E200" \
|
||
--properties '{
|
||
"rows": [{"field": "部门"}],
|
||
"values": [
|
||
{"field": "销售额", "summarize_by": "sum"},
|
||
{"field": "订单数", "summarize_by": "count", "show_data_as": "percent_of_col_total"}
|
||
],
|
||
"collapse": {"部门": ["A组"]},
|
||
"show_row_grand_total": true
|
||
}'
|
||
```
|
||
|
||
> `collapse` / `show_data_as` 为可选字段；仅使用命令文档列出的取值，并按命令返回处理无效配置。
|
||
|
||
## 核心工作流
|
||
|
||
```bash
|
||
# -- 工作流 1: 创建简单分组汇总 --
|
||
|
||
# 1. 先查 sheetId
|
||
dws sheet list --node <NODE_ID> -f json
|
||
|
||
# 2. 查看数据范围确认列名和边界
|
||
dws sheet csv-get --node <NODE_ID> --sheet-id <SHEET_ID> --range "A1:F5"
|
||
|
||
# 3. 创建透视表（按部门统计销售额）
|
||
dws sheet pivot-table create --node <NODE_ID> \
|
||
--source "'Sheet1'!A1:D100" \
|
||
--properties '{
|
||
"rows": [{"field": "部门"}],
|
||
"values": [{"field": "销售额", "summarize_by": "sum"}],
|
||
"show_row_grand_total": true
|
||
}'
|
||
|
||
# 4. 验证创建结果（用 create 返回的 targetSheetId 查询）
|
||
dws sheet pivot-table list --node <NODE_ID> --sheet-id <TARGET_SHEET_ID>
|
||
|
||
# -- 工作流 2: 多维度交叉分析 --
|
||
|
||
dws sheet pivot-table create --node <NODE_ID> \
|
||
--source "'Sheet1'!A1:E200" \
|
||
--properties '{
|
||
"rows": [{"field": "部门"}, {"field": "产品"}],
|
||
"columns": [{"field": "季度"}],
|
||
"values": [
|
||
{"field": "销售额", "summarize_by": "sum"},
|
||
{"field": "订单号", "summarize_by": "count", "display_name": "订单数"}
|
||
],
|
||
"show_row_grand_total": true,
|
||
"show_col_grand_total": true,
|
||
"show_subtotals": true
|
||
}'
|
||
|
||
# -- 工作流 3: 更新透视表配置 --
|
||
|
||
# 先获取现有配置
|
||
dws sheet pivot-table list --node <NODE_ID> --sheet-id <SHEET_ID> --pivot-table-id <PT_ID>
|
||
|
||
# 修改后回写（增加一个值字段）
|
||
dws sheet pivot-table update --node <NODE_ID> --sheet-id <SHEET_ID> --pivot-table-id <PT_ID> \
|
||
--properties '{
|
||
"rows": [{"field": "部门"}],
|
||
"values": [
|
||
{"field": "销售额", "summarize_by": "sum"},
|
||
{"field": "利润", "summarize_by": "average", "display_name": "平均利润"}
|
||
],
|
||
"show_row_grand_total": true
|
||
}'
|
||
```
|
||
|
||
## 上下文传递
|
||
|
||
| 操作 | 从返回中提取 | 用于 |
|
||
|------|-------------|------|
|
||
| `pivot-table list` | `pivotTables[].id` | 后续 update / delete 的 `--pivot-table-id` |
|
||
| `pivot-table list --pivot-table-id` | 完整配置（rows/columns/values/filters/collapse/options） | update 时作为基础配置修改后回写 |
|
||
| `pivot-table create` | `pivotTable.id` | 后续 update / delete 的 `--pivot-table-id` |
|
||
| `pivot-table create` | `pivotTable.targetSheetId` | 后续 list / update / delete 的 `--sheet-id`（透视表所在工作表） |
|
||
| `pivot-table delete` | `message` | 确认删除完成 |
|
||
| `sheet list` | 工作表的 `sheetId` | 所有 pivot-table 命令的 `--sheet-id` |
|
||
|
||
## 注意事项
|
||
|
||
- [强制] **`--sheet-id` 获取规范**：`sheetId` 未知时必须先通过 `dws sheet list --node <NODE_ID> --format json` 查询，禁止凭空编造（如臆测为 `Sheet1`、`sheet1`、`0`、`default` 等）
|
||
- [强制] **创建后必须验证**：透视表创建后必须调用 `pivot-table list` 验证配置是否正确
|
||
- [强制] **pivot-table-id 禁止臆测**：必须通过 `pivot-table list` 获取真实的透视表 ID，不可编造
|
||
- [强制] **source 必须精确**：数据源范围必须从表头行开始，精确覆盖数据区域，先用 `csv-get` 确认数据边界
|
||
- **field 名称必须准确**：rows/columns/values/filters 中的 field 值必须与源数据表头完全一致（区分大小写）
|
||
- **透视表自动新建子表**：创建的透视表默认放置在自动新建的子表中，不会覆盖源数据。可通过 `--target-sheet-id` 和 `--target-position` 指定放置到已有工作表
|
||
- **不支持修改数据源**：update 仅可修改字段配置和显示选项，不可修改 source
|
||
- **折叠状态**：collapse 字段用于控制行字段的展开/折叠，格式为 {字段名: [要折叠的项]}
|
||
- **大 JSON 用 @file**：`--properties` 支持 `@文件路径` 读取本地 JSON 文件
|