将 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。