BigQuery'den okuma

Bu sayfada, ee.FeatureCollection.loadBigQueryTable() ve ee.FeatureCollection.runBigQuery() yöntemlerini kullanarak BigQuery tablolarını ee.FeatureCollection nesneleri olarak Earth Engine iş akışlarına nasıl entegre edeceğiniz 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 indeksleme ekler. Bu işlev, Earth Engine'in etkileşimli ortamını kullanarak sonuçları doğrudan istemciye döndürür. Böylece sonuçlar, daha büyük bir analizin bileşeni olarak görüntülenebilir veya kullanılabilir.

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

# 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 Earth Engine yöntemlerinde olduğu gibi arayana faturalandırılır (EECU'lara genel bakış bölümüne bakın).

Verilerin Earth Engine'e aktarılmasıyla ilişkili ek BigQuery maliyeti yoktur. İlgili BigQuery kullanımı, kullanılan projenin Google Cloud API Kontrol Paneli'nde (API kullanımını izleme bölümüne bakın) görünür ancak BigQuery verilerini bu şekilde okumak için herhangi bir ücret alınmaz.

BigQuery'den veri sorgulama

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ümanına bakın).

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

# 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çin yapılan her çağrı ayrı bir BigQuery sorgu işi başlatır (sorgular hakkında daha fazla bilgiyi Sorgu çalıştırma dokümanında bulabilirsiniz). Bu sayede, temel BigQuery özelliklerini kullanabilirsiniz:

• İş geçmişi: Projenizin sorgu yürütmelerinin altı aylık geçmişine erişin (daha fazla bilgi için İşleri listeleme bölümüne bakın).
• 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 alarak gereksiz ücretlendirmeleri önler (daha fazla bilgi için Önbelleğe alınmış sorgu sonuçlarını kullanma başlıklı makaleyi inceleyin).

Sorgular veya BigQuery'de nasıl kullanılacakları 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 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.

Verilerin Earth Engine'e aktarılmasıyla ilişkili ek BigQuery maliyeti yoktur. İlgili BigQuery kullanımı, kullanılan projenin Google Cloud API Kontrol Paneli'nde (API kullanımını izleme bölümüne bakın) görünür ancak BigQuery verilerini bu şekilde okumak için herhangi bir ücret alınmaz.

ee.FeatureCollection.runBigQuery() ile ilişkili olası maliyetleri kontrol etmek için maxBytesBilled parametresi koruma görevi görür. Bu sınırı aşan BigQuery işleri başarısız olur ve faturalandırılmaz. maxBytesBilled varsayılan değeri 100 GB'tır. Aramanız bu sınırı aştığı için 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ştirilmesi gerekir. Uygun API'leri etkinleştirmek için API'yi etkinleştirme sayfasındaki talimatları uygulayın.

Standart Earth Engine rolleri ve izinlerine ek olarak, referans verilen BigQuery tablosunda okuma erişiminiz, hedef projede okuma oturumları ve işleri oluşturma izniniz olmalıdır. 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 düzeyde paralelleştirilmiş BigQuery tablo verisi işleminden yararlanabilmesi için Earth Engine filtrelerini BigQuery'nin anlayabileceği bir dile çevirip tablo okuma isteğiyle birlikte gönderiyoruz. Bu yaklaşım, filtre işlemeyi BigQuery yığınına taşısa da iki sınırlamaya tabidir:

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

   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.

   Bu hatanın yaygın bir nedeni, çok sayıda köşe içeren geometrilere göre filtreleme yapılmasıdır. Bu sorunu çözmek için sorunlu nesnede ee.Geometry.simplify() işlevini kullanmayı deneyin.

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

Veri endeksleme

Earth Engine koleksiyonları dahili indekslemeyi kullanır. BigQuery ise tabloların indekslenmesini önermez. Bu iki sistemin birlikte çalışmasını sağlamak için aşağıdaki şekilde koleksiyon dizinleri 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 arayanın sorumluluğundadır. Aksi takdirde, koleksiyon beklenmedik şekilde çalışabilir. Özellik dizini boş olmayan bir dize olmalıdır. Bu nedenle, system:index sütunu için dize olmayan veya null değeri içeren bir BigQuery tablosu yüklenemez.

• 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 kararlıdır. Aksi takdirde, indekslerin aynı özelliklere karşılık geldiğinden emin olamayız. Bu nedenle, arayan için tam olarak benzersiz veri dizine ekleme önemliyse BigQuery'ye system:index sütununu manuel olarak eklemenizi öneririz.

Sınırlamalar

• Bir ee.FeatureCollection.loadBigQueryTable() çağrısında referans verilen tablonun seçilen 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 gösterilir:

  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, yalnızca gerekli sütunları salt okunur hale getirmek için daha kısıtlayıcı seçiciler kullanmayı veya BigQuery'deki tabloyu önceden işlemek ve getirilen veri miktarını azaltmak için ee.FeatureCollection.runBigQuery() kullanmayı düşünebilirsiniz.

• ee.FeatureCollection.runBigQuery() yöntemi, sorgu sonucu boyutlarına 10 GB sınırı uygular. Kaynak tablolar rastgele boyutta olabilir ancak daha büyük veri hacimlerinin işlenmesi sorgu maliyetlerini artırır.

• Çevrilen 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() kullanımı Earth Engine uygulamalarında kullanılamaz.

Uyarılar

• ee.FeatureCollection.loadBigQueryTable(), bağlı veri kümelerindeki kaynakları desteklemez. Bu tür bir tablodan veri yüklemeye çalışıldığında "tablo bulunamadı" hatası oluşur.

  Geçici çözüm olarak, ee.FeatureCollection.runBigQuery() komutunu, bağlı veri kümesinden istenen tabloyu belirten bir sorguyla çalıştırmayı deneyin. Ö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ında system:index ile birleştirme işlemi beklenmedik davranışlara yol açabilir. Bunun olmasını önlemek için BigQuery tablosuna system:index öğesini manuel olarak eklemeyi veya tabloyu farklı bir mülkte birleştirmeyi deneyin. Dizine ekleme hakkında daha fazla bilgiyi Veri dizine ekleme bölümünde bulabilirsiniz.

• ee.FeatureCollection.randomColumn() yöntemi, BigQuery'nin otomatik olarak oluşturduğu kimliklerle çalışmaz. ee.FeatureCollection.randomColumn() yönteminde rowKeys parametresini kullanarak alternatif bir anahtar belirtmeyi düşünebilirsiniz. Ayrıca, BigQuery kaynak tablosuna random veya system:index sütunlarını manuel olarak da ekleyebilirsiniz. Dizine ekleme hakkında daha fazla bilgiyi Veri dizine ekleme bölümünde bulabilirsiniz.