深入解析 StarRocks BE 的 ConnectorBenchmark 模块：基于 Benchgen 的 Benchmark 连接器实现与模块边界约束

深入解析 StarRocks BE 的 ConnectorBenchmark 模块基于 Benchgen 的 Benchmark 连接器实现与模块边界约束【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocksStarRocks BE 中的ConnectorBenchmark是连接器Connector体系内的一个特殊实现它不读取任何真实的外部数据源而是借助 Benchgen 数据生成引擎在查询执行时按需合成 Schema 与数据用于在不依赖存储、服务或完整 Exec 的情况下验证 Connector 契约与扫描链路。本文以 be/src/connector/benchmark/AGENTS.md 为骨架结合其源码实现、构建配置与模块边界清单讲解该模块的设计意图、类结构、数据流、可配置参数以及工程治理规则。模块定位为 Connector 契约提供无外部依赖的基准数据源在 StarRocks 的 BE 端Connector 抽象层承担了对外部数据源Hive、Iceberg、JDBC、Elasticsearch、MySQL、文件系统、湖存储等的统一读写接入。ConnectorBenchmark在其中扮演一个特殊角色它是唯一一个不连接任何真实外部系统、而是由 Benchgen 按参数现场生成数据的连接器实现。其模块描述明确写道Benchgen-backed benchmark connector implementation above connector contracts without registry composition, storage, service, or full Exec coupling.这句话概括了它的三重定位Benchgen-backed数据来源是benchgen库而非文件、网络或远端服务Above connector contracts它只依赖Connector、DataSourceProvider、DataSource这些连接器契约位于 be/src/connector_primitive/connector.h无 registry composition、无 storage、无 service、无完整 Exec 耦合它刻意保持轻量只做扫数据、产出 Chunk这一件事。从代码结构看该模块由四个文件组成职责划分非常清晰文件职责benchmark_connector.h / benchmark_connector.cpp实现BenchmarkConnector、BenchmarkDataSourceProvider、BenchmarkDataSource三层连接器主体benchmark_scanner.h / benchmark_scanner.cpp实现BenchmarkScanner负责把 Benchgen 生成的 Arrow RecordBatch 转换为 StarRocks Chunk连接器三层结构Connector → DataSourceProvider → DataSourceStarRocks 的 Connector 体系采用连接器Connector→ 数据源提供者DataSourceProvider→ 数据源DataSource的三级结构ConnectorBenchmark完整实现了这一套契约BenchmarkConnector继承starrocks::connector::Connectorconnector_type()返回ConnectorType::BENCHMARK通过create_data_source_provider()把扫描节点ConnectorScanNode和 Thrift 计划节点TPlanNode封装为BenchmarkDataSourceProvider。BenchmarkDataSourceProvider继承DataSourceProvider持有ConnectorScanNode*与TBenchmarkScanNode负责按TScanRange创建BenchmarkDataSource其中insert_local_exchange_operator()返回true每个数据源独立算子、支持本地交换accept_empty_scan_ranges()返回false不接受空扫描范围。BenchmarkDataSource继承DataSource是真正的数据生产单元实现open()、get_next()、close()以及raw_rows_read()、num_rows_read()、num_bytes_read()、cpu_time_spent()等指标接口。值得注意的是模块边界清单 be/module_boundary_manifest.json 中connectorbenchmark条目给出的约束它只允许依赖ConnectorPrimitive、Expr、Runtime、ChunkCore、ColumnCore、Types、Common、Base、Gutil、StarRocksGen这些低层目标而禁止引入connector/connector_registry.h与exec/exec_env.h。也就是说这个模块只负责实现不负责注册——注册动作被明确要求放到ModuleBootstrapbe/src/module/connector_bootstrap.cpp 中实际 include 了connector/benchmark/benchmark_connector.h与清单中modulebootstrap允许 includeconnector/benchmark/的规则完全一致。数据流剖析从 TPlanNode 到 Chunk 的完整调用链一个 benchmark 查询在 BE 端经历如下数据流参数解析BenchmarkDataSource::_init_params从TBenchmarkScanNode读取db_name、table_name从TBenchmarkScanRange读取start_row、row_count组合成BenchmarkScannerParam定义于 benchmark_scanner.h并交给BenchmarkScanner。Benchgen 初始化BenchmarkScanner::open把db_name通过benchgen::SuiteIdFromString()映射为SuiteId若解析失败返回InvalidArgument(Unknown benchmark database: ...)再调用benchgen::MakeRecordBatchIterator()创建RecordBatchIterator拿到 ArrowSchema。类型转换规划BenchmarkScanner::_init_converters对每个 SlotDescriptor用build_arrow_column_convert_plan()构建 Arrow→StarRocks 的转换函数树若需要类型转换need_cast为真则通过VectorizedCastExprFactory::from_type()生成 Cast 表达式否则直接用ColumnRef引用原始列。列缺失时返回NotFound(Benchmark column ... not found in schema)。数据产出BenchmarkScanner::get_next从迭代器拉取arrow::RecordBatch_next_batch按_max_chunk_size切片用convert_arrow_array_to_column()逐列转换出 raw chunk经raw_chunk-filter(_chunk_filter)过滤后再逐列执行 Cast 表达式得到最终 Chunk。外层循环BenchmarkDataSource::get_next循环拉取直至 Chunk 非空或 EOFEOF 时返回Status::EndOfFile同时累加_rows_read与_bytes_read供指标统计。这一链路与文件类连接器如 be/src/connector/file 的 scanner高度一致唯一的差异在于数据源被替换成了 Benchgen 合成器因此它非常适合用来在不搭建任何外部环境的前提下验证 Connector 扫描算子、Arrow 类型转换、Cast 表达式与 Chunk 组装链路。参数说明db_name、table_name 与生成选项BenchmarkScannerParam是连接器与 Benchgen 之间的唯一参数载体其字段在 benchmark_scanner.h 中定义为struct BenchmarkScannerParam { std::string db_name; std::string table_name; benchgen::GeneratorOptions options; };各参数的来源与语义结合_init_params与open的源码逻辑参数来源语义与默认值db_nameTBenchmarkScanNode.db_name必须能通过SuiteIdFromString()映射为已知SuiteId否则报InvalidArgument等价于 Benchgen 中的 benchmark 套件Suite名table_nameTBenchmarkScanNode.table_name套件内具体表名用于在生成的 Arrow Schema 中定位字段同时作为ArrowConvertContext.current_file参与转换上下文options.scale_factorTBenchmarkScanNode.scale_factor可选数据规模缩放因子未设置时默认1.0options.start_rowTBenchmarkScanRange.start_row从第几行开始生成用于多扫描范围并行切分options.row_countTBenchmarkScanRange.row_count可选并受_read_limit约束生成行数扫描范围未携带时取-1不限若存在_read_limit则取两者较小值options.chunk_sizestate-chunk_size()单次产出 Chunk 的行数上限若非法则回退到state-chunk_size()仍为 0 时兜底4096这些字段来自 Thrift 定义TBenchmarkScanNode、TBenchmarkScanRange见 gensrc/thrift 目录下相关 thrift 文件意味着扫描参数是由 FE 端在计划阶段下发的BE 只负责消费。构建与模块边界如何编译、为什么这样隔离ConnectorBenchmark的构建入口在 be/src/connector/CMakeLists.txt 第 309–332 行由WITH_CONNECTOR_BENCHMARK开关控制if (WITH_CONNECTOR_BENCHMARK) ADD_BE_LIB(ConnectorBenchmark benchmark/benchmark_connector.cpp benchmark/benchmark_scanner.cpp ) target_link_libraries(ConnectorBenchmark PUBLIC ConnectorPrimitive Expr Runtime ChunkCore ColumnCore Types Common Base Gutil StarRocksGen) target_link_libraries(ConnectorBenchmark PRIVATE benchgen arrow) endif()从依赖拆分可以看出设计者的边界意图PUBLIC 依赖全部是稳定的低层目标连接器契约、表达式、运行时、列/块、类型、公共/基础工具、生成代码PRIVATE 依赖只有benchgen与arrow——这两个是 Benchmark 连接器独有的实现细节被严格封闭在模块内部不向外泄露。同时ConnectorBenchmark也被纳入 be/src/module/CMakeLists.txt 的ModuleBootstrap目标依赖中与清单modulebootstrap条目允许的 include 前缀含connector/benchmark/吻合。整个 BE 模块体系base、gutil、common、connectorprimitive、connectorbenchmark、modulebootstrap等都在 be/module_boundary_manifest.json 中登记每一条都声明了 owned roots、allowed include prefixes、allowed target deps 与 remediation 建议。工程治理AGENTS.md 的生成与机械校验本文所依据的 be/src/connector/benchmark/AGENTS.md 本身是一份自动生成的模块边界文档文件头明确标注BEGIN GENERATED: BE MODULE HARNESSES它并非手写而是由 be/module_boundary_manifest.json 渲染而来修改清单后执行python3 build-support/render_be_agents.py --write可重新生成各模块的 AGENTS.md执行python3 build-support/check_be_module_boundaries.py --mode full可在 CI 中机械地验证同样的规则对应的测试见 build-support/test_render_be_agents.py 与 build-support/test_check_be_module_boundaries.py。对connectorbenchmark模块清单给出的 Remediation 建议是把该模块严格限定为 benchgen 连接器实现注册动作放入 ModuleBootstrap避免把 Connector 注册表、存储、服务或完整 Exec 代码拉入连接器库。这类文档即规范、规范可校验的做法让模块边界不再停留在口头约定而是变成可在构建期强制执行的工程约束。小结ConnectorBenchmark是理解 StarRocks BE Connector 架构的一个极佳切入点它麻雀虽小却完整覆盖了连接器注册 → Provider 创建 → DataSource 扫描 → Benchgen 取数 → Arrow 转换 → Cast 表达式 → Chunk 产出的整条链路且不依赖任何外部系统天然适合作为连接器契约的测试载体。通过阅读 benchmark_connector.cpp 与 benchmark_scanner.cpp 的源码再对照 be/module_boundary_manifest.json 中的边界规则读者既能掌握一个真实连接器的实现套路也能理解 StarRocks BE 如何用机械校验来守住模块间的依赖纪律。【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考