Mengekspor ke BigQuery

Ringkasan

Arsitektur komputasi Earth Engine dioptimalkan untuk membuat komputasi gambar (berbasis piksel) cepat dan skalabel. BigQuery juga dioptimalkan untuk pemrosesan data tabel (vektor) yang skalabel, dan memiliki banyak fitur yang menjadikannya pelengkap yang bagus untuk Earth Engine.

Contoh alur kerja meliputi:

• Melakukan join BigQuery besar pada data yang dihasilkan di Earth Engine
• Menambahkan anotasi pada data vektor dengan statistik yang berasal dari gambar untuk pemrosesan lebih lanjut di BigQuery
• Mengekspor data dari Earth Engine secara berkala ke tabel BigQuery yang dapat ditambahkan

Jika Anda memiliki kasus penggunaan bagus lainnya, kami ingin mendengarnya.

Dasar-dasar BigQuery

Istilah Penting: Set data BigQuery - penampung tingkat teratas dalam project Cloud yang digunakan untuk mengatur dan mengontrol akses ke tabel Anda.

Earth Engine menulis ke tabel BigQuery, dan semua tabel terdapat dalam set data. Tugas ekspor akan gagal jika set data yang ditentukan tidak ada di BigQuery. Cari tahu selengkapnya di pengantar set data BigQuery.

Pembuatan set data

Set data memiliki sejumlah opsi waktu pembuatan, termasuk nama, region penyimpanan, dan perilaku masa berlaku (beserta beberapa opsi lanjutan lainnya).

Ada berbagai mekanisme untuk membuat set data, tetapi cara sederhana untuk memulai adalah melalui konsol Cloud:

1. Buka halaman BigQuery di konsol Cloud.
2. Klik "Aktifkan" untuk mengaktifkan API, jika diminta.
3. Dari tab "SQL Workspace", klik menu tiga titik () di samping project.
4. Pilih opsi "Create dataset".
5. Ikuti panduan konfigurasi.

Untuk semua opsi guna membuat dan mengonfigurasi set data, lihat dokumentasi BigQuery.

Izin

Selain peran dan izin standar yang diperlukan untuk menggunakan Earth Engine, pemanggil juga memerlukan izin BigQuery yang benar di project atau set data Cloud.

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

Setiap kombinasi peran Identity and Access Management (IAM) bawaan berikut menyertakan izin yang diperlukan:

• bigquery.dataEditor plus bigquery.jobUser
• bigquery.dataOwner plus bigquery.jobUser
• bigquery.user
• bigquery.admin

Harga

BigQuery adalah layanan Google Cloud berbayar, sehingga Anda akan dikenai tagihan untuk penggunaan BigQuery, termasuk penyimpanan dan analisis data Earth Engine yang Anda ekspor ke BigQuery.

Untuk mengetahui detail harga fitur ekspor BigQuery Earth Engine, lihat bagian harga di bawah.

Konfigurasi ekspor

Sintaksis

Editor Kode (JavaScript)

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

Penyiapan Python

Lihat halaman Lingkungan Python untuk mengetahui informasi tentang Python API dan penggunaan geemap untuk pengembangan interaktif.

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()

Spesifikasi skema otomatis atau manual

Jika tidak ada tabel di BigQuery, Earth Engine akan mencoba menentukan skema menggunakan properti ee.Feature pertama dalam koleksi. Ini adalah tebakan terbaik, dan Anda dapat membuat koleksi dengan skema fitur pertama yang berbeda dari skema fitur lainnya.

Jika Anda memerlukan skema tertentu di tabel BigQuery, konfigurasikan dengan membuat tabel kosong dengan skema target.

Nama properti

Properti pada fitur Earth Engine sesuai dengan kolom di BigQuery. Earth Engine menggunakan nama "geo" untuk menulis geometri ee.Feature (pemilih ".geo") ke BigQuery.

Untuk menghindari penggantian nama, pastikan objek ee.Feature Anda memiliki properti yang merupakan nama kolom yang valid dan tidak ada yang bernama "geo" (karena nama ini digunakan untuk geometri fitur, yang tidak memiliki nama di Earth Engine).

Karakter yang tidak valid dalam nama properti menyebabkan ekspor gagal, karena adanya batasan pada nama kolom BigQuery.

Konversi jenis

Data Earth Engine (nilai properti ee.Feature) dikonversi ke jenis BigQuery yang setara jika memungkinkan. Perhatikan bahwa nullability dikontrol oleh skema tabel, bukan jenisnya.

