Apache DataFusion 51.0.0 升级指南：Arrow 57 基线与 API 重构的完整迁移手册

大数据数据分析后端【免费下载链接】datafusionApache DataFusion SQL Query Engine项目地址https://gitcode.com/gh_mirrors/datafu/datafusion点击查看免费下载本文以 Apache DataFusion 官方 51.0.0 版本升级指南为主线系统梳理该版本的全部破坏性变更与迁移步骤Arrow/Parquet 依赖升级、FunctionRegistry新增方法、datafusion-proto序列化接口改用TaskContext、FileScanConfig投影字段重构、TableSchema引入以及多个 crate 重组。阅读并对照实践后你将能够把基于 DataFusion 的自定义FunctionRegistry、FileSource、物理计划序列化与文件扫描等代码平滑迁移到 51.0.0并理解每一项改动背后的设计动机与源码实现依据。版本总览Arrow 57 与 MSRV 提升51.0.0 是 DataFusion 围绕 Apache Arrow 生态基线升级的一个里程碑版本底层核心依赖与 Rust 工具链要求同步提高Arrow / Parquet 升级到 57.0.0DataFusion 将底层 Apache Arrow 实现升级到57.0.0同时连带升级了多个相关 crate包括prost、tonic、pyo3和substrait。这意味着凡是传递依赖这些 crate 的项目在升级 DataFusion 时都需要同步刷新锁定版本。MSRV 更新到 1.88.0Minimum Supported Rust Version最低支持 Rust 版本提升到1.88.0。升级前请先确认你的工具链满足该要求可通过rustc --version检查否则需要先更新 Rust 工具链。FunctionRegistry新增udafs与udwfs方法FunctionRegistrytrait 在 51.0.0 中新增了两个方法udafs和udwfs分别返回已注册的用户自定义聚合函数UDAF与窗口函数UDWF名称集合。此前该 trait 只有udfs标量 UDF和higher_order_function_names高阶函数两个列举名称类方法聚合与窗口函数的名称列表无法直接枚举。在源码层面datafusion/expr/src/registry.rs 中的 trait 定义已明确pub trait FunctionRegistry { /// Returns names of all available scalar user defined functions. fn udfs(self) - HashSetString; /// Returns names of all available higher order user defined functions. fn higher_order_function_names(self) - HashSetString; /// Returns names of all available aggregate user defined functions. fn udafs(self) - HashSetString; /// Returns names of all available window user defined functions. fn udwfs(self) - HashSetString; // ... }迁移要求所有自定义实现FunctionRegistry的类型都需要补齐这两个方法返回已注册函数名称的HashSetString。官方升级指南给出的实现模式如下impl FunctionRegistry for FunctionRegistryImpl { fn udfs(self) - HashSetString { self.scalar_functions.keys().cloned().collect() } fn udafs(self) - HashSetString { self.aggregate_functions.keys().cloned().collect() } fn udwfs(self) - HashSetString { self.window_functions.keys().cloned().collect() } }如果你的注册表内部用HashMapString, ArcAggregateUDF、HashMapString, ArcWindowUDF之类的结构存储函数直接对keys()做cloned().collect()即可。注意这与已有udfs()的实现方式保持一致返回的是名称而非函数对象本身函数对象仍通过udf()、udaf()、udwf()按名查询。datafusion-proto物理计划序列化改用TaskContext51.0.0 对datafusion-protocrate 中处理物理计划序列化serde的公共 API 做了一致性调整原先要求传入SessionContext或RuntimeEnv的方法现在统一改为要求TaskContext。受影响的方法包括physical_plan_from_bytes、parse_physical_expr等。例如从字节反序列化物理计划- let plan2 physical_plan_from_bytes(bytes, ctx)?; let plan2 physical_plan_from_bytes(bytes, ctx.task_ctx())?;TaskContext内部持有RuntimeEnv因此try_into_physical_plan这类方法不再需要显式的RuntimeEnv参数let result_exec_plan: Arcdyn ExecutionPlan proto - .try_into_physical_plan(ctx, runtime.deref(), composed_codec) . .try_into_physical_plan(ctx.task_ctx(), composed_codec)对应的函数实现在 datafusion/proto/src/bytes/mod.rs 中physical_plan_from_bytes及其带扩展编解码器的变体physical_plan_from_bytes_with_extension_codec都已调整为接收TaskContext。同时PhysicalExtensionCodectrait 的try_decode()方法的参数也由dyn FunctionRegistry改为TaskContextpub trait PhysicalExtensionCodec { fn try_decode( self, buf: [u8], inputs: [Arcdyn ExecutionPlan], - registry: dyn FunctionRegistry, ctx: TaskContext, ) - ResultArcdyn ExecutionPlan;这一调整的动机在于解码物理计划时往往既需要函数注册表也需要运行时环境信息直接传入TaskContext可以让自定义编解码器从ctx中同时拿到这两类资源而无需把多个参数分别传入。升级时只需将调用处改为传入ctx.task_ctx()并在自定义PhysicalExtensionCodec实现中把registry参数替换为ctx。SessionState::sql_to_statement改用Dialect枚举SessionState::sql_to_statement方法的dialect参数类型从str改成了Dialect。Dialect是定义在datafusion-commoncrate 的config模块下的一个枚举见 datafusion/common/src/config.rs取代了原先直接传字符串的做法为 SQL 方言选择提供了类型安全与更好的校验。当前Dialect枚举支持以下方言变体Generic默认、MySQL、PostgreSQL别名postgres、Hive以及通过dialect_metadata!宏继续扩展的其他方言。在 datafusion/core/src/execution/session_state.rs 的实现中sql_to_statement会通过dialect_from_str将枚举转换为对应的解析器方言并把不支持的方言直接以错误形式拒绝pub fn sql_to_statement( self, sql: str, dialect: Dialect, ) - datafusion_common::ResultStatement { let dialect dialect_from_str(dialect).ok_or_else(|| { plan_datafusion_err!( Unsupported SQL dialect: {dialect}. Available dialects: {}., Dialect::available() ) })?; // ... 使用 DFParserBuilder 解析 }迁移方式把原来传入的str例如postgresql改为对应枚举值例如Dialect::PostgreSQL。字符串形式的方言名容易拼写错误且运行时才报错枚举则可以在编译期拦截无效值——这正是该改动想要达成的类型安全收益。crate 重组一ListingTable移入datafusion-catalog-listing社区长期以来希望把ListingTable等重量级实现从datafusion核心 crate 中剥离以加快核心 crate 的构建速度。51.0.0 完成了这一拆分ListingOptions、ListingTable、ListingTableConfig现在位于datafusion-catalog-listingcrate 中对应源码分别为 datafusion/catalog-listing/src/options.rs、datafusion/catalog-listing/src/table.rs 和 datafusion/catalog-listing/src/config.rs。这些类型仍在datafusioncrate 中重新导出re-export因此对大多数现有用户的代码影响极小原有的导入路径通常依然可用。迁移建议如果只依赖datafusioncrate一般无需改动如果显式引用了datafusion-catalog-listing请确保 Cargo 依赖清单中加入了该 crate并把导入路径改为use datafusion_catalog_listing::{ListingOptions, ListingTable, ListingTableConfig};。如果你关注的是 Hive 分区表的自动推断行为可同时参考上一个版本50.0.0引入的datafusion.execution.listing_table_factory_infer_partitions配置项见 DataFusion 50.0.0 升级指南两者配合理解更完整。crate 重组二ArrowSource移入datafusion-datasource-arrow紧随上一项重组ArrowSource代码从datafusion核心 crate 中移出进入独立的datafusion-datasource-arrowcrate实现位于 datafusion/datasource-arrow/src/source.rs。这与 AVRO、CSV、JSON、Parquet 数据源的既有模式保持一致——每种文件格式拥有独立的数据源 crate。迁移建议如果你在代码中直接使用了ArrowSource需要把导入路径更新为datafusion_datasource_arrow::ArrowSource并在 Cargo.toml 中补充该依赖。仅通过datafusioncrate 间接使用 Arrow 数据源的场景则基本不受影响。FileScanConfig::projection重命名为projection_exprsFileScanConfig的projection字段更名为projection_exprs且类型从OptionVecusize改为OptionProjectionExprs。这一改动使得投影下推projection pushdown能力大幅增强不再局限于列索引而是支持任意物理表达式在扫描阶段求值。直接访问字段的迁移let config: FileScanConfig ...; let projection config.projection;应改为let config: FileScanConfig ...; let projection_exprs config.projection_exprs;Builder 方法的迁移FileScanConfigBuilder::with_projection()已被弃用改用with_projection_indices()。在源码 datafusion/datasource/src/file_scan_config/mod.rs 中可以确认with_projection带有#[deprecated(since 51.0.0, note Use with_projection_indices instead)]标记内部只是转调with_projection_indices它目前仍然可用但会在未来版本中移除let config FileScanConfigBuilder::new(url, file_source) - .with_projection(Some(vec![0, 2, 3])) .with_projection_indices(Some(vec![0, 2, 3])) .build();ProjectionExprs是什么它是一个表示投影物理表达式列表的新类型。可以从列索引构造这正是with_projection_indices内部所做的也支持任意物理表达式从而实现扫描期间的表达式求值等高级特性。如果需要从ProjectionExprs中取回列索引可以使用其方法let projection_exprs: ProjectionExprs ...; // Get the column indices if the projection only contains simple column references let indices projection_exprs.column_indices();需要注意的是column_indices()只在投影仅包含简单列引用时才有意义一旦投影中包含任意表达式该方法无法返回完整索引列表此时应直接操作表达式本身。DESCRIBE query语义修正51.0.0 修正了一个历史行为此前DESCRIBE query是EXPLAIN query的别名输出的是查询的执行计划从本版本开始DESCRIBE query输出的是查询计算得到的模式schema与DESCRIBE table_name的行为保持一致。升级后请注意区分想看执行计划继续用EXPLAIN query想看查询结果集的列结构列名、类型、是否可空等则用DESCRIBE query。datafusion.execution.time_zone默认值变更datafusion.execution.time_zone配置的默认值从字符串00:00GMT/Zulu 时间改为OptionString默认值为None。在 datafusion/common/src/config.rs 的配置定义中可以确认pub time_zone: OptionString, default None这一改动是为了更好地支持标量 UDF如now、current_date、current_time、to_timestamp等使用默认时区。如果你希望恢复旧行为执行以下 SQL 即可SET TIMEZONE 00:00;或者在构造SessionConfig时显式设置time_zone为Some(00:00)。需要注意由于默认值现在是None依赖时区默认值的 SQL 行为可能与 50.x 及更早版本不同升级后应重点回归测试与时区相关的函数。TableSchema引入与FileSource::with_schema()签名变更51.0.0 在datafusion-datasourcecrate 中引入了新的TableSchema结构体用于更清晰地管理带分区列的表模式。它区分了三层概念文件模式File schema磁盘上实际数据文件的模式分区列Partition columns由目录结构派生的列例如 Hive 风格分区/date2025-10-10/regionus-west/中的date与region这些列并不存在于数据文件内而是在查询执行时根据文件位置追加到每一行表模式Table schema文件模式与分区列合并后的完整模式。从源码 datafusion/datasource/src/table_schema.rs 可以看到TableSchema内部还缓存了virtual_columns由读取器生成、不来自文件也不来自目录结构的虚拟列如row_number并预计算了完整表模式因此任何表示都可以廉价引用、无需重复拼接分配。构建TableSchema的首选方式是TableSchema::builder(file_schema).with_table_partition_cols(cols).build()。伴随该结构体的引入FileSource::with_schema()方法签名从接收SchemaRef改为接收TableSchema。受影响范围实现了自定义FileSource的用户需要更新代码只使用内置文件源Parquet、CSV、JSON、AVRO、Arrow的用户不受影响。自定义FileSource迁移示例仅需文件模式的常见场景use datafusion_datasource::file::FileSource; -use arrow::datatypes::SchemaRef; use datafusion_datasource::TableSchema; impl FileSource for MyCustomSource { - fn with_schema(self, schema: SchemaRef) - Arcdyn FileSource { fn with_schema(self, schema: TableSchema) - Arcdyn FileSource { Arc::new(Self { - schema: Some(schema), // Use schema.file_schema() to get the file schema without partition columns schema: Some(Arc::clone(schema.file_schema())), ..self.clone() }) } }需要同时访问分区列的高级实现fn with_schema(self, schema: TableSchema) - Arcdyn FileSource { Arc::new(Self { file_schema: Arc::clone(schema.file_schema()), partition_cols: schema.table_partition_cols().clone(), table_schema: Arc::clone(schema.table_schema()), ..self.clone() }) }注意大多数FileSource实现只需要存储文件模式不含分区列如第一个示例所示。同时存储三种模式表示的第二种写法通常只用于高级场景——例如ParquetSource需要用文件模式构建裁剪pruning谓词而用表模式做过滤条件下推逻辑需要不同表示服务于不同操作。直接使用TableSchema构造FileScanConfig或处理表模式与分区列use datafusion_datasource::TableSchema; use arrow::datatypes::{Schema, Field, DataType}; use std::sync::Arc; // Create a TableSchema with partition columns let file_schema Arc::new(Schema::new(vec![ Field::new(user_id, DataType::Int64, false), Field::new(amount, DataType::Float64, false), ])); let partition_cols vec![ Arc::new(Field::new(date, DataType::Utf8, false)), Arc::new(Field::new(region, DataType::Utf8, false)), ]; let table_schema TableSchema::new(file_schema, partition_cols); // Access different schema representations let file_schema_ref table_schema.file_schema(); // Schema without partition columns let full_schema table_schema.table_schema(); // Complete schema with partition columns let partition_cols_ref table_schema.table_partition_cols(); // Just the partition columns如上例所示TableSchema提供了file_schema()、table_schema()、table_partition_cols()三个访问器分别返回文件模式不含分区列、完整表模式含分区列以及仅分区列。注意在 55.0.0 中TableSchema::new已标记为弃用更推荐TableSchema::builder(file_schema).with_table_partition_cols(partition_cols).build()的构建方式。AggregateUDFImpl方法重命名supports_within_group_clauseAggregateUDFImpl::is_ordered_set_aggregate更名为AggregateUDFImpl::supports_within_group_clause对应的AggregateUDF::is_ordered_set_aggregate也更名为AggregateUDF::supports_within_group_clause。新名称更准确地反映了该方法的实际作用它只表示该聚合函数是否允许使用 SQL 的WITHIN GROUP语法用于有序集合聚合例如percentile_cont(x) WITHIN GROUP (ORDER BY y)。该改动不涉及任何功能变化仅重命名。实现位于 datafusion/expr/src/udaf.rs如果你在自定义聚合 UDF 中重写了此方法只需同步修改方法名。升级检查清单对照 51.0.0 的变更建议按以下清单逐项排查你的代码库依赖与工具链Arrow/Parquet 升级到 57.0.0连带prost、tonic、pyo3、substraitRust 工具链不低于 1.88.0FunctionRegistry实现补充udafs()与udwfs()方法物理计划序列化datafusion-proto相关调用改用ctx.task_ctx()自定义PhysicalExtensionCodec::try_decode()的registry参数改为ctxSQL 方言sql_to_statement传入Dialect::XXX枚举而非字符串导入路径ListingTable系列迁移到datafusion-catalog-listingArrowSource迁移到datafusion-datasource-arrow两者在datafusioncrate 中仍被重新导出FileScanConfig字段访问改用projection_exprsbuilder 改用with_projection_indices()DESCRIBE query确认脚本中依赖旧语义输出执行计划的用例改为EXPLAIN时区配置如需保持旧行为执行SET TIMEZONE 00:00;自定义FileSourcewith_schema()改收TableSchema通过schema.file_schema()取文件模式聚合 UDF方法名改为supports_within_group_clause。将上述变更与本文给出的源码路径对照阅读特别是 datafusion/expr/src/registry.rs、datafusion/datasource/src/table_schema.rs、datafusion/datasource/src/file_scan_config/mod.rs、datafusion/common/src/config.rs即可系统完成 51.0.0 的平滑迁移。本系列其余版本的升级说明可参见 docs/source/library-user-guide/upgrading 目录下的对应文档。赞分享大数据数据分析后端【免费下载链接】datafusionApache DataFusion SQL Query Engine项目地址https://gitcode.com/gh_mirrors/datafu/datafusion点击查看免费下载相关推荐Apache DataFusion 53.0.0 升级指南核心 API 破坏性变更与完整迁移手册Apache DataFusion 53.0.0 升级指南核心 API 破坏性变更与完整迁移手册 导读 本文以 Apache DataFusion 53.0.大数据数据分析后端Apache DataFusion 50.0.0 升级指南从 Hive 分区自动推断到 UDF 特质重构的完整迁移手册Apache DataFusion 50.0.0 升级指南从 Hive 分区自动推断到 UDF 特质重构的完整迁移手册 本指南基于 Apache DataFu大数据数据分析后端LeakCanary 2.0 升级迁移指南从 1.x 重写 API 到新架构的完整实战手册LeakCanary 2.0 升级迁移指南从 1.x 重写 API 到新架构的完整实战手册 LeakCanary 2 是一次推翻重来的大版本重写核心变化包括开发工具代码质量质量保障移动开发上一篇ArchiSteamFarm内存优化GC策略与对象生命周期管理下一篇SlopeCraft终极指南如何将任何图片转化为Minecraft立体地图画创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考