使用 Acero 和 Substrait#

为了使用 Acero，你需要创建一个执行计划。这是一种用于描述你希望对数据应用哪些计算的模型。Acero 有其内部的执行计划表示形式，但大多数用户不应直接与之交互，因为这会将他们的代码与 Acero 耦合在一起。

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

Substrait 一致性#

Substrait 为许多不同的情况定义了一套广泛的算子和函数，Acero 不太可能完全满足所有定义的 Substrait 算子和函数。为了帮助了解哪些功能可用，以下章节定义了 Acero 当前已实现的功能以及适用的任何注意事项。

计划（Plans）#

  • 一个计划应该有一个单一的顶层关系（relation）。

  • 消费者目前基于 Substrait 0.20.0 版本。任何在此之后添加的功能将不受支持。

  • 由于 0.20.0 版本中的破坏性变更，任何早于 0.20.0 的 Substrait 计划都将被拒绝。

扩展（Extensions）#

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

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

关系（通用）（Relations in general）#

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

读取关系（Read Relations）#

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

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

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

  • 所有 URI 必须使用 file 方案。

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

  • Substrait 规范要求 filter 必须由读取关系完全满足。然而，Acero 仅将读取过滤器用于下推投影（pushdown projection），它可能无法完全满足要求。用户通常应该在读取关系之后附加一个具有相同过滤表达式的额外过滤关系。

过滤关系（Filter Relations）#

  • 无已知注意事项。

投影关系（Project Relations）#

  • 无已知注意事项。

连接关系（Join Relations）#

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

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

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

聚合关系（Aggregate Relations）#

  • 最多支持一个分组集合。

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

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

  • 度量不能带有过滤器。

  • 度量不能带有排序。

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

  • 度量的阶段必须是 AGGREGATION_PHASE_INITIAL_TO_RESULT。

表达式（通用）（Expressions (general)）#

  • Substrait 规范中的多个地方允许在过滤或投影关系之外使用表达式。例如，连接表达式或聚合分组集合。Acero 通常期望这些表达式是直接引用。规划器应在将计划交付给 Acero 之前，将隐式投影提取为正式的投影关系。

字面量（Literals）#

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

类型（Types）#

  • 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 必须不可为空

函数（Functions）#

  • 以下函数有注意事项或根本不受支持。请注意，这不是一个详尽的列表。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。