Jenis Earth Engine	Jenis BigQuery	Catatan
ee.String	STRING
ee.Number	FLOAT atau INTEGER
ee.Geometry	GEOGRAPHY
ee.Date	TIMESTAMP
ee.ByteString	BYTES
ee.Array	STRUCT<ARRAY<INT64>, ARRAY<INT64|FLOAT64>>	Lihat bagian tentang array
Jenis ee.* lainnya	tidak didukung	Lihat bagian tentang nilai JSON

Array

Earth Engine mengekspor ee.Array multi-dimensi ke STRUCT<ARRAY<INT64> dimensions, ARRAY<INT64|FLOAT64> values>, mirip dengan format yang digunakan oleh fungsi ML.DECODE_IMAGE BigQuery.

Array pertama dalam struct, dimensions, berisi dimensi array Earth Engine, $d_1$ hingga $d_n$.

Array kedua dalam struct, values, berisi semua nilai dalam array multidimensi, yang diratakan menjadi satu array BigQuery. Jumlah total nilai dalam array yang diratakan adalah $\sum_{i=1}^n d_i$, dan nilai pada indeks $(i_i, \ldots, i_n)$ dalam array Earth Engine asli sesuai dengan nilai pada indeks berikut dalam array yang diratakan:

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

Untuk kasus umum, ekspresi pengindeksan untuk array values adalah sebagai berikut:

Ukuran Array	Dimensi	Ekspresi Pengindeksan
1 dimensi	d1	[i1]
2 dimensi	d1, d2	[(i1 * d2) + i2]
Tiga dimensi	d1, d2, d3	[(i1 * d2 * d3) + (i2 * d3) + i3]

Misalnya, pertimbangkan array 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]
      ]
    ]);

Array ini diterjemahkan ke STRUCT BigQuery yang elemen dimensions-nya adalah array [2, 3, 4] dan elemen values-nya adalah array [1, 2, 3, 4, 5, 6, 7, 8, ..., 21, 22, 23, 24] yang diratakan. Indeks dalam array yang diratakan dapat dihitung sebagai [(i1 * 12) + (i2 * 4) + i3].

Nilai JSON

Untuk mendukung data yang lebih terstruktur dalam sel, Anda dapat mengenkode nilai Earth Engine sebagai objek JSON. BigQuery mendukung operasi SQL pada data yang dienkode JSON, yang memungkinkan kueri yang "melihat ke dalam" nilai JSON yang dienkode yang Anda buat di Earth Engine.

Editor Kode (JavaScript)

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

Penyiapan Python

Lihat halaman Lingkungan Python untuk mengetahui informasi tentang Python API dan penggunaan geemap untuk pengembangan interaktif.

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()

Konversi geometri

BigQuery memiliki dukungan terbatas untuk berbagai proyeksi, sehingga semua geometri Earth Engine ditransformasikan menjadi EPSG:4326 geodesik menggunakan margin error sebesar 1 meter.

Untuk memiliki kontrol yang lebih baik atas proses transformasi ini, Anda dapat memetakan fitur secara manual dan mengubah geometrinya, misalnya:

Editor Kode (JavaScript)

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

Penyiapan Python

Lihat halaman Lingkungan Python untuk mengetahui informasi tentang Python API dan penggunaan geemap untuk pengembangan interaktif.

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)

Perhatian: Orientasi poligon yang lebih besar dari belahan bumi dapat dibalik selama ekspor. Lihat masalah umum untuk mengetahui detail selengkapnya.

Performa

Performa Earth Engine

Komputasi Earth Engine sering kali menjadi bottleneck untuk operasi Export. Untuk tujuan ini, penting untuk mengatur pemrosesan Anda untuk paralelisme maksimum. Setiap komputasi yang di-bake dalam pemrosesan serial (misalnya, ee.FeatureCollection.iterate()) dapat menyebabkan ekspor Anda berjalan lambat atau gagal.

Performa di BigQuery

Menyusun dan mengelompokkan data dengan benar adalah cara terbaik untuk memastikan kueri dapat dibuat efisien di BigQuery. Jika tidak ada tabel yang sudah ada di BigQuery, tabel yang diekspor dari Earth Engine akan dikelompokkan berdasarkan geometri fitur (jika ada). Pengelompokan menurut kolom geografi sangat umum untuk data geospasial. Hal ini meningkatkan performa dan mengurangi biaya untuk kueri yang menggunakan filter spasial, terutama untuk operasi BigQuery seperti:

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

WHERE ST_Intersects(<table_column>, <constant_geography>)

Menambahkan pengelompokan ke tabel yang tidak dikelompokkan juga umumnya tidak membahayakan apa pun, meskipun mungkin sedikit meningkatkan waktu untuk memuat data ke tabel. Untuk mengetahui informasi selengkapnya tentang pengoptimalan kueri, lihat dokumentasi BigQuery.

