صادر کردن به BigQuery

نمای کلی

معماری محاسباتی Earth Engine برای سریع و مقیاس‌پذیر کردن محاسبات تصویر (مبتنی بر پیکسل) بهینه‌سازی شده است. BigQuery نیز به‌طور مشابه برای پردازش مقیاس‌پذیر داده‌های جدولی (بردارها) بهینه‌سازی شده است و ویژگی‌های بسیاری دارد که آن را به مکمل خوبی برای Earth Engine تبدیل می‌کند.

نمونه‌های گردش کار عبارت‌اند از:

  • انجام دادن پیوندهای بزرگ BigQuery روی داده‌های تولیدشده در Earth Engine
  • حاشیه‌نویسی داده‌های برداری با آمار برگرفته از تصاویر برای پردازش بیشتر در BigQuery
  • صادر کردن دوره‌ای داده‌ها از Earth Engine به جدول BigQuery قابل‌افزودن

اگر موارد استفاده عالی دیگری دارید، خوشحال می‌شویم درباره آن‌ها بشنویم!

مبانی BigQuery

Earth Engine در جدول‌های BigQuery می‌نویسد و همه جدول‌ها در مجموعه‌های داده قرار دارند. اگر مجموعه‌داده مشخص‌شده در BigQuery وجود نداشته باشد، صادر کردن تکالیف ناموفق خواهد بود. در مقدمه مجموعه داده‌های BigQuery بیشتر بدانید.

ایجاد مجموعه داده

مجموعه داده‌ها تعدادی گزینه زمان ایجاد دارند، ازجمله نام، منطقه ذخیره‌سازی، و رفتار انقضا (به‌همراه چندین گزینه پیشرفته‌تر دیگر).

سازوکارهای مختلفی برای ایجاد مجموعه‌داده وجود دارد، اما یک راه ساده برای شروع ازطریق کنسول Cloud است:

  1. به صفحه BigQuery در کنسول Cloud بروید.
  2. درصورت درخواست، روی «فعال کردن» کلیک کنید تا میانای برنامه‌سازی کاربردی فعال شود.
  3. از برگه «فضای کاری SQL»، روی منوِ سه‌نقطه‌ای () در کنار پروژه کلیک کنید.
  4. گزینه «ایجاد مجموعه داده» را انتخاب کنید.
  5. راهنمای پیکربندی را دنبال کنید.

برای دیدن همه گزینه‌های ایجاد و پیکربندی مجموعه داده، اسناد BigQuery را ببینید.

اجازه‌ها

علاوه‌بر نقش‌ها و اجازه‌های استاندارد موردنیاز برای استفاده از Earth Engine، فراخوانندگان به اجازه‌های BigQuery صحیح در پروژه Cloud یا مجموعه داده نیز نیاز دارند.

  • bigquery.tables.get
  • bigquery.tables.create
  • bigquery.tables.updateData
  • bigquery.tables.delete
  • bigquery.jobs.create

هرکدام از ترکیب‌های زیر از نقش‌های ازپیش تعریف‌شده «مدیریت هویت و دسترسی‌ها» (IAM) شامل اجازه‌های لازم است:

  • ‫bigquery.dataEditor به‌علاوه bigquery.jobUser
  • ‫bigquery.dataOwner به‌علاوه bigquery.jobUser
  • bigquery.user
  • bigquery.admin

قیمت‌گذاری

BigQuery سرویس پولی Google Cloud است، بنابراین برای استفاده از BigQuery، ازجمله ذخیره‌سازی و تجزیه‌وتحلیل داده‌های Earth Engine که به BigQuery صادر می‌کنید، هزینه‌هایی متحمل خواهید شد.

برای جزئیات قیمت‌گذاری ویژگی صادر کردن BigQuery در Earth Engine، بخش قیمت‌گذاری زیر را ببینید.

صادر کردن پیکربندی

نحو

ویرایشگر کد (جاوا اسکریپت)

Export.table.toBigQuery({
  collection: features,
  table: 'myproject.mydataset.mytable',
  description: 'put_my_data_in_bigquery',
  append: true,
  overwrite: false
});

راه‌اندازی Python

برای اطلاعات درباره Python API و استفاده از geemap برای توسعه تعاملی، به صفحه Python Environment مراجعه کنید.

import ee
import geemap.core as geemap

Colab (Python)

task = ee.batch.Export.table.toBigQuery(
    collection=features,
    table='myproject.mydataset.mytable',
    description='put_my_data_in_bigquery',
    append=True,
    overwrite=False,
)
task.start()

