Odczytywanie z BigQuery

Na tej stronie opisano, jak zintegrować tabele BigQuery z przepływami pracy Earth Engine jako obiekty ee.FeatureCollection, korzystając z metod ee.FeatureCollection.loadBigQueryTable() i ee.FeatureCollection.runBigQuery().

Wczytywanie danych z BigQuery

Funkcja ee.FeatureCollection.loadBigQueryTable() czyta bezproblemowo tabelę BigQuery do obiektu ee.FeatureCollection. Łączy się z wybraną tabelą, konwertuje wszystkie typy danych, zachowuje niezbędne filtry i selektory oraz w razie potrzeby dodaje indeksowanie do kolekcji. Funkcja korzysta z interaktywnego środowiska Earth Engine, zwracając wyniki bezpośrednio do klienta, aby można je było wyświetlić lub użyć jako element większej analizy.

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

Płatności

Koszt godzin EECU wykorzystanych podczas przetwarzania żądania jest naliczany do wywołującego, tak jak w przypadku każdej innej metody Earth Engine (patrz omówienie EECU).

Przenoszenie danych do Earth Engine nie wiąże się z dodatkowymi kosztami w BigQuery. Odpowiednie wykorzystanie BigQuery będzie widoczne na panelu interfejsu Google Cloud API używanego projektu (patrz Monitorowanie wykorzystania interfejsu API), ale odczytywanie danych z BigQuery w ten sposób nie powoduje żadnych kosztów.

Wykonywanie zapytań o dane z BigQuery

Metoda ee.FeatureCollection.runBigQuery() uruchamia zapytanie SQL w BigQuery i zwraca wyniki jako obiekt ee.FeatureCollection (więcej informacji o zapytaniach znajdziesz w dokumentacji poświęconej uruchamianiu zapytań).

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

Zapytania BigQuery

Każde wywołanie funkcji ee.FeatureCollection.runBigQuery() inicjuje osobne zadanie zapytania BigQuery (więcej informacji o zapytaniach znajdziesz w dokumentacji Wykonywanie zapytań).

  • Historia zadań: możesz wyświetlić 6-miesięczną historię wykonywania zapytań w projekcie (więcej informacji znajdziesz w sekcji Lista zadań).
  • Przyspieszanie wykonywania zapytań przez ich buforowanie: BigQuery automatycznie buforuje wyniki zapytań, gdy jest to możliwe. Kolejne identyczne zapytania pobierają dane z pamięci podręcznej, co zapobiega naliczaniu zbędących opłat (więcej informacji znajdziesz w artykule Używanie wyników zapytań przechowywanych w pamięci podręcznej).

Aby dowiedzieć się więcej o zapytaniach i sposobach ich używania w BigQuery, zapoznaj się z dokumentacją BigQuery.

Płatności

Koszt jednostek EECU użytych podczas przetwarzania żądania jest naliczany do wywołującego w taki sam sposób jak w przypadku innych metod Earth Engine (patrz omówienie jednostek EECU). Dodatkowo wykonanie zapytania jest rozliczane na rzecz wywołującego zgodnie z modelem rozliczeń BigQuery.

Przenoszenie danych do Earth Engine nie wiąże się z dodatkowymi kosztami w BigQuery. Odpowiednie wykorzystanie BigQuery będzie widoczne na panelu interfejsu Google Cloud API (patrz Monitorowanie wykorzystania interfejsu API), ale nie będzie naliczane żadne opłaty za odczyt danych z BigQuery w ten sposób.

Aby kontrolować potencjalne koszty związane z ee.FeatureCollection.runBigQuery(), parametr maxBytesBilled pełni funkcję zabezpieczenia. Każde zadanie BigQuery, które przekroczy ten limit, zakończy się niepowodzeniem i nie zostanie naliczone. Wartością domyślną parametru maxBytesBilled jest 100 GB. Jeśli wywołanie zostanie zablokowane z powodu przekroczenia tego limitu, możesz podać inną wartość w skrypcie.

Wymagania wstępne i uprawnienia

Aby korzystać z tej funkcji, w projekcie Cloud wywołującego musi być włączony interfejs BigQuery API i BigQuery Storage API. Aby włączyć odpowiednie interfejsy API, postępuj zgodnie z instrukcjami podanymi na stronie Włącz interfejs API.

Oprócz standardowych ról i uprawnień Earth Engine musisz mieć dostęp do odczytu w tabeli BigQuery, z której pochodzą dane, oraz uprawnienia do tworzenia sesji odczytu i zadań w projekcie docelowym. Wymagane uprawnienia BigQuery:

  • bigquery.tables.get (w dowolnej tabeli)
  • bigquery.tables.getData (w dowolnej tabeli)
  • bigquery.readSession.create
  • bigquery.jobs.create

Szczegółowe informacje o zarządzaniu uprawnieniami znajdziesz w dokumentacji kontroli dostępu w BigQuery.

Filtrowanie danych

