התאמה אישית של פונקציות Python ל-BigQuery DataFrames

התאמה אישית של פונקציות Python ל-BigQuery DataFrames מאפשרת להפוך את הקוד לאובייקטים של BigQuery שניתנים להתאמה לעומס, כמו פונקציות בהגדרת המשתמש (UDF) או פונקציות מרוחקות. אתם יכולים לפרוס את הפונקציות המותאמות אישית האלה כדי להשתמש בספריות קוד פתוח ולבצע פעולות שמעבר ליכולות של ממשקי API של SQL סטנדרטי.

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות לביצוע המשימות שמפורטות במאמר הזה, בקשו מהאדמין לתת לכם את התפקידים הבאים ב-IAM ברמת הפרויקט:

• עריכה של נתוני BigQuery (roles/bigquery.dataEditor)
• אדמין של חיבור BigQuery ‏ (roles/bigquery.connectionAdmin)
• מפתח Cloud Functions ‏ (roles/cloudfunctions.developer)
• משתמש בחשבון שירות (roles/iam.serviceAccountUser)
• צפייה באובייקטים באחסון (roles/storage.objectViewer)

להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.

פונקציות בהגדרת המשתמש (UDF)

באמצעות פונקציות בהגדרת המשתמש (גרסת טרום-השקה (Preview)), אתם יכולים להפוך את פונקציית Python בהתאמה אישית לפונקציית Python בהגדרת המשתמש. במאמר יצירת פונקציית UDF קבועה ב-Python מופיעה דוגמה לשימוש.

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

דרישות

כדי להשתמש ב-UDF של BigQuery DataFrames, צריך להפעיל את BigQuery API בפרויקט. אם אתם מספקים את הפרמטר bigquery_connection בפרויקט, אתם צריכים להפעיל גם את BigQuery Connection API.

הסרת המשאבים

בנוסף לניקוי פריטי המידע שנוצרו בענן ישירות במסוף Google Cloud או באמצעות כלים אחרים, אתם יכולים לנקות את פונקציות ה-UDF של BigQuery DataFrames שנוצרו עם ארגומנט שם מפורש באמצעות הפקודה bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

מגבלות

• הקוד ב-UDF חייב להיות עצמאי, כלומר הוא לא יכול להכיל הפניות לייבוא או למשתנה שמוגדרים מחוץ לגוף הפונקציה.
• הקוד ב-UDF חייב להיות תואם ל-Python 3.11, כי זו הסביבה שבה הקוד מופעל בענן.
• אם מריצים מחדש את קוד ההגדרה של ה-UDF אחרי שינויים קלים בקוד הפונקציה (למשל, שינוי שם של משתנה או הוספת שורה חדשה), ה-UDF נוצר מחדש, גם אם השינויים האלה לא משפיעים על ההתנהגות של הפונקציה.
• קוד המשתמש גלוי למשתמשים עם גישת קריאה לשגרות של BigQuery, לכן צריך לכלול תוכן רגיש רק בזהירות.
• בכל פרויקט יכולות להיות עד 1,000 פונקציות Cloud Run בו-זמנית במיקום של BigQuery.

הפונקציה המוגדרת על ידי המשתמש (UDF) של BigQuery DataFrames פורסת פונקציית Python של BigQuery שמוגדרת על ידי המשתמש, וחלות עליה המגבלות הרלוונטיות.

פונקציות משירותים חיצוניים

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

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

• פונקציית Cloud Run.

• חיבור ל-BigQuery.

  כברירת מחדל, המערכת משתמשת בחיבור בשם bigframes-default-connection. אם אתם מעדיפים, אתם יכולים להשתמש בחיבור מוגדר מראש ל-BigQuery, ובמקרה כזה אפשר לדלג על יצירת החיבור. לחשבון השירות של החיבור שמוגדר כברירת מחדל מוקצה התפקיד של Cloud Run (roles/run.invoker).

• פונקציה מרוחקת של BigQuery שמשתמשת בפונקציית Cloud Run שנוצרה באמצעות החיבור ל-BigQuery.

דרישות

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

• BigQuery API (bigquery.googleapis.com)
• BigQuery Connection API (bigqueryconnection.googleapis.com)
• Cloud Functions API (cloudfunctions.googleapis.com)
• Cloud Run Admin API (run.googleapis.com)‎
• ‫Artifact Registry API ‏ (artifactregistry.googleapis.com)
• Cloud Build API (cloudbuild.googleapis.com)
• Compute Engine API (compute.googleapis.com)
• Cloud Resource Manager API (cloudresourcemanager.googleapis.com)

