Datentypsystem von BigQuery DataFrames verwenden

Das Datentypsystem von BigQuery DataFrames basiert auf BigQuery-Datentypen. Dieses Design sorgt für eine nahtlose Integration und Abstimmung mit dem Google Cloud Data Warehouse und spiegelt die integrierten Typen wider, die für die Daten speicherung in BigQuery verwendet werden.

Typzuordnungen

In der folgenden Tabelle sind die Datentypentsprechungen in BigQuery, BigQuery DataFrames und anderen Python-Bibliotheken sowie die jeweiligen Unterstützungsstufen aufgeführt:

Datentyp BigQuery BigQuery DataFrames Integrierte Python-Funktion PyArrow
Boolesch BOOL pandas.BooleanDtype() bool bool_()
Ganzzahl INT64 pandas.Int64Dtype() int int64()
Float FLOAT64 pandas.Float64Dtype() float float64()
String STRING pandas.StringDtype(storage="pyarrow") str string()
Byte BYTES pandas.ArrowDtype(pyarrow.binary()) bytes binary()
Datum DATE pandas.ArrowDtype(pyarrow.date32()) datetime.date date32()
Zeit TIME pandas.ArrowDtype(pyarrow.time64("us")) datetime.time time64("us")
Datum/Uhrzeit DATETIME pandas.ArrowDtype(pyarrow.timestamp("us")) datetime.datetime timestamp("us")
Zeitstempel TIMESTAMP pandas.ArrowDtype(pyarrow.timestamp("us", tz="UTC")) Datetime.datetime mit Zeitzone timestamp("us", tz="UTC")
Numerisch NUMERIC pandas.ArrowDtype(pyarrow.decimal128(38, 9)) decimal.Decimal decimal128(38, 9)
Große numerische Werte BIGNUMERIC pandas.ArrowDtype(pyarrow.decimal256(76, 38)) decimal.Decimal decimal256(76, 38)
List<T> ARRAY<T> pandas.ArrowDtype(pyarrow.list_(T)) list[T] list_(T)
Struct STRUCT pandas.ArrowDtype(pyarrow.struct()) dict struct()
JSON JSON pandas.ArrowDtype(pyarrow.json_(pa.string()) in pandas Version 3.0 oder höher und PyArrow Version 19.0 oder höher. Andernfalls werden JSON-Spalten als pandas.ArrowDtype(db_dtypes.JSONArrowType()) dargestellt. Diese Feature befindet sich im Vorschaumodus. Nicht unterstützt json_() (Vorschau)
Geografie GEOGRAPHY Geopandas.array.GeometryDtype()
wird nur von to_pandas() unterstützt.		 Nicht unterstützt Nicht unterstützt
Zeitdifferenz Nicht unterstützt pandas.ArrowDtype(pyarrow.duration("us")) datetime.timedelta duration("us")

Typkonvertierungen

Bei Verwendung mit lokalen Daten konvertiert BigQuery DataFrames Datentypen in die entsprechenden BigQuery DataFrames-Entsprechungen, sofern eine Typzuordnung definiert ist, wie im folgenden Beispiel gezeigt:

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 bestimmt das Verhalten, wenn es Abweichungen zwischen den Datentypentsprechungen gibt. In seltenen Fällen, in denen die integrierte Python-Typfunktion anders als ihr PyArrow-Gegenstück funktioniert, bevorzugt BigQuery DataFrames im Allgemeinen das PyArrow-Verhalten, um die Konsistenz zu gewährleisten.

Im folgenden Codebeispiel wird der Vorgang datetime.date + timedelta verwendet, um zu zeigen, dass BigQuery DataFrames im Gegensatz zur Python-Bibliothek für Datum und Uhrzeit, die weiterhin eine Datumsinstanz zurückgibt, dem PyArrow-Verhalten folgt und eine Zeitstempelinstanz zurückgibt:

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]

Spezielle Typen

In den folgenden Abschnitten werden die speziellen Datentypen beschrieben, die von BigQuery DataFrames verwendet werden.

JSON

