Ler pelo BigQuery

Esta página descreve como integrar tabelas do BigQuery a fluxos de trabalho do Earth Engine como objetos ee.FeatureCollection usando os métodos ee.FeatureCollection.loadBigQueryTable() e ee.FeatureCollection.runBigQuery().

Carregar dados do BigQuery

A função ee.FeatureCollection.loadBigQueryTable() lê uma tabela do BigQuery em um objeto ee.FeatureCollection. Ele se conecta a uma tabela especificada, converte todos os tipos de dados, aplica os filtros e seletores necessários e adiciona a indexação à coleção, se necessário. A função usa o ambiente interativo do Earth Engine, retornando resultados diretamente ao cliente para serem visualizados ou usados como um componente de uma análise maior.

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

Faturamento

O custo das horas de EECU usadas durante o processamento da solicitação é cobrado do autor da chamada, como em qualquer outro método do Earth Engine. Consulte a Visão geral das EECUs.

Não há custos adicionais do BigQuery associados à transferência dos dados para o Earth Engine. O uso correspondente do BigQuery vai aparecer no Painel da API do Google Cloud do projeto usado. Consulte Monitorar o uso da API, mas nenhum custo será gerado para ler os dados do BigQuery dessa forma.

Consultar dados do BigQuery

O método ee.FeatureCollection.runBigQuery() executa uma consulta SQL do BigQuery e retorna os resultados como um objeto ee.FeatureCollection. Consulte Executar um documento de consulta para saber mais sobre consultas.

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

Consultas do BigQuery

Cada chamada para ee.FeatureCollection.runBigQuery() inicializa um job de consulta do BigQuery (consulte mais informações sobre consultas na documentação de execução de uma consulta), permitindo que você use os principais recursos do BigQuery:

  • Histórico de jobs: acesse um histórico de seis meses das execuções de consulta do seu projeto. Saiba mais em Listar jobs.
  • Armazenamento em cache de consultas: o BigQuery armazena automaticamente os resultados das consultas em cache, quando possível. Consultas idênticas subsequentes extraem dados do cache, evitando cobranças redundantes. Para saber mais, consulte Como usar resultados de consulta em cache.

Para saber mais sobre consultas ou como usá-las no BigQuery, consulte a documentação do BigQuery.

Faturamento

O custo das EECUs usadas durante o processamento da solicitação é cobrado do autor da chamada, como em qualquer outro método do Earth Engine (consulte a Visão geral das EECUs). Além disso, a execução de uma consulta é faturada para o autor da chamada de acordo com o modelo de faturamento do BigQuery.

Não há custos adicionais do BigQuery associados à transferência dos dados para o Earth Engine. O uso correspondente do BigQuery vai aparecer no Painel da API do Google Cloud do projeto usado. Consulte Monitorar o uso da API, mas nenhum custo será gerado para ler os dados do BigQuery dessa forma.

Para controlar os custos potenciais associados a ee.FeatureCollection.runBigQuery(), o parâmetro maxBytesBilled atua como uma proteção. Qualquer job do BigQuery que exceda esse limite vai falhar e não será cobrado. O valor padrão de maxBytesBilled é 100 GB. Se a chamada for bloqueada por exceder esse limite, especifique um valor diferente no script.

Pré-requisitos e permissões

Para usar esse recurso, o projeto do Cloud do autor da chamada precisa ter a API BigQuery e a API BigQuery Storage ativadas. Siga as instruções na página Ativar a API para ativar as APIs adequadas.

Além das funções e permissões padrão do Earth Engine, você precisa ter acesso de leitura à tabela do BigQuery referenciada, permissão para criar sessões de leitura e jobs no projeto de destino. As permissões específicas do BigQuery necessárias são:

  • bigquery.tables.get (em qualquer tabela acessada)
  • bigquery.tables.getData (em qualquer tabela acessada)
  • bigquery.readSession.create
  • bigquery.jobs.create

Consulte a documentação do controle de acesso do BigQuery para informações detalhadas sobre como gerenciar permissões.

Filtragem de dados

