Odczytywanie z BigQuery

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

Wczytywanie danych z BigQuery

Funkcja ee.FeatureCollection.loadBigQueryTable() odczytuje tabelę BigQuery i tworzy z niej obiekt ee.FeatureCollection. Łączy się z określoną tabelą, konwertuje wszystkie typy danych, stosuje 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 było je wyświetlić lub wykorzystać jako element większej analizy.

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

Płatności

Koszt godzin EECU wykorzystanych podczas przetwarzania żądania jest naliczany dzwoniącemu 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 BigQuery. Odpowiednie wykorzystanie BigQuery będzie widoczne na panelu interfejsów API Google Cloud w używanym projekcie (patrz Monitorowanie wykorzystania interfejsu API), ale odczytywanie danych BigQuery w ten sposób nie będzie generować kosztów.

Wykonywanie zapytań o dane z BigQuery

Metoda ee.FeatureCollection.runBigQuery() wykonuje zapytanie SQL w BigQuery i zwraca wyniki jako obiekt ee.FeatureCollection (więcej informacji o zapytaniach znajdziesz w tym dokumencie).

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

Zapytania BigQuery

Każde wywołanie funkcji ee.FeatureCollection.runBigQuery() rozpoczyna osobne zadanie zapytania w BigQuery (więcej informacji o zapytaniach znajdziesz w dokumentacji dotyczącej uruchamiania zapytań), co umożliwia korzystanie z kluczowych funkcji BigQuery:

• Historia zadań: dostęp do 6-miesięcznej historii wykonywania zapytań w projekcie (więcej informacji znajdziesz w sekcji Lista zadań).
• Pamięć podręczna zapytań: BigQuery automatycznie zapisuje w pamięci podręcznej wyniki zapytań, gdy jest to możliwe. Kolejne identyczne zapytania pobierają dane z pamięci podręcznej, co zapobiega niepotrzebnym opłatom (więcej informacji znajdziesz w artykule Używanie wyników zapytań przechowywanych w pamięci podręcznej).

Więcej informacji o zapytaniach i sposobach ich używania w BigQuery znajdziesz w dokumentacji BigQuery.

Płatności

Koszt jednostek EECU użytych podczas przetwarzania żądania jest naliczany na koncie wywołującego, tak jak w przypadku każdej innej metody Earth Engine (patrz Omówienie jednostek EECU). Dodatkowo uruchomienie zapytania jest rozliczane na koncie wywołującego zgodnie z modelem rozliczeń BigQuery.

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

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 naliczona za nie opłata. Domyślna wartość parametru maxBytesBilled to 100 GB. Jeśli połączenie zostanie zablokowane z powodu przekroczenia tego limitu, możesz określić 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. Postępuj zgodnie z instrukcjami na stronie Włączanie interfejsu API, aby włączyć odpowiednie interfejsy API.

Oprócz standardowych ról i uprawnień Earth Engine musisz mieć dostęp do odczytu w odniesieniu do tabeli BigQuery, do której się odwołujesz, oraz uprawnienia do tworzenia sesji odczytu i zadań w projekcie docelowym. Wymagane są te uprawnienia BigQuery:

• bigquery.tables.get (w dowolnej tabeli, do której masz dostęp)
• bigquery.tables.getData (w dowolnej tabeli, do której masz dostęp)
• bigquery.readSession.create
• bigquery.jobs.create

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

Filtrowanie danych

Każdy element ee.FeatureCollection można filtrować za pomocą metody .filter(Filter). Aby umożliwić użytkownikom Google Earth Engine korzystanie z wysoce zrównoleglonego przetwarzania danych tabelarycznych BigQuery, tłumaczymy filtry Earth Engine na język zrozumiały dla BigQuery i wysyłamy je razem z żądaniem odczytu tabeli. To podejście przenosi przetwarzanie filtrów do stosu BigQuery, ale ma też 2 ograniczenia:

1. Podobnie jak w przypadku innych zapytań w BigQuery (patrz limity BigQuery) rozmiar tego żądania jest ograniczony do 10 MB. Oznacza to, że przekazywane filtry nie mogą być zbyt skomplikowane. Przekroczenie limitu 10 MB powoduje wyświetlenie tego błędu:

   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ących wiele wierzchołków jest częstą przyczyną tego błędu. Aby rozwiązać ten problem, rozważ użycie funkcji ee.Geometry.simplify() w przypadku problematycznego obiektu.

2. Niektórych bardziej skomplikowanych filtrów Earth Engine nie można przekonwertować na 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

Kolekcje Earth Engine korzystają z indeksowania wewnętrznego, natomiast BigQuery odradza indeksowanie tabel. Aby te 2 systemy mogły ze sobą współpracować, tworzymy indeksy kolekcji w ten sposób:

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

  W takich przypadkach to dzwoniący musi zadbać o to, aby indeksy były niepowtarzalne. W przeciwnym razie kolekcja może działać w nieoczekiwany sposób. Indeks cechy musi być niepustym ciągiem znaków, więc wczytywanie tabeli BigQuery z wartością inną niż ciąg znaków lub nullw kolumnie system:index zakończy się niepowodzeniem.

• 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, z uwzględnieniem filtrów. W przeciwnym razie nie będziemy mogli polegać na indeksach, które odpowiadają tym samym funkcjom. Jeśli więc dokładne indeksowanie unikalnych danych jest ważne dla wywołującego, 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. Przekroczenie 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ż wybór bardziej restrykcyjnych selektorów, aby odczytywać tylko niezbędne kolumny, lub użyj ee.FeatureCollection.runBigQuery(), aby wstępnie przetworzyć tabelę w BigQuery i zmniejszyć ilość pobieranych danych.

• Metoda ee.FeatureCollection.runBigQuery() nakłada limit 10 GB na rozmiary wyników zapytania. Tabele źródłowe mogą mieć dowolny rozmiar, ale przetwarzanie większych ilości danych zwiększy koszty zapytań.

• Rozmiar przetłumaczonego filtra jest ograniczony do 10 MB. Szczegółowe informacje znajdziesz w sekcji Filtrowanie danych.

• Korzystanie z ee.FeatureCollection.loadBigQueryTable() lub ee.FeatureCollection.runBigQuery() nie jest możliwe w przypadku aplikacji Earth Engine.

Zastrzeżenia

• ee.FeatureCollection.loadBigQueryTable() nie obsługuje zasobów z połączonych zbiorów danych. Próba wczytania danych z takiej tabeli powoduje błąd „Nie znaleziono tabeli”.

  Aby obejść ten problem, możesz uruchomić ee.FeatureCollection.runBigQuery() z zapytaniem określającym żądaną 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łączenie na podstawie system:index w przypadku tabel BigQuery z automatycznie generowanymi identyfikatorami może prowadzić do nieoczekiwanych zachowań. Aby temu zapobiec, rozważ dodanie system:index do tabeli BigQuery ręcznie lub połączenie tabeli z inną właściwością. Więcej informacji o indeksowaniu znajdziesz w sekcji Indeksowanie danych.

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