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

# 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](/faq/ontology).

A ontologia mora em um único arquivo YAML, o `graph_mapping.yaml`, versionado no seu [Workspace Git](/getting-started/configuration). 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.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`).
  </Step>
</Steps>

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](/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.
</Tip>

<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.
</Warning>

***

## Impacto no grafo

Nem toda mudança tem o mesmo custo. O reprocessamento depende do tipo de alteração:

| Mudança                                         | Efeito                                               |
| ----------------------------------------------- | ---------------------------------------------------- |
| Adicionar ou remover atributo de um tipo        | Não reprocessa o histórico                           |
| Adicionar um tipo de entidade novo              | Não reprocessa o histórico                           |
| Adicionar relacionamento entre tipos existentes | O Memory Worker preenche as arestas no próximo ciclo |

<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](/faq/ontology).
</Note>

***

## Próximos passos

<CardGroup cols={2}>
  <Card title="Ontologia — como funciona" icon="diagram-project" href="/faq/ontology">
    O conceito, os perfis-base por operação e quando pedir ajuda do time.
  </Card>

  <Card title="Ontology API" icon="terminal" href="/api-reference/memory/ontology">
    Request e response de cada endpoint, com exemplos em curl, Python e TypeScript.
  </Card>

  <Card title="Configuração do Workspace" icon="folder-gear" href="/getting-started/configuration">
    Onde o graph\_mapping.yaml mora e como o Workspace Git versiona a ontologia.
  </Card>

  <Card title="Transformations (dbt)" icon="table" href="/admin/transformations">
    As tabelas clean/ que alimentam os nós vêm das transformations.
  </Card>
</CardGroup>