Cada ee.FeatureCollection pode ser filtrado usando o método .filter(Filter). Para permitir que os usuários do Google Earth Engine se beneficiem do processamento de dados tabulares altamente paralelos do BigQuery, traduzimos os filtros do Earth Engine para uma linguagem que o BigQuery entende e os enviamos com uma solicitação de leitura de tabela. Essa abordagem move o processamento de filtro para a pilha do BigQuery, mas também está sujeita a duas limitações:

  1. Como todas as outras consultas no BigQuery (consulte Cotas do BigQuery), essa solicitação é limitada a 10 MB. Isso significa que os filtros transmitidos não podem ser muito complicados. O limite de 10 MB resulta no seguinte erro:

    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.

    A filtragem por geometrias que contêm muitos vértices é uma causa comum desse erro. Para resolver esse problema, use ee.Geometry.simplify() no objeto problemático.

  2. Alguns filtros mais complicados do Earth Engine não podem ser convertidos nos equivalentes do BigQuery. Por exemplo, o BigQuery não oferece suporte a verificações de igualdade de ARRAY. Nesses casos, não traduzimos o filtro, mas o aplicamos no Earth Engine depois de ler os dados.

Indexação de dados

As coleções do Earth Engine dependem da indexação interna, enquanto o BigQuery não recomenda manter tabelas indexadas. Para fazer com que esses dois sistemas funcionem juntos, criamos índices de coleção da seguinte maneira:

  • Se a tabela do BigQuery tiver uma coluna chamada system:index, ela será usada para indexar FeatureCollection.

    Nesses casos, cabe ao autor da chamada garantir que os índices sejam exclusivos. Caso contrário, a coleção pode apresentar um comportamento inesperado. O índice de recursos precisa ser uma string não vazia. Portanto, o carregamento da tabela do BigQuery com um valor que não seja uma string ou null para uma coluna system:index vai falhar.

  • Se a tabela do BigQuery não tiver a coluna system:index, ela será gerada automaticamente.

    Os índices entre duas solicitações de leitura são estáveis, mas somente se as solicitações forem exatamente iguais, levando em consideração os filtros. Caso contrário, não podemos confiar em índices para corresponder aos mesmos recursos. Portanto, se o indexação de dados exatamente únicos for importante para o autor da chamada, recomendamos adicionar a coluna system:index no BigQuery manualmente.

Limitações

  • O tamanho de todas as colunas selecionadas da tabela referenciadas em uma chamada ee.FeatureCollection.loadBigQueryTable() é limitado a 400 GB. Ao atingir esse limite, ocorrerá o seguinte erro:

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

    Nesses casos, escolha seletores mais restritivos para as colunas necessárias de leitura somente ou use ee.FeatureCollection.runBigQuery() para pré-processar a tabela no BigQuery e reduzir a quantidade de dados buscados.

  • O método ee.FeatureCollection.runBigQuery() impõe um limite de 10 GB nos tamanhos de resultados de consulta. Embora as tabelas de origem possam ter tamanho arbitrário, o processamento de volumes maiores de dados aumenta os custos de consulta.

  • O tamanho do filtro traduzido é limitado a 10 MB. Consulte a seção Filtragem de dados para mais detalhes.

  • O uso de ee.FeatureCollection.loadBigQueryTable() ou ee.FeatureCollection.runBigQuery() não está disponível com apps do Earth Engine.

Advertências

  • O ee.FeatureCollection.loadBigQueryTable() não oferece suporte a recursos de conjuntos de dados vinculados. Tentar carregar dados dessa tabela resulta no erro "tabela não encontrada".

    Como solução alternativa, execute ee.FeatureCollection.runBigQuery() com uma consulta que especifique a tabela solicitada do conjunto de dados vinculado. Por exemplo:

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

  • A mesclagem em system:index para tabelas do BigQuery com IDs gerados automaticamente pode levar a comportamentos inesperados. Para evitar isso, considere adicionar system:index à tabela do BigQuery manualmente ou mesclar a tabela em uma propriedade diferente. Leia mais sobre a indexação na seção "Indexação de dados".

  • O método ee.FeatureCollection.randomColumn() não funciona com IDs gerados automaticamente pelo BigQuery. Considere especificar uma chave alternativa usando o parâmetro rowKeys no método ee.FeatureCollection.randomColumn(). Também é possível adicionar manualmente colunas random ou system:index à tabela de origem do BigQuery. Leia mais sobre a indexação na seção "Indexação de dados".