Quando usar
Use este guia quando o seu time precisa enviar dados para a Uncover por uma integração customizada, ou seja, quando os dados não estão disponíveis por uma conexão nativa da plataforma.
Na prática, esse fluxo é indicado quando você mantém os dados em sistemas próprios, pipelines internos, data lakes, data warehouses ou outras fontes que precisam ser disponibilizadas para a Uncover em um formato controlado.
O objetivo é disponibilizar os dados para que a Uncover consiga consumi-los a partir de views ou tabelas no BigQuery.
Como a integração funciona
A integração customizada via GCS conecta 3 partes:
Seu pipeline: gera e envia os arquivos de dados em formato Parquet.
Bucket GCS da Uncover: recebe os arquivos enviados pelo seu time.
BigQuery da Uncover: lê os arquivos do bucket e disponibiliza os dados em tabelas e views para uso na plataforma.
O destino final dos dados é o BigQuery. Depois que os arquivos chegam ao bucket, a Uncover cria uma external table para leitura dos arquivos e uma view para expor a versão mais recente dos dados.
Para consumo na plataforma, a recomendação é usar sempre a view final criada pela Uncover, e não a external table bruta.
Visão geral do fluxo
A integração customizada funciona em 6 etapas:
A Uncover confirma os pré-requisitos com você.
A Uncover provisiona a infraestrutura de recebimento de dados, incluindo bucket, permissões e automações.
A Uncover envia a chave de acesso ao contato técnico informado, seguindo um processo seguro.
Você configura o pipeline de envio recorrente, seguindo o padrão de pastas e arquivos.
A Uncover valida o primeiro envio e cria as tabelas e views no BigQuery.
Com as views prontas, a Uncover conclui a conexão na plataforma.
O que você precisa preparar
Antes de iniciar a configuração técnica, alinhe com a Uncover:
A lista de tabelas que serão enviadas.
O nome exato de cada tabela.
O contato técnico responsável, com nome, cargo, e-mail e telefone.
A frequência de envio dos dados.
Se o envio será sempre completo ou, em caso de inviabilidade, incremental.
Depois, garanta que o seu time consegue:
Gerar arquivos em Parquet.
Automatizar o envio recorrente dos arquivos.
Manter o schema consistente ao longo do tempo.
Autenticar no GCS usando uma Service Account Key (JSON) enviada pela Uncover.
Confirmar o primeiro envio para validação técnica.
Sempre que possível, envie a tabela completa em cada carga. O envio incremental só deve ser usado quando o envio completo não for viável e precisa ser alinhado previamente com a Uncover.
Como devem ser os dados recebidos
Formato dos arquivos
Os arquivos devem ser enviados em formato Parquet.
Esse formato é necessário para que a Uncover consiga criar external tables no BigQuery a partir dos arquivos armazenados no bucket.
Para evitar falhas de leitura:
Use sempre o mesmo formato de arquivo.
Evite enviar CSV, Excel, JSON ou outros formatos nesse fluxo.
Não compacte o arquivo Parquet antes do envio, a menos que isso tenha sido alinhado com a Uncover.
Estrutura de pastas e arquivos
Use este padrão de caminho:
gs://uncover-data-loading-{client_name}/{nome_da_tabela}/_updated_at={timestamp}/{arquivo}.parquet
Cada parte do caminho tem uma função:
{client_name}: identificador da conta, informado pela Uncover.{nome_da_tabela}: nome exato da tabela. Esse nome vira o diretório da tabela no bucket._updated_at={timestamp}: versão do envio. Use um timestamp Unix inteiro, como1756384304.{arquivo}.parquet: nome do arquivo. Recomendamos incluir a data ou outro identificador que ajude o seu time a rastrear o envio.
Exemplo:
gs://uncover-data-loading-acme/vendas/_updated_at=1756384304/vendas-2026-04-14.parquet
Nesse exemplo:
acmeé o identificador da conta.vendasé o nome da tabela.1756384304é o timestamp Unix do envio.vendas-2026-04-14.parqueté o arquivo enviado.
O nome do diretório da tabela precisa ser estável. Se o seu time enviar vendas
em um dia e vendas_diarias em outro, a Uncover entenderá como tabelas diferentes.
Conteúdo e consistência do schema
Para evitar falhas e retrabalho:
Mantenha o mesmo schema ao longo do tempo, com os mesmos nomes e tipos de colunas.
Evite alterar o tipo de uma coluna já enviada, por exemplo, enviar uma coluna como número em um dia e como texto no outro.
Evite renomear colunas sem alinhamento prévio.
Evite remover colunas sem alinhamento prévio.
Combine previamente com a Uncover qualquer mudança estrutural no dado.
Mudanças de schema podem exigir ajustes nas tabelas, views ou na conexão da plataforma.
Envio completo e envio incremental
Envio completo
No modelo ideal, cada carga contém todos os dados de cada tabela enviada.
Nesse caso, a Uncover usa a partição mais recente, identificada pelo maior _updated_at, para expor a versão atual da tabela na view final.
Use esse modelo sempre que o volume de dados permitir.
Envio incremental
Quando não for viável enviar a tabela completa, o envio incremental pode ser combinado com a Uncover.
Nesse modelo:
Você faz uma primeira carga histórica com dados a partir de uma data acordada.
A partir do dia seguinte, você envia diariamente os dados do dia anterior.
Você informa uma coluna como chave de deduplicação.
Você informa uma coluna como chave de ordenação.
Para compor o dado completo, a Uncover considera todos os envios, ordena pela chave de ordenação e mantém a última ocorrência de cada chave de deduplicação.
O envio incremental é mais sensível a falhas. Use esse modelo apenas quando o envio completo não for viável e depois de alinhar as regras de deduplicação e ordenação com a Uncover.
Passo a passo
1. Confirmar pré-requisitos
A Uncover só inicia o envio de credenciais depois que estes pontos estão confirmados:
Contrato confirmado.
NDA assinado.
Contato técnico validado.
Nomes das tabelas confirmados.
Estrutura esperada dos dados alinhada.
Essas confirmações ajudam a garantir que a chave seja enviada para a pessoa correta e que a infraestrutura seja criada com os nomes e permissões adequados.
2. Receber a chave de acesso
A autenticação no bucket é feita por uma Service Account Key (JSON).
O envio da chave segue um processo seguro:
A chave é compactada em um arquivo
.zipcom senha forte.O
.zipé enviado por e-mail para o contato técnico responsável.A senha é transmitida separadamente, via Gmail Confidential Mode.
A Uncover confirma o recebimento e solicita confirmação formal por e-mail.
A senha do .zip nunca deve ser enviada no mesmo canal do arquivo.
A chave permite listagem, escrita e deleção no bucket. Por segurança, ela não permite leitura. Isso significa que não é possível baixar dados previamente enviados.
3. Configurar o pipeline de envio
Depois de receber a chave, configure o pipeline do seu time para:
Gerar o arquivo Parquet.
Gravar o arquivo no diretório correto da tabela.
Incluir o
_updated_atcomo timestamp Unix inteiro no caminho.Enviar os arquivos para o bucket informado pela Uncover.
Executar o envio com a recorrência combinada.
Checklist rápido antes de enviar
O arquivo está em Parquet.
O diretório
{nome_da_tabela}está correto.O
_updated_até um timestamp Unix inteiro.O schema está consistente com os envios anteriores.
O envio foi concluído sem erro no pipeline do seu time.
4. Fazer o primeiro upload de teste
Recomendamos que o primeiro envio seja tratado como um teste controlado.
Depois do upload, valide com a Uncover:
Se o arquivo chegou ao bucket.
Se o caminho segue o padrão esperado.
Se o arquivo está em Parquet.
Se o schema pode ser lido corretamente.
Se o nome da tabela está correto.
Se houver erro de path, formato ou schema, ajuste o pipeline e faça um novo envio.
5. Entender o que acontece depois do upload
Para cada tabela enviada, a Uncover cria:
raw__{nome_da_tabela}: external table que lê os arquivos Parquet no bucket.{nome_da_tabela}: view que expõe a versão mais recente dos dados, com base no maior_updated_at.
Exemplo:
Diretório enviado | External table criada | View para consumo |
|
|
|
|
|
|
Use sempre a view ({nome_da_tabela}) para consumir o dado mais recente. A external table raw__{nome_da_tabela} é uma camada técnica de leitura dos arquivos no bucket.
6. Concluir a conexão na plataforma Uncover
Com as views prontas no BigQuery, a Uncover conclui a conexão na plataforma usando o conector de BigQuery.
Nessa etapa, a Uncover pode solicitar validações adicionais, como:
confirmação de quais views devem ser consumidas,
validação de acesso,
conferência de campos esperados,
confirmação de que os dados mais recentes estão aparecendo corretamente.
Prazos
Os prazos abaixo são uma referência para planejamento. Eles começam a contar depois que os pré-requisitos estiverem confirmados: contrato, NDA, contato técnico, nomes das tabelas e estrutura esperada dos dados.
Os prazos podem variar conforme o volume de dados, a complexidade do schema, a disponibilidade do contato técnico e a necessidade de ajustes no primeiro envio.
Prazos por etapa
Etapa | O que precisa estar pronto | Prazo de referência |
Envio da chave de acesso | Contrato, NDA, contato técnico, bucket e nomes das tabelas confirmados | De 1 a 3 dias úteis, conforme a prioridade da solicitação |
Primeiro upload de teste | Pipeline configurado para gerar e enviar 1 arquivo Parquet no padrão combinado | Depende do prazo interno do seu time |
Validação do primeiro envio | Arquivo enviado no bucket, com path, formato e schema corretos | Até 1 dia útil após o primeiro envio, se não houver ajustes no formato |
Criação de tabelas e views no BigQuery | Primeiro envio validado e nomes de tabela confirmados | Até 1 dia útil após o envio validado |
Conexão na plataforma Uncover | Views prontas e escopo de consumo confirmado | Até 1 dia útil após as views estarem prontas |
O prazo mais variável costuma ser o primeiro upload de teste, porque depende da configuração do pipeline pelo seu time técnico.
Problemas comuns
Os problemas mais comuns são:
O arquivo não está em Parquet.
O path não segue o padrão do bucket.
O
_updated_atnão é um timestamp Unix inteiro.O schema mudou sem alinhamento prévio.
O primeiro envio não contém dados suficientes para validar a estrutura.
Ter nome de campo igual nome da tabela (no caso nome da tabela vai ser o nome da pasta onde estão os arquivos).
Nome de campo não segue a regra de nomenclatura do BQ:
Deve conter apenas letras, números e sublinhados (underscore).
Começar com uma letra ou sublinhado.
Ter no máximo 300 caracteres.
Nomes duplicados na mesma tabela, mesmo com diferença de maiúsculas e minúsculas.
Segurança
A chave enviada é uma Service Account Key (JSON) com permissões restritas ao bucket.
A chave permite listagem, escrita e deleção.
A chave não permite leitura.
A chave é exclusiva para envio de dados ao bucket informado pela Uncover.
Não use a mesma chave em outros contextos.
Não compartilhe a chave fora do time responsável pelo pipeline.
Você não consegue baixar arquivos previamente enviados usando essa chave. Essa restrição reduz o risco de exposição de dados já carregados no bucket.
Rotação de chaves
A rotação é obrigatória a cada 90 dias corridos, contados a partir da emissão da chave.
O fluxo é:
D-14: a Uncover avisa sobre a renovação e agenda o envio da nova chave.
D-0: a nova chave é enviada seguindo o mesmo protocolo seguro.
Após a confirmação de que a nova chave está funcionando, a chave anterior é revogada.
Revogação imediata
A chave pode ser revogada antes da rotação em situações como:
encerramento de contrato,
solicitação formal,
suspeita de vazamento ou comprometimento,
mudança de bucket,
mudança de tecnologia,
necessidade de substituição emergencial da credencial.
Ainda com dúvidas? Nossa equipe está pronta para ajudar! Fale conosco pelo suporte ou envie um e-mail para [email protected]