Datentypsystem von BigQuery DataFrames verwenden

Das Datentypsystem von BigQuery DataFrames basiert auf BigQuery-Datentypen. Dieses Design sorgt für eine nahtlose Integration und Ausrichtung auf dasGoogle Cloud Data Warehouse und spiegelt die integrierten Typen wider, die für die Datenspeicherung in BigQuery verwendet werden.

Typzuordnungen

In der folgenden Tabelle sind die entsprechenden Datentypen 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)
Liste 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-Äquivalente, 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 entsprechenden Datentypen gibt. In seltenen Fällen, in denen sich der integrierte Python-Typ anders verhält als das PyArrow-Pendant, wird in BigQuery DataFrames in der Regel das PyArrow-Verhalten bevorzugt, 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-Datetime-Bibliothek, 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, die das JSON-Format von BigQuery (ein einfacher Standard) verwenden, 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. Das ist ein Arrow-Erweiterungstyp, der als einfacher Wrapper für pa.string() fungiert. Neuere Setups (pandas 3.0 und höher sowie PyArrow 19.0 und höher) verwenden dagegen die neuere pa.json_(pa.string())-Darstellung.

timedelta

Der Typ timedelta hat im nativen Typsystem von BigQuery kein direktes Äquivalent. Zur Verwaltung von Zeitrahmendaten verwendet BigQuery DataFrames den Typ INT64 als zugrunde liegendes Speicherformat in BigQuery-Tabellen. Die Ergebnisse Ihrer Berechnungen sollten dem Verhalten entsprechen, das Sie von gleichwertigen Operationen 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 Mikrosekundenpräzision. 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 Funktion bigframes.pandas.to_timedelta können Sie ein BigQuery DataFrames-Objekt vom Typ Series 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 umgerechnet und in INT64-Spalten gespeichert. Um die Typinformationen beizubehalten, fügt BigQuery DataFrames den Beschreibungen dieser Spalten den String #microseconds hinzu. Bei einigen Vorgängen, z. B. der Ausführung von SQL-Abfrage und dem Aufrufen von UDFs, bleiben Spaltenbeschreibungen nicht erhalten. Die Typinformationen für timedelta 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 ListAccessor-Objekt können Sie Vorgänge für jedes Listenelement ausführen. Verwenden Sie dazu die Listeneigenschaft des Series-Objekts, 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-Accessor

Das StructAccessor-Objekt kann auf Felder in einer Reihe von Strukturen zugreifen und diese verarbeiten. Das API-Accessor-Objekt 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-Properties 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-Accessor

Sie können mit dem Attribut str eines Series-Objekts auf das StringAccessor-Objekt 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

Zugriffsberechtigter für geografische Daten

BigQuery DataFrames bietet ein GeographyAccessor-Objekt, das ähnliche APIs wie die GeoSeries-Struktur der GeoPandas-Bibliothek hat. Sie können das GeographyAccessor-Objekt mit dem Attribut 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