> ## Documentation Index
> Fetch the complete documentation index at: https://strattumai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/admin/manage-ontology).
***
## 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:
```text theme={null}
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 |
```yaml theme={null}
- 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:
```text theme={null}
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
```yaml theme={null}
- 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:
```text theme={null}
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.
A estrutura do arquivo, campo a campo, e um exemplo completo que roda.
O que fica achável de graça e o que precisa declarar.