مشخصات طرح‌واره خودکار یا دستی

اگر جدولی در BigQuery وجود نداشته باشد، Earth Engine تلاش می‌کند بااستفاده از ویژگی‌های اولین ee.Feature در مجموعه، طرح‌واره‌ای را تعیین کند. این بهترین حدس است و ممکن است مجموعه‌ای ساخته شود که در آن طرح‌واره ویژگی اول با طرح‌واره ویژگی‌های دیگر متفاوت باشد.

اگر به طرح‌واره خاصی در جدول BigQuery نیاز دارید، آن را با ایجاد جدول خالی با طرح‌واره هدف پیکربندی کنید.

نام‌های دارایی

مشخصه‌های عارضه‌های Earth Engine با ستون‌های BigQuery مطابقت دارد. Earth Engine از نام «geo» برای نوشتن هندسه ee.Feature (انتخابگر «‎.geo») در BigQuery استفاده می‌کند.

برای جلوگیری از هرگونه تغییر نام، مطمئن شوید که اشیای ee.Feature شما دارای ویژگی‌هایی هستند که نام‌های ستون معتبر هستند و هیچ‌کدام «geo» نام‌گذاری نشده‌اند (زیرا این نام برای هندسه ویژگی استفاده می‌شود که در Earth Engine نامی ندارد).

نویسه‌های نامعتبر در نام‌های دارایی باعث می‌شود صادر کردن به‌دلیل محدودیت‌های نام‌های ستون BigQuery ناموفق باشد.

تبدیل نوع

داده‌های Earth Engine (مقادیر ویژگی‌های ee.Feature) درصورت امکان به نوع BigQuery معادل تبدیل می‌شوند. توجه داشته باشید که تهی‌پذیری توسط طرح جدول کنترل می‌شود، نه نوع.

نوع Earth Engine نوع BigQuery یادداشت‌ها
ee.String STRING
ee.Number FLOAT یا INTEGER
ee.Geometry GEOGRAPHY
ee.Date TIMESTAMP
ee.ByteString BYTES
ee.Array STRUCT<ARRAY<INT64>, ARRAY<INT64|FLOAT64>> بخش مربوط به آرایه‌ها را ببینید
انواع دیگر ee.* پشتیبانی‌نشده بخش مربوط به مقادیر JSON را ببینید

آرایه‌ها

Earth Engine هر ee.Array چندبعدی را به STRUCT<ARRAY<INT64> dimensions, ARRAY<INT64|FLOAT64> values> صادر می‌کند، مشابه قالبی که توسط تابع ML.DECODE_IMAGE در BigQuery استفاده می‌شود.

آرایه اول در ساختار، dimensions، حاوی ابعاد آرایه Earth Engine، $d_1$ تا $d_n$ است.

آرایه دوم در ساختار، values، حاوی همه مقادیر در آرایه چندبعدی است که در یک آرایه BigQuery مسطح شده است. تعداد کل مقادیر در آرایه مسطح‌شده $\sum_{i=1}^n d_i$ است، و مقدار در نمایه $(i_i, \ldots, i_n)$ در آرایه اصلی Earth Engine با مقدار در نمایه زیر در آرایه مسطح‌شده مطابقت دارد:

\[ \sum_{j=1}^n \left( i_j \cdot \prod_{k=j+1}^n d_k \right) \]

برای موارد رایج، عبارت نمایه‌سازی برای آرایه values به‌صورت زیر است:

اندازه آرایه ابعاد Indexing Expression
یک‌بعدی d1 [i1]
۲ بعدی d1, d2 [(i1 * d2) + i2]
سه‌بعدی d1, d2, d3 [(i1 * d2 * d3) + (i2 * d3) + i3]

برای مثال، آرایه Earth Engine 2x3x4 را درنظر بگیرید:

    ee.Array([
      [
        [1, 2, 3, 4],
        [5, 6, 7, 8],
        [9, 10, 11, 12]
      ],
      [
        [13, 14, 15, 16],
        [17, 18, 19, 20],
        [21, 22, 23, 24]
      ]
    ]);

این آرایه به BigQuery STRUCT ترجمه می‌شود که عنصر dimensions آن آرایه [2, 3, 4] و عنصر values آن آرایه مسطح‌شده [1, 2, 3, 4, 5, 6, 7, 8, ..., 21, 22, 23, 24] است. نمایه‌ها در آرایه مسطح‌شده را می‌توان به‌صورت [(i1 * 12) + (i2 * 4) + i3] محاسبه کرد.

