CardBench 零样本基数估计训练数据下载与实战指南：数据集、元数据与查询图获取全解析

• 人工智能
• 深度学习
• NLP
• 计算机视觉
• 强化学习

本文是 CardBench（CardBench: A Benchmark for Learned Cardinality Estimation in Relational Databases）零样本基数估计基准中数据制品（Artifacts）获取与使用的完整实战指南。文章围绕 DowloadArtifacts.md 展开，详细梳理数据集 CSV、PostgreSQL 建表/导入脚本、数据集元数据（schema、column statistics、string statistics）以及三类训练查询图（Single Table / Binary Join / Multi Join）的下载清单，并结合仓库源码说明这些制品在 CardBench 训练数据生成管线中的位置与消费方式。读完本文，你将掌握 CardBench 全部公开制品的清单结构、下载方法、还原到 PostgreSQL 的完整步骤，以及如何用 Sparse Deferred 读取 npz 训练查询图进行模型训练与评估。

图：CardBench 训练数据集生成管道——从数据库出发，经过统计信息计算、查询生成与执行、基数采集，最终得到带注释的查询图（QueryGraphs）。本文介绍的制品正是该管道的最终产物与中间数据。

一、CardBench 与它的公开制品体系

CardBench 是面向关系数据库学习型基数估计（learned cardinality estimation）的基准，仓库由两部分组成：训练数据集（存于training_datasets目录）与生产训练数据集的代码。官方公开的制品（Artifacts）包括四类：

这些制品的用途在 README.md 中被明确为两条路径：

1. 直接用查询图训练/评估基数估计模型——最简单，不需要运行 CardBench 代码，是绝大多数用户的使用方式（详见 TrainingQueryGraphs.md）；
2. 复用数据集与元数据生成新工作负载——通过generate_queries_and_save_to_file.py、run_queries.py等代码重建查询图。

由于完整跑一遍统计计算、查询执行管线的成本很高，官方在发布代码的同时发布了最终产物与中间制品，DowloadArtifacts.md正是这份制品清单的索引。

二、数据集 CSV：底层数据与还原方式

DowloadArtifacts.md明确指出："The underlying data for the datasets is available in CSV files"，即所有数据集的底层表数据以 CSV 形式提供，并配套提供两套 SQL 脚本用于在PostgreSQL 兼容数据库中还原：

• 建表脚本（Create schema scripts）：*_create_tables_pg_oss.sql，按数据集命名，共 20 份；
• 导入脚本（Copy dataset CSV to PG scripts）：*_copy_to_postgres.sql，将 CSV 复制到对应表。

两个脚本目录下的数据集覆盖了 accident、airline、consumer、employee、movielens、tpch_10G 以及 15 个sample_*数据集（如sample_cms_synthetic_patient_data_omop、sample_geo_openstreetmap、sample_stackoverflow、sample_wikipedia等），与 TrainingQueryGraphs.md 中的训练数据集清单一一对应。带sample_前缀的库名即文档中所说的"进行了下采样（down sampled）"的数据库。

2.1 导入脚本中的关键占位符

使用导入脚本前必须注意：DowloadArtifacts.md明确说明脚本中含有DATASET_PATH_PREFIX占位符，需要将其替换为 CSV 文件下载后的父目录实际路径。例如consumer_copy_to_postgres.sql中的典型模式为：

COPY table_name FROM 'DATASET_PATH_PREFIX/consumer/xxx.csv' WITH (FORMAT csv, HEADER true);

将DATASET_PATH_PREFIX全部替换为你本地的 CSV 父目录即可执行。这是还原数据集时最容易出错的一步，务必在导入前全局替换。

2.2 还原步骤总览

结合脚本用途，完整还原流程为：

1. 从 GCS 下载 20 个数据集的 CSV 文件到统一父目录；
2. 在 PostgreSQL 中依次执行对应数据集的*_create_tables_pg_oss.sql创建表；
3. 全局替换*_copy_to_postgres.sql中的DATASET_PATH_PREFIX占位符；
4. 执行导入脚本完成数据装载。

三、数据集元数据：查询生成器的输入

除原始数据外，官方还发布了每个数据集的元数据 JSON，命名规则为dataset_name.{schema,column_statistics,string_statistics}.json，即每个数据集三份：

• *.schema.json：表结构（列名、列类型），对应calculate_statistics_library中收集的表/列信息；
• *.column_statistics.json：列级统计，如null_frac、num_unique、row_count、数值列的分位数与 min/max 等；
• *.string_statistics.json：字符串列的统计，如频率词、唯一值等。

这三类 JSON 正是查询生成器（query generator）的输入。在 README.md 中说明：查询生成器以包含数据库 schema、列统计、字符串列统计的 JSON 文件集为输入；这些 JSON 可由calculate_statistics_and_save_to_database.py计算的统计信息，通过 save_dataset_statistics_to_json_files.py 生成；仓库同时内置了生成好的 JSON 于generate_queries_library/dataset_statistics_jsons，若直接使用现有 JSON，可跳过统计计算这一步。

