O modelo de dados

Depois de importada, uma folha de Excel deixa de ser um ficheiro e passa a ser uma entidade: uma coisa com nome, campos e tipos, que o construtor de consultas conhece.

Esta página explica o que é criado, como são gerados os nomes, e o que acontece quando se reimporta.

Entidades e campos

Cada tabela importada dá origem a uma entidade. A entidade tem:

• um nome técnico (Vendas, Lojas, Produtos) — é o que as consultas gravadas referem;
• um nome de exibição — o nome da folha de Excel, que é o que a interface mostra;
• uma lista de campos, um por coluna, cada um com nome e tipo.

No exemplo da Nortada, as três importações produzem:

Entidade	Campos
Vendas	numero, data, lojaId, produtoId, vendedorId, canal, quantidade, desconto, valor, custo
Lojas	lojaId, loja, cidade, distrito, regiao, tipo, abertura, areaM2
Produtos	produtoId, produto, categoria, marca, preco, custoUnitario

Como os nomes são gerados

Há duas transformações, e vale a pena saber qual e qual.

Nome da coluna na tabela — o que escreve no assistente de importação, normalizado: minusculas, sem acentos, caracteres estranhos substituidos por _.

Valor Líquido  ->  valor_liquido
Data Emissão   ->  data_emissao
Área (m2)      ->  area_m2

Nome do campo no modelo — derivado do anterior, em camelCase. É este que vê no construtor de consultas e nas condições.

valor_liquido  ->  valorLiquido
data_emissao   ->  dataEmissao
loja_id        ->  lojaId
area_m2        ->  areaM2

Os acentos são transliterados antes de tudo o resto, e não removidos: Avaliação fica Avaliacao e não Avaliao.

O nome da entidade sai do nome da folha pela mesma via, em PascalCase. Não há singularização: uma folha chamada Vendas dá a entidade Vendas, não Venda. O nome que escolheu é o que reconhece.

Tipos no modelo

Os tipos do modelo vêm do que ficou gravado, não de adivinhação posterior:

Tipo na importação	Tipo no modelo
Texto	String
Número inteiro	Int
Número decimal	Float
Data	Date
Sim/Não	Int (0 ou 1)

O tipo Date é o que activa a granularidade temporal no construtor (dia, semana, mês, trimestre, ano) e os filtros de período relativo.

Ligações entre entidades

O modelo não guarda relações. Não há nada a declarar entre Vendas e Lojas no separador de dados.

As ligações fazem-se onde são precisas: dentro de cada consulta, no construtor, indicando que campo de que tabela casa com que campo de que outra. Ver Junções entre tabelas.

Isto é uma escolha e não uma falta. Cada consulta diz explicitamente como as tabelas se ligam, o que evita que um modelo mal declarado envenene silenciosamente todas as consultas de todos os dashboards.

Facilite as junções na importação

De o mesmo nome a coluna dos dois lados da ligação. Nos ficheiros da Nortada, Vendas.loja_id e Lojas.loja_id chamam-se o mesmo, e ligar as duas tabelas não levanta dúvidas.

O nome técnico é estável

Depois de uma entidade existir, o seu nome técnico não muda, mesmo que renomeie a tabela na interface. Só o nome de exibição acompanha.

A razão é simples: as consultas gravadas referem a entidade pelo nome técnico. Se ele mudasse, todos os widgets que a usam deixavam de encontrar a tabela.

O que acontece ao reimportar

Reimportar uma tabela (em modo de substituição ou acrescento) actualiza o modelo automaticamente:

• os campos são redescobertos a partir da tabela real, por introspecção;
• colunas novas passam a existir no modelo;
• tipos alterados são reflectidos;
• o nome técnico da entidade mantem-se.

Isto significa que corrigir o tipo de uma coluna e reimportar chega para que os widgets voltem a funcionar bem — sem tocar nas consultas.

Onde o modelo aparece

Sitio	Como aparece
Construtor de consultas	Lista de tabelas para adicionar ao canvas, com os campos e os tipos
API GraphQL	Uma consulta por entidade, com os campos como argumentos de filtro
Servidor MCP	Um assistente pode ler o modelo para saber o que existe antes de propor um dashboard

Ver API GraphQL e Assistentes de IA (MCP).