Perhatikan bahwa setelan pengelompokan hanya memengaruhi data baru yang ditulis ke tabel.

Demo: menggunakan reduceRegions

Dalam beberapa kasus, Anda dapat menggunakan reduceRegions untuk mendapatkan paralelisme sebanyak mungkin dari infrastruktur pemrosesan Earth Engine. Contoh ini menunjukkan cara menggunakan panggilan reduceRegions dalam jumlah yang lebih kecil (beberapa ratus) daripada puluhan ribu panggilan reduceRegion (pendekatan biasa untuk memetakan fungsi di seluruh koleksi).

Editor Kode (JavaScript)

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'
});

Penyiapan Python

Lihat halaman Lingkungan Python untuk mengetahui informasi tentang Python API dan penggunaan geemap untuk pengembangan interaktif.

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()

Paralelisasi tugas

Dengan opsi {append: true}, beberapa tugas dapat menulis data ke tabel BigQuery secara serentak. Ini adalah mekanisme untuk menulis data dengan throughput yang lebih tinggi, tetapi dengan mengorbankan peningkatan kompleksitas (mengelola antrean tugas, mencoba lagi, dll.).

Perbedaan performa antara parameter append dan overwrite

Perhatikan bahwa menimpa lebih lambat daripada menambahkan karena BigQuery harus memproses data baru sebelum menimpa data lama. Menetapkan parameter {overwrite: true} saat mengekspor ke tabel BigQuery yang ada akan memicu proses penggantian yang aman:

1. Tabel sementara: data diekspor ke tabel sementara baru dalam set data tujuan.
2. Penggantian atomik: konten tabel sementara disalin ke tabel tujuan akhir, yang menggantikan data yang ada dalam satu transaksi atomik.
3. Pembersihan: tabel sementara dihapus.

Hal ini memastikan bahwa error selama ekspor tidak akan merusak data yang ada. Untuk tabel kecil, penundaan biasanya berlangsung beberapa menit.

Alternatif berperforma tinggi

Untuk alur kerja yang memerlukan throughput sangat tinggi, pertimbangkan untuk menggunakan GeoBeam untuk memindahkan data dari Earth Engine ke BigQuery. Hal ini memerlukan lebih banyak konfigurasi dan infrastruktur, jadi sebaiknya mulai dengan fungsi Earth Engine bawaan.

Harga

Perhatian: Meskipun Anda menggunakan Earth Engine secara gratis sebagai pengguna nonkomersial atau non-operasional, penggunaan BigQuery akan menimbulkan tagihan di akun Penagihan Google Cloud project Cloud Anda.

Mengekspor ke BigQuery adalah proses batch yang menggunakan waktu EECU batch. Jika Anda menggunakan Earth Engine secara komersial atau operasional, mengekspor data ke BigQuery akan mengenakan biaya waktu EECU yang digunakan tugas. Semua penggunaan dapat dipantau dengan alat pemantauan yang sama persis dengan yang digunakan untuk Earth Engine lainnya.

Akun penagihan cloud

Untuk menulis data ke BigQuery, project Cloud terkait harus mengaktifkan akun penagihan. Untuk mempelajari konfigurasi akun penagihan lebih lanjut, lihat dokumen akun penagihan Cloud.

Egress

Pratinjau: Operasi tulis dari Earth Engine ke BigQuery tidak menghasilkan tagihan masuk atau keluar Cloud saat ini, tetapi akan melakukannya di masa mendatang.

Semua biaya traffic masuk dan keluar ditagih sebagai traffic jaringan standar.

Earth Engine hanya dihosting di AS, tetapi set data BigQuery dapat dihosting di sejumlah region lainnya. Bergantung pada region dan volume data yang terlibat, menulis data dari Earth Engine ke BigQuery dapat menghasilkan traffic jaringan yang cukup besar.

Masalah umum

Orientasi untuk poligon besar

Fungsi BigQuery Export membalik poligon yang lebih besar dari belahan bumi dengan membalikkan orientasinya (mengubah poligon menjadi pelengkap geometrisnya). Dalam kasus yang jarang terjadi, poligon yang lebih besar dari belahan bumi mungkin gagal dimuat.

Jika diperlukan, poligon yang telah dibalik dapat dikoreksi dalam BigQuery dengan membaliknya lagi, menggunakan ekspresi BigQuery ST_Difference(ST_GeogFromText('fullglobe'), geo).

Untuk informasi selengkapnya, lihat di sini.