从源码看，save_dataset_statistics_to_json_files.py 依次调用write_dataset_schema_to_json_file、write_dataset_column_statistics_to_json_file、write_dataset_string_statistics_to_json_file三个写入器（位于generate_queries_library/），从元数据库读取统计信息并输出到configuration.DIRECTORY_PATH_JSON_FILES指定的目录——这与下载到的元数据 JSON 结构一致。

3.1 元数据在统计管线中的来源

元数据背后的统计计算由 calculate_statistics_and_save_to_database.py 完成，它封装了calculate_statistics_library中的一系列步骤：collect_and_write_table_information、collect_and_write_column_information、calculate_and_write_column_statistics、calculate_and_write_extra_column_statistics、calculate_and_write_percentiles、calculate_and_write_unique_values、calculate_and_write_frequent_words、calculate_and_write_column_histograms、create_table_samples_fixsize、calculate_and_write_pearson_correlation等。所有统计结果存入元数据库的统计表中，表结构由 statistics_sql_tables_definition.sql 定义，例如：

• tables_info/columns_info：表与列的基本信息；
• columns_stats：null_frac、num_unique、row_count；
• columns_*_extra_stats（按 INT64 / FLOAT64 / NUMERIC / STRING / DATE / DATETIME 等类型分表）：min/max、分位数、均值、唯一值、频率词等；
• columns_correlation：列间 Pearson 相关系数；
• pk_fk：主外键关系；
• histograms_table：近似分位数直方图。

这些表的定义与下载到的 JSON 元数据字段一一对应，理解它们有助于解读元数据内容。仓库中 configuration.py 的TYPES_TO_TABLES映射展示了不同列类型如何路由到不同的统计表（如INT64→columns_int64_extra_stats、STRING→columns_string_extra_stats），可作为解读元数据的参考。

四、训练查询图：三类 npz 与命名规则

训练查询图是 CardBench 的核心训练制品。每个训练实例是一个"SQL 查询 → 带注释的图"的表示：查询在 BigQuery 上实际执行得到基数（cardinality）作为图的上下文（context）一并存储，SQL 字符串也包含在图上下文中。DowloadArtifacts.md按三个子目录组织：

• single_table/：<database>_single_table.npz，查询对单表应用 1–4 个过滤谓词；
• binary_join/：<database>_binary_join.npz，查询连接两张表且每表应用 1–3 个过滤谓词；
• multi_join/：<database>_multi_join.npz，查询包含 1–7 个连接、每表 0–2 个过滤谓词。

文件命名规则为database_name_<single_table/binary_join/multi_join>.npz（TrainingQueryGraphs.md）。示例查询：

-- Single Table 示例（tpch_10G） SELECT count(*) FROM tpch_10G.nation as nation WHERE nation.n_nationkey <= 6 AND nation.n_comment IS NULL AND nation.n_regionkey >= 1; -- Binary Join 示例（tpch_10G） SELECT count(*) FROM tpch_10G.region as region JOIN tpch_10G.nation as nation ON region.r_regionkey = nation.n_regionkey WHERE nation.n_comment IS NOT NULL AND nation.n_nationkey != 5;

各数据集的规模概览（节选自 TrainingQueryGraphs.md）：

4.1 查询图在生成管线中的位置

查询图文件是generate_training_querygraphs_and_save_to_file.py的产物。从源码调用链看，该脚本按workload_id与query_run_id从元数据库的WORKLOAD_DEFINITION_TABLE与QUERY_RUN_INFORMATION_TABLE读取查询与基数，然后依次执行：

1. convert_sql_to_relational_operators：SQL → 关系算子（JOIN / SCAN）；
2. convert_relational_operators_to_query_plan：关系算子 → 带统计注释的查询计划图；
3. convert_query_plan_to_graph：查询计划 → 通用图表示；
4. validate_query_plan_and_graph：校验；
5. create_sparse_deferred_graph_struct_object：转为 Sparse Deferred 图结构对象，最终写入.npz文件。

脚本中还内置了open_source_graphs_naming映射（如'7046_193': 'tpch_10G_single_table.npz'），说明下载的 npz 与内部workload_id_query_run_id的对应关系，也印证了下载文件与生成代码的一致性。此外脚本会过滤掉零基数查询与"无 JOIN / WHERE / GROUP BY 子句"的查询，并只保留唯一查询。

五、使用训练查询图：Sparse Deferred 读取实战

训练数据使用 Sparse Deferred 目录即相关实现）定义的GraphStruct编码，提供 TF/JAX 友好的序列化格式。读取 npz 需要python >= 3.10、sparse-deferred与numpy（均可通过 pip 安装）。

以下为 TrainingQueryGraphs.md 提供的读取示例，可用于任何下载的 npz：