Każdy ee.FeatureCollection można filtrować za pomocą metody .filter(Filter). Aby umożliwić użytkownikom Google Earth Engine korzystanie z wysoce równoległego przetwarzania danych tabelarycznych BigQuery, przekształcamy filtry Earth Engine w język zrozumiały dla BigQuery i wysyłamy je razem z prośbą o odczytanie tabeli. Takie podejście przenosi przetwarzanie filtrów do pakietu BigQuery, ale wiąże się też z 2 ograniczeniami:

  1. Podobnie jak każde inne zapytanie w BigQuery (patrz kwoty BigQuery), to żądanie ma ograniczony rozmiar do 10 MB. Oznacza to, że przekazywane filtry nie mogą być zbyt skomplikowane. Osiągnięcie limitu 10 MB powoduje ten błąd:

    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.

    Filtrowanie według geometrii zawierającej wiele wierzchołków jest częstą przyczyną tego błędu. Aby rozwiązać ten problem, spróbuj użyć funkcji ee.Geometry.simplify() na problematycznym obiekcie.

  2. Niektórych bardziej skomplikowanych filtrów Earth Engine nie można przekształcić w ich odpowiedniki w BigQuery. Na przykład BigQuery nie obsługuje sprawdzania równości tablic. W takich przypadkach nie tłumaczymy filtra, tylko stosujemy go w Earth Engine po odczytaniu danych.

Indeksowanie danych

Zbiory Earth Engine korzystają z wewnętrznego indeksowania, podczas gdy BigQuery nie zaleca indeksowania tabel. Aby te dwa systemy mogły ze sobą współpracować, tworzymy indeksy zbiorów w taki sposób:

  • Jeśli tabela BigQuery zawiera kolumnę o nazwie system:index, używamy jej do indeksowania kolekcji elementów.

    W takich przypadkach dzwoniąca osoba musi zadbać o to, aby indeksy były unikalne. W przeciwnym razie kolekcja może działać w nieoczekiwany sposób. Indeks cech musi być niepustym ciągiem znaków, więc wczytywanie tabeli BigQuery z wartością niebędącą ciągiem znaków lub null w kolumnie system:index spowoduje niepowodzenie.

  • Jeśli tabela BigQuery nie zawiera kolumny system:index, jest ona generowana automatycznie.

    Indeksy między dwoma żądaniami odczytu są stabilne, ale tylko wtedy, gdy żądania są dokładnie takie same, biorąc pod uwagę filtry. W przeciwnym razie nie możemy polegać na indeksach, które odpowiadają tym samym funkcjom. Jeśli więc wywołujący uważa, że unikalne indeksowanie danych jest ważne, zalecamy ręczne dodanie kolumny system:index w BigQuery.

Ograniczenia

  • Rozmiar wszystkich wybranych kolumn tabeli, do której odwołuje się wywołanie ee.FeatureCollection.loadBigQueryTable(), jest ograniczony do 400 GB. Osiągnięcie tego limitu spowoduje wyświetlenie tego błędu:

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

    W takich przypadkach rozważ użycie bardziej restrykcyjnych selektorów do niezbędnych kolumn tylko do odczytu lub użycie funkcji ee.FeatureCollection.runBigQuery() do wstępnego przetwarzania tabeli w BigQuery i zmniejszenia ilości pobieranych danych.

  • Metoda ee.FeatureCollection.runBigQuery() nakłada limit 10 GB na rozmiar wyników zapytania. Chociaż tabele źródłowe mogą mieć dowolną wielkość, przetwarzanie większych objętości danych zwiększa koszty zapytań.

  • Rozmiar przetłumaczonego filtra jest ograniczony do 10 MB. Więcej informacji znajdziesz w sekcji Filtrowanie danych.

  • W przypadku aplikacji Earth Engine nie można używać atrybutów ee.FeatureCollection.loadBigQueryTable() ani ee.FeatureCollection.runBigQuery().

Zastrzeżenia

  • ee.FeatureCollection.loadBigQueryTable()nie obsługuje zasobów z połączonych zbiorów danych. Próba załadowania danych z takiej tabeli powoduje błąd „tabela nie została znaleziona”.

    Aby obejść ten problem, uruchom zapytanie ee.FeatureCollection.runBigQuery() z wyspecyfikowaną tabelą z połączonego zbioru danych. Przykład:

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

  • Złączanie za pomocą kolumny system:index w przypadku tabel BigQuery z identyfikatorami generowanymi automatycznie może powodować nieoczekiwane zachowania. Aby temu zapobiec, możesz ręcznie dodać kolumnę system:index do tabeli BigQuery lub złączać tabelę z inną usługą. Więcej informacji o indeksowaniu znajdziesz w sekcji Indeksowanie danych.

  • Metoda ee.FeatureCollection.randomColumn() nie działa z identyfikatorami generowanymi automatycznie przez BigQuery. Rozważ podanie klucza alternatywnego za pomocą parametru rowKeys w metodzie ee.FeatureCollection.randomColumn(). Możesz też ręcznie dodać do tabeli źródłowej BigQuery kolumny random lub system:index. Więcej informacji o indeksowaniu znajdziesz w sekcji Indeksowanie danych.