קריאה מ-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 אחרת (ראו סקירה כללית על EECUs).

העברת הנתונים ל-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:

  • היסטוריית משימות: גישה להיסטוריה של ששת החודשים האחרונים של ביצועי השאילתות בפרויקט (מידע נוסף זמין בקטע רשימת משימות).
  • אחסון שאילתות במטמון: 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 המתאימים.

בנוסף לתפקידים וההרשאות הרגילים ב-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 ב-method‏ ee.FeatureCollection.randomColumn(). אפשר גם להוסיף עמודות random או system:index לטבלת המקור ב-BigQuery באופן ידני. מידע נוסף על הוספה לאינדקס זמין בקטע הוספת נתונים לאינדקס.