Membaca dari BigQuery

Halaman ini menjelaskan cara mengintegrasikan tabel BigQuery ke dalam alur kerja Earth Engine sebagai objek ee.FeatureCollection, menggunakan metode ee.FeatureCollection.loadBigQueryTable() dan ee.FeatureCollection.runBigQuery().

Memuat data dari BigQuery

Fungsi ee.FeatureCollection.loadBigQueryTable() membaca tabel BigQuery dengan lancar ke dalam objek ee.FeatureCollection. Proses ini terhubung ke tabel yang ditentukan, mengonversi semua jenis data, menerapkan filter dan pemilih yang diperlukan, serta menambahkan pengindeksan ke koleksi jika diperlukan. Fungsi ini menggunakan lingkungan interaktif Earth Engine, yang menampilkan hasil langsung ke klien untuk dilihat atau digunakan sebagai komponen analisis yang lebih besar.

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

Penagihan

Biaya EECU-jam yang digunakan selama pemrosesan permintaan ditagih kepada pemanggil seperti untuk metode Earth Engine lainnya (lihat Ringkasan EECU).

Tidak ada biaya BigQuery tambahan yang terkait dengan transfer data ke Earth Engine. Penggunaan BigQuery yang sesuai akan terlihat di Dasbor API Google Cloud project yang digunakan (lihat Memantau penggunaan API), tetapi tidak ada biaya yang akan dikenakan untuk membaca data BigQuery dengan cara ini.

Membuat kueri data dari BigQuery

Metode ee.FeatureCollection.runBigQuery() menjalankan kueri SQL BigQuery dan menampilkan hasilnya sebagai objek ee.FeatureCollection (lihat dokumen Menjalankan kueri untuk mempelajari kueri lebih lanjut).

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

Kueri BigQuery

Setiap panggilan ke ee.FeatureCollection.runBigQuery() memulai tugas kueri BigQuery terpisah (lihat informasi selengkapnya tentang kueri dalam dokumentasi Menjalankan kueri), sehingga Anda dapat menggunakan kemampuan utama BigQuery:

• Histori tugas: Akses histori enam bulan eksekusi kueri project Anda (lihat selengkapnya di Mencantumkan tugas).
• Penyimpanan cache kueri: BigQuery otomatis menyimpan hasil kueri dalam cache jika memungkinkan. Kueri identik berikutnya mengambil data dari cache, sehingga mencegah biaya yang berlebihan (lihat selengkapnya di Menggunakan hasil kueri yang di-cache)

Untuk mempelajari kueri atau cara menggunakannya di BigQuery, lihat dokumentasi BigQuery.

Penagihan

Biaya EECU yang digunakan selama pemrosesan permintaan ditagih kepada pemanggil seperti untuk metode Earth Engine lainnya (lihat ringkasan EECU). Selain itu, menjalankan kueri akan ditagih kepada pemanggil sesuai dengan model penagihan BigQuery.

Tidak ada biaya BigQuery tambahan yang terkait dengan transfer data ke Earth Engine. Penggunaan BigQuery yang sesuai akan terlihat di Dasbor API Google Cloud project yang digunakan (lihat Memantau penggunaan API), tetapi tidak ada biaya yang akan dikenakan untuk membaca data BigQuery dengan cara ini.

Untuk mengontrol potensi biaya yang terkait dengan ee.FeatureCollection.runBigQuery(), parameter maxBytesBilled berfungsi sebagai pengamanan. Setiap tugas BigQuery yang melampaui batas ini akan gagal dan tidak ditagih. Nilai default maxBytesBilled adalah 100 GB. Jika panggilan Anda diblokir karena melebihi batas ini, Anda dapat menentukan nilai yang berbeda dalam skrip.

Prasyarat dan izin

Untuk menggunakan fitur ini, project Cloud pemanggil harus mengaktifkan BigQuery API dan BigQuery Storage API. Ikuti petunjuk di halaman Enable API untuk mengaktifkan API yang sesuai.

Selain peran dan izin Earth Engine standar, Anda harus memiliki akses baca pada tabel BigQuery yang dirujuk, izin untuk membuat sesi dan tugas baca di project target. Izin BigQuery khusus yang diperlukan adalah:

• bigquery.tables.get (di tabel yang diakses)
• bigquery.tables.getData (di tabel yang diakses)
• bigquery.readSession.create
• bigquery.jobs.create

Lihat dokumentasi kontrol akses BigQuery untuk mengetahui informasi mendetail tentang cara mengelola izin.

Pemfilteran data

Setiap ee.FeatureCollection dapat difilter menggunakan metode .filter(Filter). Untuk memungkinkan pengguna Google Earth Engine memanfaatkan pemrosesan data tabular BigQuery yang sangat paralel, kami menerjemahkan filter Earth Engine ke bahasa yang dapat dipahami oleh BigQuery dan mengirimkannya bersama dengan permintaan baca tabel. Pendekatan ini memang memindahkan pemrosesan filter ke stack BigQuery, tetapi juga tunduk pada dua batasan:

