הפניה למשתני מערכת

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

שם	סוג	קריאה וכתיבה או קריאה בלבד	תיאור
@@current_job_id	STRING	קריאה-בלבד	מזהה המשימה שמתבצעת כרגע. בהקשר של שאילתה עם כמה הצהרות, הפונקציה מחזירה את המשימה שאחראית להצהרה הנוכחית, ולא את כל השאילתה עם כמה ההצהרות.
@@dataset_id	STRING	קריאה וכתיבה	המזהה של מערך הנתונים שמוגדר כברירת מחדל בפרויקט הנוכחי. המזהה הזה משמש כשלא מצוין בשאילתה מערך נתונים לפרויקט. אפשר להשתמש בהצהרה SET כדי להקצות את @@dataset_id למזהה של מערך נתונים אחר בפרויקט הנוכחי. אפשר להגדיר את משתני המערכת @@dataset_project_id ו-@@dataset_id ולהשתמש בהם ביחד.
@@dataset_project_id	STRING	קריאה וכתיבה	המזהה של פרויקט ברירת המחדל שמשמש כשלא צוין פרויקט למערך נתונים שמשמש בשאילתה. אם לא מגדירים את @@dataset_project_id או אם מגדירים אותו ל-NULL, המערכת משתמשת בפרויקט שמריץ את השאילתה (@@project_id). אפשר להשתמש בהצהרה SET כדי להקצות את @@dataset_project_id למזהה פרויקט אחר. אפשר להגדיר את משתני המערכת @@dataset_project_id ו-@@dataset_id ולהשתמש בהם ביחד.
@@last_job_id	STRING	קריאה-בלבד	מזהה המשימה של המשימה האחרונה שבוצעה בשאילתה הנוכחית עם כמה הצהרות, לא כולל המשימה הנוכחית. אם השאילתה עם כמה הצהרות מכילה הצהרות CALL, יכול להיות שהמשימה הזו נוצרה בפרוצדורה אחרת.
@@location	STRING	קריאה וכתיבה	המיקום שבו השאילתה תרוץ. אפשר להגדיר את @@location רק כמחרוזת מילולית עם מיקום תקין. הצהרת SET @@location חייבת להיות ההצהרה הראשונה בשאילתה. אם יש חוסר התאמה בין @@location לבין הגדרת מיקום אחרת של השאילתה, תופיע שגיאה. כדי לשפר את זמן האחזור של שאילתות שמוגדר בהן @@location, אפשר להשתמש במצב יצירה אופציונלית של משימות. אפשר להשתמש במשתנה המערכת @@location בתוך פונקציות UDF ב-SQL ופונקציות טבלה.
@@max_staleness_override	INTERVAL	קריאה וכתיבה	מבטל את מרווח הזמן המקסימלי של חוסר עדכניות לכל הישויות הרלוונטיות שנשלחו לגביהן שאילתות במסגרת השאילתה הנוכחית עם כמה הצהרות או במסגרת הסשן הנוכחי. הישויות הרלוונטיות כוללות טבלאות בסטרימינג, טבלאות של סימון נתונים שהשתנו (CDC) ותצוגות מהותיות) שנשלחה אליהן שאילתה בתוך השאילתה הנוכחית עם כמה הצהרות או בסשן הנוכחי. כברירת מחדל, בכל פעם שמריצים שאילתה, BigQuery מחזיר את התוצאות העדכניות ביותר או מכבד את האפשרות max_staleness שהוגדרה לישות. אפשר להשתמש ב-@@max_staleness_override כדי להתאים אישית באופן דינמי את ההתנהגות של נתונים לא עדכניים, בלי לשנות את ההגדרות של הטבלה או התצוגה: הפחתת זמן האחזור והעלויות של השאילתות: כדי לאפשר נתונים לא עדכניים, מגדירים את @@max_staleness_override למרווח לא שלילי – לדוגמה, INTERVAL 10 MINUTE. כדי לוודא שהתוצאות מעודכנות לחלוטין: כדי לאלץ החלה של שינויים או רענונים בהמתנה בזמן הרצת השאילתה, מגדירים את @@max_staleness_override לערך INTERVAL 0 SECOND. ביטול ההחרגה: כדי לחזור להגדרות של max_staleness ברמת הישות, מגדירים את @@max_staleness_override כ-NULL.
@@project_id	STRING	קריאה-בלבד	מזהה הפרויקט ששימש להרצת השאילתה הנוכחית. בהקשר של פרוצדורה, @@project_id מתייחס לפרויקט שמריץ את השאילתה עם כמה הצהרות, ולא לפרויקט שבבעלותו הפרוצדורה.
@@query_label	STRING	קריאה וכתיבה	תווית השאילתה שרוצים לשייך למשימות השאילתה בשאילתה הנוכחית עם כמה הצהרות או בסשן הנוכחי. אם מגדירים את התווית בשאילתה, היא תופיע בכל משימות השאילתה הבאות בסקריפט או בסשן. אם לא מגדירים את משתנה המערכת הזה בשאילתה, הערך שלו הוא NULL. דוגמה להגדרה של משתנה המערכת הזה מופיעה במאמר שיוך משימות בסשן לתווית.
@@reservation	STRING	קריאה וכתיבה	מאפשר לציין או לשנות את ההזמנה שבה משתמשים כדי להריץ את ההצהרות הבאות. צריך להשתמש בפורמט הבא: projects/project_id/locations/location/reservations/reservation_id. מאלצת את השאילתה להשתמש בחיוב על פי דרישה כשהיא מוגדרת ל-'none'. לשם כך, צריך להגדיר את reservation_override_mode של הפרויקט או הארגון לערך ALLOW_ANY_OVERRIDE. אפשר להגדיר את הערך הזה באמצעות הצהרות ALTER PROJECT SET OPTIONS או ALTER ORGANIZATION SET OPTIONS. אם נתקלתם בבעיות, אתם יכולים לבקש תמיכה. המיקום של ההזמנה חייב להתאים למיקום שבו השאילתה פועלת. אם הערך של @@reservation הוא NULL, המקום השמור מזוהה באופן אוטומטי על סמך הגדרות ההקצאה שתואמות למאפייני השאילתה.
@@row_count	INT64	קריאה-בלבד	אם משתמשים בשאילתה עם כמה פקודות והפקודה הקודמת היא DML, מציין את מספר השורות שנוספו, שונו או נמחקו כתוצאה מאותה פקודת DML. אם ההצהרה הקודמת היא הצהרת `MERGE`, הערך של @@row_count מייצג את המספר הכולל של השורות שנוספו, שונו ונמחקו. הערך הזה הוא NULL אם לא מדובר בשאילתה עם כמה הצהרות.
@@script.bytes_billed	INT64	קריאה-בלבד	מספר הבייטים הכולל שחויבו עד עכשיו במשימת השאילתה מרובת ההצהרות שפועלת כרגע. הערך הזה הוא NULL אם הוא לא במשימה.
@@script.bytes_processed	INT64	קריאה-בלבד	סך כל הבייטים שעובדו עד עכשיו במשימת השאילתה מרובת ההצהרות שפועלת כרגע. הערך הזה הוא NULL אם הוא לא במשימה.
@@script.creation_time	TIMESTAMP	קריאה-בלבד	זמן היצירה של משימת השאילתה עם מספר ההצהרות שפועלת כרגע. הערך הזה הוא NULL אם הוא לא במשימה.
@@script.job_id	STRING	קריאה-בלבד	מזהה המשימה של משימת השאילתה עם כמה הצהרות שפועלת כרגע. הערך הזה הוא NULL אם הוא לא במשימה.
@@script.num_child_jobs	INT64	קריאה-בלבד	מספר המשימות הצאצא שהושלמו כרגע. הערך הזה הוא NULL אם הוא לא במשימה.
@@script.slot_ms	INT64	קריאה-בלבד	מספר אלפיות השנייה של משבצות שנוצלו עד עכשיו על ידי הסקריפט. הערך הזה הוא NULL אם הוא לא במשימה.
@@session_id	STRING	קריאה-בלבד	מזהה הסשן שהשאילתה הנוכחית משויכת אליו. אפשר להשתמש במשתנה המערכת @@session_id בפונקציות SQL בהגדרת המשתמש, בפונקציות טבלה ובתצוגות לוגיות. אי אפשר להשתמש במשתנה המערכת הזה בתצוגות מהותיות.
@@time_zone	STRING	קריאה וכתיבה	אזור הזמן שמוגדר כברירת מחדל לשימוש בפונקציות SQL שתלויות באזור זמן, כשלא מצוין אזור זמן כארגומנט. אפשר לשנות את @@time_zone באמצעות הצהרת SET לכל שם חוקי של אזור זמן. בתחילת כל סקריפט, @@time_zone מתחיל בתור "UTC".