مقادیر JSON

برای پشتیبانی از داده‌های ساختاریافته غنی‌تر در یک سلول، می‌توان مقادیر Earth Engine را به‌عنوان اشیاء JSON کدگذاری کرد. BigQuery از عملیات SQL روی داده‌های JSON-encoded پشتیبانی می‌کند، که امکان پُرسمان‌هایی را فراهم می‌کند که مقادیر JSON-encoded تولیدشده در Earth Engine را «بررسی می‌کنند».

ویرایشگر کد (جاوا اسکریپت)

var states = ee.FeatureCollection('TIGER/2018/States');
var mod11a1 = ee.ImageCollection('MODIS/061/MOD11A1');

// Find the max day and night temperatures per pixel for a given time.
var maxTemp = mod11a1
    .select(['LST_Day_1km', 'LST_Night_1km'])
    .filterDate('2023-05-15', '2023-05-25')
    .max();

// Annotate each state with its max day/night temperatures.
var annotatedStates = states.map(function (e) {
  var dict = maxTemp.reduceRegion({
    reducer: ee.Reducer.max(),
    geometry: e.geometry(),
    scale: 10 * 1000,  // 10 km
  });
  // Convert the dictionary to JSON and add it as a property.
  return e.set('maxTemp', ee.String.encodeJSON(dict));
});

Export.table.toBigQuery(annotatedStates);

راه‌اندازی Python

برای اطلاعات درباره Python API و استفاده از geemap برای توسعه تعاملی، به صفحه Python Environment مراجعه کنید.

import ee
import geemap.core as geemap

Colab (Python)

states = ee.FeatureCollection('TIGER/2018/States')
mod11a1 = ee.ImageCollection('MODIS/061/MOD11A1')

# Find the max day and night temperatures per pixel for a given time.
max_temp = (
    mod11a1.select(['LST_Day_1km', 'LST_Night_1km'])
    .filterDate('2023-05-15', '2023-05-25')
    .max()
)


def get_max_temp_for_state(e):
  max_temp_dict = max_temp.reduceRegion(
      reducer=ee.Reducer.max(),
      geometry=e.geometry(),
      scale=10 * 1000,  # 10 km
  )
  # Convert the dictionary to JSON and add it as a property.
  return e.set('maxTemp', ee.String.encodeJSON(max_temp_dict))


# Annotate each state with its max day/night temperatures.
annotated_states = states.map(get_max_temp_for_state)

task = ee.batch.Export.table.toBigQuery(
    collection=annotated_states, table='myproject.mydataset.mytable'
)
task.start()

تبدیل هندسی

BigQuery پشتیبانی محدودی از طرح‌افکنی‌های مختلف دارد، بنابراین همه هندسه‌های Earth Engine بااستفاده از حاشیه خطای ۱ متر به EPSG:4326 ژئودزیک تبدیل می‌شوند.

برای کنترل دقیق‌تر بر این فرایند تبدیل، می‌توانید به‌صورت دستی ویژگی‌ها را نگاشت کنید و هندسه آن‌ها را تبدیل کنید، برای مثال:

ویرایشگر کد (جاوا اسکریپت)

var transformedCollection = originalCollection.map(function transformGeo(e) {
  var myErrorMargin = 10 * 1000;  // meters
  return e.setGeometry(e.geometry(myErrorMargin, 'EPSG:4326', true));
});

راه‌اندازی Python

برای اطلاعات درباره Python API و استفاده از geemap برای توسعه تعاملی، به صفحه Python Environment مراجعه کنید.

import ee
import geemap.core as geemap

Colab (Python)

def transform_geo(e):
  my_error_margin = 10 * 1000  # meters
  return e.setGeometry(e.geometry(my_error_margin, 'EPSG:4326', True))


transformed_collection = original_collection.map(transform_geo)

عملکرد

عملکرد Earth Engine

محاسبات Earth Engine اغلب گلوگاه عملیات Export است. برای این منظور، مهم است که پردازش خود را برای حداکثر موازی‌سازی سازماندهی کنید. هرگونه محاسباتی که در پردازش سریال گنجانده شده باشد (برای مثال، ee.FeatureCollection.iterate()) می‌تواند باعث شود صادر کردن شما به‌کندی اجرا شود یا ناموفق باشد.

عملکرد در BigQuery

