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 elGoogle 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 tipos de datos equivalentes en BigQuery, BigQuery DataFrames y otras bibliotecas de Python, así como sus niveles de compatibilidad:

Tipo de datos BigQuery Permite trabajar con BigQuery DataFrames. Incorporado 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)
Número grande BIGNUMERIC pandas.ArrowDtype(pyarrow.decimal256(76, 38)) decimal.Decimal decimal256(76, 38)
List 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 usan con datos locales, los BigQuery DataFrames convierten 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 los casos excepcionales en los que la función de tipo integrada de Python se comporta 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 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 usan los DataFrames de BigQuery.

JSON

En BigQuery DataFrames, las columnas que usan el formato JSON de BigQuery (un estándar ligero) se representan con pandas.ArrowDtype. El tipo subyacente exacto de Arrow 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 recientes (pandas 3.0 y versiones posteriores, y PyArrow 19.0 y versiones posteriores) utilizan la representación pa.json_(pa.string()) más reciente.

timedelta

El tipo timedelta no tiene un equivalente directo en el sistema de tipos nativos de BigQuery. Para administrar los datos de duración, BigQuery DataFrames utiliza el tipo INT64 como 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 de timedelta en los DataFrames de BigQuery y los objetos de 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 de timedelta en una tabla de BigQuery, los valores se convierten en microsegundos y se almacenan en columnas de 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 de 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 a la lista

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

Accessor de struct

El objeto StructAccessor puede acceder a los campos y procesarlos en una serie de structs. 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 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 hace que tu código sea más fácil de entender y menos propenso a errores.

Descriptor de acceso a cadenas

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

Accessor de ubicación geográfica

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?