> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strattum.ai/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.

> [!NOTE]
>
> Esta página é sobre **modelar**. Para o procedimento de salvar, validar e ativar uma versão, veja [Gerenciar a ontologia](https://docs.strattum.ai/admin/manage-ontology.md).

***

## 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
```

> [!TIP]
>
> 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.

> **[Escrevendo uma ontologia](https://docs.strattum.ai/admin/ontology-writing.md)**
>
> A estrutura do arquivo, campo a campo, e um exemplo completo que roda.

> **[Campos pesquisáveis](https://docs.strattum.ai/admin/ontology-searchable-fields.md)**
>
> O que fica achável de graça e o que precisa declarar.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.