ساختاردهی و خوشه‌بندی صحیح داده‌ها بهترین راه برای اطمینان از کارآمد بودن پُرسمان‌ها در BigQuery است. اگر جدولی ازقبل در BigQuery وجود نداشته باشد، جدول‌های صادرشده از Earth Engine براساس هندسه عارضه‌ها (درصورت وجود) خوشه‌بندی می‌شوند. خوشه‌بندی براساس فیلد جغرافیایی برای داده‌های زمین‌مکانی بسیار رایج است. این نوع داده عملکرد را بهبود می‌بخشد و هزینه پُرسمان‌هایی را که از فیلترهای فضایی استفاده می‌کنند کاهش می‌دهد، به‌ویژه برای عملیات BigQuery مانند:

WHERE ST_DWithin(<table_column>, <constant_geography>, <distance>)
WHERE ST_Intersects(<table_column>, <constant_geography>)

افزودن خوشه‌بندی به جدول خوشه‌بندی‌نشده نیز معمولاً مشکلی ایجاد نمی‌کند، هرچند ممکن است زمان بار کردن داده‌ها در جدول را کمی افزایش دهد. برای اطلاعات بیشتر درباره بهینه‌سازی پُرسمان، اسناد BigQuery را ببینید.

توجه داشته باشید که تنظیمات خوشه‌بندی فقط بر داده‌های جدید نوشته‌شده در جدول تأثیر می‌گذارد.

نسخه نمایشی: استفاده از reduceRegions

در برخی موارد، می‌توان از reduceRegions استفاده کرد تا بیشترین موازی‌سازی ممکن را از زیرساخت پردازش Earth Engine دریافت کرد. این مثال نشان می‌دهد که چگونه از تعداد کمتری از فراخوانی‌های reduceRegions (چند صد) به‌جای ده‌ها هزار فراخوانی reduceRegion (رویکرد معمول برای نگاشت یک تابع روی یک مجموعه) استفاده کنید.

ویرایشگر کد (جاوا اسکریپت)

var lucas = ee.FeatureCollection('JRC/LUCAS_HARMO/COPERNICUS_POLYGONS/V1/2018');
var s2 = ee.ImageCollection('COPERNICUS/S2_SR_HARMONIZED');

// Fetch the unique date values from the dataset.
var dates = lucas.aggregate_array('survey_date')
    .distinct()
    .map(function (date) {
      return ee.Date.parse('dd/MM/yy', date);
    });

// For each date, annotate the LUCAS samples with the Sentinel-2 band values for
// a two-week window.
function getLucasSamplesForDate(date) {
  date = ee.Date(date);
  var imageForDate = s2
    .filterDate(
      date.advance(-1, 'week'),
      date.advance(1, 'week'))
    .select('B.*');
  var median = imageForDate.median();
  var lucasForDate = lucas.filter(
    ee.Filter.equals('survey_date', date.format('dd/MM/yy')));
  var sample = median.reduceRegions({
    collection: lucasForDate,
    reducer: ee.Reducer.mean(),
    scale: 10,
    tileScale: 8,
  });
  return sample;
}

// Flatten the collection.
var withSamples =
    ee.FeatureCollection(dates.map(getLucasSamplesForDate))
      .flatten();

Export.table.toBigQuery({
  collection: withSamples,
  description: 'lucas_s2_annotated'
});

راه‌اندازی Python

برای اطلاعات درباره Python API و استفاده از geemap برای توسعه تعاملی، به صفحه Python Environment مراجعه کنید.

import ee
import geemap.core as geemap

Colab (Python)

lucas = ee.FeatureCollection('JRC/LUCAS_HARMO/COPERNICUS_POLYGONS/V1/2018')
s2 = ee.ImageCollection('COPERNICUS/S2_SR_HARMONIZED')

# Fetch the unique date values from the dataset.
dates = (
    lucas.aggregate_array('survey_date')
    .distinct()
    .map(lambda date: ee.Date.parse('dd/MM/yy', date))
)


# For each date, annotate the LUCAS samples with the Sentinel-2 band values for
# a two-week window.
def get_lucas_samples_for_date(date):
  date = ee.Date(date)
  image_for_date = s2.filterDate(
      date.advance(-1, 'week'), date.advance(1, 'week')
  ).select('B.*')
  median = image_for_date.median()
  lucas_for_date = lucas.filter(
      ee.Filter.equals('survey_date', date.format('dd/MM/yy'))
  )
  sample = median.reduceRegions(
      collection=lucas_for_date,
      reducer=ee.Reducer.mean(),
      scale=10,
      tileScale=8,
  )
  return sample


