Экспорт в BigQuery

Обзор

Вычислительная архитектура Earth Engine оптимизирована для быстрого и масштабируемого вычисления изображений (на основе пикселей). BigQuery также оптимизирован для масштабируемой обработки табличных данных (векторов) и имеет множество функций, которые делают его хорошим дополнением к Earth Engine.

Примеры рабочих процессов включают:

• Выполнение больших объединений BigQuery для данных, созданных в Earth Engine.
• Аннотирование векторных данных статистикой, полученной на основе изображений, для дальнейшей обработки в BigQuery.
• Периодический экспорт данных из Earth Engine в добавляемую таблицу BigQuery.

Если у вас есть другие замечательные варианты использования, мы будем рады услышать о них !

Основы BigQuery

Earth Engine записывает данные в таблицы BigQuery, и все таблицы содержатся в наборах данных. Задачи экспорта завершаются неудачно, если указанный набор данных отсутствует в BigQuery. Подробную информацию можно найти во введении к набору данных BigQuery .

Создание набора данных

Наборы данных имеют ряд параметров времени создания, включая имя, область хранения и срок действия (наряду с несколькими другими, более продвинутыми параметрами).

Существует множество механизмов создания наборов данных , но начать проще всего через облачную консоль:

1. Перейдите на страницу BigQuery в консоли Cloud .
2. Нажмите «Включить», чтобы включить API, если будет предложено.
3. На вкладке «Рабочая область SQL» щелкните трехточечное меню ( more_vert ) рядом с проектом.
4. Выберите опцию «Создать набор данных».
5. Следуйте руководству по настройке.

Обо всех вариантах создания и настройки набора данных см. в документации BigQuery .

Разрешения

Помимо стандартных ролей и разрешений, необходимых для использования Earth Engine, вызывающим абонентам также необходимы правильные разрешения BigQuery для облачного проекта или набора данных.

• bigquery.tables.get
• bigquery.tables.create
• bigquery.tables.updateData
• bigquery.tables.delete
• bigquery.jobs.create

Любая из следующих комбинаций предопределенных ролей управления идентификацией и доступом (IAM) включает необходимые разрешения:

• bigquery.dataEditor плюс bigquery.jobUser
• bigquery.dataOwner плюс bigquery.jobUser
• bigquery.user
• bigquery.admin

Цены

BigQuery – это платный сервис Google Cloud, поэтому за использование BigQuery, включая хранение и анализ любых данных Earth Engine, которые вы экспортируете в BigQuery, взимается плата .

Подробную информацию о ценах на функцию экспорта BigQuery Earth Engine см. в разделе цен ниже.

Экспортировать конфигурацию

Синтаксис

  Export.table.toBigQuery({
    'collection': myFeatureCollection,
    'table': 'myproject.mydataset.mytable',
    'description': 'put_my_data_in_bigquery',
    'append': true,
    'overwrite': false
  });

  task = ee.batch.Export.table.toBigQuery(
      collection=myFeatureCollection,
      table='myproject.mydataset.mytable',
      description='put_my_data_in_bigquery',
      append=True,
      overwrite=False)
  task.start()

Автоматическая или ручная спецификация схемы

Если в BigQuery нет таблицы, Earth Engine пытается определить схему, используя свойства первого ee.Feature в коллекции. Это наилучшее предположение, и можно создать коллекцию, в которой схема первого объекта отличается от схемы других объектов.

Если вам требуется определенная схема для таблицы BigQuery, настройте ее, создав пустую таблицу с целевой схемой .

Имена свойств

Свойства функций Earth Engine соответствуют столбцам в BigQuery. Earth Engine использует имя «geo» для записи геометрии ee.Feature (селектор «.geo») в BigQuery.

Чтобы избежать переименования, убедитесь, что ваши объекты ee.Feature имеют свойства, которые являются допустимыми именами столбцов , и ни одно из них не имеет имени «geo» (поскольку это имя используется для геометрии объекта, который не имеет имени в Earth Engine).

