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

# Gerenciar a ontologia

> O passo a passo operacional para editar, validar, ativar e reverter versões da ontologia do Memory sem derrubar o grafo em produção.

Esta página é o procedimento operacional de mudança da ontologia: como você edita o `graph_mapping.yaml`, salva um rascunho, valida, ativa e reverte se preciso. Para o conceito (o que é a ontologia e quando pedir ajuda do time), veja [Ontologia — como funciona](https://docs.strattum.ai/faq/ontology.md).

A ontologia mora em um único arquivo YAML, o `graph_mapping.yaml`, versionado no seu [Workspace Git](https://docs.strattum.ai/getting-started/configuration.md). Cada mudança gera uma versão numerada, e só uma versão fica ativa por vez.

***

## O fluxo em três etapas

Toda mudança segue a mesma sequência: salvar rascunho, validar, ativar. O rascunho não entra em produção sozinho.

**1. Salvar o rascunho**

Edite o `graph_mapping.yaml` (pelo Console em **Memory → Configuration** ou direto no Git) e salve. Pela API, isso é um `PUT /v1/ontology` com o `yaml_text`. O rascunho é criado com `is_current: false` e recebe um número de versão sequencial.

**2. Validar**

A plataforma valida a estrutura do YAML antes de aplicar. Pela API, `POST /v1/ontology/validate` retorna `valid: true` ou uma lista de `errors`. Se um nó aponta para uma tabela `clean/` que não existe ou um campo está errado, a validação reprova e aponta onde.

**3. Ativar**

Ao ativar, a nova versão vira a corrente e todas as outras são desativadas. Pela API, `POST /v1/ontology/apply` com o `id` da versão salva. A plataforma registra quem ativou e quando (`applied_by`, `applied_at`).

A ativação inicializa os labels de nó no FalkorDB de forma idempotente (via `MERGE`), então reaplicar a mesma ontologia não duplica nada. Erros no FalkorDB durante a ativação são não-fatais: o registro da versão é gravado no PostgreSQL de qualquer forma.

***

## O que cada endpoint faz

Quando você automatiza a mudança em vez de usar o Console, estes são os endpoints do fluxo. A referência completa está em [Ontology API](https://docs.strattum.ai/api-reference/memory/ontology).

| Endpoint | Método | Para quê |
| - | - | - |
| `/v1/ontology` | `GET` | Ler a ontologia atualmente ativa |
| `/v1/ontology` | `PUT` | Salvar um rascunho novo (não ativa) |
| `/v1/ontology/validate` | `POST` | Checar a estrutura do YAML sem salvar |
| `/v1/ontology/apply` | `POST` | Ativar uma versão salva por `id` |
| `/v1/ontology/history` | `GET` | Listar todas as versões, da mais recente para a mais antiga |
| `/v1/ontology/status` | `GET` | Ver se há ontologia ativa e qual a versão |

***

## Versionamento e rollback

Cada versão salva fica guardada. O `GET /v1/ontology/history` lista todas, da mais recente para a mais antiga, com `applied_by` e `applied_at` de cada ativação.

Para reverter, ative de novo uma versão anterior: pegue o `id` dela no histórico e chame `POST /v1/ontology/apply` com esse `id`. A versão antiga volta a ser a corrente e a atual é desativada.

> [!TIP]
>
> Como a ativação é idempotente, reverter é a mesma operação de ativar. Não há passo especial de rollback, é só reaplicar a versão que você quer de volta.

> [!WARNING]
>
> `POST /v1/ontology/apply` desativa todas as outras versões e reescreve o schema do grafo ativo. Valide antes de ativar e confirme o `id` correto, principalmente ao automatizar a chamada.

***

## Impacto no grafo

O grafo continua disponível durante qualquer mudança de ontologia. Ele só é recriado do zero se você chamar `POST /v1/ontology/apply` com `reset=true`, e o Console nunca envia esse parâmetro. Sem ele, o Memory Worker compara a ontologia nova com a anterior e aplica só a diferença:

| Mudança | O que acontece no grafo | O que o worker lê |
| - | - | - |
| Remover propriedade de um nó | A propriedade some daquele tipo | Nada |
| Adicionar propriedade a um nó | Os nós ganham a propriedade no lugar | A fonte daquele nó, uma vez |
| Remover propriedade de uma aresta | A propriedade some daquele tipo de aresta | Nada |
| Adicionar propriedade a uma aresta | As arestas ganham a propriedade | A fonte daquela aresta, uma vez |
| Remover um tipo de aresta | As arestas desse tipo são apagadas | Nada |
| Adicionar um tipo de aresta | As arestas novas aparecem | Só a fonte daquela aresta |
| Remover um tipo de nó | Os nós e as arestas deles são apagados | Nada |
| Adicionar um tipo de nó | Os nós novos aparecem | A fonte do novo tipo |
| Mudar identidade (`er_fields`, `id_field`, tabela de origem, busca da aresta, entidade ou data da timeline) | Os itens são relidos e gravados primeiro, e só depois os antigos que sobraram são apagados | O tipo e as arestas que o tocam |

Na mudança de identidade, o dado antigo continua visível até o novo estar gravado. Se a releitura falhar, nada é apagado.

### Dicas de modelagem

* **Uma linha por id.** Cada nó vem de uma tabela com uma linha por id. Para ligar duas entidades por uma tabela de junção, use a junção só na aresta.
* **`er_fields` só para identificador único.** CPF, CNPJ e protocolo servem. E-mail e telefone compartilhados fundem pessoas diferentes numa só. Com `er_fields` declarado, o `search_entity` acha a entidade pelo CPF ou CNPJ, com ou sem pontuação.
* **`indexed_fields` para filtro.** Colunas que a operação filtra (status, cor, ano) vão em `indexed_fields`, nunca em `er_fields`.

Detalhes em [Campos pesquisáveis](https://docs.strattum.ai/admin/ontology-searchable-fields.md) e [Padrões e armadilhas](https://docs.strattum.ai/admin/ontology-patterns.md).

> [!NOTE]
>
> Ajustar atributo, trocar o confidence threshold de aprovação automática e mudar quais tabelas `clean/` alimentam um tipo já modelado são operações self-service. Modelagem inicial do grafo e entity resolution complexo são onde o time da Strattum entra. Ver [Ontologia — nível de dependência](https://docs.strattum.ai/faq/ontology.md).

***

## Próximos passos

> **[Ontologia — como funciona](https://docs.strattum.ai/faq/ontology.md)**
>
> O conceito, os perfis-base por operação e quando pedir ajuda do time.

> **[Ontology API](https://docs.strattum.ai/api-reference/memory/ontology)**
>
> Request e response de cada endpoint, com exemplos em curl, Python e TypeScript.

> **[Configuração do Workspace](https://docs.strattum.ai/getting-started/configuration.md)**
>
> Onde o graph\_mapping.yaml mora e como o Workspace Git versiona a ontologia.

> **[Transformations (dbt)](https://docs.strattum.ai/admin/transformations.md)**
>
> As tabelas clean/ que alimentam os nós vêm das transformations.


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