Cómo manipular datos con BigQuery DataFrames

En este documento, se describen las capacidades de manipulación de datos disponibles con los BigQuery DataFrames. Puedes encontrar las funciones que se describen en la biblioteca bigframes.bigquery.

Roles obligatorios

Para obtener los permisos que necesitas para completar las tareas de este documento, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Cuando realizas la autenticación de usuario final en un entorno interactivo, como un notebook, el REPL de Python o la línea de comandos, BigQuery DataFrames solicita la autenticación, si es necesario. De lo contrario, consulta cómo configurar las credenciales predeterminadas de la aplicación para varios entornos.

API de pandas

Una característica destacada de BigQuery DataFrames es que la API de bigframes.pandas está diseñada para ser similar a las APIs de la biblioteca de Pandas. Este diseño te permite emplear patrones de sintaxis conocidos para las tareas de manipulación de datos. Las operaciones definidas a través de la API de BigQuery DataFrames se ejecutan del lado del servidor y operan directamente en los datos almacenados en BigQuery, lo que elimina la necesidad de transferir conjuntos de datos fuera de BigQuery.

Para verificar qué APIs de pandas son compatibles con BigQuery DataFrames, consulta APIs de pandas compatibles.

Inspecciona y manipula datos

Puedes usar la API de bigframes.pandas para realizar operaciones de inspección y cálculo de datos. En el siguiente muestra de código, se usa la biblioteca bigframes.pandas para inspeccionar la columna body_mass_g, calcular la media body_mass y calcular la media body_mass por species:

import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Inspect one of the columns (or series) of the DataFrame:
bq_df["body_mass_g"]

# Compute the mean of this series:
average_body_mass = bq_df["body_mass_g"].mean()
print(f"average_body_mass: {average_body_mass}")

# Find the heaviest species using the groupby operation to calculate the
# mean body_mass_g:
(
    bq_df["body_mass_g"]
    .groupby(by=bq_df["species"])
    .mean()
    .sort_values(ascending=False)
    .head(10)
)

Biblioteca de BigQuery

La biblioteca de BigQuery proporciona funciones de SQL de BigQuery que podrían no tener un equivalente en pandas. En las siguientes secciones, se presentan algunos ejemplos.

Procesa valores de arreglos

Puedes usar la función bigframes.bigquery.array_agg() en la biblioteca bigframes.bigquery para agregar valores después de una operación groupby:

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

s = bpd.Series([0, 1, 2, 3, 4, 5])

# Group values by whether they are divisble by 2 and aggregate them into arrays
bbq.array_agg(s.groupby(s % 2 == 0))
# False    [1 3 5]
# True     [0 2 4]
# dtype: list<item: int64>[pyarrow]

También puedes usar las funciones de array array_length() y array_to_string().

Crea un objeto Series struct

Puedes usar la función bigframes.bigquery.struct() en la biblioteca bigframes.bigquery para crear un nuevo objeto Series struct con subcampos para cada columna en un DataFrame:

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Create a new STRUCT Series with subfields for each column in a DataFrames.
lengths = bbq.struct(
    bq_df[["culmen_length_mm", "culmen_depth_mm", "flipper_length_mm"]]
)

lengths.peek()
# 146	{'culmen_length_mm': 51.1, 'culmen_depth_mm': ...
# 278	{'culmen_length_mm': 48.2, 'culmen_depth_mm': ...
# 337	{'culmen_length_mm': 36.4, 'culmen_depth_mm': ...
# 154	{'culmen_length_mm': 46.5, 'culmen_depth_mm': ...
# 185	{'culmen_length_mm': 50.1, 'culmen_depth_mm': ...
# dtype: struct[pyarrow]

Cómo convertir marcas de tiempo en épocas de Unix

Puedes usar la función bigframes.bigquery.unix_micros() en la biblioteca bigframes.bigquery para convertir marcas de tiempo en microsegundos de Unix:

import pandas as pd

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Create a series that consists of three timestamps: [1970-01-01, 1970-01-02, 1970-01-03]
s = bpd.Series(pd.date_range("1970-01-01", periods=3, freq="d", tz="UTC"))

bbq.unix_micros(s)
# 0               0
# 1     86400000000
# 2    172800000000
# dtype: Int64

También puedes usar las funciones de tiempo unix_seconds() y unix_millis().

Usa la función escalar de SQL

Puedes usar la función bigframes.bigquery.sql_scalar() en la biblioteca bigframes.bigquery para acceder a la sintaxis de SQL arbitraria que representa una expresión de una sola columna:

import bigframes.bigquery as bbq
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"

# The sql_scalar function can be used to inject SQL syntax that is not supported
# or difficult to express with the bigframes.pandas APIs.
bq_df = bpd.read_gbq(query_or_table)
shortest = bbq.sql_scalar(
    "LEAST({0}, {1}, {2})",
    columns=[
        bq_df["culmen_depth_mm"],
        bq_df["culmen_length_mm"],
        bq_df["flipper_length_mm"],
    ],
)

shortest.peek()
#         0
# 149	18.9
# 33	16.3
# 296	17.2
# 287	17.0
# 307	15.0
# dtype: Float64

¿Qué sigue?