Недопустимые символы в именах свойств приводят к сбою экспорта из-за ограничений на имена столбцов BigQuery .

Преобразование типов

Данные Earth Engine (значения свойств ee.Feature ) по возможности преобразуются в эквивалентный тип BigQuery . Обратите внимание, что допустимость значений NULL контролируется схемой таблицы, а не ее типом.

Массивы

Earth Engine экспортирует любой многомерный ee.Array в STRUCT<ARRAY<INT64> dimensions, ARRAY<INT64|FLOAT64> values> , аналогичный формату, используемому функцией ML.DECODE_IMAGE BigQuery.

Первый массив структуры, dimensions , содержит размеры массива Earth Engine от $d_1$ до $d_n$.

Второй массив в структуре, values , содержит все значения многомерного массива, сведенные в один массив BigQuery. Общее количество значений в сведенном массиве равно $\sum_{i=1}^n d_i$, а значение по индексу $(i_i, \ldots, i_n)$ в исходном массиве Earth Engine соответствует значению по следующему индексу в сведенном массиве:

$$\sum_{j=1}^n \left( i_j \cdot \prod_{k=j+1}^n d_k \right)$$

В распространенных случаях индексное выражение для массива values выглядит следующим образом:

Например, рассмотрим массив Earth Engine 2x3x4 :

    ee.Array([
      [
        [1, 2, 3, 4],
        [5, 6, 7, 8],
        [9, 10, 11, 12]
      ],
      [
        [13, 14, 15, 16],
        [17, 18, 19, 20],
        [21, 22, 23, 24]
      ]
    ]);

Этот массив преобразуется в BigQuery STRUCT элементом dimensions которого является массив [2, 3, 4] и элементом values которого является сглаженный массив [1, 2, 3, 4, 5, 6, 7, 8, ..., 21, 22, 23, 24] . Индексы в сглаженном массиве можно вычислить как [(i1 * 12) + (i2 * 4) + i3] .

Значения JSON

Для поддержки более структурированных данных в ячейке можно кодировать значения Earth Engine как объекты JSON . BigQuery поддерживает операции SQL над данными в кодировке JSON , позволяя выполнять запросы, которые «заглядывают внутрь» закодированных значений JSON, которые вы создаете в Earth Engine.

var states = ee.FeatureCollection('TIGER/2018/States');
var mod11a1 = ee.ImageCollection('MODIS/061/MOD11A1');

// Find the max day and night temperatures per pixel for a given time.
var maxTemp = mod11a1
    .select(['LST_Day_1km', 'LST_Night_1km'])
    .filterDate('2023-05-15', '2023-05-25')
    .max();

// Annotate each state with its max day/night temperatures.
var annotatedStates = states.map(function (e) {
  var dict = maxTemp.reduceRegion({
    reducer: ee.Reducer.max(),
    geometry: e.geometry(),
    scale: 10 * 1000,  // 10 km
  });
  // Convert the dictionary to JSON and add it as a property.
  return e.set('maxTemp', ee.String.encodeJSON(dict));
});

Export.table.toBigQuery(annotatedStates);

import ee
import geemap.core as geemap

states = ee.FeatureCollection('TIGER/2018/States')
mod11a1 = ee.ImageCollection('MODIS/061/MOD11A1')

# Find the max day and night temperatures per pixel for a given time.
max_temp = (
    mod11a1.select(['LST_Day_1km', 'LST_Night_1km'])
    .filterDate('2023-05-15', '2023-05-25')
    .max()
)


def get_max_temp_for_state(e):
  max_temp_dict = max_temp.reduceRegion(
      reducer=ee.Reducer.max(),
      geometry=e.geometry(),
      scale=10 * 1000,  # 10 km
  )
  # Convert the dictionary to JSON and add it as a property.
  return e.set('maxTemp', ee.String.encodeJSON(max_temp_dict))


# Annotate each state with its max day/night temperatures.
annotated_states = states.map(get_max_temp_for_state)

task = ee.batch.Export.table.toBigQuery(
    collection=annotated_states, table='myproject.mydataset.mytable'
)
task.start()

