H&M 测试数据集¶

数据来源

H&M Personalized Fashion Recommendations
Provide product recommendations based on previous purchases
https://www.kaggle.com/competitions/h-and-m-personalized-fashion-recommendations/data

1. 数据集在项目中的角色¶

H&M 数据集是 TTD 的标准验证基线，贯穿开发全链路：

用途	说明
语义资产验证	作为 `semantic-plane/domains/hm_fashion/` 的真实数据映射
端到端联调	Agent Pipeline 完整执行：问题 → 检索 → SQL → 结果 → 可视化
评估基线	评估任务的标准测试问法集基于 H&M 业务场景
规则注入验证	验证 business_rules、business_contexts 的运行时注入效果
新手上手	开发者本地 `task dp:load-hm` 即可拥有完整测试环境

2. 表结构¶

2.1 dim_article（商品主数据，26 列）¶

商品维度表，包含商品属性的多层分类体系。

列名	类型	说明
`article_id`	VARCHAR(16)	商品 ID（主键）
`product_code`	VARCHAR(16)	产品代码（多 article 对应一个 product）
`prod_name`	TEXT	产品名称
`product_type_no`	INTEGER	产品类型编号
`product_type_name`	VARCHAR(256)	产品类型名称
`product_group_name`	VARCHAR(256)	产品组
`graphical_appearance_no`	INTEGER	外观编号
`graphical_appearance_name`	VARCHAR(256)	外观名称
`colour_group_code`	VARCHAR(8)	颜色组代码
`colour_group_name`	VARCHAR(128)	颜色组名称
`perceived_colour_value_id`	INTEGER	感知颜色值 ID
`perceived_colour_value_name`	VARCHAR(128)	感知颜色值名称
`perceived_colour_master_id`	INTEGER	感知主色 ID
`perceived_colour_master_name`	VARCHAR(128)	感知主色名称
`department_no`	INTEGER	部门编号
`department_name`	VARCHAR(256)	部门名称
`index_code`	VARCHAR(8)	分类索引代码
`index_name`	VARCHAR(256)	分类索引名称
`index_group_no`	INTEGER	索引组编号
`index_group_name`	VARCHAR(256)	索引组名称
`section_no`	INTEGER	门店区域编号
`section_name`	VARCHAR(256)	门店区域名称
`garment_group_no`	INTEGER	服装组编号
`garment_group_name`	VARCHAR(256)	服装组名称
`detail_desc`	TEXT	商品详细描述
`image_url`	TEXT	商品图片 URL（衍生列）

2.2 dim_customer（客户主数据，7 列）¶

客户维度表，包含匿名化的客户属性。

列名	类型	说明
`customer_id`	VARCHAR(64)	客户 ID（SHA256 哈希，非自然键）
`fn`	REAL	Fashion News 订阅标记 (1.0/NULL)
`active`	REAL	活跃状态标记 (1.0/NULL)
`club_member_status`	VARCHAR(32)	会员状态 (ACTIVE/PRE-CREATE/LEFT CLUB)
`fashion_news_frequency`	VARCHAR(32)	新闻推送频率 (Regularly/Monthly/NONE)
`age`	SMALLINT	客户年龄
`postal_code`	VARCHAR(128)	邮编（SHA256 哈希，不可做地理分析）

2.3 fact_transaction（交易事实，5 列）¶

购买交易事实表，为分析核心。

列名	类型	说明
`t_dat`	DATE	交易日期
`customer_id`	VARCHAR(64)	客户 ID（FK → dim_customer）
`article_id`	VARCHAR(16)	商品 ID（FK → dim_article）
`price`	DECIMAL(18,8)	归一化价格（0~1，非实际货币）
`sales_channel_id`	SMALLINT	销售渠道 (1=实体店, 2=线上)

3. 关键业务约束¶

必须理解的约束

以下约束已编码进 semantic-plane 的 business_rules 和 business_contexts 中， Backend Agent 在生成 SQL 时会自动应用这些治理规则。

#	约束	影响	对应规则
1	`price` 是归一化值 (0~1)	不是实际货币金额，不可做金额汇总或比较	`br_hm_normalised_price`
2	仅含购买记录	无退货/退款/取消数据	`bc_hm_dataset_overview`
3	`customer_id` 是 SHA256 哈希	不可反推真实客户身份	PII policy
4	`postal_code` 已哈希	不可做地理分析（城市/区域聚合无意义）	`br_hm_normalised_price` 附注
5	数据时间范围	2018-09-20 至 2020-09-22	`bc_hm_time_range`
6	`sales_channel_id` 映射	1=实体店, 2=线上	`br_hm_channel_mapping`
7	article vs product	多个 article 对应一个 product_code	`br_hm_article_vs_product`

4. 语义资产映射¶

4.1 Table Assets（Layer 1）¶

