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

本文說明各個 BigQuery 資料類型支援的通訊協定緩衝區和 Arrow 資料類型。閱讀本文前，請先參閱 BigQuery Storage Write API 總覽。

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

下表列出通訊協定緩衝區支援的資料型別，以及 BigQuery 中對應的輸入格式：

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

這個值是自 Unix 紀元 (1970 年 1 月 1 日) 算起的天數。有效範圍為 -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 年 1 月 1 日) 起算。

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 單位 = 天
String、int32
DATETIME Timestamp unit = MICROSECONDS

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

值為 WKT 或 GeoJson 格式的幾何圖形。
INTEGER int bitWidth in {8, 16, 32, 64}

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

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

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

如果是 RANGE<DATE> 欄，欄位必須是 unit=Day 的箭頭類型 Date。

如果是 RANGE<DATETIME> 欄，欄位必須是 Arrow 類型 Timestamp，且包含 unit=MICROSECONDS，但不含時區。

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

如果 start 和 end 欄位中出現 NULL 值，系統會將其視為 UNBOUNDED。
REPEATED FIELD List NULL 值必須以空清單表示。
RECORD Struct