Чтение из BigQuery

На этой странице описывается, как интегрировать таблицы BigQuery в рабочие процессы Earth Engine в виде объектов ee.FeatureCollection , используя методы ee.FeatureCollection.loadBigQueryTable() и ee.FeatureCollection.runBigQuery() .

Загрузка данных из BigQuery

Функция ee.FeatureCollection.loadBigQueryTable() автоматически считывает данные из таблицы BigQuery в объект ee.FeatureCollection . Она подключается к указанной таблице, преобразует все типы данных, применяет необходимые фильтры и селекторы , а также, при необходимости, добавляет индексы к коллекции. Функция использует интерактивную среду Earth Engine, возвращая результаты непосредственно клиенту для просмотра или использования в качестве компонента более крупного анализа.

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

Выставление счетов

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

Передача данных в Earth Engine не влечет за собой дополнительных затрат на использование BigQuery. Соответствующее использование BigQuery будет отображаться на панели мониторинга Google Cloud API используемого проекта (см. раздел «Мониторинг использования API» ), но за чтение данных BigQuery таким способом плата взиматься не будет.

Запрос данных из BigQuery

Метод ee.FeatureCollection.runBigQuery() выполняет SQL-запрос BigQuery и возвращает результаты в виде объекта ee.FeatureCollection (подробнее о запросах см. в документации по выполнению запросов).

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

Каждый вызов метода ee.FeatureCollection.runBigQuery() инициирует отдельное задание запроса BigQuery (подробнее о запросах см. в документации по выполнению запросов ), что позволяет использовать ключевые возможности BigQuery:

• История заданий : получите доступ к истории выполнения запросов по вашему проекту за последние шесть месяцев (подробнее см. в разделе «Список заданий» ).
• Кэширование запросов : BigQuery автоматически кэширует результаты запросов, если это возможно. Последующие идентичные запросы извлекают данные из кэша, предотвращая избыточные расходы (подробнее см. в разделе « Использование кэшированных результатов запросов »).

Чтобы узнать о запросах или о том, как использовать их в BigQuery, см. документацию BigQuery .

Выставление счетов

Стоимость использования блоков EECU при обработке запроса оплачивается вызывающей стороной так же, как и при любом другом методе Earth Engine (см. обзор блоков EECU ). Кроме того, выполнение запроса оплачивается вызывающей стороной в соответствии с моделью выставления счетов BigQuery .

Передача данных в Earth Engine не влечет за собой дополнительных затрат на использование BigQuery. Соответствующее использование BigQuery будет отображаться на панели мониторинга Google Cloud API используемого проекта (см. раздел «Мониторинг использования API» ), но за чтение данных BigQuery таким способом плата взиматься не будет.

Для контроля потенциальных затрат, связанных с ee.FeatureCollection.runBigQuery() , параметр maxBytesBilled служит защитой. Любое задание BigQuery, превышающее этот лимит, завершится с ошибкой и не будет оплачено. Значение maxBytesBilled по умолчанию составляет 100 ГБ. Если ваш вызов заблокирован из-за превышения этого лимита, вы можете указать другое значение в своем скрипте.

Предварительные условия и разрешения

Для использования этой функции в облачном проекте вызывающей стороны должны быть включены API BigQuery и API хранилища BigQuery. Следуйте инструкциям на странице «Включить API» , чтобы активировать соответствующие API.

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

• bigquery.tables.get (для любой таблицы, к которой осуществляется доступ)
• bigquery.tables.getData (для любой таблицы, к которой осуществляется доступ)
• bigquery.readSession.create
• bigquery.jobs.create

Подробную информацию об управлении разрешениями см. в документации по управлению доступом BigQuery .

Фильтрация данных

Каждый ee.FeatureCollection можно отфильтровать с помощью метода .filter(Filter) . Чтобы пользователи Google Earth Engine могли воспользоваться преимуществами высокопараллельной обработки табличных данных BigQuery, мы переводим фильтры Earth Engine на язык, понятный BigQuery, и отправляем их вместе с запросом на чтение таблицы. Такой подход действительно переносит обработку фильтров в стек BigQuery, но он также имеет два ограничения:

1. Как и любой другой запрос в BigQuery (см. квоты BigQuery ), этот запрос ограничен размером в 10 МБ. Это означает, что передаваемые фильтры не могут быть слишком сложными. Превышение лимита в 10 МБ приводит к следующей ошибке:

   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.

   Распространенной причиной этой ошибки является фильтрация по геометрическим объектам, содержащим много вершин. Для решения этой проблемы рассмотрите возможность использования метода ee.Geometry.simplify() для проблемного объекта.

2. Некоторые более сложные фильтры Earth Engine нельзя преобразовать в их аналоги в BigQuery. Например, BigQuery не поддерживает проверку равенства массивов. В таких случаях мы не преобразуем фильтр, а применяем его в Earth Engine после считывания данных.

Индексирование данных

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

• Если таблица BigQuery содержит столбец с именем system:index , мы используем его для индексации FeatureCollection.

  В таких случаях ответственность за уникальность индексов лежит на вызывающей стороне. В противном случае коллекция может вести себя непредсказуемым образом. Индекс функции должен быть непустой строкой, поэтому загрузка таблицы BigQuery с нестроковым или null значением для столбца system:index завершится ошибкой.

• Если таблица BigQuery не содержит столбец system:index , он генерируется автоматически.

  Индексы между двумя запросами на чтение стабильны, но только если запросы абсолютно одинаковы и учитывают фильтры. В противном случае мы не можем полагаться на то, что индексы будут соответствовать одним и тем же характеристикам. Поэтому, если для вызывающей стороны важна точная и уникальная индексация данных, мы рекомендуем добавлять столбец system:index в BigQuery вручную.

Ограничения

• Размер всех выбранных столбцов таблицы, на которую ссылается вызов ee.FeatureCollection.loadBigQueryTable() , ограничен 400 ГБ. Превышение этого лимита приведет к следующей ошибке:

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

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

• Метод ee.FeatureCollection.runBigQuery() устанавливает ограничение в 10 ГБ на размер результатов запроса. Хотя исходные таблицы могут иметь произвольный размер, обработка больших объемов данных увеличит стоимость запроса.

• Размер переведенного фильтра ограничен 10 МБ. Подробности см. в разделе «Фильтрация данных» .

• Использование ee.FeatureCollection.loadBigQueryTable() или ee.FeatureCollection.runBigQuery() недоступно в приложениях Earth Engine.

Предостережения

• Метод ee.FeatureCollection.loadBigQueryTable() не поддерживает ресурсы из связанных наборов данных . Попытка загрузки данных из такой таблицы приводит к ошибке "таблица не найдена".

  В качестве обходного пути рассмотрите возможность запуска ee.FeatureCollection.runBigQuery() с запросом, указывающим на запрашиваемую таблицу из связанного набора данных. Например:

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

• Объединение таблиц BigQuery с автоматически генерируемыми идентификаторами по system:index может привести к непредсказуемому поведению. Чтобы этого избежать, рассмотрите возможность добавления параметра system:index к таблице BigQuery вручную или объединения таблиц по другому параметру. Подробнее об индексировании см. в разделе «Индексирование данных» .

• Метод ee.FeatureCollection.randomColumn() не работает с автоматически генерируемыми идентификаторами BigQuery. Рекомендуется указать альтернативный ключ с помощью параметра rowKeys в методе ee.FeatureCollection.randomColumn() . Вы также можете вручную добавить random или столбцы system:index в исходную таблицу BigQuery. Подробнее об индексировании см. в разделе «Индексирование данных» .