Преобразование геометрии

BigQuery имеет ограниченную поддержку различных проекций , поэтому вся геометрия Earth Engine преобразуется в геодезическую EPSG:4326 с погрешностью в 1 метр.

Чтобы лучше контролировать этот процесс преобразования, вы можете вручную сопоставить объекты и преобразовать их геометрию, например:

var transformedCollection = originalCollection.map(function transformGeo(e) {
  var myErrorMargin = 10 * 1000;  // meters
  return e.setGeometry(e.geometry(myErrorMargin, 'EPSG:4326', true));
});

import ee
import geemap.core as geemap

def transform_geo(e):
  my_error_margin = 10 * 1000  # meters
  return e.setGeometry(e.geometry(my_error_margin, 'EPSG:4326', True))


transformed_collection = original_collection.map(transform_geo)

Производительность

Производительность земляного двигателя

Вычисления Earth Engine часто являются узким местом для операций Export . С этой целью важно организовать обработку так, чтобы обеспечить максимальный параллелизм. Любое вычисление, выполняемое при последовательной обработке (например, ee.FeatureCollection.iterate() ), может привести к замедлению экспорта или сбою.

Производительность в BigQuery

Правильное структурирование и кластеризация данных — лучший способ обеспечить эффективность запросов в BigQuery. Если в BigQuery еще нет таблицы, таблицы, экспортированные из Earth Engine, кластеризуются по геометрии объектов (если она присутствует). Кластеризация по географическому полю очень распространена для геопространственных данных. Это повышает производительность и снижает затраты на запросы, использующие пространственные фильтры, чаще всего для таких операций BigQuery, как:

WHERE ST_DWithin(<table_column>, <constant_geography>, <distance>)

WHERE ST_Intersects(<table_column>, <constant_geography>)

Добавление кластеризации в некластеризованную таблицу также обычно ничему не вредит, хотя может немного увеличить время загрузки данных в таблицу. Подробнее об оптимизации запросов читайте в документации BigQuery .

Обратите внимание, что настройки кластеризации влияют только на новые данные, записываемые в таблицу.

Демо: использование reduceRegions

В некоторых случаях можно использовать reduceRegions , чтобы получить как можно больше параллелизма от инфраструктуры обработки Earth Engine. В этом примере показано, как использовать меньшее количество вызовов reduceRegions (несколько сотен) вместо десятков тысяч вызовов reduceRegion (типичный подход для сопоставления функции с коллекцией).

var lucas = ee.FeatureCollection('JRC/LUCAS_HARMO/COPERNICUS_POLYGONS/V1/2018');
var s2 = ee.ImageCollection('COPERNICUS/S2_SR_HARMONIZED');

// Fetch the unique date values from the dataset.
var dates = lucas.aggregate_array('survey_date')
    .distinct()
    .map(function (date) {
      return ee.Date.parse('dd/MM/yy', date);
    });

// For each date, annotate the LUCAS samples with the Sentinel-2 band values for
// a two-week window.
function getLucasSamplesForDate(date) {
  date = ee.Date(date);
  var imageForDate = s2
    .filterDate(
      date.advance(-1, 'week'),
      date.advance(1, 'week'))
    .select('B.*');
  var median = imageForDate.median();
  var lucasForDate = lucas.filter(
    ee.Filter.equals('survey_date', date.format('dd/MM/yy')));
  var sample = median.reduceRegions({
    collection: lucasForDate,
    reducer: ee.Reducer.mean(),
    scale: 10,
    tileScale: 8,
  });
  return sample;
}

// Flatten the collection.
var withSamples =
    ee.FeatureCollection(dates.map(getLucasSamplesForDate))
      .flatten();

Export.table.toBigQuery({
  collection: withSamples,
  description: 'lucas_s2_annotated'
});

import ee
import geemap.core as geemap

lucas = ee.FeatureCollection('JRC/LUCAS_HARMO/COPERNICUS_POLYGONS/V1/2018')
s2 = ee.ImageCollection('COPERNICUS/S2_SR_HARMONIZED')

