升级指南

DataFusion 49.0.0

MSRV 已更新至 1.85.1

最低支持的 Rust 版本（MSRV）已更新为 1.85.1。详情请参阅 devlive-community/knowforge#16728。

DataFusionError 的部分变体现在使用 Box 装箱

为了减小 DataFusionError 的体积，此前以内联方式存储的若干变体现在改为使用 Box 装箱。这样可以减小 Result<T, DataFusionError> 的体积，从而减少栈的使用量以及异步状态机的体积。详情请参阅 devlive-community/knowforge#16652。

DataFusionError 中以下变体现在已装箱：

• ArrowError
• SQL
• SchemaError

这是一个破坏性变更。构造或匹配这些变体的代码都需要相应更新。

例如，要创建一个 SchemaError，不应再像这样写：

use datafusion_common::{DataFusionError, SchemaError};
DataFusionError::SchemaError(
  SchemaError::DuplicateUnqualifiedField { name: "foo".to_string() },
  Box::new(None)
)

现在你需要将内部错误 Box 起来：

use datafusion_common::{DataFusionError, SchemaError};
DataFusionError::SchemaError(
  Box::new(SchemaError::DuplicateUnqualifiedField { name: "foo".to_string() }),
  Box::new(None)
)

Arrow 类型的元数据现在由 FieldMetadata 表示

Arrow Field 的元数据现在使用 FieldMetadata 结构存储。在之前的版本中，它同时以 HashMap<String, String> 和 BTreeMap<String, String> 两种形式存储。FieldMetadata 更易于使用，也更加高效。

从 Field 创建 FieldMetadata：

 let metadata = FieldMetadata::from(&field);

要向 Field 添加元数据，请使用 add_to_field 方法：

let updated_field = metadata.add_to_field(field);

详情请参阅 devlive-community/knowforge#16317。

新增 datafusion.execution.spill_compression 配置选项

DataFusion 49.0.0 支持在溢写查询执行过程中将数据写入磁盘时对溢写文件进行压缩。新增的配置选项 datafusion.execution.spill_compression 用于控制所使用的压缩编解码器。

配置：

• 键：datafusion.execution.spill_compression
• 默认值：uncompressed
• 有效值：uncompressed、lz4_frame、zstd

用法：

use datafusion::prelude::*;
use datafusion_common::config::SpillCompression;

let config = SessionConfig::default()
    .with_spill_compression(SpillCompression::Zstd);
let ctx = SessionContext::new_with_config(config);

或者通过 SQL：

SET datafusion.execution.spill_compression = 'zstd';

有关此配置选项的更多详细信息，包括不同压缩编解码器之间的性能权衡，请参阅配置设置文档。

已弃用的 map_varchar_to_utf8view 配置选项

更多信息请参阅 issue devlive-community/knowforge#16290。旧的配置

datafusion.sql_parser.map_varchar_to_utf8view

现已被弃用，请改用下文的统一选项。如果你此前仅用它来控制 VARCHAR→Utf8View 的映射，请迁移到 map_string_types_to_utf8view。

新增 map_string_types_to_utf8view 配置选项

为了将所有 SQL 字符串类型（CHAR、VARCHAR、TEXT、STRING）统一映射为 Arrow 的零拷贝 Utf8View，DataFusion 49.0.0 引入了：

• 键：datafusion.sql_parser.map_string_types_to_utf8view
• 默认值：true

说明：

• 当值为 true（默认）时，所有 SQL 字符串类型都会映射为 Utf8View，从而避免完整的 UTF‑8 拷贝分配，提升性能。
• 当值为 false 时，DataFusion 对所有字符串类型回退到传统的 Utf8 映射。

示例

// Disable Utf8View mapping for all SQL string types
let opts = datafusion::sql::planner::ParserOptions::new()
    .with_map_string_types_to_utf8view(false);

// Verify the setting is applied
assert!(!opts.map_string_types_to_utf8view);

-- Disable Utf8View mapping globally
SET datafusion.sql_parser.map_string_types_to_utf8view = false;

-- Now VARCHAR, CHAR, TEXT, STRING all use Utf8 rather than Utf8View
CREATE TABLE my_table (a VARCHAR, b TEXT, c STRING);
DESCRIBE my_table;

废弃 SchemaAdapterFactory 与 SchemaAdapter

我们正在从转换数据（使用 SchemaAdapter）转向转换表达式本身（这种方式更高效、也更灵活）。

详见 issue devlive-community/knowforge#16800。这一变更首先应用于 Parquet 的谓词下推。默认情况下，如果你没有使用自定义的 SchemaAdapterFactory，我们会使用表达式转换。如果你设置了自定义的 SchemaAdapterFactory，我们仍会继续使用它，但会发出一条警告，提示该代码路径已被废弃。

要解决这个问题，你需要实现一个自定义的 PhysicalExprAdapterFactory，并用它取代 SchemaAdapterFactory。可参考默认值示例，了解具体做法。尽早采用这些新 API 能让你为后续变更做好准备，因为我们计划在 DataFusion 的其他领域扩大 PhysicalExprAdapterFactory 的使用范围。

详见 devlive-community/knowforge#16800。

TableParquetOptions 已更新

TableParquetOptions 结构体现在新增了 crypto 字段，用于指定 Parquet 文件的加密选项。ParquetEncryptionOptions 实现了 Default，因此你可以这样升级现有代码：

TableParquetOptions {
  global,
  column_specific_options,
  key_value_metadata,
}

改为此：

TableParquetOptions {
  global,
  column_specific_options,
  key_value_metadata,
  crypto: Default::default(), // New crypto field
}