Usa el sistema de tipos de datos de BigQuery DataFrames

El sistema de tipos de datos de BigQuery DataFrames te permite trabajar con estructuras de datos que se alinean con los tipos de almacenamiento integrados de BigQuery. Compilar tus análisis en estos tipos de datos garantiza una integración sin problemas y asignaciones de tipos confiables en todo tu almacén de datos.

Asignaciones de tipos

En la siguiente tabla, se muestran los equivalentes de tipos de datos en BigQuery, BigQuery DataFrames y otras bibliotecas de Python, así como sus niveles de compatibilidad:

Tipo de datos BigQuery Permite trabajar con BigQuery DataFrames. Integrado en Python PyArrow
Booleano BOOL pandas.BooleanDtype() bool bool_()
Número entero INT64 pandas.Int64Dtype() int int64()
Número de punto flotante FLOAT64 pandas.Float64Dtype() float float64()
String STRING pandas.StringDtype(storage="pyarrow") str string()
Bytes BYTES pandas.ArrowDtype(pyarrow.binary()) bytes binary()
Fecha DATE pandas.ArrowDtype(pyarrow.date32()) datetime.date date32()
Hora TIME pandas.ArrowDtype(pyarrow.time64("us")) datetime.time time64("us")
Fecha y hora DATETIME pandas.ArrowDtype(pyarrow.timestamp("us")) datetime.datetime timestamp("us")
Marca de tiempo TIMESTAMP pandas.ArrowDtype(pyarrow.timestamp("us", tz="UTC")) Datetime.datetime con zona horaria timestamp("us", tz="UTC")
Numérico NUMERIC pandas.ArrowDtype(pyarrow.decimal128(38, 9)) decimal.Decimal decimal128(38, 9)
Numérico grande 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()) en la versión 3.0 o posterior de pandas y en la versión 19.0 o posterior de PyArrow; de lo contrario, las columnas JSON se exponen como pandas.ArrowDtype(db_dtypes.JSONArrowType()). Esta función está en vista previa. No compatible json_() (Vista previa)
Datos geográficos GEOGRAPHY Geopandas.array.GeometryDtype()
Solo es compatible con to_pandas().		 No compatible No compatible
Timedelta No compatible pandas.ArrowDtype(pyarrow.duration("us")) datetime.timedelta duration("us")

Tipos de conversiones

Cuando se usa con datos locales, BigQuery DataFrames convierte los tipos de datos en sus equivalentes de BigQuery DataFrames correspondientes siempre que se defina una asignación de tipos, como se muestra en el siguiente ejemplo:

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 dicta el comportamiento cuando hay discrepancias entre los equivalentes de tipo de datos. En casos excepcionales en los que el tipo integrado de Python funciona de manera diferente a su contraparte de PyArrow, BigQuery DataFrames suele favorecer el comportamiento de PyArrow para garantizar la coherencia.

En la siguiente muestra de código, se usa la operación datetime.date + timedelta para indicar que, a diferencia de la biblioteca datetime de Python, que aún devuelve una instancia de fecha, BigQuery DataFrames sigue el comportamiento de PyArrow y devuelve una instancia de marca de tiempo:

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]

Tipos especiales

En las siguientes secciones, se describen los tipos de datos especiales que usa BigQuery DataFrames.

JSON

Dentro de BigQuery DataFrames, las columnas que usan el formato JSON de BigQuery (un estándar ligero) se representan con pandas.ArrowDtype. El tipo de Arrow subyacente exacto depende de las versiones de tu biblioteca. Los entornos más antiguos suelen usar db_dtypes.JSONArrowType() para la compatibilidad, que es un tipo de extensión de Arrow que actúa como un wrapper ligero alrededor de pa.string(). En cambio, las configuraciones más nuevas (pandas 3.0 y versiones posteriores, y PyArrow 19.0 y versiones posteriores) usan la representación pa.json_(pa.string()) más reciente.

timedelta

El tipo timedelta no tiene un equivalente directo dentro del sistema de tipos integrado de BigQuery. Para administrar los datos de duración, BigQuery DataFrames usa el tipo INT64 como el formato de almacenamiento subyacente en las tablas de BigQuery. Puedes esperar que los resultados de tus cálculos sean coherentes con el comportamiento que esperarías de las operaciones equivalentes realizadas con la biblioteca de pandas.

Puedes cargar valores timedelta directamente en BigQuery DataFrames y objetos Series, como se muestra en el siguiente ejemplo:

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]

A diferencia de Pandas, BigQuery DataFrames solo admite valores timedelta con precisión de microsegundos. Si tus datos incluyen nanosegundos, debes redondearlos para evitar posibles excepciones, como se muestra en el siguiente ejemplo:

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]

Puedes usar la función bigframes.pandas.to_timedelta para convertir un objeto Series de BigQuery DataFrames en el tipo timedelta, como se muestra en el siguiente ejemplo:

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]

Cuando cargas datos que contienen valores timedelta en una tabla de BigQuery, los valores se convierten en microsegundos y se almacenan en columnas INT64. Para conservar la información del tipo, BigQuery DataFrames agrega la cadena #microseconds a las descripciones de estas columnas. Algunas operaciones, como las ejecuciones de consulta en SQL y las invocaciones de UDF, no conservan las descripciones de las columnas, y la información del tipo timedelta se pierde después de que se completan estas operaciones.

Herramientas para tipos compuestos

Para ciertos tipos compuestos, BigQuery DataFrames proporciona herramientas que te permiten acceder a los valores elementales dentro de esos tipos y procesarlos.

Descriptor de acceso de lista

El objeto ListAccessor puede ayudarte a realizar operaciones en cada elemento de la lista con la propiedad de lista del objeto Series, como se muestra en el siguiente ejemplo:

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

Descriptor de acceso de struct

El objeto StructAccessor puede acceder a los campos de una serie de structs y procesarlos. El objeto descriptor de acceso de la API es series.struct, como se muestra en el siguiente ejemplo:

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 el campo struct al que planeas acceder no es ambiguo de otras propiedades de Series, puedes omitir la llamada a struct, como se muestra en el siguiente ejemplo:

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

Sin embargo, se recomienda usar struct para acceder a los campos, ya que facilita la comprensión del código y reduce la probabilidad de errores.

Descriptor de acceso de cadena

Puedes acceder al objeto StringAccessor con la propiedad str en un objeto Series, como se muestra en el siguiente ejemplo:

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

Descriptor de acceso de geografía

BigQuery DataFrames proporciona un objeto GeographyAccessor que comparte APIs similares con la estructura GeoSeries que proporciona la biblioteca GeoPandas. Puedes invocar el objeto GeographyAccessor con la propiedad geo en un objeto Series, como se muestra en el siguiente ejemplo:

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

¿Qué sigue?