Modelando seus dados

Todas as outras capacidades são configuradas contra o seu modelo de dados. A comparação compara atributos, a validação os restringe, o mascaramento os redige e a API os expõe. Acertar o modelo primeiro evita refazer todo o resto.

O que você define

A tela de modelo de dados. Todo tipo de entidade aqui foi definido pelo tenant — a plataforma não traz nenhum.

Conceito	O que é
Tipo de entidade	Um tipo de coisa que você governa — pessoa, organização, lugar, produto
Atributo	Uma informação nomeada em um tipo de entidade, com um tipo de dado
Tipo de relacionamento	Um tipo de vínculo entre dois tipos de entidade

A plataforma não impõe esquema. Seus tipos de entidade e atributos são seus, por organização.

Atributos

Cada atributo declara um tipo de dado, se é obrigatório e sua cardinalidade.

Valor único versus multivalorado

A distinção importa mais do que parece, porque muda o comportamento da comparação e da sobrevivência.

Use valor único quando	Use multivalorado quando
Há exatamente um valor significativo — um nome legal, uma data de nascimento	A entidade tem genuinamente vários — e-mails, telefones, endereços
O campo é um primitivo de comparação	Os valores formam um catálogo distinguido por uso

Um atributo multivalorado pode vincular um tipo de uso — residencial, comercial, celular — extraído de uma lista de dados de referência. A sobrevivência então resolve cada tipo de uso independentemente: um endereço residencial vencedor e um comercial, em vez de um endereço só.

Um valor por tipo de uso pode ser marcado como preferencial.

Atributos compostos

Alguns valores são estruturados, não escalares. Um endereço não é uma string; é um conjunto de partes nomeadas.

Atributos compostos são armazenados como valores estruturados, e a comparação pode mirar sub-campos — comparando códigos postais exatamente enquanto compara logradouros de forma tolerante. Isso não é expressável se o endereço for uma string única.

Uma string única não é um endereço

Uma vez achatada em texto, a estrutura não é recuperável de forma confiável. Modele compostos como compostos desde o início; comparar dois compostos inteiros com um comparador escalar é recusado, porque dois endereços completamente diferentes se comparariam como iguais.

Vínculo a dados de referência

Um atributo cujos valores vêm de uma lista controlada é vinculado a um tipo de lookup. A plataforma então aceita apenas os códigos daquela lista, e todo consumidor — a API, o console, a comparação — resolve códigos para rótulos de forma consistente.

Vincule sempre que existir um vocabulário controlado. É a diferença entre US, USA e Estados Unidos serem um valor ou três.

Tipos de relacionamento

Um tipo de relacionamento declara quais tipos de entidade ele liga, sua cardinalidade e se é simétrico. Também carrega nomes de exibição para ambas as direções, para que um vínculo se leia corretamente de qualquer ponta.

Conselhos de modelagem

• Modele o que você governa. Um atributo para algo de que você não guarda registro; um relacionamento para algo de que guarda.
• Prefira vários atributos precisos a um genérico. given_name e family_name são comparáveis; full_name é muito menos.
• Vincule a dados de referência cedo. Adaptar um vocabulário controlado depois significa limpar todos os valores existentes.
• Padronize antes de comparar. O comparador lê valores canônicos, então regras de padronização fazem parte da modelagem, não são um detalhe posterior.

A seguir

• Gerencie dados de referência
• Padronize os dados
• Compare e consolide registros

---

Última verificação no commit d3c2586b (2026-08-03)