BigQuery DataFrames のデータ型システムを使用する

BigQuery DataFrames のデータ型システムは、BigQuery のデータ型に基づいて構築されています。この設計により、Google Cloud データウェアハウスとのシームレスな統合と整合性が確保され、BigQuery でデータストレージに使用される組み込み型が反映されます。

型マッピング

次の表に、BigQuery、BigQuery DataFrames、その他の Python ライブラリのデータ型と、サポートレベルを示します。

データ型	BigQuery	BigQuery DataFrames	Python 組み込み	PyArrow
ブール値	`BOOL`	`pandas.BooleanDtype()`	`bool`	`bool_()`
整数	`INT64`	`pandas.Int64Dtype()`	`int`	`int64()`
浮動小数点数	`FLOAT64`	`pandas.Float64Dtype()`	`float`	`float64()`
文字列	`STRING`	`pandas.StringDtype(storage="pyarrow")`	`str`	`string()`
バイト	`BYTES`	`pandas.ArrowDtype(pyarrow.binary())`	`bytes`	`binary()`
日付	`DATE`	`pandas.ArrowDtype(pyarrow.date32())`	`datetime.date`	`date32()`
時間	`TIME`	`pandas.ArrowDtype(pyarrow.time64("us"))`	`datetime.time`	`time64("us")`
日時	`DATETIME`	`pandas.ArrowDtype(pyarrow.timestamp("us"))`	`datetime.datetime`	`timestamp("us")`
タイムスタンプ	`TIMESTAMP`	`pandas.ArrowDtype(pyarrow.timestamp("us", tz="UTC"))`	`Datetime.datetime`（タイムゾーンあり）	`timestamp("us", tz="UTC")`
数値	`NUMERIC`	`pandas.ArrowDtype(pyarrow.decimal128(38, 9))`	`decimal.Decimal`	`decimal128(38, 9)`
bignumeric	`BIGNUMERIC`	`pandas.ArrowDtype(pyarrow.decimal256(76, 38))`	`decimal.Decimal`	`decimal256(76, 38)`
リスト	`ARRAY<T>`	`pandas.ArrowDtype(pyarrow.list_(T))`	`list[T]`	`list_(T)`
構造体	`STRUCT`	`pandas.ArrowDtype(pyarrow.struct())`	`dict`	`struct()`
JSON	`JSON`	pandas バージョン 3.0 以降と PyArrow バージョン 19.0 以降の `pandas.ArrowDtype(pyarrow.json_(pa.string())`。それ以外の場合、JSON 列は `pandas.ArrowDtype(db_dtypes.JSONArrowType())` として公開されます。この機能はプレビュー版です。	サポート対象外	`json_()`（プレビュー）
地理	`GEOGRAPHY`	`Geopandas.array.GeometryDtype()` `to_pandas()` でのみサポートされています。	サポート対象外	サポート対象外
Timedelta	サポート対象外	`pandas.ArrowDtype(pyarrow.duration("us"))`	`datetime.timedelta`	`duration("us")`

型変換

ローカルデータで使用する場合、BigQuery DataFrames は、次の例に示すように、型マッピングが定義されている場所でデータ型を対応する BigQuery DataFrames の同等型に変換します。

import pandas as pd

import bigframes.pandas as bpd

s = pd.Series([pd.Timestamp("20250101")])
assert s.dtype == "datetime64[ns]"
assert bpd.read_pandas(s).dtype == "timestamp[us][pyarrow]"

データ型の同等性に不一致がある場合、PyArrow が動作を決定します。Python の組み込み型が PyArrow の対応する型と異なる動作をするまれなケースでは、通常、BigQuery DataFrames は一貫性を確保するために PyArrow の動作を優先します。

次のコードサンプルでは、datetime.date + timedelta オペレーションを使用して、日付インスタンスを返す Python datetime ライブラリとは異なり、BigQuery DataFrames がタイムスタンプインスタンスを返すことで PyArrow の動作に従っていることを示しています。

import datetime

import pandas as pd

import bigframes.pandas as bpd

s = pd.Series([datetime.date(2025, 1, 1)])
s + pd.Timedelta(hours=12)
# 0	2025-01-01
# dtype: object

bpd.read_pandas(s) + pd.Timedelta(hours=12)
# 0    2025-01-01 12:00:00
# dtype: timestamp[us][pyarrow]

特殊なタイプ

以降のセクションでは、BigQuery DataFrames で使用される特殊なデータ型について説明します。

JSON

BigQuery DataFrames 内では、BigQuery の JSON 形式（軽量の標準）を使用する列は pandas.ArrowDtype で表されます。基盤となる Arrow の型は、ライブラリのバージョンによって異なります。古い環境では通常、互換性のために db_dtypes.JSONArrowType() が使用されます。これは、pa.string() の軽量ラッパーとして機能する Arrow 拡張型です。一方、新しい設定（pandas 3.0 以降と PyArrow 19.0 以降）では、より新しい pa.json_(pa.string()) 表現が使用されます。

`timedelta`

timedelta 型には、BigQuery ネイティブ型のシステムに直接対応する型がありません。期間データを管理するために、BigQuery DataFrames は BigQuery テーブルの基盤となるストレージ形式として INT64 型を使用します。計算結果は、pandas ライブラリで同等のオペレーションを実行した場合の動作と一致します。

