Menggunakan sistem jenis data BigQuery DataFrames

Sistem jenis data BigQuery DataFrames dibangun berdasarkan jenis data BigQuery. Desain ini memastikan integrasi dan keselarasan yang lancar dengan Google Cloud data warehouse, yang mencerminkan jenis bawaan yang digunakan untuk penyimpanan data di BigQuery.

Pemetaan jenis

Tabel berikut menunjukkan jenis data yang setara di BigQuery, BigQuery DataFrames, dan library Python lainnya, serta tingkat dukungannya:

Jenis data BigQuery DataFrame BigQuery Bawaan Python PyArrow
Boolean BOOL pandas.BooleanDtype() bool bool_()
Bilangan bulat INT64 pandas.Int64Dtype() int int64()
Float FLOAT64 pandas.Float64Dtype() float float64()
String STRING pandas.StringDtype(storage="pyarrow") str string()
Byte BYTES pandas.ArrowDtype(pyarrow.binary()) bytes binary()
Tanggal DATE pandas.ArrowDtype(pyarrow.date32()) datetime.date date32()
Waktu TIME pandas.ArrowDtype(pyarrow.time64("us")) datetime.time time64("us")
Datetime DATETIME pandas.ArrowDtype(pyarrow.timestamp("us")) datetime.datetime timestamp("us")
Stempel waktu TIMESTAMP pandas.ArrowDtype(pyarrow.timestamp("us", tz="UTC")) Datetime.datetime dengan zona waktu timestamp("us", tz="UTC")
Angka NUMERIC pandas.ArrowDtype(pyarrow.decimal128(38, 9)) decimal.Decimal decimal128(38, 9)
Numerik besar BIGNUMERIC pandas.ArrowDtype(pyarrow.decimal256(76, 38)) decimal.Decimal decimal256(76, 38)
Daftar 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()) di pandas versi 3.0 atau yang lebih baru dan PyArrow versi 19.0 atau yang lebih baru; jika tidak, kolom JSON akan ditampilkan sebagai pandas.ArrowDtype(db_dtypes.JSONArrowType()). Fitur ini berada dalam Pratinjau. Tidak didukung json_() (Pratinjau)
Geografi GEOGRAPHY Geopandas.array.GeometryDtype()
Hanya didukung oleh to_pandas().		 Tidak didukung Tidak didukung
Timedelta Tidak didukung pandas.ArrowDtype(pyarrow.duration("us")) datetime.timedelta duration("us")

Konversi jenis

Saat digunakan dengan data lokal, DataFrame BigQuery mengonversi jenis data ke jenis data yang setara di DataFrame BigQuery di mana pun pemetaan jenis ditentukan, seperti yang ditunjukkan dalam contoh berikut:

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 menentukan perilaku jika ada perbedaan antara jenis data yang setara. Dalam kasus yang jarang terjadi saat fungsi jenis bawaan Python berperilaku berbeda dari fungsi PyArrow yang setara, BigQuery DataFrames umumnya lebih memilih perilaku PyArrow untuk memastikan konsistensi.

Contoh kode berikut menggunakan operasi datetime.date + timedelta untuk menunjukkan bahwa, tidak seperti library datetime Python yang masih menampilkan instance tanggal, BigQuery DataFrames mengikuti perilaku PyArrow dengan menampilkan instance stempel waktu:

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]

Jenis khusus

Bagian berikut menjelaskan jenis data khusus yang digunakan BigQuery DataFrames.

JSON

Dalam BigQuery DataFrames, kolom yang menggunakan format JSON BigQuery (standar ringan) diwakili oleh pandas.ArrowDtype. Jenis Arrow yang mendasarinya bergantung pada versi library Anda. Lingkungan yang lebih lama biasanya menggunakan db_dtypes.JSONArrowType() untuk kompatibilitas, yang merupakan jenis ekstensi Arrow yang berfungsi sebagai wrapper ringan di sekitar pa.string(). Sebaliknya, penyiapan yang lebih baru (pandas 3.0 dan yang lebih baru serta PyArrow 19.0 dan yang lebih baru) menggunakan representasi pa.json_(pa.string()) yang lebih baru.

timedelta

Jenis timedelta tidak memiliki padanan langsung dalam sistem jenis native BigQuery. Untuk mengelola data durasi, BigQuery DataFrames menggunakan jenis INT64 sebagai format penyimpanan pokok dalam tabel BigQuery. Anda dapat mengharapkan hasil komputasi Anda konsisten dengan perilaku yang Anda harapkan dari operasi yang setara yang dilakukan dengan library pandas.

Anda dapat langsung memuat nilai timedelta ke objek DataFrame BigQuery dan Series, seperti yang ditunjukkan dalam contoh berikut:

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]

Tidak seperti pandas, BigQuery DataFrames hanya mendukung nilai timedelta dengan presisi mikrodetik. Jika data Anda mencakup nanodetik, Anda harus membulatkannya untuk menghindari potensi pengecualian, seperti yang ditunjukkan dalam contoh berikut:

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]

Anda dapat menggunakan fungsi bigframes.pandas.to_timedelta untuk mentransmisikan objek Series BigQuery DataFrames ke jenis timedelta, seperti yang ditunjukkan dalam contoh berikut:

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]

Saat Anda memuat data yang berisi nilai timedelta ke tabel BigQuery, nilai tersebut akan dikonversi menjadi mikrodetik dan disimpan dalam kolom INT64. Untuk mempertahankan informasi jenis, BigQuery DataFrames menambahkan string #microseconds ke deskripsi kolom ini. Beberapa operasi, seperti eksekusi kueri SQL dan pemanggilan UDF, tidak mempertahankan deskripsi kolom, dan informasi jenis timedelta akan hilang setelah operasi ini selesai.

Alat untuk jenis komposit

Untuk jenis komposit tertentu, BigQuery DataFrames menyediakan alat yang memungkinkan Anda mengakses dan memproses nilai elemen dalam jenis tersebut.

Pengakses daftar

Objek ListAccessor dapat membantu Anda melakukan operasi pada setiap elemen daftar dengan menggunakan properti daftar objek Series, seperti yang ditunjukkan dalam contoh berikut:

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

Pengakses struct

Objek StructAccessor dapat mengakses dan memproses kolom dalam serangkaian struct. Objek akses API adalah series.struct, seperti yang ditunjukkan dalam contoh berikut:

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

Jika kolom struct yang ingin Anda akses tidak ambigu dari properti Series lain, Anda dapat melewati panggilan struct, seperti yang ditunjukkan dalam contoh berikut:

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

Namun, praktik terbaiknya adalah menggunakan struct untuk mengakses kolom, karena kode Anda akan lebih mudah dipahami dan tidak rentan terhadap error.

Pengakses string

Anda dapat mengakses objek StringAccessor dengan properti str pada objek Series, seperti yang ditunjukkan dalam contoh berikut:

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

Pengakses geografi

BigQuery DataFrames menyediakan objek GeographyAccessor yang memiliki API serupa dengan struktur GeoSeries yang disediakan oleh library GeoPandas. Anda dapat memanggil objek GeographyAccessor dengan properti geo pada objek Series seperti yang ditunjukkan dalam contoh berikut:

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

Langkah berikutnya