> ## 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. # Gerar a ontologia a partir do Catálogo de Dados > Guia de configuração: usar o Construtor para gerar a ontologia do Memory a partir das tabelas clean do Catálogo de Dados, revisar e aplicar. Este guia mostra como usar o Construtor, o agente de ontologia do console, para transformar as tabelas clean do Catálogo de Dados no grafo de entidades do Memory. O Construtor pergunta sobre o negócio, consulta o catálogo e propõe o grafo. Nada é salvo nem aplicado sem a sua confirmação. ## O que é a ontologia A ontologia diz ao Memory quais entidades existem na sua empresa, de qual tabela clean vem cada uma e como elas se ligam. Ela fica num arquivo YAML com versões. Cada versão aplicada atualiza o grafo de entidades que os agentes consultam. > **Entidades** > > Os tipos de coisa que o grafo guarda, como Cliente, Ticket ou Contrato. No YAML, cada tipo é um `label`. > **Origem e identidade** > > Cada tipo lê uma tabela clean e usa uma coluna para identificar o registro, em geral `external_id`. Colunas como e-mail ou CPF juntam o mesmo registro vindo de fontes diferentes. > **Relações** > > Como os tipos se ligam, por exemplo Ticket pertence a Company. No YAML, cada aresta tem um nome, as duas pontas e as colunas que ligam uma à outra. ``` Catálogo de Dados → Construtor → Rascunho → Versão aplicada → Grafo do Memory └────── Parte 1 ──────┘ └──────────── Parte 2 ────────────┘ ``` ## O que você vai fazer São duas partes, nesta ordem. Na primeira, você monta a proposta com o Construtor. Na segunda, revisa, salva e aplica. > **Parte 1 · Montar a proposta** > > 1.1 Abrir a tela Ontologia\\ > > 1.2 Contar o objetivo de negócio\\ > > 1.3 Acompanhar a análise do catálogo\\ > > 1.4 Aceitar ou rejeitar a proposta\\ > > 1.5 Ajustar por conversa (opcional) > **Parte 2 · Revisar e aplicar** > > 2.1 Conferir o rascunho\\ > > 2.2 Verificar o schema\\ > > 2.3 Salvar o rascunho\\ > > 2.4 Aplicar a versão\\ > > 2.5 Acompanhar a atualização do grafo > [!WARNING] > > **Segurança.** O Construtor lê o schema das tabelas, ou seja, os nomes e os tipos das colunas. Para testar uma ligação, ele roda consultas agregadas na camada clean, como a porcentagem de e-mails que coincidem entre duas tabelas, e recebe só números, nunca linhas. Ele usa o modelo de IA da sua empresa, escolhido na função Agente de ontologia. ## Antes de começar Confira estes itens antes de abrir o Construtor. A última coluna indica o passo em que cada um é usado. | O que você precisa | Onde conseguir | Passo | | - | - | - | | Acesso de administrador ao console. Só administradores usam o Construtor e aplicam a ontologia | [Guia de configuração de SSO e modelos de IA](https://docs.strattum.ai/getting-started/sso-and-models.md) | 1.1 | | Modelo escolhido e validado na função **Agente de ontologia**, em Modelos de IA. O modelo precisa chamar ferramentas | [Guia de configuração de SSO e modelos de IA](https://docs.strattum.ai/getting-started/sso-and-models.md), passo 2.2 | 1.2 | | Conectores salvos e dados carregados, com as tabelas clean no contexto | [Guia de Conectores e Catálogo de Dados](https://docs.strattum.ai/getting-started/connect-and-catalog.md) | 1.3 | | As perguntas de negócio que os agentes precisam responder, por exemplo, quais clientes têm tickets abertos há mais de sete dias | Áreas de negócio da sua empresa | 1.2 | > [!NOTE] > > Comece por uma pergunta de negócio importante e pelas duas ou três entidades que a respondem. Depois, amplie a ontologia em novas conversas. *** ## Parte 1 · Montar a proposta com o Construtor O Construtor conversa com você sobre o negócio, consulta o Catálogo de Dados e propõe as entidades e as relações. Cada proposta só entra no editor depois que você aceita. **Onde:** IA / Ops › Ontologia ### 1.1 Abra a tela Ontologia **Onde:** IA / Ops › Ontologia 1. No menu lateral, em **IA / Ops**, clique em **Ontologia**. 2. Numa instalação nova, a tela mostra **Nenhuma ontologia configurada**, e o selo do topo mostra **Nenhuma versão aplicada**. 3. O Construtor fica no painel da direita ⑤. Se o painel estiver recolhido, clique em **Abrir o Construtor**. ![Tela Ontologia com a barra de contagem, o grafo de entidades, as abas Rascunho, YAML e Verbalização e o painel do Construtor](https://mintcdn.com/strattumai/09Jh5eSHsK_uEBGp/images/guides/ontology-builder/01-tela-ontologia.png?fit=max\&auto=format\&n=09Jh5eSHsK_uEBGp\&q=85\&s=3307a075aafa0746ab3df45471e518be) Figura 1. Tela Ontologia com uma ontologia já aplicada: barra de contagem ①, mostrar propostas ②, grafo ③, abas do editor ④ e Construtor ⑤. | Área | O que mostra | | - | - | | Barra de contagem ① | Quantos tipos de entidade existem, quantos já têm dados, quantos estão sem entidades, o número de arestas e as mudanças no rascunho. | | Mostrar propostas ② | Ligado, o grafo mostra com linha tracejada o que o Construtor está propondo (**proposto**) e com linha cheia o que já está no arquivo (**no YAML**). | | Grafo ③ | Cada caixa é um tipo de entidade, com as tabelas de origem, a chave e o número de entidades. Clique numa caixa para ver a identidade, as propriedades e as arestas do tipo, com os atalhos **Perguntar ao construtor** e **Ver no YAML**. | | Abas do editor ④ | **Rascunho**, com o que mudou e ainda não foi aplicado. **YAML**, com o arquivo da ontologia. **Verbalização**, com o grafo escrito em frases. | | Construtor ⑤ | A conversa com o agente de ontologia. | ### 1.2 Conte o objetivo de negócio **Onde:** Ontologia › Construtor 1. Clique em **Nova conversa** ①. A conversa nova parte do YAML que está no editor. 2. O Construtor lista o que pode fazer ②: descobrir conectores e tabelas ainda não mapeados, adicionar nós e arestas, corrigir problemas de validação, criar cleans e melhorar as ligações entre entidades. 3. Escreva o objetivo no campo **Responda, pergunte ou proponha uma mudança** ③ e envie. Um pedido concreto rende uma proposta melhor: | Pedido claro | Pedido vago | | - | - | | "Quero ligar os tickets de suporte às empresas e aos contatos que abriram cada um." | "Monte a ontologia." | | "Preciso saber quanto cada cliente deve e quais faturas estão em aberto." | "Use todas as tabelas." | | "Tem algum conector ainda não mapeado nesta ontologia?" | "Melhore o grafo." | ![Painel do Construtor com o botão Nova conversa, a lista do que ele pode fazer e o campo de mensagem](https://mintcdn.com/strattumai/09Jh5eSHsK_uEBGp/images/guides/ontology-builder/02-nova-conversa.png?fit=max\&auto=format\&n=09Jh5eSHsK_uEBGp\&q=85\&s=47eb6d55ddb9a4551dc5b8f90c07d0ab) Figura 2. Construtor: Nova conversa ①, o que ele pode fazer ② e campo de mensagem ③. > [!NOTE] > > Diga como a sua empresa chama cada coisa. As tabelas usam os nomes do sistema de origem, como `contacts` ou `accounts`. Se para você o cliente é a empresa que paga e o contato é a pessoa, avise o Construtor. ### 1.3 Acompanhe a análise do catálogo **Onde:** Ontologia › Construtor Para responder ①, o Construtor consulta o Catálogo de Dados com ferramentas. Cada consulta aparece na conversa numa linha recolhida, com o nome e o status, como **Listar conectores · Concluída** ②. Clique na linha para ver a entrada e o resultado. A resposta vem em seguida ③. * **Listar conectores** e **Listar tabelas clean**: o que existe no catálogo. * **Ler schema do conector** e **Descrever tabela**: as colunas e os tipos de cada tabela. * **Ler fragmentos de ontologia**: os modelos prontos dos conectores com schema fixo, como Zendesk e HubSpot. * **Executar sonda agregada**: mede, por exemplo, quantos e-mails coincidem entre duas tabelas antes de unificar. Devolve só números. O status passa de **Em execução** para **Concluída**. **Aguardando aprovação** indica que a ação precisa da sua confirmação, e **Falhou** indica um erro (veja [Se algo não funcionar](#se-algo-não-funcionar)). ![Conversa no Construtor: pergunta sobre conectores não mapeados, consultas Listar conectores e Listar tabelas clean concluídas e resposta com as tabelas do conector sem mapeamento](https://mintcdn.com/strattumai/09Jh5eSHsK_uEBGp/images/guides/ontology-builder/03-analise-catalogo.png?fit=max\&auto=format\&n=09Jh5eSHsK_uEBGp\&q=85\&s=5d31c2680b35fdbfe762e52827f3155c) Figura 3. Construtor depois de uma pergunta ①: consultas ao catálogo ② e resposta com o conector ainda sem mapeamento ③. ### 1.4 Aceite ou rejeite a proposta **Onde:** Construtor › Proposta de alteração Quando chega a uma proposta, o Construtor mostra na conversa um cartão **Proposta de alteração**. Com **mostrar propostas** ligado (Figura 1, ②), o grafo exibe tracejado o que ele propõe. 1. Leia a proposta. Em cada entidade, confira a tabela de origem, a chave e as propriedades. Em cada relação, confira as duas pontas. 2. Se o cartão trouxer **Avisos da validação**, leia antes de decidir. Eles apontam, por exemplo, uma tabela ainda não materializada ou uma fonte não verificada no catálogo. 3. Para seguir, aceite a proposta no cartão. As mudanças entram no editor e aparecem na aba **Rascunho**. O grafo ainda não muda. 4. Para recusar, rejeite. Você pode deixar um comentário dizendo o que mudar, e o Construtor responde antes de propor de novo. Enquanto houver uma proposta aberta, o campo de mensagem fica bloqueado até você aceitar ou rejeitar. O Construtor também pode pedir para salvar (**Salvar este rascunho?**) ou aplicar (**Aplicar esta ontologia?**). Cada pedido vem num cartão próprio e só acontece com a sua confirmação. Neste guia, você salva e aplica pelos botões do topo da tela, depois de revisar o rascunho na Parte 2. > [!NOTE] > > Se faltar uma tabela clean para uma entidade, o Construtor pode propor criar uma (**Criar esta tabela na clean?**). A tabela nasce habilitada no Catálogo de Dados e sem dados. Depois de criar, carregue os dados no catálogo. ### 1.5 Ajuste por conversa (opcional) **Onde:** Ontologia › Construtor Peça mudanças na conversa, com as suas palavras. Quando o pedido muda a ontologia, ele volta como uma nova proposta para você aceitar ou rejeitar (passo 1.4). Exemplos: * "Renomeie Customer para Cliente." * "Una o cliente do CRM e o do helpdesk pelo e-mail." Antes de unificar, o Construtor pode medir com uma sonda quanto os e-mails coincidem entre as duas fontes. * "Tire a tabela de notas da proposta." * "Ligue Ticket a Company pela organização que abriu o ticket." * "Quais perguntas de negócio esta ontologia ainda não responde?" > [!NOTE] > > Uma conversa tem limite de mensagens. Para mudar de assunto, use **Nova conversa**: ela começa do YAML que está no editor. > [!TIP] > > **Parte 1 concluída.** As mudanças aceitas estão no editor, na aba Rascunho. O grafo e a versão aplicada ainda não mudaram. *** ## Parte 2 · Revisar, salvar e aplicar Antes de aplicar, você confere o que muda, verifica se as tabelas e as colunas existem e salva uma versão. Aplicar ativa essa versão e atualiza o grafo. **Onde:** IA / Ops › Ontologia ### 2.1 Confira o rascunho **Onde:** Ontologia › Abas Rascunho, YAML e Verbalização 1. Na aba **Rascunho** ①, veja a lista do que vai mudar. O número ao lado do nome conta as mudanças pendentes. Sem mudanças, a aba mostra "Nada pendente: o grafo está igual ao YAML aplicado." 2. Na aba **YAML**, clique em **Diferenças** ④ para ver o que mudou em relação à versão aplicada. 3. Na aba **Verbalização**, leia o grafo em frases, do jeito que os agentes enxergam. Vale ler com alguém da área de negócio. ![Aba YAML com o tipo Employee, a validação YAML válido e os botões Diferenças e Verificar schema](https://mintcdn.com/strattumai/09Jh5eSHsK_uEBGp/images/guides/ontology-builder/04-aba-yaml.png?fit=max\&auto=format\&n=09Jh5eSHsK_uEBGp\&q=85\&s=6b54a19520b2164b96b9382ba635d8a5) Figura 4. Aba YAML: abas do editor ①, um tipo de entidade ②, resultado da validação ③, Diferenças ④ e Verificar schema ⑤. #### Como ler um tipo no YAML | Campo | O que define | Na Figura 4 | | - | - | - | | `label` | O nome do tipo de entidade. | Employee | | `source` | A tabela clean de origem. | `clean/github_members` | | `id_field` | A coluna que identifica o registro na fonte. Ela cria a entidade quando nenhum dos `er_fields` encontra uma existente. | `external_id` | | `er_fields` | As colunas que juntam registros de fontes diferentes. Se uma delas coincidir com uma entidade existente, o registro se junta a ela. | `email` | | `properties` | As colunas que viram propriedades da entidade. | `login`, `email`, `type` e outras | | `indexed_fields` | As propriedades com índice no grafo, para filtrar mais rápido. | `type` | Na Verbalização, o mesmo tipo vira uma frase, como "Cada Employee é identificado por external\_id e unificado entre fontes por email." Na hora de aplicar (passo 2.4), o console classifica cada mudança: | Classe | Exemplos | Efeito ao aplicar | | - | - | - | | Aditiva | Tipo, campo ou aresta novos | Acrescenta ao grafo sem refazer o que já existe. | | Identidade | Troca de `id_field` ou de `er_fields` de um tipo | Refaz no grafo as entidades desses tipos. Memory, MCP e evals passam a ver a mudança. | | Display | Tier e cor de um tipo | Muda só a aparência do grafo. | > **[Conceitos da ontologia](https://docs.strattum.ai/admin/ontology-concepts.md)** > > Os campos do YAML, com exemplos de entidades, arestas e unificação entre fontes. ### 2.2 Verifique o schema **Onde:** Ontologia › Aba YAML 1. No rodapé da aba YAML, confira a validação do arquivo ③ (Figura 4): **YAML válido.** ou um erro de sintaxe com o número da linha. 2. Clique em **Verificar schema** ⑤. O console confere se cada tabela e cada coluna citadas no YAML existem nas tabelas clean. | Resultado | O que fazer | | - | - | | **Schema válido**: todos os campos existem nas tabelas clean | Siga para o passo 2.3. | | Um campo marcado com ✗ e a lista de colunas **Disponíveis** | Troque o campo por uma das colunas disponíveis ou peça a correção ao Construtor. | | **Tabela não encontrada ou sem colunas visíveis no catálogo** | No Catálogo de Dados, confira se a clean existe, está no contexto e tem dados. | | **Coluna com vários valores usada como chave** | Use a coluna como propriedade, ou crie uma clean que separe os valores, uma linha por valor, com **Nova clean** no Catálogo de Dados. | ### 2.3 Salve o rascunho **Onde:** Ontologia › Barra superior 1. Clique em **Salvar rascunho** ⑤. 2. O console confirma com "Rascunho salvo", o número de mudanças e "nada aplicado". A versão salva vai para o **Histórico** ④, ainda inativa. 3. Confira o estado ②, ao lado da versão aplicada. ![Barra superior da tela Ontologia com a versão aplicada, o estado Tudo aplicado e os botões Atualização do grafo, Histórico, Salvar rascunho e Aplicar](https://mintcdn.com/strattumai/09Jh5eSHsK_uEBGp/images/guides/ontology-builder/05-barra-superior.png?fit=max\&auto=format\&n=09Jh5eSHsK_uEBGp\&q=85\&s=c84689f21ac6905b45f2d289844dacdd) Figura 5. Barra superior da tela Ontologia: versão aplicada ①, estado ②, Atualização do grafo ③, Histórico ④, Salvar rascunho ⑤ e Aplicar ⑥. | Estado | Significado | | - | - | | Tudo aplicado | O editor está igual à versão aplicada. | | Rascunho | Há mudanças que ainda não valem no grafo. O selo mostra quantas. | | Inválido | O YAML tem erros, e o selo mostra quantos. Aplicar fica bloqueado até a correção. | Salvar não muda o grafo. Use o rascunho salvo para revisar com o time antes de aplicar. ### 2.4 Aplique a versão **Onde:** Ontologia › Barra superior 1. Clique em **Aplicar** ⑥ (Figura 5). O botão só funciona para administradores e fica bloqueado enquanto o YAML tiver erros. 2. Na janela **Aplicar**, leia o efeito de cada classe de mudança (tabela do passo 2.1). A janela lembra que a versão atual fica no Histórico e pode ser reaplicada. 3. Clique em **Aplicar agora**. 4. O console confirma com "Ontologia aplicada" e o número da versão. O selo do topo ① passa a mostrar a nova versão e a data. > [!NOTE] > > Aplicar não apaga o grafo. O Memory Worker compara a versão nova com a anterior e grava só a diferença, e o grafo segue disponível durante a atualização. A atualização começa logo depois de aplicar, mesmo com a atualização automática pausada. > [!WARNING] > > Remover um tipo de entidade apaga do grafo as entidades e as arestas desse tipo. Antes de aplicar uma remoção, confira a aba Rascunho. #### Voltar a uma versão anterior Clique em **Histórico** ④. Cada versão mostra o selo **Atual**, **Rascunho** ou **Anterior** e as datas em que foi criada e aplicada. Use **Ver diferenças** para comparar, **Carregar no editor** para partir dela ou **Aplicar** para reativá-la. ### 2.5 Acompanhe a atualização do grafo **Onde:** Ontologia › Atualização do grafo 1. Clique em **Atualização do grafo** ③ (Figura 5). 2. Confira as **Fontes lidas pela ontologia** e a **Última execução**, que mostra Em execução, Concluída, Falhou, Interrompida ou Cancelada. 3. Depois da execução, confira na barra de contagem ① (Figura 6) quantos tipos estão com dados e quantos estão sem entidades. | Opção | O que faz | | - | - | | Atualização automática | O grafo se atualiza sozinho quando uma clean ou fonte lida pela ontologia é publicada. | | Pausar atualização automática | Com a pausa ligada, o grafo só muda quando você clica em **Atualizar grafo agora**. | | Atualizar grafo agora | Roda a atualização na hora. Se já houver uma em andamento, o console avisa. | ![Barra de contagem com tipos, entidades e arestas, a opção mostrar propostas e o aviso de tipos ainda sem entidades com os atalhos Verificar fontes e Atualizar grafo agora](https://mintcdn.com/strattumai/09Jh5eSHsK_uEBGp/images/guides/ontology-builder/06-barra-contagem.png?fit=max\&auto=format\&n=09Jh5eSHsK_uEBGp\&q=85\&s=4615c428fd9967454f8818dcab566924) Figura 6. Barra de contagem ①, mostrar propostas e legenda ②, aviso de tipos ainda sem entidades ③ e atalhos ④. Quando um tipo ainda não tem entidades, a tela mostra um aviso ③. Se uma fonte do tipo estiver fora do contexto ou aguardando carga, o aviso diz qual. **Verificar fontes** ④ leva ao Catálogo de Dados para você conferir, e **Atualizar grafo agora** roda a atualização. > [!WARNING] > > No Catálogo de Dados, não tire do contexto uma tabela que a ontologia usa. O grafo fica desatualizado, e a próxima atualização é bloqueada até a ontologia ser revista. > [!TIP] > > **Parte 2 concluída.** A ontologia está aplicada, e o Memory monta o grafo a partir das tabelas clean. *** ## Como confirmar que deu certo * O selo do topo mostra **Aplicado**, com a versão e a data, e o estado **Tudo aplicado**. * No **Histórico**, a versão aparece como **Atual**. * Em **Atualização do grafo**, a **Última execução** está **Concluída**, e as fontes da ontologia aparecem em **Fontes lidas pela ontologia**. * Na barra de contagem, os tipos que você esperava preenchidos aparecem com dados. * No Catálogo de Dados, cada tabela clean usada mostra em **Alimenta** os nós e as arestas da ontologia aplicada. * Em **Memory**, as entidades aparecem com os dados das fontes. ## Se algo não funcionar | Sintoma | O que conferir | | - | - | | "O agente está indisponível no momento" | Em Configurações › Instalação › Modelos de IA, confira o modelo da função **Agente de ontologia** e clique em **Testar com o agente**. O modelo precisa chamar ferramentas. Depois, clique em **Recarregar conversa**. | | "Uma fonte necessária está fora do contexto" | No Catálogo de Dados, coloque a tabela no contexto e carregue os dados. | | "O agente usou todas as etapas deste turno" | O trabalho está salvo no rascunho. Responda "continuar". | | "Esta conversa atingiu o limite de mensagens" | Clique em **Nova conversa**. Ela começa do YAML que está no editor. | | Aplicar bloqueado porque "O YAML tem erros" | Na aba YAML, corrija os erros apontados e clique em **Verificar schema**. | | "Aplicação bloqueada: uma fonte da ontologia não existe ou não pode ser usada pelo grafo" | Nenhuma versão foi ativada. Clique em **Verificar schema** para achar a referência e corrija a tabela ou a coluna. | | Um tipo aparece sem entidades | Clique em **Verificar fontes**. Ajuste no Catálogo de Dados a fonte fora do contexto ou sem carga e clique em **Atualizar grafo agora**. | | As entidades aparecem, mas sem relações entre elas | As colunas que ligam as duas pontas não têm valores em comum. Peça ao Construtor para sondar a ligação. | | Menos entidades do que linhas na tabela | Registros com o mesmo valor num dos `er_fields`, como e-mail ou CPF, viram uma entidade só. Confira se essa unificação faz sentido. | | "O resultado da gravação é desconhecido" | Não repita a operação. Abra o **Histórico** e confira as versões antes de continuar. | | "A ontologia mudou" | Outra pessoa aplicou uma versão depois que você abriu a tela. Copie o seu YAML, se quiser mantê-lo, e recarregue. | > [!NOTE] > > Fale com o FDE da Strattum que acompanha a sua implantação para revisar a primeira modelagem antes de aplicar e para unificar entidades entre sistemas quando nenhuma coluna coincide, como CPF ou e-mail. Se enviar um print, confira antes que nenhum dado pessoal aparece nele. ## Próximo passo Abra [Memory](https://docs.strattum.ai/memory/entities.md), no menu IA / Ops, para navegar pelas entidades e pelas relações do grafo. Quando conectar uma fonte nova, volte ao Construtor e pergunte se há conectores ainda não mapeados. > **[Montar a ontologia à mão](https://docs.strattum.ai/admin/ontology-guide.md)** > > Para editar o YAML direto, sem o Construtor, veja o guia de modelagem da ontologia. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.