次の例に示すように、timedelta 値を BigQuery DataFrames と Series オブジェクトに直接読み込むことができます。

import pandas as pd

import bigframes.pandas as bpd

s = pd.Series([pd.Timedelta("1s"), pd.Timedelta("2m")])
bpd.read_pandas(s)
# 0    0 days 00:00:01
# 1    0 days 00:02:00
# dtype: duration[us][pyarrow]

pandas とは異なり、BigQuery DataFrames はマイクロ秒単位の精度の timedelta 値のみをサポートします。データにナノ秒が含まれている場合は、次の例に示すように丸めて、例外が発生しないようにする必要があります。

import pandas as pd

s = pd.Series([pd.Timedelta("999ns")])
bpd.read_pandas(s.dt.round("us"))
# 0    0 days 00:00:00.000001
# dtype: duration[us][pyarrow]

次の例に示すように、bigframes.pandas.to_timedelta 関数を使用して、BigQuery DataFrames の Series オブジェクトを timedelta 型にキャストできます。

import bigframes.pandas as bpd

bpd.to_timedelta([1, 2, 3], unit="s")
# 0    0 days 00:00:01
# 1    0 days 00:00:02
# 2    0 days 00:00:03
# dtype: duration[us][pyarrow]

timedelta 値を含むデータを BigQuery テーブルに読み込むと、値はマイクロ秒に変換され、INT64 列に保存されます。型情報を保持するため、BigQuery DataFrames はこれらの列の説明に #microseconds 文字列を追加します。SQL クエリの実行や UDF の呼び出しなどの一部のオペレーションでは、列の説明が保持されません。これらのオペレーションが完了すると、timedelta 型の情報が失われます。

複合タイプのツール

特定の複合型の場合、BigQuery DataFrames には、これらの型内の要素値にアクセスして処理できるツールが用意されています。

リストアクセサー

ListAccessor オブジェクトは、次の例に示すように、Series オブジェクトの list プロパティを使用して、各リスト要素に対してオペレーションを実行する際に役立ちます。

import bigframes.pandas as bpd

s = bpd.Series([[1, 2, 3], [4, 5], [6]])  # dtype: list<item: int64>[pyarrow]

# Access the first elements of each list
s.list[0]
# 0    1
# 1    4
# 2    6
# dtype: Int64

# Get the lengths of each list
s.list.len()
# 0    3
# 1    2
# 2    1
# dtype: Int64

構造体アクセサー

StructAccessor オブジェクトは、一連の構造体内のフィールドにアクセスして処理できます。API アクセサーオブジェクトは series.struct です。次の例をご覧ください。

import bigframes.pandas as bpd

structs = [
    {"id": 101, "category": "A"},
    {"id": 102, "category": "B"},
    {"id": 103, "category": "C"},
]
s = bpd.Series(structs)
# Get the 'id' field of each struct
s.struct.field("id")
# 0    101
# 1    102
# 2    103
# Name: id, dtype: Int64

アクセスする struct フィールドが他の Series プロパティと区別できる場合は、次の例に示すように struct の呼び出しをスキップできます。

import bigframes.pandas as bpd

structs = [
    {"id": 101, "category": "A"},
    {"id": 102, "category": "B"},
    {"id": 103, "category": "C"},
]
s = bpd.Series(structs)

# not explicitly using the "struct" property
s.id
# 0    101
# 1    102
# 2    103
# Name: id, dtype: Int64

ただし、struct を使用してフィールドにアクセスすることをおすすめします。これにより、コードが理解しやすくなり、エラーが発生しにくくなります。

文字列アクセサー

次の例に示すように、Series オブジェクトの str プロパティを使用して StringAccessor オブジェクトにアクセスできます。

import bigframes.pandas as bpd

s = bpd.Series(["abc", "de", "1"])  # dtype: string[pyarrow]

# Get the first character of each string
s.str[0]
# 0    a
# 1    d
# 2    1
# dtype: string

# Check whether there are only alphabetic characters in each string
s.str.isalpha()
# 0     True
# 1     True
# 2     False
# dtype: boolean

# Cast the alphabetic characters to their upper cases for each string
s.str.upper()
# 0    ABC
# 1     DE
# 2      1
# dtype: string

地理情報アクセサー

BigQuery DataFrames には、GeoPandas ライブラリで提供される GeoSeries 構造と同様の API を共有する GeographyAccessor オブジェクトが用意されています。次の例に示すように、Series オブジェクトの geo プロパティを使用して GeographyAccessor オブジェクトを呼び出すことができます。

from shapely.geometry import Point

import bigframes.pandas as bpd

s = bpd.Series([Point(1, 0), Point(2, 1)])  # dtype: geometry

s.geo.y
# 0    0.0
# 1    1.0
# dtype: Float64

次のステップ

BigQuery DataFrames を使用する方法を確認する。
BigQuery DataFrames セッションと I/O について確認する。
BigQuery DataFrames を使用してグラフを可視化する方法を確認する。
BigQuery DataFrames API リファレンスを確認する。