標準擴展類型#

簡介#

Arrow 欄狀格式允許定義擴展類型，以便使用自訂語意擴展標準 Arrow 資料類型。通常，這些語意將特定於系統或應用程式。然而，分享廣為人知的擴展類型的定義是有益的，以便改善整合 Arrow 欄狀資料的不同系統之間的互通性。

標準化#

標準化標準擴展類型時，必須遵循以下規則

標準擴展類型在本文檔下方描述和維護。
每個標準擴展類型都需要在 Arrow 開發郵件列表上進行個別討論和投票。
要新增的規格文本必須遵循以下要求
1. 它必須定義一個以「arrow.」開頭的明確定義的擴展名稱。
2. 其參數（如果有的話）必須在提案中描述。
3. 其序列化必須在提案中描述，並且不應需要過度的實作工作或不尋常的軟體依賴性（例如，簡單的自訂文本格式或基於 JSON 的格式是可以接受的）。
4. 其預期的語意應該也要描述，並且任何潛在的歧義或痛點都應解決或至少提及。
擴展類型應該提交一個實作；如果是非平凡的（例如，如果是參數化的），最好是兩個。

進行修改#

與標準 Arrow 資料類型一樣，標準擴展類型一旦標準化就應被視為穩定的。修改標準擴展類型（例如，擴展參數集）應為例外事件，遵循上述相同的規則，並提供向後相容性保證。

官方列表#

固定形狀張量#

擴展名稱：arrow.fixed_shape_tensor。
擴展的儲存類型：FixedSizeList，其中
- value_type 是個別張量元素的資料類型。
- list_size 是張量形狀中所有元素的乘積。
擴展類型參數
- value_type = 個別張量元素的 Arrow 資料類型。
- shape = 所包含張量的物理形狀，以陣列表示。
描述邏輯佈局的選用參數
- dim_names = 張量維度的明確名稱，以陣列表示。其長度應等於形狀長度，且等於維度數量。
  
  如果維度具有廣為人知的名稱，且它們映射到物理佈局（列優先），則可以使用 dim_names。
- permutation = 原始維度所需順序的索引，定義為陣列。
  
  索引包含值 [0, 1, .., N-1] 的排列，其中 N 是維度數量。排列指示邏輯佈局的哪個維度對應於物理張量的哪個維度（邏輯視圖的第 i 個維度對應於物理張量的編號 permutations[i] 的維度）。
  
  如果張量的邏輯順序是物理順序（列優先）的排列，則排列可能很有用。
  
  當邏輯佈局和物理佈局相等時，排列將始終為 ([0, 1, .., N-1])，因此可以省略。
序列化的描述

中繼資料必須是有效的 JSON 物件，包括所包含張量的形狀（以鍵 “shape” 的陣列表示），以及選用的維度名稱（以鍵 “dim_names” 表示）和維度的順序（以鍵 “permutation” 表示）。
- 範例：{ "shape": [2, 5]}
- 具有 NCHW 排序資料的 dim_names 中繼資料範例
  
  { "shape": [100, 200, 500], "dim_names": ["C", "H", "W"]}
- 排列的 3 維張量範例
  
  { "shape": [100, 200, 500], "permutation": [2, 0, 1]}
  
  這是物理佈局形狀，而邏輯佈局的形狀在這種情況下將為 [500, 100, 200]。

注意

固定形狀張量擴展陣列中的元素以列優先/C 連續順序儲存。

注意

Arrow 中的其他資料結構包括張量（多維陣列），用作跨程序通訊機制 (IPC) 中的訊息。

此結構與本規範定義的固定形狀張量擴展類型無關。相反地，此擴展類型允許將固定形狀張量用作 RecordBatch 或 Table 欄位中的元素。

可變形狀張量#

擴展名稱：arrow.variable_shape_tensor。
擴展的儲存類型為：StructArray，其中 struct 由 data 和 shape 欄位組成，用於描述每列單個張量
- data 是一個 List，用於保存張量元素（每個列表元素都是單個張量）。List 的值類型是張量的值類型，例如整數或浮點類型。
- shape 是張量形狀的 FixedSizeList<int32>[ndim]，其中列表 ndim 的大小等於張量的維度數量。
擴展類型參數
- value_type = 個別張量元素的 Arrow 資料類型。
描述邏輯佈局的選用參數
- dim_names = 張量維度的明確名稱，以陣列表示。其長度應等於形狀長度，且等於維度數量。
  
  如果維度具有廣為人知的名稱，且它們映射到物理佈局（列優先），則可以使用 dim_names。
