שימוש במערכת סוגי הנתונים של BigQuery DataFrames

מערכת סוגי הנתונים של BigQuery DataFrames מאפשרת לכם לעבוד עם מבני נתונים שתואמים לסוגי האחסון המובנים של BigQuery. אם תבנו את הניתוחים על סמך סוגי הנתונים האלה, תוכלו לשלב אותם בצורה חלקה ולמפות את הסוגים בצורה מהימנה במחסן הנתונים.

מיפויים של סוגים

בטבלה הבאה מוצגים סוגי נתונים מקבילים ב-BigQuery, ב-BigQuery DataFrames ובספריות אחרות של Python, וגם רמות התמיכה שלהם:

סוג נתונים BigQuery BigQuery DataFrames מובנה ב-Python PyArrow
בוליאני BOOL pandas.BooleanDtype() bool bool_()
מספר שלם INT64 pandas.Int64Dtype() int int64()
Float FLOAT64 pandas.Float64Dtype() float float64()
String STRING pandas.StringDtype(storage="pyarrow") str string()
בייטים BYTES pandas.ArrowDtype(pyarrow.binary()) bytes binary()
תאריך DATE pandas.ArrowDtype(pyarrow.date32()) datetime.date date32()
שעה TIME pandas.ArrowDtype(pyarrow.time64("us")) datetime.time time64("us")
תאריך ושעה DATETIME pandas.ArrowDtype(pyarrow.timestamp("us")) datetime.datetime timestamp("us")
חותמת הזמן TIMESTAMP pandas.ArrowDtype(pyarrow.timestamp("us", tz="UTC")) ‫Datetime.datetime עם אזור זמן timestamp("us", tz="UTC")
Numeric NUMERIC pandas.ArrowDtype(pyarrow.decimal128(38, 9)) decimal.Decimal decimal128(38, 9)
מספר גדול BIGNUMERIC pandas.ArrowDtype(pyarrow.decimal256(76, 38)) decimal.Decimal decimal256(76, 38)
List<T>‎ 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()) ב-pandas מגרסה 3.0 ואילך וב-PyArrow מגרסה 19.0 ואילך. אחרת, עמודות JSON מוצגות בתור pandas.ArrowDtype(db_dtypes.JSONArrowType()). התכונה הזו נמצאת בגרסת טרום-השקה (Preview). לא נתמך json_() (תצוגה מקדימה)
גיאוגרפיה GEOGRAPHY Geopandas.array.GeometryDtype()
נתמך רק על ידי to_pandas().		 לא נתמך לא נתמך
Timedelta לא נתמך pandas.ArrowDtype(pyarrow.duration("us")) datetime.timedelta duration("us")

המרות סוגים

כשמשתמשים ב-BigQuery DataFrames עם נתונים מחנויות מקומיות, המערכת ממירה את סוגי הנתונים לסוגים המקבילים ב-BigQuery DataFrames בכל מקום שבו מוגדר מיפוי סוגים, כמו בדוגמה הבאה:

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 קובע את ההתנהגות כשיש פערים בין סוגי הנתונים המקבילים. במקרים נדירים שבהם הסוג המובנה של Python פועל באופן שונה מהמקביל שלו ב-PyArrow, ב-BigQuery DataFrames בדרך כלל מעדיפים את ההתנהגות של PyArrow כדי להבטיח עקביות.

דוגמת הקוד הבאה משתמשת בפעולה datetime.date + timedelta כדי להראות שבניגוד לספריית datetime של Python שעדיין מחזירה מופע של תאריך, BigQuery DataFrames פועל לפי ההתנהגות של PyArrow ומחזיר מופע של חותמת זמן:

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]

סוגים מיוחדים

בקטעים הבאים מתוארים סוגי הנתונים המיוחדים שבהם משתמשים ב-BigQuery DataFrames.

JSON

