Usar 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 una 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:

Conversiones de tipos

Cuando se usan con datos locales, BigQuery DataFrames convierte los tipos de datos a sus equivalentes 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 determina el comportamiento cuando hay discrepancias entre los equivalentes de tipo de datos. En casos excepcionales en los que la función de tipo integrada de Python se comporta de forma diferente a su contraparte de PyArrow, BigQuery DataFrames suele favorecer el comportamiento de PyArrow para garantizar la coherencia.

En el siguiente ejemplo de código se usa la operación datetime.date + timedelta para mostrar que, a diferencia de la biblioteca datetime de Python, que sigue devolviendo 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

En BigQuery DataFrames, las columnas que usan el formato JSON de BigQuery (un estándar ligero) se representan mediante pandas.ArrowDtype. El tipo de Arrow subyacente exacto depende de las versiones de tu biblioteca. Los entornos anteriores suelen usar db_dtypes.JSONArrowType() para la compatibilidad, que es un tipo de extensión de Arrow que actúa como un envoltorio 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) 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 nativo de BigQuery. Para gestionar los datos de duración, BigQuery DataFrames utiliza el tipo INT64 como formato de almacenamiento subyacente en las tablas de BigQuery. Los resultados de los cálculos serán coherentes con el comportamiento que se espera de las operaciones equivalentes realizadas con la biblioteca pandas.

Puedes cargar directamente valores timedelta en objetos BigQuery DataFrames y 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]

Puede 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 a microsegundos y se almacenan en columnas INT64. Para conservar la información de tipo, BigQuery DataFrames añade la cadena #microseconds a las descripciones de estas columnas. Algunas operaciones, como las ejecuciones de consultas SQL y las invocaciones de UDF, no conservan las descripciones de las columnas y la información de tipo timedelta se pierde una vez completadas estas operaciones.

Herramientas para tipos compuestos

En el caso de algunos tipos compuestos, BigQuery DataFrames proporciona herramientas que te permiten acceder a los valores elementales 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 mediante 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

Descriptor de acceso de struct

El objeto StructAccessor puede acceder a los campos de una serie de structs 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 quieres acceder no se confunde con 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 reduce la probabilidad de que se produzcan 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

Acceso a la geografía

BigQuery DataFrames proporciona un objeto GeographyAccessor que comparte APIs similares con la estructura GeoSeries proporcionada por 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

Siguientes pasos

• Consulta cómo usar BigQuery DataFrames.
• Consulta información sobre las sesiones y las operaciones de entrada/salida de los DataFrames de BigQuery.
• Consulta cómo visualizar gráficos con DataFrames de BigQuery.
• Consulta la referencia de la API BigQuery DataFrames.