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 et un alignement fluides avec l'entrepôt de donnéesTrusted Cloud by S3NS , reflétant les types intégrés utilisés pour le stockage des données dans BigQuery.

Mappages de types

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

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 d'écarts entre les équivalents de type de données. Dans de rares cas où la fonction de type intégrée Python se comporte différemment de son homologue PyArrow, BigQuery DataFrames privilégie généralement le comportement PyArrow pour assurer 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 de PyArrow en renvoyant une instance de code temporel :

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 de BigQuery (une norme légère) sont représentées par pandas.ArrowDtype. Le type Arrow sous-jacent exact dépend des versions de vos bibliothèques. Les anciens environnements utilisent généralement db_dtypes.JSONArrowType() pour la compatibilité. Il s'agit d'un type d'extension Arrow qui sert de 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 natifs de 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 Series et BigQuery DataFrames, 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'accepte que les valeurs timedelta avec une précision à la microseconde. Si vos données incluent des nanosecondes, vous devez les arrondir pour éviter d'éventuelles exceptions, 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 fonction bigframes.pandas.to_timedelta pour caster un objet Series BigQuery DataFrames vers le 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 sur le type, BigQuery DataFrames ajoute la chaîne #microseconds aux descriptions de ces colonnes. Certaines opérations, comme les exécutions de requêtes SQL et les appels de UDF par l'utilisateur, ne conservent pas les descriptions de colonnes. Les informations de type timedelta sont alors 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 la liste en utilisant la propriété list 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 et les traiter dans une série de structs. L'objet d'accesseur d'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 est sans ambiguïté 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 rend votre code plus facile à comprendre et moins sujet aux erreurs.

Accesseur de chaîne

Vous pouvez accéder à l'objet StringAccessor avec la propriété str sur 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 géographie

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 sur un objet Series, comme indiqué 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

Étapes suivantes

• Découvrez comment utiliser BigQuery DataFrames.
• En savoir plus sur les sessions et les E/S BigQuery DataFrames
• Découvrez comment visualiser des graphiques à l'aide de BigQuery DataFrames.
• Explorez la documentation de référence de l'API BigQuery DataFrames.