כשמשתמשים בפונקציות מרוחקות של BigQuery DataFrames, צריך את התפקיד "אדמין IAM בפרויקט" (roles/resourcemanager.projectIamAdmin) אם משתמשים בחיבור ברירת המחדל של BigQuery, או את התפקיד "דפדפן" (roles/browser) אם משתמשים בחיבור שהוגדר מראש. כדי להימנע מהדרישה הזו, אפשר להגדיר את האפשרות bigframes.pandas.options.bigquery.skip_bq_connection_check לערך True. במקרה כזה, החיבור (ברירת המחדל או החיבור שהוגדר מראש) משמש כמו שהוא, בלי בדיקת קיום או הרשאות. אם אתם משתמשים בחיבור שהוגדר מראש ומדלגים על בדיקת החיבור, ודאו ש:

• החיבור נוצר במיקום הנכון.
• אם אתם משתמשים בפונקציות מרוחקות של BigQuery DataFrames, לחשבון השירות יש את התפקיד Cloud Run Invoker (roles/run.invoker) בפרויקט.

איך רואים ומנהלים את החיבורים

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

1. נכנסים לדף BigQuery במסוף Google Cloud .

   כניסה ל-BigQuery

2. בוחרים את הפרויקט שבו יצרתם את הפונקציה המרוחקת.

3. בחלונית השמאלית, לוחצים על Explorer:

   

4. בחלונית Explorer, מרחיבים את הפרויקט ולוחצים על Connections.

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

1. נכנסים לדף BigQuery במסוף Google Cloud .

   כניסה ל-BigQuery

2. בוחרים את הפרויקט שבו יצרתם את הפונקציה המרוחקת.

3. בחלונית השמאלית, לוחצים על Explorer:

   

4. בחלונית Explorer, מרחיבים את הפרויקט ולוחצים על Datasets.

5. לוחצים על מערך הנתונים שבו יצרתם את הפונקציה המרוחקת.

6. לוחצים על הכרטיסייה תרחישים.

כדי לראות ולנהל את פונקציות Cloud Run:

1. נכנסים לדף Cloud Run.

   כניסה ל-Cloud Run

2. בוחרים את הפרויקט שבו יצרתם את הפונקציה.

3. ברשימת השירותים הזמינים, מסננים לפי Function Deployment type.

4. כדי לזהות פונקציות שנוצרו על ידי BigQuery DataFrames, חפשו שמות של פונקציות עם הקידומת bigframes.

הסרת המשאבים

בנוסף לניקוי פריטי המידע שנוצרו בענן ישירות במסוף Google Cloud או באמצעות כלים אחרים, אתם יכולים לנקות את הפונקציות המרוחקות של BigQuery שנוצרו בלי ארגומנט שם מפורש, ואת פונקציות Cloud Run שמשויכות אליהן, בדרכים הבאות:

• בסשן של BigQuery DataFrames, משתמשים בפקודה session.close().
• כדי להשתמש בסשן ברירת המחדל של BigQuery DataFrames, משתמשים בפקודה bigframes.pandas.close_session().
• כדי להציג סשן קודם עם session_id, משתמשים בפקודה bigframes.pandas.clean_up_by_session_id(session_id).

אפשר גם לנקות את הפונקציות המרוחקות של BigQuery שנוצרו עם ארגומנט שם מפורש, ואת פונקציות Cloud Run שמשויכות אליהן, באמצעות הפקודה bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

מגבלות

• כשיוצרים פונקציות מרוחקות בפעם הראשונה, אפשר להשתמש בהן אחרי כ-90 שניות. יחסי תלות נוספים של חבילות עשויים להגדיל את זמן האחזור.
• אם תריצו מחדש את קוד ההגדרה של הפונקציה המרוחקת אחרי שינויים קלים בקוד הפונקציה או בסביבה שלה (למשל, שינוי שם של משתנה, הוספת שורה חדשה או הוספת תא חדש ב-notebook), יכול להיות שהפונקציה המרוחקת תיווצר מחדש, גם אם השינויים האלה לא משפיעים על ההתנהגות של הפונקציה.
• קוד המשתמש גלוי למשתמשים עם גישת קריאה לפונקציות Cloud Run, לכן צריך להיזהר כשכוללים תוכן רגיש.
• בכל פרויקט יכולות להיות עד 1,000 פונקציות Cloud Run בו-זמנית באזור מסוים. מידע נוסף זמין במאמר מכסות.

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

• מידע על יכולות למידת מכונה ו-AI באמצעות BigQuery DataFrames.
• איך יוצרים קוד של BigQuery DataFrames באמצעות Gemini
• איך מנתחים הורדות של חבילות מ-PyPI באמצעות BigQuery DataFrames
• ב-GitHub אפשר לראות את קוד המקור, דוגמאות ל-notebooks ודוגמאות ל-BigQuery DataFrames.
• מאמרי העזרה של BigQuery DataFrames API