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

BigQuery Storage Write API (gRPC) 會將每個 BigQuery 資料欄資料類型，對應至特定通訊協定緩衝區和 Apache Arrow 輸入類型和編碼格式。本文件的參考表格列出支援的類型對應、值範圍和轉換參數。如需基礎 API 概念，請參閱「BigQuery Storage Write API (gRPC) 總覽」。

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

下表列出通訊協定緩衝區支援的資料類型，以及 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 您可以提供任何精確度或小數位數小於 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> 欄的欄位必須是 Arrow 類型 Date，且包含 unit=Day。

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

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

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