- permutation = 原始維度所需順序的索引，定義為陣列。
  
  索引包含值 [0, 1, .., N-1] 的排列，其中 N 是維度數量。排列指示邏輯佈局的哪個維度對應於物理張量的哪個維度（邏輯視圖的第 i 個維度對應於物理張量的編號 permutations[i] 的維度）。
  
  如果張量的邏輯順序是物理順序（列優先）的排列，則排列可能很有用。
  
  當邏輯佈局和物理佈局相等時，排列將始終為 ([0, 1, .., N-1])，因此可以省略。
- uniform_shape = 個別張量維度的大小，保證在均勻維度中保持恆定，並且在非均勻維度中可以變化。這適用於陣列中的所有張量。均勻維度的大小以 int32 值表示，而非均勻維度的大小事先未知，並以 null 表示。如果未提供 uniform_shape，則假定所有維度都是非均勻的。包含形狀為 (2, 3, 4) 的張量的陣列，且其第一個和最後一個維度是均勻的，將具有 uniform_shape (2, null, 4)。這允許正確解釋張量，而無需考慮均勻維度，同時仍然允許利用均勻性的選用最佳化。
序列化的描述

中繼資料必須是有效的 JSON 物件，可選地包括維度名稱（以鍵 “dim_names” 表示）和維度的順序（以鍵 “permutation” 表示）。張量的形狀可以在維度的子集中定義，方法是提供鍵 “uniform_shape”。最小的中繼資料是空字串。
- 具有 NCHW 排序資料的 dim_names 中繼資料範例（請注意，第一個邏輯維度 N 映射到 data List 陣列：List 中的每個元素都是 CHW 張量，而張量 List 隱含地構成單個 NCHW 張量）
  
  { "dim_names": ["C", "H", "W"] }
- 具有一組高度固定、寬度可變且具有三個顏色通道的彩色圖像的 uniform_shape 中繼資料範例
  
  { "dim_names": ["H", "W", "C"], "uniform_shape": [400, null, 3] }
- 排列的 3 維張量範例
  
  { "permutation": [2, 0, 1] }
  
  例如，如果單個張量的物理 shape 為 [100, 200, 500]，則此排列將表示邏輯形狀為 [500, 100, 200]。

注意

除了 permutation 之外，VariableShapeTensor 的參數和儲存都與張量的物理儲存相關。

例如，考慮一個具有以下屬性的張量：: shape = [10, 20, 30] dim_names = [x, y, z] permutations = [2, 0, 1]

這表示邏輯張量具有名稱 [z, x, y] 和形狀 [30, 10, 20]。

注意

每個 data 張量元素內的值都根據對應的 shape 以列優先/C 連續順序儲存。

JSON#

擴展名稱：arrow.json。
此擴展的儲存類型為 String 或 LargeString 或 StringView。僅支援 rfc8259 中指定的 UTF-8 編碼 JSON。
擴展類型參數

此類型沒有任何參數。
序列化的描述

中繼資料可以是空字串或具有空物件的 JSON 字串。未來可能會新增其他欄位，但它們不是解釋陣列所必需的。

UUID#

擴展名稱：arrow.uuid。
擴展的儲存類型為長度為 16 位元組的 FixedSizeBinary。

注意

不需要或保證特定的 UUID 版本。此擴展將 UUID 表示為具有大端表示法的 FixedSizeBinary(16)，並且不以任何方式解釋位元組。

Opaque#

Opaque 表示 Arrow 基礎系統從外部（通常是非 Arrow）系統接收但無法解釋的類型。在這種情況下，它可以將 Opaque 傳遞給其用戶端，至少表明欄位存在並保留來自其他系統的類型相關中繼資料。

擴展參數

擴展名稱：arrow.opaque。
此擴展的儲存類型為任何類型。如果沒有基礎資料，則儲存類型應為 Null。
擴展類型參數
- type_name = 外部系統中未知類型的名稱。
- vendor_name = 外部系統的名稱。
序列化的描述

包含參數作為欄位的有效 JSON 物件。未來可能會新增其他欄位，但目前和未來的所有欄位都不是解釋陣列所必需的。

開發人員不應嘗試透過標準化這些參數的特定值來啟用 Opaque 的公用語意互通性。

理由#

與非 Arrow 系統介接需要一種處理沒有等效 Arrow 類型的資料的方法。在這種情況下，請使用 Opaque 類型，它明確表示不支援的欄位。其他解決方案不足