from sparse_deferred.structs import graph_struct GraphStruct = graph_struct.GraphStruct InMemoryDB = graph_struct.InMemoryDB # 加载 consumer_single_table 数据集 filename = "single_table/consumer_single_table.npz" db = InMemoryDB.from_file(filename) # 训练实例数 print("Number of training instances:", db.size) # 5571 # 图结构 schema（边类型定义） print("Schema:", db.schema) # {'table_to_attr': ('tables', 'attributes'), 'attr_to_pred': ...} # 节点类型 print("Node types:", db.get_item(0).nodes.keys()) # dict_keys(['g', 'tables', 'attributes', 'predicates', 'ops', 'correlations']) # 表节点特征 print("Table node features:", db.get_item(0).nodes["tables"].keys()) # dict_keys(['rows', 'name']) # 图级特征：基数、执行时间、查询 id、SQL 原文 g = db.get_item(0).nodes["g"] print("Query cardinality:", g["cardinality"][0]) print("Execution time:", g["exec_time"][0]) print("Query id:", g["query_id"][0]) print("Query:", g["query"][0])

节点类型共 6 类：g（图级，含cardinality、exec_time、query_id、query）、tables（含rows、name）、attributes（含null_frac、num_unique、data_type、分位数、min/max 等）、predicates（含predicate_operator、estimated_selectivity、constant等）、ops（operator：join/scan）、correlations（type、correlation、validity）。

值得注意的读取细节：

• 属性特征按类型填充——字符串列填充percentiles_str等字符串特征，数值列填充percentiles_num等数值特征，空特征统一用-1填充；
• 查询图中的 SQL 是以 BigQuery 风格命名的表（如bq-cost-models-exp.consumer.HOUSEHOLDS），因为查询在 BigQuery 上执行；
• 图结构中的边类型（table_to_attr、attr_to_pred、attr_to_op、op_to_op、pred_to_op、attr_to_corr、corr_to_pred等）完整刻画了查询计划的拓扑，训练/评估时可直接以db.schema为准构造 GNN。

六、从制品到自定义工作负载：代码管线的衔接

若要在下载的数据集与元数据之上生成新的工作负载，需要运行 CardBench 代码，完整流程（见 README.md）为：

1. 下采样数据库（如需要）：create_table_samples_fixsize（4K 行采样）；
2. 计算统计信息：运行 calculate_statistics_and_save_to_database.py，统计结果写入元数据库；
3. 生成训练 SQL 查询：运行 generate_queries_and_save_to_file.py，将查询按行写入 workload 文件，每个 workload 由整数workload_id标识，参数存入WORKLOAD_DEFINITION_TABLE；
4. 执行查询采集基数：运行 run_queries.pyworkload_id，结果（SQL 与基数）写入QUERY_RUN_INFORMATION_TABLE，每次运行产生新的query_run_id；
5. 生成训练查询图：运行 generate_training_querygraphs_and_save_to_file.pyworkload_id query_run_id，输出.npz。

下载的数据集元数据 JSON 可直接作为第 3 步查询生成器的输入（仓库内置的generate_queries_library/dataset_statistics_jsons即此类 JSON），从而跳过统计计算步骤；下载的查询图 npz 则可直接用于模型训练/评估，无需运行任何代码。运行前需按 configuration.py 中的注释完成配置：替换元数据库/数据表 id、DIRECTORY_PATH_JSON_FILES、DIRECTORY_PATH_QUERY_FILES、DIRECTORY_TRAINING_QUERYGRAPH_OUTPUT等路径，并设置DATA_DBTYPE/METADATA_DBTYPE（当前实现默认以 BigQuery 为后端，database_connector.py提供可扩展的数据库连接器）。原始数据还原后也可作为"data 数据库"用于执行查询。

七、常见问题与注意事项

• 导入脚本占位符未替换：DATASET_PATH_PREFIX是导入失败的常见原因，执行前务必全局替换为本地 CSV 父目录；
• 数据集为下采样版本：带sample_前缀的数据集是下采样后的版本，其统计信息与完整数据可能存在差异，论文与文档以这些制品为准；
• 查询图为分片存储：InMemoryDB.from_file支持通过 glob 匹配加载分片文件（文档说明训练数据以分片形式存储，可用 glob 找到所有分片）；
• 属性特征按类型填充：空特征值统一为 -1，读取特征时需注意不同列类型对应的特征字段（数值 vs 字符串）；
• JSON 元数据与 SQL 统计表对应：解读元数据时可对照 statistics_sql_tables_definition.sql 与 configuration.py 的TYPES_TO_TABLES映射；
• BigQuery 表名：查询图上下文中的 SQL 使用 BigQuery 项目/数据集前缀，若在你的环境中执行需相应调整。

八、小结

DowloadArtifacts.md是 CardBench 全部公开制品的总入口。本文围绕该文档，将其中的数据集 CSV、建表/导入脚本、数据集元数据、训练查询图四大类制品整理为可执行的下载与使用流程，并结合仓库源码（README.md、TrainingQueryGraphs.md、statistics_sql_tables_definition.sql、configuration.py 及generate_training_querygraphs_library/系列脚本）阐明了每个制品的生成源头与消费方式。无论是直接加载 npz 训练基数估计模型，还是在已发布数据集上生成新工作负载，本文提供的清单与代码路径都足以支撑你的下一步实验。

• 人工智能
• 深度学习
• NLP
• 计算机视觉
• 强化学习