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 ke dalam objek ee.FeatureCollection dengan lancar. Fungsi ini terhubung ke tabel yang ditentukan, mengonversi semua jenis data, menerapkan filter dan pemilih yang diperlukan, dan menambahkan pengindeksan ke koleksi jika diperlukan. Fungsi ini menggunakan lingkungan interaktive 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 Google Cloud API 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 Menjalankan dokumen 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() akan memulai tugas kueri BigQuery terpisah (lihat selengkapnya tentang kueri di Menjalankan dokumentasi kueri), sehingga Anda dapat menggunakan kemampuan BigQuery utama:

  • Histori tugas: Akses histori enam bulan eksekusi kueri project Anda (lihat selengkapnya di Daftar tugas).
  • Cache kueri: BigQuery otomatis meng-cache hasil kueri jika memungkinkan. Kueri identik berikutnya mengambil data dari cache, sehingga mencegah tagihan 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 Google Cloud API 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 melebihi batas ini akan gagal dan tidak akan 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 di 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 apa pun yang diakses)
  • bigquery.tables.getData (di tabel apa pun 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). Agar pengguna Google Earth Engine dapat memanfaatkan pemrosesan data tabel BigQuery yang sangat paralel, kami menerjemahkan filter Earth Engine ke bahasa yang dapat dipahami oleh BigQuery dan mengirimkannya bersama dengan permintaan tabel baca. 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 10 MB. Artinya, filter yang diteruskan tidak boleh terlalu rumit. Melampaui batas 10 MB akan menyebabkan 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.

    Pemfilteran menurut geometri yang berisi banyak vertex 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 BigQuery yang setara. Misalnya, BigQuery tidak mendukung pemeriksaan kesetaraan ARRAY. Dalam kasus tersebut, kita tidak menerjemahkan filter, tetapi menerapkannya di Earth Engine setelah membaca data.

Pengindeksan data

Koleksi Earth Engine mengandalkan pengindeksan internal, sedangkan BigQuery tidak merekomendasikan untuk mempertahankan tabel yang diindeks. Agar kedua sistem tersebut dapat bekerja sama, kita membuat indeks koleksi dengan cara berikut:

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

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

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

    Indeks di antara dua permintaan baca stabil, tetapi hanya jika permintaan 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 yang tepat penting bagi pemanggil, sebaiknya tambahkan kolom system:index di BigQuery secara manual.

Batasan

  • Ukuran semua kolom tabel yang dipilih dan dirujuk dalam panggilan ee.FeatureCollection.loadBigQueryTable() dibatasi hingga 400 GB. Melampaui batas ini akan menyebabkan 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 tersebut, pertimbangkan untuk memilih pemilih yang lebih ketat ke kolom yang diperlukan hanya baca atau pertimbangkan untuk menggunakan ee.FeatureCollection.runBigQuery() untuk memproses tabel di BigQuery dan menurunkan 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 Pemfilteran 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')

  • Menggabungkan pada system:index untuk tabel BigQuery dengan ID yang dibuat otomatis dapat menyebabkan perilaku yang tidak terduga. Untuk mencegah hal ini terjadi, sebaiknya tambahkan system:index ke tabel BigQuery secara manual atau gabungkan tabel di properti yang berbeda. 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.