BigQuery'den okuma

Bu sayfada, ee.FeatureCollection.loadBigQueryTable() ve ee.FeatureCollection.runBigQuery() yöntemleri kullanılarak BigQuery tablolarının ee.FeatureCollection nesneleri olarak Earth Engine iş akışlarına nasıl entegre edileceği açıklanmaktadır.

BigQuery'den veri yükleme

ee.FeatureCollection.loadBigQueryTable() işlevi, bir BigQuery tablosunu sorunsuz bir şekilde ee.FeatureCollection nesnesine okur. Belirtilen bir tabloya bağlanır, tüm veri türlerini dönüştürür, gerekli filtreleri ve seçicileri uygular ve gerekirse koleksiyona dizine ekleme ekler. İşlev, Earth Engine'ın etkileşimli ortamını kullanır ve sonuçları doğrudan istemciye döndürerek görüntülenmesi veya daha büyük bir analizin bileşeni olarak kullanılması için sunar.

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

Faturalandırma

İsteğin işlenmesi sırasında kullanılan EECU saatlerinin maliyeti, diğer tüm Earth Engine yöntemlerinde olduğu gibi arayana faturalandırılır (EECU'lara genel bakış bölümüne bakın).

Verileri Earth Engine'a aktarmayla ilişkili ek BigQuery maliyeti yoktur. İlgili BigQuery kullanımı, kullanılan projenin Google Cloud API kontrol panelinde görünür (API kullanımını izleme bölümüne bakın). Ancak BigQuery verilerini bu şekilde okumak için herhangi bir maliyete neden olmaz.

BigQuery'deki verileri sorgulayın

ee.FeatureCollection.runBigQuery() yöntemi, bir BigQuery SQL sorgusunu çalıştırır ve sonuçları ee.FeatureCollection nesnesi olarak döndürür (sorgular hakkında daha fazla bilgi edinmek için Sorgu çalıştırma dokümanlarına bakın).

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

BigQuery sorguları

ee.FeatureCollection.runBigQuery() işlevine yapılan her çağrı ayrı bir BigQuery sorgu işi başlatır (Sorgu çalıştırma dokümanlarında sorgular hakkında daha fazla bilgi edinin). Bu sayede, temel BigQuery özelliklerini kullanabilirsiniz:

  • İş geçmişi: Projenizin sorgu yürütme işlemlerinin altı aylık geçmişine erişin (İşleri listele başlıklı makaleyi inceleyin).
  • Sorgu önbelleğe alma: BigQuery mümkün olduğunda sorgu sonuçlarını otomatik olarak önbelleğe alır. Sonraki aynı sorgular, verileri önbellekten alır ve gereksiz ödemelerin yapılmasını önler (Önbelleğe alınmış sorgu sonuçlarını kullanma başlıklı makaleyi inceleyin).

Sorgular veya BigQuery'de sorguları kullanma hakkında bilgi edinmek için BigQuery belgelerine bakın.

Faturalandırma

İsteğin işlenmesi sırasında kullanılan EECU'ların maliyeti, diğer tüm Earth Engine yöntemlerinde olduğu gibi arayana faturalandırılır (EECU'lara genel bakış bölümüne bakın). Ayrıca, BigQuery faturalandırma modeline göre sorgu çalıştırma işlemi, arayana faturalandırılır.

Verileri Earth Engine'a aktarmayla ilişkili ek BigQuery maliyeti yoktur. İlgili BigQuery kullanımı, kullanılan projenin Google Cloud API kontrol panelinde görünür (API kullanımını izleme bölümüne bakın). Ancak BigQuery verilerini bu şekilde okumak için herhangi bir maliyete neden olmaz.

ee.FeatureCollection.runBigQuery() ile ilişkili olası maliyetleri kontrol etmek için maxBytesBilled parametresi bir güvenlik önlemi olarak kullanılır. Bu sınırı aşan BigQuery işleri başarısız olur ve faturalandırılmaz. maxBytesBilled için varsayılan değer 100 GB'tır. Bu sınırı aştığınız için çağrınız engellenirse komut dosyanızda farklı bir değer belirtebilirsiniz.

Ön koşullar ve izinler

Bu özelliği kullanmak için arayanın Cloud projesinde BigQuery API ve BigQuery Storage API'nin etkinleştirilmiş olması gerekir. Uygun API'leri etkinleştirmek için API'yi Etkinleştir sayfasındaki talimatları uygulayın.

Standart Earth Engine rollerine ve izinlerine ek olarak, referans verilen BigQuery tablosunda okuma erişimine, hedef projede okuma oturumları ve işler oluşturma iznine sahip olmanız gerekir. Gerekli BigQuery izinleri şunlardır:

  • bigquery.tables.get (erişilen herhangi bir tabloda)
  • bigquery.tables.getData (erişilen herhangi bir tabloda)
  • bigquery.readSession.create
  • bigquery.jobs.create

İzinleri yönetme hakkında ayrıntılı bilgi için BigQuery erişim denetimi belgelerine bakın.

Veri filtreleme

