Usa el sistema de tipos de datos de BigQuery DataFrames

El sistema de tipos de datos de BigQuery DataFrames se basa en los tipos de datos de BigQuery. Este diseño garantiza una integración y alineación perfectas con el Google Cloud almacén de datos, lo que refleja los tipos integrados que se usan para el almacenamiento de datos en BigQuery.

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 BigQuery DataFrames Python integrado 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)
Número 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 pandas versión 3.0 o posterior y PyArrow versión 19.0 o posterior; 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 a sus equivalentes correspondientes de BigQuery DataFrames 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 tipos de datos. En casos excepcionales en los que el tipo integrado de Python funciona de manera diferente a su contraparte de PyArrow, BigQuery DataFrames generalmente favorece el comportamiento de PyArrow para garantizar la coherencia.

En el siguiente muestra de código, se usa la operación datetime.date + timedelta para mostrar que, a diferencia de la biblioteca datetime de Python que aún muestra una instancia de fecha, BigQuery DataFrames sigue el comportamiento de PyArrow y muestra 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 flecha 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 flecha que actúa como un wrapper ligero alrededor de pa.string(). Por el contrario, las configuraciones más recientes (pandas 3.0 y versiones posteriores, y PyArrow 19.0 y versiones posteriores) usan la representación más reciente pa.json_(pa.string()).

timedelta

El tipo timedelta no tiene un equivalente directo dentro del sistema de tipos integrados de BigQuery. Para administrar datos de duración, BigQuery DataFrames utiliza 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 directamente los valores timedelta en BigQuery DataFrames y los 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 al 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.

Accesor de lista

El objeto ListAccessor puede ayudarte a realizar operaciones en cada elemento de la lista mediante 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

Accesor de estructura

El objeto StructAccessor puede acceder a los campos de una serie de estructuras y procesarlos. El objeto de acceso a 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 con respecto a otras propiedades 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, es una práctica recomendada usar struct para acceder a los campos, ya que facilita la comprensión del código y lo hace menos propenso a errores.

Accesor 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

Accesor de datos geográficos

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?