把 QuickSight 的业务语义从 Topics 迁到数据集层

Amazon QuickSight 正在把业务上下文的重心从 legacy Topics 推向更靠近数据本身的 semantic datasets，也就是 Dataset Enrichment。变化的关键不只是“入口换了”，而是语义定义的位置变了：字段别名、业务词汇、默认聚合、字段描述这类知识，不再只服务某个 Topic，而是沉到数据集层，供更多分析体验复用。

为什么语义应该靠近数据集

legacy Topics 的问题在于它更像一个问答场景里的语义容器。你可以在 Topic 里告诉 QuickSight：“revenue 也叫 sales”，“customer_id 不适合直接展示”，“order_date 是日期字段”。这些配置对自然语言问答很有用，但它们被绑定在 Topic 上。

Dataset Enrichment 的方向是把这些业务语义直接附着到 dataset：字段名称、同义词、描述、业务含义、字段可见性、聚合方式等上下文，跟随数据集一起被消费。对团队来说，这通常意味着三件事：

• 同一份业务定义可以服务多个分析入口，而不是在多个 Topic 中重复维护。
• 数据集所有者能更早参与语义建模，减少 BI 层和数据层之间的解释偏差。
• 迁移时需要盘点 Topic 中已有的业务规则，不能只复制字段名。

换句话说，迁移不是“删除旧 Topic、创建新数据集”这么简单，而是一次业务语义资产整理。

legacy Topics 和 Dataset Enrichment 的边界

可以把 legacy Topics 理解成面向问答体验的主题层，把 semantic datasets 理解成面向数据资产的语义层。

Topic 更关注用户会怎么问：例如“top customers by revenue last quarter”这类自然语言问题，需要同义词、字段提示和问法约束。Dataset Enrichment 更关注字段本身是什么：例如 net_revenue 的业务定义、默认聚合方式、是否允许被终端用户直接使用。

迁移时不要机械地一对一搬运。建议按下面几类拆开判断：

这里最容易踩坑的是“团队方言”。销售团队说的 bookings、财务团队说的 recognized revenue、运营团队说的 GMV，可能看起来都像 revenue，但口径未必一致。迁移到 dataset 层之前，应该确认这些词到底是不是同一个字段的同义词。

三种迁移路径

1. 单 Topic 对单 Dataset：直接整理并迁移

这是最简单的情况。一个 Topic 主要围绕一个 QuickSight dataset，字段语义也没有跨多个数据源。做法是先导出 Topic 清单，再按字段整理 enrichment 映射。

适合条件：

• Topic 中大多数字段来自同一个 dataset。
• 同义词和字段描述已经比较稳定。
• 用户使用量可控，迁移后容易验证问答结果。

2. 多个 Topic 指向同一 Dataset：合并重复语义

这种场景更常见：不同团队为同一个销售数据集建了多个 Topic，各自维护一套字段别名。迁移时不要把所有同义词直接堆到 dataset 上，而要先去重、合并、评审。

重点看三类冲突：

• 同一个业务词在不同 Topic 中指向不同字段。
• 同一个字段在不同团队里有不同显示名。
• 某些字段在一个 Topic 中被隐藏，在另一个 Topic 中开放。

数据集层的语义更“公共”，因此迁移后的定义应该代表组织级口径，而不是某个 dashboard 的临时便利。

3. 一个 Topic 横跨多个 Dataset：先拆语义，再迁移

如果 legacy Topic 本身融合了多个业务域，例如订单、客户、营销投放都在一个 Topic 中，迁移前要先确认这些语义是否应该回到各自 dataset。不要为了保持旧 Topic 的形状，把所有字段都塞进一个超大的 enriched dataset。

更稳妥的做法是：

• 把字段按源 dataset 和业务域分组。
• 将通用字段语义迁回对应 dataset。
• 对跨域问题保留组合视图、分析模型或文档说明。

这类迁移通常需要业务方参与，因为它会暴露长期积累的字段口径问题。

可以这样实践：先做 Topic 语义盘点

下面这个示例假设你使用 AWS CLI 读取 QuickSight Topic 元数据，先生成迁移盘点文件。不同账号、区域和权限下 API 返回结构可能不同，脚本把原始 JSON 保存下来，便于人工审查和后续转换。

运行前需要修改：

• AWS_ACCOUNT_ID：你的 AWS 账号 ID。
• AWS_REGION：QuickSight 所在区域。
• 确认当前 AWS 凭证有读取 QuickSight Topic 的权限。