ב-BigQuery DataFrames, עמודות שמשתמשות בפורמט JSON של BigQuery (תקן קל) מיוצגות על ידי pandas.ArrowDtype. סוג ה-Arrow הבסיסי המדויק תלוי בגרסאות הספרייה שלכם. בסביבות ישנות יותר בדרך כלל משתמשים ב-db_dtypes.JSONArrowType() לצורך תאימות, שהוא סוג של תוסף Arrow שפועל כמעטפת קלה סביב pa.string(). לעומת זאת, בהגדרות חדשות יותר (pandas מגרסה 3.0 ואילך ו-PyArrow מגרסה 19.0 ואילך) נעשה שימוש בייצוג pa.json_(pa.string()) העדכני יותר.

timedelta

לסוג timedelta אין מקבילה ישירה במערכת הסוגים המובנית של BigQuery. כדי לנהל נתוני משך זמן, BigQuery DataFrames משתמש בסוג INT64 כפורמט האחסון הבסיסי בטבלאות ב-BigQuery. התוצאות של החישובים אמורות להיות עקביות עם ההתנהגות הצפויה מפעולות מקבילות שבוצעו באמצעות ספריית pandas.

אפשר לטעון ערכי timedelta ישירות לאובייקטים של Series ו-BigQuery DataFrames, כמו בדוגמה הבאה:

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]

בניגוד ל-pandas, ‏BigQuery DataFrames תומך רק בערכי timedelta עם דיוק של מיקרו-שניות. אם הנתונים כוללים ננו-שניות, צריך לעגל אותן כדי למנוע חריגות פוטנציאליות, כמו בדוגמה הבאה:

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]

אפשר להשתמש בפונקציה bigframes.pandas.to_timedelta כדי להמיר אובייקט Series של BigQuery DataFrames לסוג timedelta, כמו בדוגמה הבאה:

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]

כשאתם טוענים נתונים שמכילים ערכי timedelta לטבלה ב-BigQuery, הערכים מומרים למיקרו-שניות ונשמרים בעמודות INT64. כדי לשמור את פרטי הסוג, BigQuery DataFrames מוסיף את המחרוזת #microseconds לתיאורים של העמודות האלה. פעולות מסוימות, כמו הפעלות של שאילתות SQL וקריאות ל-UDF, לא שומרות את תיאורי העמודות, ופרטי הסוג timedelta אובדים אחרי שהפעולות האלה מסתיימות.

כלים לסוגים מורכבים

לסוגים מסוימים של נתונים מורכבים, BigQuery DataFrames מספק כלים שמאפשרים לגשת לערכים הבסיסיים בסוגים האלה ולעבד אותם.

רשימת ה-accessors

האובייקט ListAccessor יכול לעזור לכם לבצע פעולות בכל רכיב ברשימה באמצעות המאפיין list של האובייקט Series, כמו בדוגמה הבאה:

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

האובייקט StructAccessor יכול לגשת לשדות בסדרה של מבנים ולעבד אותם. אובייקט הגישה ל-API הוא series.struct, כמו בדוגמה הבאה:

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

אם השדה struct שאתם רוצים לגשת אליו לא משתמע לשתי פנים ממאפיינים אחרים של Series, אתם יכולים לדלג על הקריאה ל-struct, כמו בדוגמה הבאה:

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

עם זאת, השיטה המומלצת היא להשתמש ב-struct כדי לגשת לשדות, כי כך קל יותר להבין את הקוד והוא פחות נוטה לשגיאות.

‫accessor של מחרוזת

אפשר לגשת לאובייקט StringAccessor באמצעות המאפיין str באובייקט Series, כמו בדוגמה הבאה:

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 של מיקום גיאוגרפי

ב-BigQuery DataFrames יש אובייקט GeographyAccessor שמשתף ממשקי API דומים עם המבנה GeoSeries שמספקת הספרייה GeoPandas. אפשר להפעיל את האובייקט GeographyAccessor עם המאפיין geo באובייקט Series, כמו בדוגמה הבאה:

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

המאמרים הבאים