In BigQuery DataFrames werden Spalten im BigQuery JSON-Format (einem einfachen Standard) durch pandas.ArrowDtype dargestellt. Der genaue zugrunde liegende Arrow-Typ hängt von Ihren Bibliotheksversionen ab. In älteren Umgebungen wird in der Regel db_dtypes.JSONArrowType() für die Kompatibilität verwendet. Dies ist ein Arrow-Erweiterungstyp, der als einfache Wrapper-Funktion für pa.string() dient. Im Gegensatz dazu wird in neueren Setups (pandas 3.0 und höher und PyArrow 19.0 und höher) die neuere Darstellung pa.json_(pa.string()) verwendet.

timedelta

Für den Typ timedelta gibt es keine direkte Entsprechung im integrierten Typsystem von BigQuery. Zur Verwaltung von Zeitdifferenzdaten verwendet BigQuery DataFrames den Typ INT64 als zugrunde liegendes Speicherformat in BigQuery-Tabellen. Die Ergebnisse Ihrer Berechnungen sind mit dem Verhalten identisch, das Sie von entsprechenden Vorgängen mit der pandas-Bibliothek erwarten würden.

Sie können timedelta-Werte direkt in BigQuery DataFrames- und Series-Objekte laden, wie im folgenden Beispiel gezeigt:

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]

Im Gegensatz zu pandas unterstützt BigQuery DataFrames nur timedelta-Werte mit Mikrosekundengenauigkeit. Wenn Ihre Daten Nanosekunden enthalten, müssen Sie sie runden, um potenzielle Ausnahmen zu vermeiden, wie im folgenden Beispiel gezeigt:

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]

Mit der bigframes.pandas.to_timedelta Funktion können Sie ein BigQuery DataFrames Series Objekt in den Typ timedelta umwandeln, wie im folgenden Beispiel gezeigt:

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]

Wenn Sie Daten mit timedelta-Werten in eine BigQuery-Tabelle laden, werden die Werte in Mikrosekunden konvertiert und in INT64-Spalten gespeichert. Um die Typinformationen beizubehalten, fügt BigQuery DataFrames den String #microseconds an die Beschreibungen dieser Spalten an. Bei einigen Vorgängen wie SQL-Abfrageausführungen und UDF-Aufrufen bleiben Spaltenbeschreibungen nicht erhalten und die timedelta-Typinformationen gehen nach Abschluss dieser Vorgänge verloren.

Tools für zusammengesetzte Typen

Für bestimmte zusammengesetzte Typen bietet BigQuery DataFrames Tools, mit denen Sie auf die Elementwerte in diesen Typen zugreifen und sie verarbeiten können.

Listenzugriffsfunktion

Mit dem Objekt ListAccessor können Sie Vorgänge für jedes Listenelement ausführen, indem Sie die Listeneigenschaft des Objekts Series verwenden, wie im folgenden Beispiel gezeigt:

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

Struct-Zugriffsfunktion

Mit dem Objekt StructAccessor können Sie auf Felder in einer Reihe von Structs zugreifen und sie verarbeiten. Das API-Zugriffsobjekt ist series.struct, wie im folgenden Beispiel gezeigt:

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

Wenn das struct-Feld, auf das Sie zugreifen möchten, eindeutig von anderen Series-Eigenschaften zu unterscheiden ist, können Sie den Aufruf von struct überspringen, wie im folgenden Beispiel gezeigt:

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

Es empfiehlt sich jedoch, struct für den Zugriff auf Felder zu verwenden, da dies den Code verständlicher und weniger fehleranfällig macht.

String-Zugriffsfunktion

Sie können mit der Eigenschaft str für ein Series-Objekt auf das Objekt StringAccessor zugreifen, wie im folgenden Beispiel gezeigt:

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

Geografie-Zugriffsfunktion

BigQuery DataFrames bietet ein Objekt GeographyAccessor, das ähnliche APIs wie die GeoSeries-Struktur der GeoPandas-Bibliothek verwendet. Sie können das Objekt GeographyAccessor mit der Eigenschaft geo für ein Series-Objekt aufrufen, wie im folgenden Beispiel gezeigt:

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

Nächste Schritte