Skip to main content
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. A ontologia mora em um único arquivo YAML, o graph_mapping.yaml, versionado no seu Workspace Git. 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.

​
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.
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.
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: 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 e Padrões e armadilhas.
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.

​
Próximos passos

Ontologia — como funciona

O conceito, os perfis-base por operação e quando pedir ajuda do time.

Ontology API

Request e response de cada endpoint, com exemplos em curl, Python e TypeScript.

Configuração do Workspace

Onde o graph_mapping.yaml mora e como o Workspace Git versiona a ontologia.

Transformations (dbt)

As tabelas clean/ que alimentam os nós vêm das transformations.