כדי לשמור על תאימות לדורות קודמים, ביטויים שמשתמשים בהם בסעיף OPTIONS או FOR SYSTEM TIME AS OF מוגדרים כברירת מחדל לאזור הזמן America/Los_Angeles, וכל שאר הביטויים של תאריך/שעה מוגדרים כברירת מחדל לאזור הזמן UTC. אם @@time_zone הוגדר מוקדם יותר בשאילתה עם כמה הצהרות, אזור הזמן שנבחר יחול על כל הביטויים של התאריך/השעה, כולל משפטי OPTIONS ו-FOR SYSTEM TIME AS OF.

בנוסף למשתני המערכת שהוצגו קודם, אתם יכולים להשתמש במשתני המערכת של EXCEPTION במהלך ביצוע של שאילתה עם כמה הצהרות. למידע נוסף על משתני המערכת של EXCEPTION, קראו את ההצהרה של השפה הפרוצדורלית BEGIN...EXCEPTION.

דוגמאות

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

SET @@dataset_project_id = 'MyProject';

בדוגמה הבאה, מרווח הזמן המקסימלי של חוסר עדכניות לשאילתות הבאות בסשן מוגדר ל-10 דקות:

SET @@max_staleness_override = INTERVAL 10 MINUTE;

כדי לאלץ את השאילתות להחזיר את התוצאות העדכניות ביותר ולהחיל שינויים בהמתנה בזמן הרצת השאילתה:

