קריאה מ-BigQuery

בדף הזה מוסבר איך לשלב טבלאות של BigQuery בתהליכי עבודה של Earth Engine כאובייקטים של ee.FeatureCollection, באמצעות השיטות ee.FeatureCollection.loadBigQueryTable() ו-ee.FeatureCollection.runBigQuery().

טעינת נתונים מ-BigQuery

הפונקציה ee.FeatureCollection.loadBigQueryTable() קוראת בצורה חלקה טבלה של BigQuery לתוך אובייקט ee.FeatureCollection. הוא מתחבר לטבלה שצוינה, ממיר את כל סוגי הנתונים, מחיל את המסננים והבוררים הנדרשים ומוסיף אינדקס לאוסף אם צריך. הפונקציה משתמשת בסביבה האינטראקטיבית של Earth Engine ומחזירה תוצאות ישירות ללקוח לצפייה או לשימוש כרכיב בניתוח גדול יותר.

JavaScript

// Load the BigQuery table with a specified geometry column.
var features = ee.FeatureCollection.loadBigQueryTable({
  table: 'my_project.my_dataset.my_table',
  geometryColumn: 'geo'
});

// Display features on the map.
Map.addLayer(features);

Python

# Load the BigQuery table with a specified geometry column.
features = ee.FeatureCollection.loadBigQueryTable(
    table='my_project.my_dataset.my_table',
    geometryColumn='geo')

# Display the first feature.
display(features.first().getInfo())

חיוב

העלות של שעות EECU שנעשה בהן שימוש במהלך העיבוד של הבקשה מחויבת למתקשר, כמו בכל שיטה אחרת של Earth Engine (ראו סקירה כללית על EECU).

העברת הנתונים אל Earth Engine לא כרוכה בתוספת תשלום ב-BigQuery. השימוש המקביל ב-BigQuery יוצג בלוח הבקרה של Google Cloud API של הפרויקט שבו נעשה שימוש (ראו מעקב אחר השימוש ב-API), אבל לא תחויבו על קריאת נתונים מ-BigQuery בדרך הזו.

שאילתת נתונים מ-BigQuery

השיטה ee.FeatureCollection.runBigQuery() מריצה שאילתת SQL ב-BigQuery ומחזירה את התוצאות כאובייקט ee.FeatureCollection (מידע נוסף על שאילתות זמין במאמר הרצת שאילתה).

JavaScript

// Construct a BigQuery query.
var query = 'SELECT * FROM my_project.my_dataset.my_table WHERE column > 1000';

// Run the query and return the results as a FeatureCollection.
var features = ee.FeatureCollection.runBigQuery(query);

// Print the first feature.
print(features.first());

Python

# Construct a BigQuery query.
query = 'SELECT * FROM my_project.my_dataset.my_table WHERE column > 1000'

# Run the query and retrieve the results as a FeatureCollection.
features = ee.FeatureCollection.runBigQuery(query)

# Print the first feature.
print(features.first().getInfo())

שאילתות BigQuery

כל קריאה ל-ee.FeatureCollection.runBigQuery() יוצרת משימת שאילתה נפרדת ב-BigQuery (מידע נוסף על שאילתות זמין במאמר הרצת שאילתה), ומאפשרת לכם להשתמש ביכולות המרכזיות של BigQuery:

  • היסטוריית משרות: גישה להיסטוריה של ביצועי השאילתות בפרויקט שלכם במשך שישה חודשים (מידע נוסף זמין במאמר List jobs).
  • שמירת תוצאות שאילתות במטמון: מערכת BigQuery שומרת תוצאות של שאילתות במטמון באופן אוטומטי, כשזה אפשרי. שאילתות זהות חוזרות מאחזרות נתונים מהמטמון, וכך נמנעים חיובים מיותרים (מידע נוסף על שימוש בתוצאות של שאילתות שנשמרו במטמון)

מידע על שאילתות או על אופן השימוש בהן ב-BigQuery זמין במסמכי BigQuery.

חיוב