资产 ID	文件	对应表
`tbl_hm_dim_article`	`domains/hm_fashion/dim_article.yaml`	`gold_hm.dim_article`
`tbl_hm_dim_customer`	`domains/hm_fashion/dim_customer.yaml`	`gold_hm.dim_customer`
`tbl_hm_fact_transaction`	`domains/hm_fashion/fact_transaction.yaml`	`gold_hm.fact_transaction`

4.2 Metric Assets（Layer 1）¶

资产 ID	文件	含义
`met_hm_transaction_count`	`metrics/transaction_count.yaml`	交易笔数
`met_hm_unique_customer_count`	`metrics/unique_customer_count.yaml`	唯一客户数
`met_hm_unique_article_purchased`	`metrics/unique_article_purchased.yaml`	被购买商品种类数
`met_hm_avg_transaction_price`	`metrics/avg_transaction_price.yaml`	平均交易价格（归一化）
`met_hm_repeat_purchase_rate`	`metrics/repeat_purchase_rate.yaml`	复购率

4.3 Join Rules（Layer 1）¶

文件	内容
`join_rules/hm_fashion_joins.yaml`	fact_transaction ↔ dim_article、fact_transaction ↔ dim_customer 的关联规则

4.4 Business Terms（Layer 1+2）¶

文件	内容
`terms/hm_fashion_terms.yaml`	销量、复购率、渠道、商品分类等业务术语定义

4.5 Term Relationships（Layer 2）¶

文件	内容
`term_relationships/hm_fashion_relationships.yaml`	术语间同义/层级/关联关系

4.6 Few-shot Examples（Layer 1）¶

文件	内容
`few_shots/hm_fashion_examples.yaml`	典型问法 → SQL 示例对

4.7 Business Rules（Layer 3）¶

文件	关键规则
`business_rules/hm_fashion_rules.yaml`	`br_hm_normalised_price`、`br_hm_channel_mapping`、`br_hm_article_vs_product` 等

4.8 Business Contexts（Layer 3）¶

文件	关键上下文
`business_contexts/hm_fashion_contexts.yaml`	`bc_hm_dataset_overview`、`bc_hm_time_range`、`bc_hm_multichannel`

5. 数据加载¶

5.1 加载流程¶

graph LR
    A[CSV 文件] -->|aws s3 sync| B[MinIO S3]
    B -->|COPY FROM STDIN| C[pg_mooncake]
    C --> D[gold_hm schema]

加载命令:

# 完整流程（含依赖启动）
task dp:up          # 启动 PostgreSQL + pg_mooncake + MinIO
task dp:publish-sp  # 发布语义元数据到 S3（Backend 自动同步 R+V+G）
task dp:load-hm     # 加载 H&M 数据 (CSV → pg_mooncake)

5.2 数据目录¶

load_hm_data.py 默认读取本地路径：

~/opt/dataset/hm-personalized-fashion-recommendations/
├── articles.csv
├── customers.csv
└── transactions_train.csv

可通过 --data-dir 覆盖：

uv run --package ttd-data-plane ttd-load-hm --data-dir /path/to/hm-data

5.3 技术细节¶

步骤	操作	目标
1	`aws s3 sync`	CSV 增量上传到 MinIO (`s3://talktodata/hm-data/`)
2	`CREATE TABLE` + `mooncake.create_table()`	在 pg_mooncake 创建源表和列存镜像
3	`COPY FROM STDIN`	通过 psycopg 流式加载数据到源表

连接信息:

服务	DSN	端口
pg_mooncake	`postgresql://postgres:postgres@localhost:5436/ttd_lake`	5436
MinIO S3	`http://localhost:9000`	9000
MinIO Console	`http://localhost:9001`	9001

5.4 DDL 位置¶

表结构定义在 data-plane/sql/100_hm_create_schema.sql，schema 为 gold_hm。

跨环境兼容

DDL 使用标准 SQL 语法，同时兼容本地 pg_mooncake 和生产 Redshift。源表使用 _src 后缀，通过 mooncake.create_table() 创建列存镜像保持规范表名。

6. 典型查询场景¶

以下是基于 H&M 数据集的典型用户问法示例：

问法	涉及资产	路由
"上个月销量最高的商品是什么？"	`tbl_hm_fact_transaction` + `tbl_hm_dim_article`	nl2sql_query
"复购率超过 30% 的客户有多少？"	`met_hm_repeat_purchase_rate`	kpi_lookup
"线上和线下渠道的客户年龄分布对比"	全部三表 + `br_hm_channel_mapping`	deep_analysis_workflow
"GMV 趋势是什么样的？"	`br_hm_normalised_price` (触发澄清)	clarification_required
"商品分类和颜色之间有什么关系？"	`tbl_hm_dim_article` (图推理)	graph_reasoning

测试提示

关于 "GMV" 或 "收入" 的问法会触发 br_hm_normalised_price 规则， Agent 会主动告知用户 price 是归一化值，不代表实际金额。