BigQuery DataFrames-Datentypsystem verwenden

Mit dem Datentypsystem von BigQuery DataFrames können Sie mit Datenstrukturen arbeiten, die mit integrierten BigQuery-Speichertypen übereinstimmen. Wenn Sie Ihre Analysen auf diesen Datentypen aufbauen, ist eine nahtlose Integration und zuverlässige Typzuordnung in Ihrem Data Warehouse gewährleistet.

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 Python-integriert 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)
BigNumeric 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()) angezeigt. Diese Feature befindet sich im Vorschaumodus. Nicht unterstützt json_() (Vorabversion)
Geografie GEOGRAPHY Geopandas.array.GeometryDtype()
Wird nur von to_pandas() unterstützt.		 Nicht unterstützt Nicht unterstützt
Timedelta Nicht unterstützt pandas.ArrowDtype(pyarrow.duration("us")) datetime.timedelta duration("us")

Typkonvertierungen

Bei der Verwendung mit lokalen Daten konvertiert BigQuery DataFrames Datentypen in die entsprechenden BigQuery DataFrames-Äquivalente, sofern eine Typzuordnung definiert ist. Dies wird 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 Datentypäquivalenten gibt. In seltenen Fällen, in denen sich der integrierte Python-Typ von seinem PyArrow-Äquivalent unterscheidet, bevorzugt BigQuery DataFrames im Allgemeinen das PyArrow-Verhalten, um 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 „datetime“, die immer 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 JSON-Format von BigQuery (einem einfachen Standard) durch pandas.ArrowDtype dargestellt. Der genaue zugrunde liegende Arrow-Typ hängt von Ihren Bibliotheksversionen ab. Ältere Umgebungen verwenden aus Kompatibilitätsgründen in der Regel db_dtypes.JSONArrowType(). Dies ist ein Arrow-Erweiterungstyp, der als einfacher Wrapper für pa.string() fungiert. Im Gegensatz dazu verwenden neuere Setups (pandas 3.0 und höher sowie PyArrow 19.0 und höher) die neuere pa.json_(pa.string())-Darstellung.

timedelta

Der Typ timedelta hat keine direkte Entsprechung im integrierten BigQuery-Typsystem. Zum Verwalten von Dauerdaten verwendet BigQuery DataFrames den Typ INT64 als zugrunde liegendes Speicherformat in BigQuery-Tabellen. Die Ergebnisse Ihrer Berechnungen sollten mit dem Verhalten übereinstimmen, 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 Mikrosekunden-Genauigkeit. 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-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 umgewandelt und in INT64-Spalten gespeichert. Damit die Typinformationen erhalten bleiben, hängt BigQuery DataFrames den String #microseconds an die Beschreibungen dieser Spalten an. Bei einigen Vorgängen wie SQL-Abfrageausführungen und UDF-Aufrufen werden Spaltenbeschreibungen nicht beibehalten 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.

Listen-Accessor

Mit dem ListAccessor-Objekt können Sie Vorgänge für jedes Listenelement ausführen. Verwenden Sie dazu das Listenattribut 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 Structs zugreifen und diese 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 unterscheidbar 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 Ihr Code dadurch leichter verständlich und weniger fehleranfällig wird.

String-Zugriffsfunktion

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

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