صادرات به BigQuery

نمای کلی

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

نمونه گردش کار شامل:

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

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

اصول BigQuery

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

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

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

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

1. به صفحه BigQuery در کنسول Cloud بروید.
2. در صورت درخواست، برای فعال کردن API روی "فعال کردن" کلیک کنید.
3. از تب "SQL Workspace"، روی منوی سه نقطه ( more_vert ) در کنار پروژه کلیک کنید.
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': myFeatureCollection,
    'table': 'myproject.mydataset.mytable',
    'description': 'put_my_data_in_bigquery',
    'append': true,
    'overwrite': false
  });

  task = ee.batch.Export.table.toBigQuery(
      collection=myFeatureCollection,
      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 هر 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 به صورت زیر است:

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

    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]
      ]
    ]);

این آرایه به یک STRUCT BigQuery ترجمه می شود که عنصر 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 پشتیبانی می‌کند، و به درخواست‌هایی اجازه می‌دهد که مقادیر JSON کدگذاری‌شده‌ای را که در 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);

import ee
import geemap.core as geemap

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 با استفاده از حاشیه خطای 1 متر به EPSG:4326 geodesic تبدیل می شوند.

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

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

import ee
import geemap.core as geemap

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)

عملکرد

عملکرد موتور زمین

محاسبات موتور زمین اغلب گلوگاه عملیات 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'
});

import ee
import geemap.core as geemap

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 که وظایف استفاده می‌کنند از شما هزینه دریافت می‌کند. تمام استفاده ها را می توان دقیقاً با همان ابزارهای نظارتی که برای بقیه Earth Engine کار می کند، بررسی کرد.

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

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

خروج

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

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

مسائل شناخته شده

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

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

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

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