# Flatten the collection.
with_samples = ee.FeatureCollection(
    dates.map(get_lucas_samples_for_date)
).flatten()

task = ee.batch.Export.table.toBigQuery(
    collection=with_samples,
    table='myproject.mydataset.mytable',
    description='lucas_s2_annotated',
)
task.start()

موازی‌سازی تکلیف

با گزینه {append: true}، این امکان وجود دارد که چند تکلیف به‌طور هم‌زمان داده‌ها را در جدول BigQuery بنویسند. این مکانیزمی برای نوشتن داده‌ها با توان عملیاتی بالاتر است، اما با هزینه افزایش پیچیدگی (مدیریت صف وظایف، تلاش مجدد و غیره) همراه است.

تفاوت‌های عملکرد بین پارامترهای append و overwrite

توجه داشته باشید که بازنویسی کندتر از افزودن است زیرا BigQuery باید داده‌های جدید را قبل‌از بازنویسی داده‌های قدیمی پردازش کند. تنظیم پارامتر {overwrite: true} هنگام صادر کردن به جدول BigQuery موجود، فرایند بازنویسی ایمن را راه‌اندازی می‌کند:

  1. جدول موقت: داده‌ها به جدول موقت جدیدی در مجموعه داده مقصد صادر می‌شود.
  2. رونویسی اتمی: محتوای جدول موقت در جدول مقصد نهایی کپی می‌شود و داده‌های موجود را در یک تراکنش اتمی واحد جایگزین می‌کند.
  3. پاک‌سازی: جدول موقت حذف می‌شود.

این کار تضمین می‌کند که خطاهای احتمالی درطول صادر کردن داده‌ها باعث خراب شدن داده‌های موجود شما نشود. برای جدول‌های کوچک، این تأخیر معمولاً چند دقیقه است.

جایگزین‌های با عملکرد بالا

برای گردش‌های کاری که به توان گذرداد بسیار بالایی نیاز دارند، استفاده از GeoBeam را برای انتقال داده‌ها از Earth Engine به BigQuery درنظر بگیرید. این کار به پیکربندی و زیرساخت بیشتری نیاز دارد، بنابراین پیشنهاد می‌کنیم با عملکرد داخلی Earth Engine شروع کنید.

قیمت‌گذاری

صادر کردن به BigQuery فرایندی دسته‌ای است که زمان EECU دسته‌ای مصرف می‌کند. اگر از Earth Engine به‌صورت تجاری یا عملیاتی استفاده می‌کنید، صادر کردن داده به BigQuery هزینه EECU-time را که تکالیف استفاده می‌کنند از شما کسر می‌کند. همه موارد استفاده را می‌توان با همان ابزارهای پایش که برای بقیه Earth Engine کار می‌کنند، پایش کرد.

حساب‌های صورت‌حساب Cloud

برای نوشتن داده در BigQuery، پروژه Cloud مرتبط باید حساب صورت‌حساب فعال داشته باشد. برای کسب اطلاعات بیشتر درباره پیکربندی حساب صورت‌حساب، به اسناد حساب صورت‌حساب Cloud مراجعه کنید.

خروج

همه هزینه‌های ورودی و خروجی به‌عنوان ترافیک شبکه استاندارد محاسبه می‌شود.

Earth Engine فقط در ایالات متحده میزبانی می‌شود، اما مجموعه‌داده‌های BigQuery را می‌توان در تعدادی از مناطق دیگر میزبانی کرد. بسته به مناطق و حجم داده‌های درگیر، نوشتن داده‌ها از Earth Engine به BigQuery می‌تواند ترافیک شبکه قابل‌توجهی ایجاد کند.

مشکلات شناخته‌شده

جهت چندضلعی‌های بزرگ

تابع صادر کردن BigQuery چندضلعی‌های بزرگ‌تر از نیم‌کره را با معکوس کردن جهت آن‌ها (تغییر چندضلعی به متمم هندسی آن) وارونه می‌کند. در موارد نادر، چندضلعی‌های بزرگ‌تر از نیم‌کره ممکن است بار نشوند.

درصورت نیاز، چندضلعی‌هایی که معکوس شده‌اند را می‌توان در BigQuery با معکوس کردن مجدد آن‌ها بااستفاده از عبارت BigQuery ST_Difference(ST_GeogFromText('fullglobe'), geo) اصلاح کرد.

برای اطلاعات بیشتر، اینجا را ببینید.