העלות של יחידות EECU שנעשה בהן שימוש במהלך עיבוד הבקשה מחויבת למבצע השיחה כמו בכל שיטה אחרת של Earth Engine (ראו סקירה כללית על יחידות EECU). בנוסף, הפעלת שאילתה כרוכה בחיוב של המתקשר בהתאם למודל החיוב של BigQuery.

העברת הנתונים אל Earth Engine לא כרוכה בתוספת תשלום ב-BigQuery. השימוש המקביל ב-BigQuery יוצג בלוח הבקרה של Google Cloud API של הפרויקט שבו נעשה שימוש (ראו מעקב אחר השימוש ב-API), אבל לא תחויבו על קריאת נתונים מ-BigQuery בדרך הזו.

כדי לשלוט בעלויות פוטנציאליות שקשורות ל-ee.FeatureCollection.runBigQuery(), הפרמטר maxBytesBilled משמש כאמצעי הגנה. כל עבודה ב-BigQuery שחורגת מהמגבלה הזו תיכשל ולא יחויב עליה תשלום. ערך ברירת המחדל של maxBytesBilled הוא 100GB. אם השיחה שלכם נחסמת בגלל חריגה מהמגבלה הזו, אתם יכולים לציין ערך אחר בסקריפט.

דרישות מוקדמות והרשאות

כדי להשתמש בתכונה הזו, צריך להפעיל את BigQuery API ואת BigQuery Storage API בפרויקט Cloud של המתקשר. פועלים לפי ההוראות בדף Enable API (הפעלת ה-API) כדי להפעיל את ממשקי ה-API המתאימים.

בנוסף לתפקידים ולהרשאות הרגילים של Earth Engine, צריך שתהיה לכם הרשאת קריאה בטבלת BigQuery שאליה מתבצעת ההפניה, והרשאה ליצור סשנים של קריאה ועבודות בפרויקט היעד. ההרשאות הספציפיות שנדרשות ב-BigQuery הן:

  • bigquery.tables.get (בכל טבלה שאליה יש גישה)
  • bigquery.tables.getData (בכל טבלה שאליה יש גישה)
  • bigquery.readSession.create
  • bigquery.jobs.create

מידע מפורט על ניהול הרשאות זמין במאמרי העזרה בנושא בקרת גישה ב-BigQuery.

סינון נתונים

אפשר לסנן כל ee.FeatureCollection באמצעות השיטה .filter(Filter). כדי לאפשר למשתמשים ב-Google Earth Engine ליהנות מעיבוד מקביל מאוד של נתונים טבלאיים ב-BigQuery, אנחנו מתרגמים את המסננים של Earth Engine לשפה שמובנת על ידי BigQuery ושולחים אותם יחד עם בקשה לקריאת טבלה. הגישה הזו אכן מעבירה את עיבוד המסננים ל-BigQuery stack, אבל היא כפופה גם לשתי מגבלות:

  1. בדומה לכל שאילתה אחרת ב-BigQuery (ראו מכסות ב-BigQuery), הבקשה הזו מוגבלת לגודל של 10MB. המשמעות היא שהמסננים שעוברים לא יכולים להיות מסובכים מדי. חריגה מהמגבלה של 10MB תוביל לשגיאה הבאה:

    Filter sent to BigQuery is too long. This error may be caused by too complicated geometry in geometry filters. Consider simplifying the filter and used values.

    סינון לפי צורות גיאומטריות שמכילות הרבה קודקודים הוא סיבה נפוצה לשגיאה הזו. כדי לפתור את הבעיה הזו, כדאי להשתמש ב-ee.Geometry.simplify() באובייקט הבעייתי.

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