SET @@max_staleness_override = INTERVAL 0 SECOND;

כדי לאפס את ההגדרה של ביטול ההתיישנות בחזרה להגדרות ברמת הטבלה, מגדירים את @@max_staleness_override לערך NULL:

SET @@max_staleness_override = NULL;

השאילתה הבאה מחזירה את אזור הזמן שמוגדר כברירת מחדל:

SELECT @@time_zone AS default_time_zone;

+-------------------+
| default_time_zone |
+-------------------+
| UTC               |
+-------------------+

אפשר להשתמש במשתני מערכת עם שאילתות DDL ו-DML. לדוגמה, הנה כמה דרכים להשתמש במשתנה המערכת @@time_zone כשיוצרים ומעדכנים טבלה:

BEGIN
  CREATE TEMP TABLE MyTempTable
  AS SELECT @@time_zone AS default_time_zone;
END;

CREATE OR REPLACE TABLE MyDataset.MyTable(default_time_zone STRING)
  OPTIONS (description = @@time_zone);

UPDATE MyDataset.MyTable
SET default_time_zone = @@time_zone
WHERE TRUE;

יש מקומות שבהם אי אפשר להשתמש במשתני מערכת בשאילתות DDL ו-DML. לדוגמה, אי אפשר להשתמש במשתנה מערכת בתור שם של פרויקט, קבוצת נתונים או טבלה. השאילתה הבאה גורמת לשגיאה כשכוללים את משתנה המערכת @@dataset_id בנתיב של טבלה:

BEGIN
  CREATE TEMP TABLE @@dataset_id.MyTempTable (id STRING);
END;

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

בסשן לדוגמה תוכלו לראות דוגמאות לשימוש במשתני מערכת בסשנים.