引發錯誤表示即使只有一個不支援的欄位也會使所有操作都無法進行，即使（例如）使用者只是想查看綱要。
刪除不支援的欄會誤導使用者了解實際綱要。
不支援的類型可能不存在擴展類型。
即時產生擴展類型會錯誤地暗示支援。

應用程式不應圍繞 vendor_name 和 type_name 制定慣例。這些參數旨在讓人類最終使用者了解不支援哪種類型。應用程式可能會嘗試解釋這些欄位，但必須為中斷做好準備（例如，當稍後使用自訂擴展類型支援該類型時）。同樣地，Opaque 不是檔案格式的通用容器。MIME 類型等考量無關緊要。在這兩種情況下，請改為建立自訂擴展類型。

範例

支援連線外部資料庫的 Flight SQL 服務可能會在外部表格中遇到具有不支援類型的欄。在這種情況下，它可以使用 Opaque[Null] 類型至少報告欄位存在且具有特定的名稱和類型名稱。這讓用戶端知道欄位存在，但不支援。此處使用 Null 作為儲存類型，因為僅涉及綱要。

擴展中繼資料的範例將是
```
{"type_name": "varray", "vendor_name": "Oracle"}
```
ADBC PostgreSQL 驅動程式以一系列帶長度前綴的位元組欄位形式取得結果。但是驅動程式並非總是知道如何剖析位元組，因為可能存在擴展（例如 PostGIS）。它可以使用 Opaque[Binary] 仍然將這些位元組傳回給應用程式，應用程式可能能夠自行剖析資料。Opaque 將欄與實際二進位欄區分開來，並清楚地表明該值直接來自 PostgreSQL。（首選自訂擴展類型，但始終會有驅動程式不知道的擴展。）

擴展中繼資料的範例將是
```
{"type_name": "geometry", "vendor_name": "PostGIS"}
```
ADBC PostgreSQL 驅動程式也可能知道如何剖析位元組，但不知道預期的語意。例如，複合類型可以為現有類型新增新的語意，有點像 Arrow 擴展類型。在這種情況下，驅動程式將能夠剖析基礎位元組，但仍將使用 Opaque 類型。

考慮 PostgreSQL 文件中 complex 類型的範例。將類型映射到普通的 Arrow struct 類型會失去意義，就像 Arrow 系統決定透過刪除擴展中繼資料來處理所有擴展類型一樣不受歡迎。相反地，驅動程式可以使用 Opaque[Struct] 來傳遞複合類型資訊。（嘗試將其映射到 Arrow 定義的複雜類型是錯誤的：它不知道使用者定義類型的正確語意，使用者定義類型的正確語意不能也不應硬式編碼到驅動程式中。）

擴展中繼資料的範例將是
```
{"type_name": "database_name.schema_name.complex", "vendor_name": "PostgreSQL"}
```
Arrow Java 程式庫中的 JDBC 配接器將 JDBC 結果集轉換為 Arrow 陣列，並且可以從結果集中取得 Arrow 綱要。然而，JDBC 允許驅動程式傳回任意 Java 物件。

驅動程式可以使用 Opaque[Null] 作為綱要轉換期間的預留位置，僅在應用程式嘗試擷取實際資料時才會出錯。這樣，用戶端至少可以內省結果綱要，以決定是否可以繼續擷取資料，或僅查詢某些欄。

擴展中繼資料的範例將是
```
{"type_name": "OTHER", "vendor_name": "JDBC driver name"}
```

8 位元布林值#

Bool8 使用 1 個位元組（8 位元）來表示布林值，以儲存每個值，而不是像原始 Arrow 布林值類型中那樣僅使用 1 位元。雖然不如原始表示法緊湊，但 Bool8 可能與各種也使用 1 個位元組儲存布林值的系統具有更好的零複製相容性。

擴展名稱：arrow.bool8。
此擴展的儲存類型為 Int8，其中
- false 由值 0 表示。
- true 可以使用任何非零值指定。最好是 1。
擴展類型參數

此類型沒有任何參數。
序列化的描述

中繼資料是空字串。

社群擴展類型#

除了上面列出的標準擴展類型外，還存在已在特定領域內建立為標準的 Arrow 擴展類型。這些類型尚未透過 Arrow 開發郵件列表上的討論和投票正式指定為標準，但在 Arrow 開發人員的子社群中廣為人知。

GeoArrow#

GeoArrow 定義了一系列用於表示向量幾何圖形的 Arrow 擴展類型。它在 Arrow 地理空間子社群中廣為人知。GeoArrow 規範尚未最終確定。