Modelo de dados e elementos de projeto

As tabelas de um projeto costumam compartilhar nomes de colunas: Period, Org, Account. Um elemento de projeto descreve um desses nomes uma só vez, para o projeto inteiro. Toda tabela com uma coluna com esse nome passa a mostrar a mesma descrição, máscara e dimensão, e você deixa de digitar o mesmo memorando em dezenas de tabelas.

A página Modelo de dados na página inicial do projeto lista os elementos de um projeto, mostra quais tabelas compartilham cada um e sinaliza onde as tabelas divergem.

O que um elemento contém

Configuração	O que faz
Nome	O nome da coluna que o elemento descreve, escrito exatamente como as colunas o têm.
Descrição	O que a coluna contém. As colunas que não têm memorando próprio mostram esta descrição.
Tipo	O tipo de dados que o projeto espera para esta coluna. Ele é verificado, não aplicado. Consulte Conflitos de tipo.
Máscara	Uma máscara numérica. As colunas que não têm máscara própria usam esta.
Dimensão	Uma dimensão da qual vêm os valores da coluna. As colunas que não têm dimensão própria usam esta.
Aliases	Outros nomes de coluna que significam a mesma coisa.

Como uma coluna recebe um elemento

Uma coluna é vinculada a um elemento quando o ID dela é igual ao nome do elemento ou a um dos aliases dele. A correspondência é exata: period e Period são nomes diferentes, então adicione period como alias de Period se quiser ambos.

Adicione ou exclua um elemento e toda coluna correspondente o acompanha.

O que uma coluna assume do elemento dela

Uma coluna vinculada assume a Descrição, a Máscara e a Dimensão do elemento onde o valor dela está em branco. Um valor que você define na própria coluna sempre prevalece. O elemento nunca altera o que está armazenado em uma tabela: exclua-o e cada coluna volta exatamente ao que tinha.

O Tipo não é assumido do elemento.

Abrir a página Modelo de dados

Abra o projeto e escolha Modelo de dados na barra lateral da página inicial do projeto. O indicador da barra lateral mostra quantos elementos o projeto tem. Você também pode abrir a página a partir de uma coluna:

No Explorador de tabelas, ative Propriedades da coluna e selecione uma coluna. A linha Elemento mostra o elemento da coluna ou, se ela não tiver nenhum e você puder editar o projeto, Transformar em elemento. Clique nela para abrir a página Modelo de dados nesse elemento, ou em um novo elemento que começa com a descrição, a máscara e a dimensão da própria coluna.
Na lista do que usa uma dimensão, uma linha chamada Elemento do projeto abre a página Modelo de dados.

Todos que podem abrir o projeto podem ver a página. Para criar, alterar ou excluir elementos, você precisa de acesso de gravação ao projeto, e o projeto não pode estar bloqueado. Caso contrário, a página diz “Você pode ver o modelo de dados aqui, mas não alterá-lo.”

Criar um elemento

Na página Modelo de dados, clique em Novo elemento.
Digite um Nome. Preencha Descrição, Tipo, Máscara e Dimensão conforme necessário. Deixe Tipo em Qualquer tipo para aceitar qualquer tipo.
Em Aliases, digite outros nomes de coluna que signifiquem o mesmo, um por linha.
Clique em Salvar.

Um elemento não pode ter um nome ou alias que outro elemento já tenha. Para alterar um elemento, clique no lápis (Editar elemento) ao lado dele. Se você o renomear, o nome antigo permanece como alias para que as colunas dele continuem com o elemento.

Para remover um, abra-o e clique em Excluir, depois confirme com Excluir elemento. A confirmação informa quantas tabelas estão vinculadas a ele. Nada armazenado nessas tabelas muda.

Elementos sugeridos

Em Sugerido, a página lista nomes de colunas que valem a pena virar elementos:

Um nome que ainda não é um elemento nem um alias e que está em duas ou mais tabelas, quando o tipo da coluna pode ser uma chave de junção (um tipo desconhecido conta), exibido como “nome está em n tabelas”. Clique em Criar elemento para criá-lo.
Um nome que corresponde ao nome ou a um alias de um elemento, ignorando maiúsculas, minúsculas e sublinhados, mesmo que esteja em apenas uma tabela, exibido como “nome parece elemento (n tabelas)”. Clique em Adicionar alias para vincular as colunas dele a esse elemento.

Ler o modelo de dados

O seletor Grafo e Matriz acima da tela mostra as mesmas tabelas e elementos de duas formas.

Grafo. Cada elemento é um centro, e cada tabela é um cartão ligado aos elementos para os quais tem uma coluna. Um 1 em uma linha marca uma coluna que é a única chave da tabela. Uma tabela com uma chave composta por várias colunas não é marcada. A página abre em um elemento e nas tabelas dele. Clique em um elemento para focar nele, clique em uma tabela para focar nela ou clique duas vezes em uma tabela para abri-la. Os chips ao lado de Ocultar elementos ocultam ou mostram os elementos que você não quer no desenho.
Matriz. Uma linha por tabela e uma coluna por elemento. Use Filtrar por nome da tabela para restringir as linhas.

Conflitos de tipo

Uma tabela cuja coluna tem um tipo diferente do das demais é sinalizada sob o elemento: “coluna é tipo em tabela, o que difere das outras tabelas.” Os tipos são comparados por família, então um inteiro e um decimal não entram em conflito. Se o elemento tiver um Tipo, as demais são comparadas com a família dele. Se não tiver, são comparadas com a família que a maioria das colunas usa e, em caso de empate entre duas famílias, usa-se a primeira em ordem alfabética. Um conflito é apenas um aviso; ele não altera nada.

Uma tabela que não pode ser lida fica de fora e é contada na página, em vez de interrompê-la.

Onde você vê os elementos

Os elementos aparecem como uma etiqueta com o nome do elemento:

Explorador de tabelas. A lista de colunas tem uma coluna Marcas com a etiqueta, ao lado das etiquetas de Dimensão e Acesso a linhas. Passe o mouse sobre a etiqueta para ver o elemento, a descrição e a dimensão dele.
Propriedades da coluna. A linha Elemento abre o elemento. Quando Descrição, Máscara ou Dimensão está em branco, o campo mostra “Do elemento nome: valor” como dica. A dica não é salva com a coluna.
Guia Data Mapping da etapa. As colunas de origem e de destino que pertencem a um elemento mostram a etiqueta dele depois do nome da coluna.

Usar elementos pela API REST e pelo MCP

A API REST lê e altera elementos em /rest/v1/analyze/projects/{project_id}/elements:

Solicitação	O que faz
`GET`	Retorna `elements` e `index`, que mapeia o nome de cada coluna vinculada ao nome do elemento dela.
`PUT`	Cria ou substitui um elemento a partir de `name`, `memo`, `dtype`, `mask`, `dimension` e `aliases`. Adicione `rename_from` para renomear um.
`DELETE` com `?name=`	Exclui o elemento indicado.
`GET` `/graph`	Retorna o que a página Modelo de dados mostra: cada elemento com a contagem de tabelas e os conflitos de tipo, as colunas vinculadas de cada tabela e as sugestões.

Os metadados da tabela retornam os valores armazenados em cada coluna, não os valores que ela assume de um elemento. Para descobrir de qual elemento uma coluna assume valores, procure o nome dela no index do GET de elementos.

Um assistente conectado por MCP usa element_find, element_upsert e element_delete. As descrições de tabela dele mostram o memorando de cada coluna com o valor do elemento preenchido onde a coluna não tem um.