将 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
bool	i8
int8	i16
int16	i32
int32	i64
int64	fp32
float32	fp64
float64	float64
string	string
utf8	binary
binary	timestamp
日期	timestamp_tz
时间	date
date32		time
time64		time
interval_year		time
目前不支持		time
interval_day		time
目前不支持	uuid
binary	FIXEDCHAR
VARCHAR	FIXEDBINARY	fixed_size_binary
DECIMAL		time
decimal128	STRUCT
struct	Arrow 结构字段将没有名称（空字符串）	NSTRUCT

目前不支持

• LIST

  • list

  • MAP

• Substrait 尚未明确 URI 应该采取何种形式来表示标准函数。Acero 将在 GitHub 的 main 分支上查找 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。