Ler pelo BigQuery

Nesta página, descrevemos como integrar tabelas do BigQuery aos 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 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 é faturado ao 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 de dados para o Earth Engine. O uso correspondente do BigQuery vai aparecer no painel de APIs do Google Cloud do projeto usado (consulte Monitorar o uso da API), mas não haverá custos para ler 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 Documento "Executar uma 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() inicia um job de consulta do BigQuery separado. Para saber mais sobre consultas, consulte a documentação de como executar uma consulta. Assim, você pode usar os principais recursos do BigQuery:

• Histórico de jobs: acesse um histórico de seis meses das execuções de consultas 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 recuperam dados do cache, evitando cobranças redundantes. Saiba mais em Como usar resultados de consulta armazenados 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 é faturado ao autor da chamada, como em qualquer outro método do Earth Engine (consulte Visão geral das EECUs). Além disso, a execução de uma consulta é cobrada do autor da chamada de acordo com o modelo de faturamento do BigQuery.

Não há custos adicionais do BigQuery associados à transferência de dados para o Earth Engine. O uso correspondente do BigQuery vai aparecer no painel de APIs do Google Cloud do projeto usado (consulte Monitorar o uso da API), mas não haverá custos para ler dados do BigQuery dessa forma.

Para controlar os custos potenciais associados ao ee.FeatureCollection.runBigQuery(), o parâmetro maxBytesBilled atua como uma proteção. Qualquer job do BigQuery que exceder 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 Google Cloud do usuário precisa ter a API BigQuery e a API BigQuery Storage ativadas. Siga as instruções na página "Ativar API" para ativar as APIs adequadas.

Além dos papéis e permissões padrão do Earth Engine, você precisa ter acesso de leitura à tabela do BigQuery referenciada e permissão para criar sessões e jobs de leitura 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 de 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 do BigQuery altamente paralelizado, traduzimos os filtros do Earth Engine para uma linguagem compreensível pelo BigQuery e os enviamos junto com uma solicitação de leitura de tabela. Essa abordagem move o processamento de filtros 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 tem um limite de tamanho de 10 MB. Isso significa que os filtros aprovados não podem ser muito complicados. Exceder 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.

   Filtrar 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 para os 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 e 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 coleta da seguinte maneira:

• Se a tabela do BigQuery tiver uma coluna chamada system:index, vamos usá-la para indexar FeatureCollection.

  Nesses casos, cabe ao autor da chamada garantir que os índices sejam exclusivos. Caso contrário, a coleta pode se comportar de maneira inesperada. O índice de recursos precisa ser uma string não vazia. Portanto, o carregamento de uma tabela do BigQuery com um valor não 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, considerando os filtros. Caso contrário, não podemos confiar em índices para corresponder aos mesmos recursos. Portanto, se a indexação de dados precisamente únicos for importante para o usuário, recomendamos adicionar manualmente a coluna system:index no BigQuery.

Limitações

• O tamanho de todas as colunas selecionadas da tabela referenciada em uma chamada de ee.FeatureCollection.loadBigQueryTable() é limitado a 400 GB. Se você atingir esse limite, vai receber 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, considere escolher seletores mais restritivos para ler apenas as colunas necessárias ou use ee.FeatureCollection.runBigQuery() para pré-processar a tabela no BigQuery e diminuir a quantidade de dados buscados.

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

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

• Não é possível usar ee.FeatureCollection.loadBigQueryTable() ou ee.FeatureCollection.runBigQuery() com apps do Earth Engine.

Advertências

• O ee.FeatureCollection.loadBigQueryTable() não é compatível com 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 especifica 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 junção em system:index para tabelas do BigQuery com IDs gerados automaticamente pode resultar em comportamentos inesperados. Para evitar que isso aconteça, considere adicionar system:index à tabela do BigQuery manualmente ou fazer a junção da tabela em uma propriedade diferente. Leia mais sobre indexação na seção Indexação de dados.

• O método ee.FeatureCollection.randomColumn() não funciona com IDs gerados automaticamente do 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 indexação na seção Indexação de dados.