搭配 Substrait 使用 Acero

為了使用 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 scheme

• 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 不完全支援不可空類型，並且可能允許輸入具有 null 值而不拒絕它。

• 下表顯示目前支援的 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 選項

  • 對於 and、or、xor 函式，Acero 不支援接受超過兩個引數的核心

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