O motor BigQuery permite ler dados de uma tabela no Google BigQuery e gravar dados nela, incluindo em conjuntos de dados públicos.
A leitura usa a API REST do BigQuery (tabledata.list), portanto, apenas tabelas nativas podem ser lidas (visões, visões materializadas e tabelas externas não podem). A gravação usa inserções por streaming (tabledata.insertAll), o que exige que o faturamento esteja habilitado para o projeto.
As gravações não são atômicas: um INSERT grande é enviado em lotes (no máximo 500 linhas por solicitação e também dividido para permanecer abaixo do limite de 10 MB para o tamanho das solicitações do BigQuery), uma única solicitação pode ser parcialmente bem-sucedida (o BigQuery pode confirmar algumas linhas de uma solicitação e rejeitar outras com insertErrors) e um lote posterior pode ser rejeitado após lotes anteriores terem sido aceitos — em ambos os casos, as linhas já confirmadas permanecem no BigQuery enquanto a consulta relata um erro. Cada linha contém um insertId estável (derivado do ID da consulta e da posição ordinal da linha), para que o BigQuery deduplique, na medida do possível, as linhas reenviadas; como o insertId depende da posição ordinal, executar novamente o mesmo INSERT deduplica apenas quando as linhas são apresentadas na mesma ordem (por exemplo, em modo de thread única, com max_threads = 1 e max_insert_threads = 1). Consulte as limitações da função de tabela bigquery para obter detalhes.
A lista de colunas é opcional: quando omitida, a estrutura é inferida a partir do esquema da tabela do BigQuery. Quando especificadas, as colunas podem ser um subconjunto das colunas do BigQuery, e cada coluna deve ser declarada com o tipo exato para o qual o esquema do BigQuery é mapeado (consulte o mapeamento de tipos de dados). Uma tabela cuja definição omite um campo REQUIRED do BigQuery sem uma expressão de valor padrão pode ser lida, mas não receber gravações: as inserções por streaming do BigQuery rejeitam linhas que omitem esse campo; portanto, esse INSERT é rejeitado antecipadamente. Quando o campo REQUIRED omitido declara uma defaultValueExpression, o BigQuery preenche o valor padrão, e a tabela continua aceitando gravações. Um RECORD NULLABLE é mapeado para Nullable(Tuple(...)) para que registros NULL possam ser gravados e lidos sem perda; criar essa tabela, seja com a estrutura inferida ou declarada explicitamente, requer a configuração enable_nullable_tuple_type, como ocorre com qualquer coluna Nullable(Tuple). Ao declarar colunas explicitamente, um campo RECORD pode ser declarado como um Tuple(...) simples para evitar essa configuração, ao custo de converter um NULL do registro inteiro em uma tupla padrão; a única diferença aceita em relação ao tipo inferido é remover o Nullable que envolve o Tuple de um RECORD, e somente nesse mesmo registro — a anulabilidade não pode ser transferida para outro registro, interno ou externo.
Parâmetros do motor
project — O projeto do Google Cloud proprietário do conjunto de dados.dataset — O nome do conjunto de dados.table — O nome da tabela.access_token — Um token de acesso OAuth 2.0 (argumento posicional opcional).
Os parâmetros também podem ser informados como uma coleção nomeada, com substituições key = value. Consulte a função de tabela bigquery para ver a lista completa de chaves e a descrição dos métodos de autenticação. Exatamente um método de autenticação deve ser fornecido; para uma tabela permanente, uma service_account_key ou um refresh_token é preferível a um access_token, pois os tokens de acesso expiram em uma hora.
Última modificação em 14 de agosto de 2026
