支援的通訊協定緩衝區和 Arrow 資料類型

本文件說明每個 BigQuery 資料類型支援的通訊協定緩衝區和 Arrow 資料類型。請先閱讀 BigQuery Storage Write API 簡介。

支援的通訊協定緩衝區資料類型

下表列出 protocol buffers 支援的資料類型，以及 BigQuery 中的對應輸入格式：

BigQuery 資料類型 支援的通訊協定緩衝區類型
BOOL bool、int32、int64、uint32、uint64、google.protobuf.BoolValue
BYTES bytes、string、google.protobuf.BytesValue
DATE int32 (建議)、int64、string

這個值是從 Unix 紀元 (1970-01-01) 起算的天數。有效範圍為 -719162 (0001-01-01) 至 2932896 (9999-12-31)。
DATETIME、TIME string

值必須是 DATETIME 或 TIME 字面值。
int64

使用 CivilTimeEncoder 類別執行轉換。
FLOAT double、float、google.protobuf.DoubleValue、google.protobuf.FloatValue
GEOGRAPHY string

這個值是 WKT 或 GeoJSON 格式的幾何圖形。
INTEGER int32、int64、uint32、enum、google.protobuf.Int32Value、google.protobuf.Int64Value、google.protobuf.UInt32Value
JSON string
NUMERIC、BIGNUMERIC int32、int64、uint32、uint64、double、float、string
bytes、google.protobuf.BytesValue

使用 BigDecimalByteStringEncoder 類別執行轉換作業。
STRING string、enum、google.protobuf.StringValue
TIME string

值必須是 TIME 常值。
TIMESTAMP int64 (建議)、int32、uint32、google.protobuf.Timestamp

這個值以微秒為單位，自 Unix 紀元 (1970-01-01) 起算。
INTERVAL string、google.protobuf.Duration

字串值必須是 INTERVAL 常值。
RANGE<T> message

在 proto 中，巢狀訊息類型包含兩個欄位 start 和 end，兩個欄位必須是相同的支援通訊協定緩衝區類型，且對應至 BigQuery 資料類型 T。T 必須是 DATE、DATETIME 或 TIMESTAMP。如果在 Proto 訊息中未設定欄位 (start 或 end)，則代表無邊界。在以下範例中，f_range_date 代表資料表中的 RANGE 欄。由於 proto 訊息中未設定 end 欄位，因此這個範圍的結束邊界是無限的。

{
  f_range_date: {
    start: 1
  }
}
REPEATED FIELD array

proto 中的陣列類型會對應至 BigQuery 中的重複欄位。
RECORD message

proto 中的巢狀訊息類型會對應至 BigQuery 中的記錄欄位。

支援的 Apache Arrow 資料類型

下表列出 Apache Arrow 支援的資料類型，以及 BigQuery 中的對應輸入格式。

BigQuery 資料類型 支援的 Apache Arrow 類型 支援的類型參數
BOOL Boolean
BYTES Binary
DATE Date unit = Day
String、int32
DATETIME Timestamp unit = MICROSECONDS

時區為空白
FLOAT FloatingPoint {SINGLE, DOUBLE} 的精確度
GEOGRAPHY Utf8

這個值是 WKT 或 GeoJSON 格式的幾何圖形。
INTEGER int bitWidth 在 {8, 16, 32, 64}

is_signed = false
JSON Utf8
NUMERIC Decimal128 您可以提供 NUMERIC 值，其精確度或比例小於 BigQuery 支援的範圍。
BIGNUMERIC Decimal256 您可以提供 BIGNUMERIC，其精確度或比例小於 BigQuery 支援的範圍。
STRING Utf8
TIMESTAMP Timestamp unit= MICROSECONDS

timezone = UTC
INTERVAL Interval 單位為 {YEAR_MONTH, DAY_TIME, MONTH_DAY_NANO}
Utf8
RANGE<T> Struct

Arrow 結構體必須有兩個名為 start 和 end 的子欄位。

對於 RANGE<DATE> 欄，欄位必須是箭頭類型的 Date，並搭配 unit=Day。

對於 RANGE<DATETIME> 欄，欄位必須是使用 unit=MICROSECONDS 的 Arrow 類型 Timestamp，且不含時區。

對於 RANGE<TIMESTAMP>，欄位必須是箭頭類型 Timestamp，並包含 unit=MICROSECONDS、timezone=UTC。

start 和 end 欄位中的任何 NULL 值都會視為 UNBOUNDED。
REPEATED FIELD List NULL 值必須以空白清單表示。
RECORD Struct