Utiliser le système de types de données BigQuery DataFrames

Le système de types de données BigQuery DataFrames est basé sur les types de données BigQuery. Cette conception assure une intégration parfaite et un alignement avec l' Google Cloud entrepôt de données, reflétant les types intégrés utilisés pour le stockage des données dans BigQuery.

Mappages des types

Le tableau suivant présente les équivalents des types de données dans BigQuery, BigQuery DataFrames et d'autres bibliothèques Python, ainsi que leurs niveaux de compatibilité :

Type de données BigQuery BigQuery DataFrames Python intégré PyArrow
Booléen BOOL pandas.BooleanDtype() bool bool_()
Integer INT64 pandas.Int64Dtype() int int64()
Float FLOAT64 pandas.Float64Dtype() float float64()
Chaîne STRING pandas.StringDtype(storage="pyarrow") str string()
Octets BYTES pandas.ArrowDtype(pyarrow.binary()) bytes binary()
Date DATE pandas.ArrowDtype(pyarrow.date32()) datetime.date date32()
Heure TIME pandas.ArrowDtype(pyarrow.time64("us")) datetime.time time64("us")
Date/Heure DATETIME pandas.ArrowDtype(pyarrow.timestamp("us")) datetime.datetime timestamp("us")
Horodatage TIMESTAMP pandas.ArrowDtype(pyarrow.timestamp("us", tz="UTC")) Datetime.datetime avec fuseau horaire timestamp("us", tz="UTC")
Numérique NUMERIC pandas.ArrowDtype(pyarrow.decimal128(38, 9)) decimal.Decimal decimal128(38, 9)
Grand nombre BIGNUMERIC pandas.ArrowDtype(pyarrow.decimal256(76, 38)) decimal.Decimal decimal256(76, 38)
Liste<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()) dans pandas version 3.0 ou ultérieure et PyArrow version 19.0 ou ultérieure ; sinon, les colonnes JSON sont exposées en tant que pandas.ArrowDtype(db_dtypes.JSONArrowType()). Cette fonctionnalité est disponible en version bêta. Non compatible json_() (bêta)
Zone géographique GEOGRAPHY Geopandas.array.GeometryDtype()
Compatible avec to_pandas() uniquement.		 Non compatible Non compatible
Timedelta Non compatible pandas.ArrowDtype(pyarrow.duration("us")) datetime.timedelta duration("us")

Conversions de types

Lorsqu'il est utilisé avec des données locales, BigQuery DataFrames convertit les types de données en leurs équivalents BigQuery DataFrames chaque fois qu'un mappage de type est défini, comme illustré dans l'exemple suivant :

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 dicte le comportement en cas de différences entre les équivalents de types de données. Dans de rares cas où le type intégré Python fonctionne différemment de son homologue PyArrow, BigQuery DataFrames privilégie généralement le comportement PyArrow pour garantir la cohérence.

L'exemple de code suivant utilise l'opération datetime.date + timedelta pour montrer que, contrairement à la bibliothèque Python datetime qui renvoie toujours une instance de date, BigQuery DataFrames suit le comportement PyArrow en renvoyant une instance d'horodatage :

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]

Types spéciaux

Les sections suivantes décrivent les types de données spéciaux utilisés par BigQuery DataFrames.

JSON

Dans BigQuery DataFrames, les colonnes utilisant le format JSON BigQuery (une norme légère) sont représentées par pandas.ArrowDtype. Le type Arrow sous-jacent exact dépend des versions de votre bibliothèque. Les environnements plus anciens utilisent généralement db_dtypes.JSONArrowType() pour la compatibilité. Il s'agit d'un type d'extension Arrow qui agit comme un wrapper léger autour de pa.string(). En revanche, les configurations plus récentes (pandas 3.0 et versions ultérieures, et PyArrow 19.0 et versions ultérieures) utilisent la représentation pa.json_(pa.string()) plus récente.

timedelta

Le type timedelta n'a pas d'équivalent direct dans le système de types intégré BigQuery. Pour gérer les données de durée, BigQuery DataFrames utilise le type INT64 comme format de stockage sous-jacent dans les tables BigQuery. Vous pouvez vous attendre à ce que les résultats de vos calculs soient cohérents avec le comportement que vous attendez des opérations équivalentes effectuées avec la bibliothèque pandas.

Vous pouvez charger directement les valeurs timedelta dans les objets BigQuery DataFrames et Series, comme illustré dans l'exemple suivant :

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]

Contrairement à pandas, BigQuery DataFrames n'est compatible qu'avec les valeurs timedelta avec une précision en microsecondes. Si vos données incluent des nanosecondes, vous devez les arrondir pour éviter les exceptions potentielles, comme illustré dans l'exemple suivant :

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]

Vous pouvez utiliser la bigframes.pandas.to_timedelta fonction pour caster un objet Series BigQuery DataFrames au type timedelta, comme illustré dans l'exemple suivant :

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]

Lorsque vous chargez des données contenant des valeurs timedelta dans une table BigQuery, les valeurs sont converties en microsecondes et stockées dans des colonnes INT64. Pour préserver les informations de type, BigQuery DataFrames ajoute la chaîne #microseconds aux descriptions de ces colonnes. Certaines opérations, telles que les exécutions de requêtes SQL et les appels de fonctions UDF, ne conservent pas les descriptions de colonnes, et les informations de type timedelta sont perdues une fois ces opérations terminées.

Outils pour les types composites

Pour certains types composites, BigQuery DataFrames fournit des outils qui vous permettent d'accéder aux valeurs élémentaires de ces types et de les traiter.

Accesseur de liste

L'objet ListAccessor peut vous aider à effectuer des opérations sur chaque élément de liste à l'aide de la propriété de liste de l'objet Series, comme illustré dans l'exemple suivant :

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

Accesseur de structure

L'objet StructAccessor peut accéder aux champs d'une série de structures et les traiter. L'objet accesseur de l'API est series.struct, comme illustré dans l'exemple suivant :

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

Si le champ struct auquel vous prévoyez d'accéder n'est pas ambigu par rapport aux autres propriétés Series, vous pouvez ignorer l'appel de struct, comme illustré dans l'exemple suivant :

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

Toutefois, il est recommandé d'utiliser struct pour accéder aux champs, car cela facilite la compréhension de votre code et réduit le risque d'erreurs.

Accesseur de chaîne

Vous pouvez accéder à l'objet StringAccessor avec la propriété str d'un objet Series, comme illustré dans l'exemple suivant :

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

Accesseur de zone géographique

BigQuery DataFrames fournit un objet GeographyAccessor qui partage des API similaires avec la structure GeoSeries fournie par la bibliothèque GeoPandas. Vous pouvez appeler l'objet GeographyAccessor avec la propriété geo d'un objet Series, comme illustré dans l'exemple suivant :

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

Étape suivante