# upFiles - finalidade e papel no processo de dados
[](https://estante-ses.sorocaba.sp.gov.br/uploads/images/gallery/2025-12/axgimage.png)
## Criação de tabelas e estruturação de dados
O [upFiles](https://saudedigital.sorocaba.sp.gov.br/upFiles/) <[https://saudedigital.sorocaba.sp.gov.br/upFiles/](https://saudedigital.sorocaba.sp.gov.br/upFiles/)> é uma ferramenta desenvolvida internamente pela Saúde Digital para suprir limitações identificadas em soluções de upload de dados utilizadas de forma nativa por ferramentas de análise. Seu principal objetivo é permitir a **criação de tabelas em banco de dados PostgreSQL a partir de planilhas**, de forma padronizada, controlada e reutilizável, viabilizando análises posteriores no Metabase.
Diferentemente de soluções mais simples de upload, o upFiles foi concebido para trabalhar com **grandes volumes de dados**, sem limitação prática de tamanho de arquivo, e para permitir maior controle sobre a estrutura das tabelas criadas. Essa abordagem se mostrou necessária especialmente diante das limitações dos relatórios extraídos de sistemas como o Sistema de Gestão Pública de Saúde, que, em sua versão web, apresenta restrições significativas na organização e padronização dos dados.
### Preparação prévia dos dados
Antes de iniciar qualquer processo no upFiles, é fundamental que os dados estejam organizados em formato de **planilha padrão**, com informações separadas por colunas, cada coluna representando um único tipo de dado. Essa organização é essencial para que o sistema consiga interpretar corretamente a estrutura do arquivo.
Em situações em que o relatório não apresenta cabeçalho adequado, o upFiles possui uma tratativa básica para identificar colunas a partir das primeiras linhas de dados. Nesses casos, colunas sem nome são criadas automaticamente e devem ser revisadas e renomeadas durante a etapa de configuração. Ainda assim, recomenda-se que os dados já sejam preparados previamente de forma estruturada, sempre que possível.
### Etapa 1 – Envio do arquivo para início do processamento
O processo de criação de tabela no upFiles começa com o **upload do arquivo**, momento em que o sistema passa a analisar a estrutura da planilha.
[](https://estante-ses.sorocaba.sp.gov.br/uploads/images/gallery/2025-12/oc8image.png)
Após o envio, o sistema realiza a leitura do arquivo e apresenta um **preview com as primeiras 20 linhas**, permitindo verificar como os dados foram interpretados antes de avançar para a configuração da tabela.
[](https://estante-ses.sorocaba.sp.gov.br/uploads/images/gallery/2025-12/VDsimage.png)
### Etapa 2 – Configuração da tabela
Na etapa de configuração, o usuário define como a tabela será criada no banco de dados. Quando o objetivo é criar uma nova base, deve ser mantida a opção **Criar nova tabela**.
[](https://estante-ses.sorocaba.sp.gov.br/uploads/images/gallery/2025-12/XpJimage.png)
A definição do **nome da tabela** é obrigatória. O próprio sistema aplica automaticamente um prefixo identificador às tabelas criadas pelo upFiles, permitindo que elas sejam facilmente reconhecidas no banco de dados e listadas separadamente de outras tabelas que não se originam da ferramenta.
#### Chave Primária (PK)
Nesta etapa também é possível definir uma **chave primária**, conhecida como PK. A chave primária é um campo que identifica unicamente cada registro da tabela, sendo utilizada para evitar duplicidades e permitir atualizações controladas dos dados.
Quando o relatório não possui um identificador único confiável, o upFiles permite a criação de uma **chave hash automática**, solução especialmente útil em cenários em que os sistemas de origem não fornecem uma chave primária adequada.
[](https://estante-ses.sorocaba.sp.gov.br/uploads/images/gallery/2025-12/6Y1image.png)
### Configuração das colunas
O upFiles utiliza, inicialmente, os nomes das colunas presentes na planilha, mas permite que esses nomes sejam editados para facilitar o uso futuro no Metabase. Para cada coluna, o sistema apresenta exemplos de valores, auxiliando na escolha do tipo de dado mais adequado.
Os tipos disponíveis incluem:
- Texto
- Inteiro
- Inteiro grande
- Decimal
- Data, com conversão ou já estruturada
- Hora
- Data e hora, com conversão ou já estruturada
[](https://estante-ses.sorocaba.sp.gov.br/uploads/images/gallery/2025-12/v00image.png)
Também existe a opção de **anonimização de colunas**, recurso importante para atendimento à LGPD, especialmente em casos em que os dados possam ser utilizados em painéis com acesso ampliado.
Adicionalmente, é possível criar **colunas customizadas com valor fixo**, utilizadas em situações específicas para facilitar a integração futura entre bases distintas no Metabase.
### Confirmação da estrutura da tabela
Ao final da configuração, a estrutura definida é confirmada. Nesta primeira execução, o sistema **apenas cria a tabela no banco de dados**, sem inserir os dados da planilha. Essa separação entre criação da tabela e carga de dados foi adotada como medida de segurança, garantindo maior controle sobre a estrutura antes da inserção efetiva das informações.
[](https://estante-ses.sorocaba.sp.gov.br/uploads/images/gallery/2025-12/sgyimage.png)
É importante destacar que a criação de tabelas no upFiles envolve conceitos de banco de dados e, por esse motivo, recomenda-se que essa etapa seja realizada por profissionais com maior familiaridade técnica ou sob orientação adequada.
As informações inseridas no sistema são registradas com identificação do responsável pelo envio e carimbo de data e hora, permitindo rastreabilidade e facilitando eventuais manutenções no banco de dados. Algumas ações, como a exclusão de tabelas, não são realizadas pela interface do upFiles e dependem de procedimentos técnicos diretos no banco de dados.
A próxima página deste capítulo apresenta a **etapa de upload de dados**, que consiste na inserção efetiva das informações na tabela já criada, processo consideravelmente mais simples e operacional.
---
## Upload de Dados em tabelas estruturadas
Após a criação e validação da estrutura de uma tabela no upFiles, a próxima etapa consiste no **upload dos dados propriamente ditos**. Essa fase é operacionalmente mais simples do que a criação da tabela, pois utiliza uma estrutura já definida previamente, reduzindo o risco de inconsistências estruturais.
Assim como na etapa inicial de criação, o processo começa com o **upload do arquivo**, seguido da visualização de um preview com as primeiras linhas, permitindo uma conferência visual para garantir que os dados foram interpretados corretamente pelo sistema.
[](https://estante-ses.sorocaba.sp.gov.br/uploads/images/gallery/2025-12/VDsimage.png)
### Seleção da tabela de destino
Com os dados validados visualmente, a etapa seguinte consiste em alterar a opção de configuração para **Upload de Dados**. Nesse momento, a interface passa a apresentar uma lista de tabelas já existentes, criadas anteriormente por meio do próprio upFiles.
[](https://estante-ses.sorocaba.sp.gov.br/uploads/images/gallery/2025-12/TC7image.png)
**Validação de compatibilidade entre planilha e tabela** Durante a etapa de configuração do upload, o upFiles realiza uma verificação automática de compatibilidade entre a estrutura da planilha enviada e a estrutura da tabela selecionada como destino. Essa validação considera, principalmente, a quantidade e a ordem das colunas, uma vez que o mapeamento dos dados ocorre por posição.
A lista exibida contempla apenas tabelas originadas pelo upFiles, facilitando a identificação correta da base que receberá os novos dados. A seleção da tabela correta é essencial para garantir a integridade das informações e a continuidade das análises futuras no Metabase.
### Definição do comportamento do upload
Após selecionar a tabela de destino, o usuário deve definir **como os novos dados serão tratados em relação aos registros já existentes**. Existem duas possibilidades principais:
- **Substituir tudo (limpa e reinsere)**: remove os dados atuais da tabela e insere apenas os dados do novo arquivo.
- **Adicionar aos dados existentes**: mantém os registros atuais e insere os novos dados na mesma tabela.
[](https://estante-ses.sorocaba.sp.gov.br/uploads/images/gallery/2025-12/LURimage.png)
Quando a opção de adicionar aos dados existentes é selecionada, torna-se necessário definir o comportamento em caso de registros duplicados, com base na chave primária previamente configurada.
### Tratamento de duplicidades
Nos casos em que um registro do novo arquivo possui a mesma chave primária de um registro já existente na tabela, o sistema permite duas abordagens:
- **Ignorar e manter os dados antigos**: os registros existentes são preservados e os novos são descartados quando ocorre duplicidade.
- **Atualizar (sobrescrever com novos)**: os registros existentes são substituídos pelos dados mais recentes do arquivo enviado.
[](https://estante-ses.sorocaba.sp.gov.br/uploads/images/gallery/2025-12/5ZDimage.png)
Essa escolha deve considerar o objetivo da base de dados e a forma como os relatórios são atualizados ao longo do tempo.
### Identificação e auditoria do upload
Antes da execução do upload, o sistema solicita a **identificação do responsável pelo envio**, por meio do CPF. Essa informação é utilizada exclusivamente para fins de rastreabilidade e auditoria, permitindo identificar quando e por quem determinado conjunto de dados foi inserido.
[](https://estante-ses.sorocaba.sp.gov.br/uploads/images/gallery/2025-12/FKnimage.png)
Após a confirmação, o processo de upload é iniciado e os dados passam a integrar a tabela selecionada, ficando disponíveis para análise no Metabase.
[](https://estante-ses.sorocaba.sp.gov.br/uploads/images/gallery/2025-12/yE5image.png)
### Uso dos dados no Metabase
Concluído o upload, o trabalho de estruturação no upFiles é finalizado. A partir desse ponto, a exploração, análise e visualização dos dados passam a ser realizadas diretamente no Metabase, por meio da criação ou atualização de painéis, gráficos e consultas.
Essa separação entre **estruturação de dados** e **análise visual** reforça a lógica adotada pela Saúde Digital, garantindo maior controle sobre as bases de dados e mais segurança no uso das informações.
---