Her ee.FeatureCollection, .filter(Filter) yöntemi kullanılarak filtrelenebilir. Google Earth Engine kullanıcılarının yüksek paralellikli BigQuery tablo veri işleme özelliğinden yararlanabilmesi için Earth Engine filtrelerini BigQuery tarafından anlaşılabilir bir dile çevirip bir tablo okuma isteğiyle birlikte göndeririz. Bu yaklaşım, filtre işlemeyi BigQuery yığınına taşır ancak iki sınırlamaya da tabidir:

  1. BigQuery'deki diğer tüm sorgular gibi (BigQuery kotalarına bakın) bu istek de 10 MB ile sınırlıdır. Bu nedenle, iletilen filtreler çok karmaşık olamaz. 10 MB sınırına ulaşıldığında aşağıdaki hata meydana gelir:

    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.

    Çok sayıda köşe içeren geometrilere göre filtreleme yapmak bu hatanın yaygın bir nedenidir. Bu sorunu çözmek için sorunlu nesnede ee.Geometry.simplify() işlevini kullanabilirsiniz.

  2. Daha karmaşık olan bazı Earth Engine filtreleri, BigQuery eşdeğerlerine dönüştürülemez. Örneğin, BigQuery ARRAY eşitlik kontrollerini desteklemez. Bu gibi durumlarda, filtreyi çevirmeyiz. Bunun yerine, verileri okuduktan sonra filtreyi Earth Engine'da uygularız.

Veri dizine ekleme

Earth Engine koleksiyonları dahili dizine eklemeye dayanır. BigQuery ise tabloların dizine eklenmesini önermez. Bu iki sistemin birlikte çalışmasını sağlamak için koleksiyon dizinlerini aşağıdaki şekilde oluştururuz:

  • BigQuery tablosunda system:index adlı bir sütun varsa FeatureCollection'ı dizine eklemek için bu sütunu kullanırız.

    Bu gibi durumlarda, dizinlerin benzersiz olduğundan emin olmak aramayı yapan kullanıcıya aittir. Aksi takdirde koleksiyon beklenmedik şekilde kötü davranabilir. Özellik dizini boş olmayan bir dize olmalıdır. Bu nedenle, BigQuery tablosu bir system:index sütunu için dize olmayan veya null değeriyle yüklenirse yükleme başarısız olur.

  • BigQuery tablosunda system:index sütunu yoksa otomatik olarak oluşturulur.

    İki okuma isteği arasındaki dizinler kararlıdır ancak yalnızca filtreler dikkate alınarak istekler tam olarak aynıysa. Aksi takdirde, dizinlerin aynı özelliklere karşılık gelmesini bekleyemeyiz. Bu nedenle, tam olarak benzersiz veri dizine ekleme özelliği arayan için önemliyse system:index sütununu BigQuery'ye manuel olarak eklemenizi öneririz.

Sınırlamalar

  • ee.FeatureCollection.loadBigQueryTable() çağrısında referans verilen tablonun seçili tüm sütunlarının boyutu 400 GB ile sınırlıdır. Bu sınıra ulaşıldığında aşağıdaki hata meydana gelir:

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

    Bu gibi durumlarda, gerekli sütunları salt okunur yapmak için daha kısıtlayıcı seçiciler seçmeyi veya tabloyu BigQuery'de ön işleme tabi tutmak ve getirilen verilerin miktarını azaltmak için ee.FeatureCollection.runBigQuery() kullanmayı düşünebilirsiniz.

  • ee.FeatureCollection.runBigQuery() yöntemi, sorgu sonucu boyutları için 10 GB sınırı uygular. Kaynak tablolar herhangi bir boyutta olabilir ancak daha büyük veri hacimleri işlendiğinde sorgu maliyetleri artar.

  • Çevrilmiş filtre boyutu 10 MB ile sınırlıdır. Ayrıntılar için Veri filtreleme bölümüne bakın.

  • ee.FeatureCollection.loadBigQueryTable() veya ee.FeatureCollection.runBigQuery(), Earth Engine uygulamalarında kullanılamaz.

Uyarılar

  • ee.FeatureCollection.loadBigQueryTable(), Bağlı Veri Kümeleri'ndeki kaynakları desteklemez. Bu tür tablolardan veri yüklemeye çalışmak "tablo bulunamadı" hatasına neden olur.

    Geçici çözüm olarak, bağlı veri kümesinden istenen tabloyu belirten bir sorgu ile ee.FeatureCollection.runBigQuery() çalıştırabilirsiniz. Örneğin:

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

  • Otomatik olarak oluşturulan kimliklere sahip BigQuery tabloları için system:index ile birleştirme yapmak beklenmedik davranışlara neden olabilir. Bunun olmasını önlemek için system:index değerini BigQuery tablosuna manuel olarak ekleyebilir veya tabloyu farklı bir mülkte birleştirebilirsiniz. Dizine ekleme hakkında daha fazla bilgiyi Veri dizine ekleme bölümünde bulabilirsiniz.

  • ee.FeatureCollection.randomColumn() yöntemi, BigQuery tarafından otomatik olarak oluşturulan kimliklerle çalışmaz. ee.FeatureCollection.randomColumn() yönteminde rowKeys parametresini kullanarak alternatif bir anahtar belirtebilirsiniz. BigQuery kaynak tablosuna manuel olarak random veya system:index sütunları da ekleyebilirsiniz. Dizine ekleme hakkında daha fazla bilgiyi Veri dizine ekleme bölümünde bulabilirsiniz.