הוספת נתונים לאינדקס

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

  • אם טבלת BigQuery מכילה עמודה בשם system:index, אנחנו משתמשים בה כדי ליצור אינדקס ל-FeatureCollection.

    במקרים כאלה, המתקשר צריך לוודא שהאינדקסים ייחודיים. אחרת, יכול להיות שהקולקציה תתנהג בצורה לא צפויה. אינדקס הפיצ'ר חייב להיות מחרוזת לא ריקה, ולכן טעינה של טבלת BigQuery עם ערך שאינו מחרוזת או nullעבור עמודה system:index תיכשל.

  • אם הטבלה ב-BigQuery לא מכילה את העמודה system:index, היא נוצרת באופן אוטומטי.

    האינדקסים בין שתי בקשות קריאה הם יציבים, אבל רק אם הבקשות זהות לחלוטין, כולל המסננים. אחרת, לא נוכל להסתמך על כך שהאינדקסים מתאימים לאותן תכונות. לכן, אם חשוב למתקשר לבצע אינדוקס של נתונים ייחודיים באופן מדויק, מומלץ להוסיף את העמודה system:index ב-BigQuery באופן ידני.

מגבלות

  • הגודל של כל העמודות שנבחרו בטבלה שאליה מתבצעת הפניה בקריאה ee.FeatureCollection.loadBigQueryTable() מוגבל ל-400GB. חריגה מהמגבלה הזו תגרום לשגיאה הבאה:

    Failed to read table from BigQuery: Requested data size is too large to read. Consider using selectors to specify only required columns.

    במקרים כאלה, כדאי לבחור סלקטורים מגבילים יותר כדי לקרוא רק את העמודות הנדרשות, או להשתמש ב-ee.FeatureCollection.runBigQuery() כדי לבצע עיבוד מקדים של הטבלה ב-BigQuery ולהקטין את כמות הנתונים שאוחזרו.

  • בשיטה ee.FeatureCollection.runBigQuery() יש מגבלה של 10GB על גודל תוצאות השאילתה. אף על פי שגודל טבלאות המקור יכול להיות שרירותי, עיבוד של נפחי נתונים גדולים יותר יגדיל את עלויות השאילתות.

  • גודל המסנן המתורגם מוגבל ל-10MB. פרטים נוספים זמינים בקטע סינון נתונים.

  • אי אפשר להשתמש ב-ee.FeatureCollection.loadBigQueryTable() או ב-ee.FeatureCollection.runBigQuery() באפליקציות של Earth Engine.

נקודות שצריך לשים לב אליהן:

  • הפונקציה ee.FeatureCollection.loadBigQueryTable() לא תומכת במשאבים ממערכי נתונים מקושרים. ניסיון לטעון נתונים מטבלה כזו יוביל לשגיאה 'הטבלה לא נמצאה'.

    כפתרון עקיף, אפשר להריץ את ee.FeatureCollection.runBigQuery() עם שאילתה שמציינת את הטבלה המבוקשת ממערך הנתונים המקושר. לדוגמה:

    JavaScript

    var features = ee.FeatureCollection.runBigQuery({
  query: 'SELECT * FROM my_project.my_linked_dataset.my_table',
  geometryColumn: 'geo'
});

    Python

    features = ee.FeatureCollection.runBigQuery(
  query='SELECT * FROM my_project.my_linked_dataset.my_table',
  geometryColumn='geo')

  • ביצוע הצטרפות ב-system:index לטבלאות BigQuery עם מזהים שנוצרו אוטומטית עלול להוביל להתנהגויות לא צפויות. כדי למנוע את המצב הזה, כדאי להוסיף system:index לטבלת BigQuery באופן ידני או לצרף את הטבלה לנכס אחר. מידע נוסף על הוספה לאינדקס זמין בקטע הוספת נתונים לאינדקס.

  • השיטה ee.FeatureCollection.randomColumn() לא פועלת עם מזהים שנוצרו אוטומטית ב-BigQuery. כדאי לציין מפתח חלופי באמצעות הפרמטר rowKeys בשיטה ee.FeatureCollection.randomColumn(). אפשר גם להוסיף באופן ידני עמודות random או system:index לטבלת המקור ב-BigQuery. מידע נוסף על הוספה לאינדקס זמין בקטע הוספת נתונים לאינדקס.