使用 Acero 与 Substrait

为了使用 Acero，您需要创建一个执行计划。这是描述您想要应用于数据的计算的模型。Acero 有自己的内部表示形式用于执行计划，但大多数用户不应直接与之交互，因为它会将他们的代码耦合到 Acero。

Substrait 是一种用于执行计划的开放标准。Acero 实施了 Substrait 的“消费者”接口。这意味着 Acero 可以接受 Substrait 计划并完成计划，加载请求的数据并应用所需的计算。通过使用 Substrait 计划，用户可以轻松地在以后切换到不同的执行引擎。

Substrait 兼容性

Substrait 为许多不同的情况定义了一套广泛的操作符和函数，Acero 不太可能完全满足所有定义的 Substrait 操作符和函数。为了帮助理解哪些功能可用，以下部分定义了哪些功能目前已在 Acero 中实现以及适用的任何注意事项。

计划

• 计划应具有一个单一的顶层关系。

• 消费者目前基于 Substrait 的 0.20.0 版本。任何添加的更新功能都将不受支持。

• 由于 0.20.0 中的重大更改，任何早于 0.20.0 的 Substrait 计划都将被拒绝。

扩展

• 如果计划包含任何扩展类型变体，则将被拒绝。

• 高级扩展可以通过提供 arrow::engine::ExtensionProvider 的自定义实现来提供。

关系（一般）

• 任何未在下面明确列出的关系将不受支持，并将导致计划被拒绝。

读取关系

• 不支持 projection 属性，包含此属性的计划将被拒绝。

• 不支持 VirtualTable 和 ExtensionTable 读取类型。包含这些类型的计划将被拒绝。

• 目前仅支持 parquet 和 arrow 文件格式。

• 所有 URI 必须使用 file 方案

• partition_index、start 和 length 不受支持。包含这些属性的非默认值的计划将被拒绝。

• Substrait 规范要求 filter 必须由读取关系完全满足。但是，Acero 仅使用读取过滤器进行下推投影，它可能无法完全满足。用户通常应该在读取关系之后附加具有相同过滤器表达式的额外过滤器关系。

过滤器关系

• 没有已知的注意事项

投影关系

• 没有已知的注意事项

连接关系

• 不支持连接类型 JOIN_TYPE_SINGLE，包含此类型的计划将被拒绝。

• 连接表达式必须是对 equal 或 is_not_distinct_from 函数的调用。调用中的两个参数都必须是直接引用。仅支持单个连接键。

• 不支持 post_join_filter 属性，并将被忽略。

聚合关系

• 最多支持一个分组集。

• 每个分组表达式都必须是直接引用。

• 每个度量的参数都必须是直接引用。

• 度量可能没有过滤器

• 度量可能没有排序

• 度量的调用必须是 AGGREGATION_INVOCATION_ALL 或 AGGREGATION_INVOCATION_UNSPECIFIED

• 度量的阶段必须是 AGGREGATION_PHASE_INITIAL_TO_RESULT

表达式（一般）

• Substrait 规范中的各种地方允许在过滤器或投影关系之外使用表达式。例如，连接表达式或聚合分组集。Acero 通常希望这些表达式是直接引用。规划者应该在将计划传递到 Acero 之前将隐式投影提取到正式的投影关系中。

字面量

• 具有非默认可空性的字面量将导致计划被拒绝。

类型

• Acero 不完全支持不可为空类型，并且可能允许输入具有空值而不会拒绝它。

• 下表显示了目前支持的 Arrow 类型和 Substrait 类型类之间的映射

Substrait/Arrow 类型映射

Substrait 类型	Arrow 类型	注意事项
boolean	boolean
i8	int8
i16	int16
i32	int32
i64	int64
fp32	float32
fp64	float64
string	string
binary	binary
timestamp	timestamp<MICRO,””>
timestamp_tz	timestamp<MICRO,”UTC”>
date	date32<DAY>
time	time64<MICRO>
interval_year		目前不支持
interval_day		目前不支持
uuid		目前不支持
FIXEDCHAR<L>		目前不支持
VARCHAR<L>		目前不支持
FIXEDBINARY<L>	fixed_size_binary<L>
DECIMAL<P,S>	decimal128<P,S>
STRUCT<T1…TN>	struct<T1…TN>	Arrow 结构体字段将没有名称（空字符串）
NSTRUCT<N:T1…N:Tn>		目前不支持
LIST<T>	list<T>
MAP<K,V>	map<K,V>	K 不能为可空类型

函数

• 以下函数有注意事项或根本不受支持。请注意，这不是一个完整的列表。Substrait 正在快速添加函数，新的函数可能缺失。

  • Acero 不支持溢出时的 SATURATE 选项

  • Acero 不支持为函数 and、or、xor 接受超过两个参数的内核

• Substrait 尚未明确确定标准函数的 URI 应该采用何种形式。Acero 将查找 main GitHub 分支的 URI。换句话说，对于文件 functions_arithmetic.yaml，Acero 预计 https://github.com/substrait-io/substrait/blob/main/extensions/functions_arithmetic.yaml

  • Acero 具有尚未成为 Substrait 一部分的函数（或者可能永远不会作为官方函数添加）。要调用这些函数，您可以使用特殊 URI urn:arrow:substrait_simple_extension_function。如果遇到此 URI，Acero 将仅根据函数名称进行匹配，并将忽略任何函数选项。

  • 或者，URI 可以完全为空，Acero 将仅根据函数名称进行匹配。此回退机制是非标准的，应被认为已弃用，应优先考虑使用上面的特殊 URI。