#!/usr/bin/env bash
set -euo pipefail

AWS_ACCOUNT_ID="123456789012"
AWS_REGION="us-east-1"
OUT_DIR="quicksight-topic-inventory"

mkdir -p "$OUT_DIR/topics"

aws quicksight list-topics \
  --aws-account-id "$AWS_ACCOUNT_ID" \
  --region "$AWS_REGION" \
  > "$OUT_DIR/topics.json"

jq -r '.Topics[]?.TopicId // empty' "$OUT_DIR/topics.json" | while read -r topic_id; do
  echo "Exporting topic: $topic_id"
  aws quicksight describe-topic \
    --aws-account-id "$AWS_ACCOUNT_ID" \
    --topic-id "$topic_id" \
    --region "$AWS_REGION" \
    > "$OUT_DIR/topics/$topic_id.json"
done

echo "Inventory written to $OUT_DIR"

拿到原始 Topic 后，可以用一个简单的迁移评审表承接字段语义。下面是一个可复制改造的 YAML 模板，用来记录“从 Topic 到 dataset enrichment”的决策，而不是直接把旧配置无脑迁过去。

# semantic-dataset-migration.yaml
account_id: "123456789012"
region: "us-east-1"
source_topics:
  - topic_id: "sales-qa-topic"
    owner: "sales-analytics"
    usage_note: "Used by sales managers for natural-language Q&A"

target_dataset:
  dataset_id: "sales-curated-dataset"
  business_owner: "revenue-operations"
  technical_owner: "data-platform"

fields:
  - physical_name: "net_revenue"
    proposed_display_name: "Net Revenue"
    description: "Revenue after discounts and refunds, excluding tax."
    synonyms:
      - "sales"
      - "revenue"
      - "net sales"
    default_aggregation: "SUM"
    visible_to_authors: true
    migration_decision: "move_to_dataset_enrichment"
    reviewer: "finance"

  - physical_name: "customer_id"
    proposed_display_name: "Customer ID"
    description: "Stable internal identifier for a customer."
    synonyms:
      - "account id"
    default_aggregation: "COUNT_DISTINCT"
    visible_to_authors: false
    migration_decision: "move_with_restricted_visibility"
    reviewer: "data-governance"

  - physical_name: "promo_campaign_name"
    proposed_display_name: "Campaign Name"
    description: "Marketing campaign label from the attribution system."
    synonyms:
      - "promotion"
      - "campaign"
    default_aggregation: "NONE"
    visible_to_authors: true
    migration_decision: "needs_business_review"
    reviewer: "marketing-ops"

如果团队想进一步自动化，可以把这个 YAML 放进代码仓库，用 pull request 做评审。这样业务语义的变更会留下记录，也更容易回答“为什么这个字段被叫作 Net Revenue”。

验证迁移是否真的成功

迁移完成后，不要只检查配置页面。更可靠的验证方式是拿用户过去常问的问题做回归测试。可以准备一组问题清单：

Show total revenue by month for the last 12 months
Top 10 customers by net revenue this quarter
Count of active customers by region
Average order value by sales channel
Refund amount as a percentage of gross revenue

每个问题至少检查三件事：

• QuickSight 是否选择了正确字段。
• 聚合方式是否符合业务口径。
• 字段显示名和解释是否能被业务用户理解。

对于高风险数据集，建议保留一段并行期：legacy Topic 仍可访问，但新问题优先引导到 enriched dataset。等核心问答、dashboard 作者体验和权限边界都验证完，再关闭旧 Topic。

迁移检查清单

落地时可以按这份清单推进：

• 已导出 legacy Topics 的字段、同义词、描述和可见性配置。
• 已识别 Topic 与 dataset 的对应关系：一对一、多对一、还是跨多个 dataset。
• 已处理同义词冲突，尤其是 revenue、customer、booking 这类高频业务词。
• 已让业务 owner 审核字段描述和默认聚合。
• 已准备自然语言问题回归集。
• 已规划并行期和回滚方式。
• 已记录哪些 Topic 配置不适合迁到 dataset 层。

Dataset Enrichment 的价值在于让业务上下文成为数据资产的一部分，而不是散落在一个个问答主题里。迁移时慢一点，把字段口径理清楚，比快速复制配置更重要。语义一旦进入数据集层，就会影响更多作者和消费者；这正是它有价值的地方，也是它需要治理的原因。