Conceitos da ontologia

As quatro ideias que sustentam uma ontologia — entidade, a diferença entre id_field e er_fields, o que é um identificador e como uma aresta liga ids.

A ontologia é um arquivo YAML que descreve o mundo do seu negócio: que coisas existem, como se reconhece cada uma, e como se ligam. Ela não descreve telas, não descreve pipelines e não descreve os sistemas de origem.

Tudo que a plataforma faz com identidade e grafo sai daí. Não há código por cliente.

Três frases resumem o resto desta trilha:

1. id_field cunha, er_fields acha. O primeiro cria um id novo quando nada casou; o segundo é consultado antes, e é o que funde fontes diferentes.
2. er_fields é OU, nunca E. Cada campo da lista, sozinho, tem que identificar a coisa. Não existe chave composta.
3. A ontologia não tem nada de visualização. Rótulo e cor são derivados; se você está declarando como algo aparece na tela, está no arquivo errado.

Esta página é sobre modelar. Para o procedimento de salvar, validar e ativar uma versão, veja Gerenciar a ontologia.

---

1. Entidade é uma coisa do mundo real

Não é uma linha de tabela. Não é um registro de sistema. É a coisa: aquela pessoa, aquele carro, aquele imóvel, aquele contrato.

Uma entidade costuma aparecer em vários sistemas ao mesmo tempo, cada um com a sua chave e o seu jeito de escrever:

CRM       CRM-001   cpf 111.222.333-44
ERP       ERP-777   cpf 11122233344          ← a mesma pessoa
Cobrança  COB-999   cpf 111222333-44         ← a mesma pessoa
RH        RH-555    cpf 111.222.333/44       ← a mesma pessoa

Quatro linhas, quatro chaves, quatro formatos. Uma entidade. Juntar isso é o trabalho principal da ontologia.

Cada entidade ganha um entity_id (um UUID) que é estável: a mesma coisa tem o mesmo id hoje, amanhã e depois de reprocessar.

---

2. id_field cunha. er_fields acha.

A confusão mais comum é tratar os dois como sinônimo. Eles respondem perguntas diferentes:

Campo	Pergunta	Quando é usado
id_field	como eu CRIO um id novo?	só quando nada casou
er_fields	como eu ACHO quem já existe?	sempre, antes de criar

- label: Cliente
  source: clean/crm_contatos
  id_field: external_id        # a chave do CRM — garante que a mesma linha
                               # sempre dê o mesmo id, quantas vezes rodar
  er_fields: [cpf, email]      # o que faz esta fonte encontrar a pessoa que
                               # outra fonte já criou

A ordem importa e é sempre a mesma:

linha da clean
   ↓
1. PROCURA   por todos os er_fields (e pela própria chave, primeiro)
   ↓ achou → adota o entity_id que já existe
   ↓ não achou
2. CRIA      um id novo a partir do id_field
   ↓
3. REGISTRA  todas as chaves da linha, para a próxima achar

Declarar er_fields numa ontologia que já está rodando não re-chaveia nada. A busca consulta a chave própria primeiro, então quem já existe mantém o id que tem.

---

3. Identificador é o que obriga duas linhas a serem a mesma coisa

Esse é o critério, e é o único que importa:

Se duas linhas tiverem o mesmo valor neste campo, elas são obrigatoriamente a mesma coisa no mundo real?

Serve	Não serve	Por quê não
cpf, cnpj	nome	existem dois João Silva
placa, chassi, renavam	data, horario	mil coisas às 16:30
matricula_imovel	owner_id, responsavel	uma pessoa tem 247 reuniões
numero_contrato, numero_apolice	cidade, status	categoria, não identidade
ean, isbn, chave_nfe	telefone corporativo	a matriz inteira compartilha
código de parceiro do ERP	e-mail de setor (contato@)	vira uma pessoa só

Qualquer nome de campo funciona. Não existe lista fixa: matricula, passaporte, codigo_associado, duns — se passa no teste, é identificador.

---

4. A aresta liga ids, não campos

- type: POSSUI_VEICULO
  source: clean/detran          # a tabela que CARREGA a ligação
  from:
    label: Cliente
    match_field: cpf            # por qual identificador achar
    source_column: cpf_dono     # em qual coluna desta tabela ele está
  to:
    label: Carro
    match_field: placa
    source_column: placa

O que acontece com uma linha do DETRAN:

cpf_dono = "111.222.333-44"  →  normaliza  →  "11122233344"  →  Ana (62fc0c8e…)
placa    = "ABC1D23"         →  normaliza  →  "abc1d23"      →  o carro (017788bb…)

escreve:  (Ana)-[:POSSUI_VEICULO]->(o carro)

O campo some. A aresta guarda id com id. Por isso o carro achado pela placa e o carro achado pelo chassi são o mesmo nó, e o contrato alcança os dois.

A tabela do source: da aresta é aquela que tem as duas colunas — é ela que sabe que essas duas coisas se ligam.

---

Um vocabulário mínimo

Termo	O que é
label	o tipo da entidade: Cliente, Carro, Imovel. PascalCase, singular.
source	a tabela da camada clean que alimenta. Sempre começa com clean/.
entity_id	o UUID estável da entidade.
fusão	duas linhas de fontes diferentes virando uma entidade.
normalizador	a regra que tira pontuação e caixa antes de comparar.
camada clean	onde o dado já chegou tratado, via dbt. A ontologia lê de lá.

---

O que não vai na ontologia

• Transformação de dado. Limpar, converter, juntar colunas — isso é a camada clean (dbt SQL). A ontologia lê colunas que já existem.
• Validação de negócio. Dígito verificador de CPF, faixa de valor, obrigatoriedade.
• Aparência. Cor, ícone, ordem, o que aparece primeiro.
• Permissão. O ACL viaja na linha, da clean para o grafo.

Escrevendo uma ontologia

A estrutura do arquivo, campo a campo, e um exemplo completo que roda.

Campos pesquisáveis

O que fica achável de graça e o que precisa declarar.