Use o sistema de tipos de dados do BigQuery DataFrames

O sistema de tipos de dados do BigQuery DataFrames baseia-se nos tipos de dados do BigQuery. Este design garante uma integração perfeita e o alinhamento com o Trusted Cloud by S3NS armazém de dados, refletindo os tipos incorporados usados para o armazenamento de dados no BigQuery.

Mapeamentos de tipos

A tabela seguinte mostra os equivalentes dos tipos de dados no BigQuery, nos DataFrames do BigQuery e noutras bibliotecas Python, bem como os respetivos níveis de suporte:

Conversões de tipo

Quando usados com dados locais, os DataFrames do BigQuery convertem os tipos de dados nos respetivos equivalentes dos DataFrames do BigQuery sempre que um mapeamento de tipos estiver definido, conforme mostrado no exemplo seguinte:

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]"

O PyArrow determina o comportamento quando existem discrepâncias entre os equivalentes dos tipos de dados. Em casos raros em que as funções de tipo incorporadas do Python funcionam de forma diferente da respetiva contrapartida do PyArrow, os DataFrames do BigQuery favorecem geralmente o comportamento do PyArrow para garantir a consistência.

O exemplo de código seguinte usa a operação datetime.date + timedelta para mostrar que, ao contrário da biblioteca datetime do Python que continua a devolver uma instância de data, o BigQuery DataFrames segue o comportamento do PyArrow devolvendo uma instância de data/hora:

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 especiais

As secções seguintes descrevem os tipos de dados especiais que os DataFrames do BigQuery usam.

JSON

Nos DataFrames do BigQuery, as colunas que usam o formato JSON do BigQuery (uma norma simples) são representadas por pandas.ArrowDtype. O tipo de seta subjacente exato depende das versões da sua biblioteca. Os ambientes mais antigos usam normalmente db_dtypes.JSONArrowType() para compatibilidade, que é um tipo de extensão Arrow que funciona como um wrapper simples em torno de pa.string(). Por outro lado, as configurações mais recentes (pandas 3.0 e posteriores, e PyArrow 19.0 e posteriores) usam a representação pa.json_(pa.string()) mais recente.

timedelta

O tipo timedelta não tem um equivalente direto no sistema de tipos nativos do BigQuery. Para gerir dados de duração, os DataFrames do BigQuery usam o tipo INT64 como o formato de armazenamento subjacente nas tabelas do BigQuery. Pode esperar que os resultados dos seus cálculos sejam consistentes com o comportamento que esperaria de operações equivalentes realizadas com a biblioteca pandas.

Pode carregar diretamente valores timedelta em objetos e Series DataFrames do BigQuery, conforme mostrado no exemplo seguinte:

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]

Ao contrário do pandas, os DataFrames do BigQuery só suportam valores timedelta com precisão de microssegundos. Se os seus dados incluírem nanosegundos, tem de arredondá-los para evitar potenciais exceções, conforme mostrado no exemplo seguinte:

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]

Pode usar a função bigframes.pandas.to_timedelta para converter um objeto Series BigQuery DataFrames no tipo timedelta, conforme mostrado no exemplo seguinte:

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]

Quando carrega dados que contêm valores timedelta para uma tabela do BigQuery, os valores são convertidos em microssegundos e armazenados em colunas INT64. Para preservar as informações de tipo, a app BigQuery DataFrames anexa a string #microseconds às descrições destas colunas. Algumas operações, como as execuções de consultas SQL e as invocações de UDF, não preservam as descrições das colunas, e as informações do tipo timedelta são perdidas após a conclusão destas operações.

Ferramentas para tipos compostos

Para determinados tipos compostos, os DataFrames do BigQuery oferecem ferramentas que lhe permitem aceder e processar os valores elementares nesses tipos.

Aceder à lista

O objeto ListAccessor pode ajudar a realizar operações em cada elemento da lista usando a propriedade list do objeto Series, conforme mostrado no exemplo seguinte:

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

Struct accessor

O objeto StructAccessor pode aceder e processar campos numa série de estruturas. O objeto de acesso à API é series.struct, conforme mostrado no exemplo seguinte:

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

Se o campo struct ao qual planeia aceder não for ambíguo em relação a outras propriedades Series, pode ignorar a chamada struct, conforme mostrado no exemplo seguinte:

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

No entanto, é uma prática recomendada usar struct para aceder aos campos, porque torna o seu código mais fácil de compreender e menos propenso a erros.

Acesso de string

Pode aceder ao objeto StringAccessor com a propriedade str num objeto Series, conforme mostrado no exemplo seguinte:

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

Acesso à geografia

O BigQuery DataFrames fornece um objeto GeographyAccessor que partilha APIs semelhantes com a estrutura GeoSeries fornecida pela biblioteca GeoPandas. Pode invocar o objeto GeographyAccessor com a propriedade geo num objeto Series, como mostrado no exemplo seguinte:

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

O que se segue?

• Saiba como usar os DataFrames do BigQuery.
• Saiba mais sobre as sessões e a E/S do BigQuery DataFrames.
• Saiba como visualizar gráficos com os DataFrames do BigQuery.
• Explore a referência da API BigQuery DataFrames.