# Fetch the unique date values from the dataset.
dates = (
    lucas.aggregate_array('survey_date')
    .distinct()
    .map(lambda date: ee.Date.parse('dd/MM/yy', date))
)


# For each date, annotate the LUCAS samples with the Sentinel-2 band values for
# a two-week window.
def get_lucas_samples_for_date(date):
  date = ee.Date(date)
  image_for_date = s2.filterDate(
      date.advance(-1, 'week'), date.advance(1, 'week')
  ).select('B.*')
  median = image_for_date.median()
  lucas_for_date = lucas.filter(
      ee.Filter.equals('survey_date', date.format('dd/MM/yy'))
  )
  sample = median.reduceRegions(
      collection=lucas_for_date,
      reducer=ee.Reducer.mean(),
      scale=10,
      tileScale=8,
  )
  return sample


# Flatten the collection.
with_samples = ee.FeatureCollection(
    dates.map(get_lucas_samples_for_date)
).flatten()

task = ee.batch.Export.table.toBigQuery(
    collection=with_samples,
    table='myproject.mydataset.mytable',
    description='lucas_s2_annotated',
)
task.start()

Распараллеливание задач

С помощью параметра {append: true} несколько задач могут одновременно записывать данные в таблицу BigQuery. Это механизм записи данных с более высокой пропускной способностью, но за это приходится платить повышенной сложностью (управление очередью задач, повторные попытки и т. д.).

Различия в производительности между параметрами append и overwrite

Обратите внимание, что перезапись выполняется медленнее, чем добавление, поскольку BigQuery должен обработать новые данные перед перезаписью старых. Установка параметра {overwrite: true} при экспорте в существующую таблицу BigQuery запускает безопасный процесс перезаписи:

1. Временная таблица: данные экспортируются в новую временную таблицу в целевом наборе данных.
2. Атомарная перезапись: содержимое временной таблицы копируется в конечную таблицу назначения, заменяя существующие данные в одной атомарной транзакции.
3. Очистка: временная таблица удаляется.

Это гарантирует, что ошибки во время экспорта не повредят существующие данные. Для небольших столов задержка обычно составляет несколько минут.

Высокопроизводительные альтернативы

Для рабочих процессов, требующих очень высокой пропускной способности, рассмотрите возможность использования GeoBeam для перемещения данных из Earth Engine в BigQuery . Это требует дополнительной настройки и инфраструктуры, поэтому мы предлагаем начать со встроенной функции Earth Engine.

Цены

Экспорт в BigQuery — это пакетный процесс, который занимает пакетное время EECU. Если вы используете Earth Engine на коммерческой основе или в эксплуатации, при экспорте данных в BigQuery с вас взимается плата за время EECU, используемое задачами. Все использование можно отслеживать с помощью тех же инструментов мониторинга , которые работают для остальной части Earth Engine.

Облачные платежные аккаунты

Чтобы записывать данные в BigQuery, в связанном облачном проекте должен быть включен платежный аккаунт. Дополнительную информацию о настройке платежного аккаунта см. в документации по платежному аккаунту Cloud .

Выход

Все входящие и исходящие затраты тарифицируются как стандартный сетевой трафик.

Earth Engine размещается только в США, но наборы данных BigQuery могут размещаться в ряде других регионов . В зависимости от регионов и объемов данных запись данных из Earth Engine в BigQuery может генерировать значительный сетевой трафик.

Известные проблемы

Ориентация для больших полигонов

Функция экспорта BigQuery инвертирует многоугольники, размер которых превышает полусферу, меняя их ориентацию на противоположную (изменяя многоугольник на его геометрическое дополнение). В редких случаях полигоны размером больше полусферы могут не загружаться.

При необходимости инвертированные полигоны можно исправить в BigQuery, снова инвертировав их с помощью выражения BigQuery ST_Difference(ST_GeogFromText('fullglobe'), geo) .

Дополнительную информацию см. здесь .