1. Seperti setiap kueri lainnya di BigQuery (lihat kuota BigQuery), permintaan ini dibatasi hingga berukuran 10 MB. Artinya, filter yang lulus tidak boleh terlalu rumit. Jika mencapai batas 10 MB, akan muncul error berikut:

   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.

   Memfilter berdasarkan geometri yang berisi banyak verteks adalah penyebab umum error ini. Untuk mengatasi masalah ini, pertimbangkan untuk menggunakan ee.Geometry.simplify() pada objek yang bermasalah.

2. Beberapa filter Earth Engine yang lebih rumit tidak dapat dikonversi ke filter BigQuery yang setara. Misalnya, BigQuery tidak mendukung pemeriksaan kesamaan ARRAY. Dalam kasus tersebut, kami tidak menerjemahkan filter dan menerapkannya di Earth Engine setelah membaca data.

Pengindeksan data

Koleksi Earth Engine mengandalkan pengindeksan internal, sedangkan BigQuery tidak menganjurkan agar tabel tetap diindeks. Untuk membuat kedua sistem tersebut bekerja sama, kita membuat indeks kumpulan dengan cara berikut:

• Jika tabel BigQuery berisi kolom bernama system:index, kami akan menggunakannya untuk mengindeks FeatureCollection.

  Dalam kasus seperti itu, pemanggil harus memastikan indeks unik. Jika tidak, koleksi dapat berperilaku tidak terduga. Indeks fitur harus berupa string yang tidak kosong, sehingga pemuatan tabel BigQuery dengan nilai non-string atau null untuk kolom system:index akan gagal.

• Jika tabel BigQuery tidak berisi kolom system:index, kolom tersebut akan dibuat secara otomatis.

  Indeks di antara dua permintaan baca bersifat stabil, tetapi hanya jika permintaannya sama persis, dengan mempertimbangkan filter. Jika tidak, kita tidak dapat mengandalkan indeks untuk sesuai dengan fitur yang sama. Oleh karena itu, jika pengindeksan data unik secara presisi penting bagi pemanggil, sebaiknya tambahkan kolom system:index di BigQuery secara manual.

Batasan

• Ukuran semua kolom tabel yang dipilih yang dirujuk dalam panggilan ee.FeatureCollection.loadBigQueryTable() dibatasi hingga 400 GB. Jika batas ini tercapai, akan muncul error berikut:

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

  Dalam kasus seperti itu, pertimbangkan untuk memilih pemilih yang lebih ketat untuk hanya membaca kolom yang diperlukan atau pertimbangkan untuk menggunakan ee.FeatureCollection.runBigQuery() untuk memproses tabel di BigQuery dan mengurangi jumlah data yang diambil.

• Metode ee.FeatureCollection.runBigQuery() memberlakukan batas 10 GB pada ukuran hasil kueri. Meskipun tabel sumber dapat berukuran arbitrer, pemrosesan volume data yang lebih besar akan meningkatkan biaya kueri.

• Ukuran filter yang diterjemahkan dibatasi hingga 10 MB. Lihat bagian Memfilter data untuk mengetahui detailnya.

• Penggunaan ee.FeatureCollection.loadBigQueryTable() atau ee.FeatureCollection.runBigQuery() tidak tersedia dengan aplikasi Earth Engine.

Peringatan

• ee.FeatureCollection.loadBigQueryTable() tidak mendukung resource dari Set Data Tertaut. Mencoba memuat data dari tabel tersebut akan menghasilkan error "tabel tidak ditemukan".

  Sebagai solusinya, pertimbangkan untuk menjalankan ee.FeatureCollection.runBigQuery() dengan kueri yang menentukan tabel yang diminta dari set data tertaut. Contoh:

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

• Penggabungan pada system:index untuk tabel BigQuery dengan ID yang dibuat otomatis dapat menyebabkan perilaku yang tidak terduga. Untuk mencegah hal ini terjadi, pertimbangkan untuk menambahkan system:index ke tabel BigQuery secara manual atau menggabungkan tabel di properti lain. Baca selengkapnya tentang pengindeksan di bagian Pengindeksan data.

• Metode ee.FeatureCollection.randomColumn() tidak berfungsi dengan ID yang dibuat otomatis BigQuery. Pertimbangkan untuk menentukan kunci alternatif menggunakan parameter rowKeys dalam metode ee.FeatureCollection.randomColumn(). Anda juga dapat menambahkan kolom random atau system:index secara manual ke tabel sumber BigQuery. Baca selengkapnya tentang pengindeksan di bagian Pengindeksan data.