Чтение из BigQuery

Примечание: Функции ee.FeatureCollection.loadBigQueryTable() и ee.FeatureCollection.runBigQuery() находятся в режиме Preview . Чтобы запросить поддержку или оставить отзыв о них, отправьте электронное письмо по адресу [e-mail] .

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

Загрузить данные из BigQuery

Предварительная версия: Функция ee.FeatureCollection.loadBigQueryTable() находится в стадии предварительной версии и может измениться.

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

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

Питон

# 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-часов, использованных при обработке запроса, выставляется вызывающей стороне, как и для любого другого метода Earth Engine (см. обзор EECU ).

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

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

Предварительная версия: Функция ee.FeatureCollection.runBigQuery() находится в стадии предварительной версии и может измениться.

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

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

Питон

# 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 .

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

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

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

Чтобы использовать эту функцию, в проекте Cloud вызывающей стороны должны быть включены API BigQuery и API BigQuery Storage. Следуйте инструкциям на странице Включить 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 не поддерживает проверки равенства ARRAY. В таких случаях мы не транслируем фильтр, а вместо этого применяем его в 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() не поддерживает ресурсы из Linked Datasets . Попытка загрузить данные из такой таблицы приводит к ошибке «таблица не найдена».

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

  JavaScript

  var features = ee.FeatureCollection.runBigQuery({
    query: 'SELECT * FROM my_project.my_linked_dataset.my_table',
    geometryColumn: 'geo'
  });
        

  Питон

  features = ee.FeatureCollection.runBigQuery(
    query='SELECT * FROM my_project.my_linked_dataset.my_table',
    geometryColumn='geo')
        

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

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