Montar a ontologia

A ontologia diz à Strattum o que existe nos seus dados e como as coisas se ligam: um cliente abre chamados, um contato trabalha numa empresa. Com ela, a Strattum monta o grafo da Memory, que junta o mesmo cliente visto em sistemas diferentes e deixa os assistentes de IA responderem perguntas sobre ele. A ontologia fica na tela Ontologia do Console. Só administradores a alteram.

O jeito recomendado: o Construtor

Na tela Ontologia, clique em Abrir o Construtor. Ele pergunta sobre o seu negócio, olha as tabelas dos seus conectores e propõe a ontologia pronta. Você revisa a proposta, aceita e aplica. O Construtor aparece quando está habilitado na sua instalação. Se o painel disser que ele está indisponível, fale com quem administra a Strattum, ou monte a ontologia à mão, como explicado abaixo.

Fazer à mão

A ontologia é um arquivo YAML com três partes:

nodes: os tipos de coisa que existem, como cliente, empresa ou chamado. Cada um vem de uma tabela.
edges: as ligações entre eles, como “o chamado foi aberto pelo cliente”.
timeline: eventos com data, que aparecem na linha do tempo de uma entidade.

Um exemplo completo

Imagine um CRM, com as tabelas de contatos e de atividades, e um sistema de suporte, com as tabelas de solicitantes e de chamados. A mesma pessoa está cadastrada nos dois sistemas. A ontologia abaixo:

junta o contato do CRM e o solicitante do suporte num cliente só, pelo e-mail;
cria os chamados e liga cada um a quem o abriu;
coloca as atividades do CRM na linha do tempo do cliente.

nodes:
  - label: Customer                     # o tipo, em PascalCase
    source: clean/crm_contacts          # a tabela que alimenta este tipo
    connector: hubspot                  # de qual conector a tabela vem
    id_field: external_id               # a coluna que identifica cada linha
    er_fields: [email, phone]           # colunas que reconhecem o mesmo cliente em outros sistemas
    properties: [external_id, email, phone, name]   # colunas que entram no grafo

  - label: Customer                     # o mesmo tipo, vindo de outra fonte
    source: clean/support_requesters
    connector: zendesk
    id_field: requester_id              # o id do solicitante no suporte
    er_fields: [email]                  # o e-mail liga este cliente ao do CRM
    properties: [requester_id, email, name, plan]

  - label: Ticket
    source: clean/support_tickets
    id_field: external_id
    properties: [external_id, subject, status, requester_email, created_at]

edges:
  - type: REQUESTED_BY                  # o nome da ligação, em MAIÚSCULAS
    source: clean/support_tickets       # a tabela onde a ligação aparece
    from:
      label: Ticket
      join_key: external_id             # cada linha é o próprio chamado
    to:
      label: Customer
      match_field: email                # procura o cliente pelo e-mail...
      source_column: requester_email    # ...usando esta coluna do chamado

timeline:
  - event_type: crm_activity
    source: clean/crm_activities
    entity_join: "contact_id -> Customer.external_id"    # a coluna que aponta para o cliente
    timestamp_field: created_at
    properties: [activity_type, notes]

Como o cliente das duas fontes vira um só

Os dois itens de nodes têm o mesmo label, Customer, e cada um lê uma tabela. Quando uma linha do CRM e uma do suporte têm o mesmo e-mail, a Strattum as reconhece como a mesma pessoa e cria uma entidade só, com as informações das duas:

Origem	Linha
CRM (`clean/crm_contacts`)	`external_id: c-17`, `email: ana@empresa.com.br`, `phone: +5511999999999`, `name: Ana Souza`
Suporte (`clean/support_requesters`)	`requester_id: z-904`, `email: Ana@Empresa.com.br`, `plan: premium`
Cliente no grafo	`Ana Souza`, com e-mail, telefone, plano e os ids dos dois sistemas

O e-mail com maiúsculas no suporte não atrapalha, porque a Strattum normaliza os identificadores antes de comparar. Para juntar fontes de um mesmo tipo:

Repita o label e mude o source. Cada fonte tem o próprio id_field e as próprias properties.
As fontes precisam ter um identificador em comum em er_fields. Ele pode ser direto (as duas têm email) ou em cadeia: o CRM compartilha cpf com o ERP, e o ERP compartilha email com o suporte.
Se as fontes não têm nenhum identificador em comum, a validação recusa a ontologia, porque os clientes de uma nunca se encontrariam com os da outra.

Três regras resolvem a maior parte dos casos:

source começa com clean/, seguido do nome da tabela tratada do conector. Se a tabela vem de uma fonte federada, o prefixo é fed/.
Toda coluna citada em id_field, er_fields ou indexed_fields precisa estar em properties.
Use er_fields só para colunas que identificam a pessoa ou empresa sozinhas, como e-mail, telefone, CPF ou CNPJ. É por elas que a Strattum reconhece que o cliente do CRM e o do suporte são a mesma pessoa. Nunca coloque ali uma coluna que se repete, como status ou cidade.

Para ligar dois tipos, use join_key quando a tabela já traz o identificador do outro lado, e match_field quando a ligação é por um valor como o e-mail.

Aplicar

Na tela Ontologia, aba YAML, clique em Editar e cole ou altere o YAML. O Console valida enquanto você edita.
Clique em Verificar schema para conferir se as tabelas e colunas existem.
Clique em Salvar rascunho. Nada muda no grafo ainda.
Clique em Aplicar e confirme em Aplicar agora.

Para voltar atrás, abra o Histórico, escolha uma versão anterior e aplique de novo.

Os campos

O arquivo tem um campo opcional no topo, version, que você pode usar para numerar as suas versões. Os demais campos ficam dentro de nodes, edges e timeline.

Campos de um tipo (`nodes`)

Cada item de nodes descreve um tipo de coisa e a tabela de onde ele vem.

Campo	Para que serve	Exemplo	Obrigatório
`label`	O nome do tipo, em PascalCase (inicial maiúscula, sem espaço, acento nem sublinhado). É o nome que aparece no grafo.	`Customer`	sim
`source`	A tabela que alimenta o tipo. Cada linha vira uma entidade. Começa com `clean/` para tabela tratada de conector, ou `fed/` para view de uma fonte federada.	`clean/crm_contacts`	sim
`id_field`	A coluna que identifica cada linha dentro dessa tabela, como o id do registro no sistema de origem.	`external_id`	sim
`properties`	As colunas que entram no grafo como informação da entidade. Coluna fora dessa lista não entra.	`[external_id, email, name]`	sim
`er_fields`	As colunas que reconhecem a mesma entidade em outros sistemas. Duas linhas com o mesmo valor em uma delas viram uma entidade só.	`[email, cpf]`	não
`identifier_columns`	Liga um nome de `er_fields` a uma coluna com outro nome nesta tabela. Serve quando um sistema chama o CPF de `documento`, por exemplo.	`{cpf: documento}`	não
`normalizers`	Diz como limpar o valor de um identificador antes de comparar. A chave é o nome em `er_fields` ou o `id_field`. Veja a tabela de normalizadores.	`{matricula: alnum}`	não
`indexed_fields`	Colunas que as pessoas usam para filtrar, como status ou ano. Deixa o filtro mais rápido e não junta entidades.	`[status, year]`	não
`connector`	O nome do conector de origem. O Console usa para mostrar o ícone.	`hubspot`	não
`connector_instance`	Separa duas conexões do mesmo conector, como duas contas de Salesforce, para que as entidades delas nunca se juntem. Não pode ter `:`. Com uma conexão só, deixe em branco.	`salesforce#vendas`	não
`display_tier`	Se o tipo aparece ligado quando você abre o grafo no Console: `entity` aparece (padrão), `activity` e `detail` começam escondidos. Não muda os dados.	`detail`	não
`display_color`	A cor do tipo no grafo do Console. Sem ela, o Console escolhe uma cor.	`"#f59e0b"`	não

Identificadores: `id_field` e `er_fields`

O id_field diz qual é a linha. O er_fields diz quem é a entidade. Um chamado só existe no sistema de suporte, então basta o id_field. Um cliente aparece no CRM, no suporte e no ERP, então ganha também er_fields, para que a Strattum reconheça que é a mesma pessoa. Coloque em er_fields só colunas que identificam a entidade sozinhas: e-mail, telefone, CPF, CNPJ, placa, matrícula. Uma coluna que se repete entre entidades diferentes, como status, cidade ou cor, juntaria todas elas numa só. Para filtrar por essas colunas, use indexed_fields. Toda coluna citada em id_field, er_fields e indexed_fields precisa estar também em properties.

Normalizadores

Antes de comparar identificadores, a Strattum limpa os valores, para que (11) 99999-9999 e 11999999999 sejam o mesmo telefone. Quando a coluna se chama email, phone, telefone, cpf ou cnpj, a limpeza certa é escolhida pelo nome. Para outro nome, declare em normalizers, usando o nome que está em er_fields.

Normalizador	O que faz	Exemplo
`email`	Minúsculas, sem espaços e sem o `+apelido`	`Ana+x@X.COM` vira `ana@x.com`
`phone`	Só dígitos, com `+55` na frente	`(11) 99999-9999` vira `+5511999999999`
`cpf`	Só dígitos; descarta o valor se não tiver 11	`111.222.333-44` vira `11122233344`
`cnpj`	Só dígitos; descarta o valor se não tiver 14	`11.222.333/0001-81` vira `11222333000181`
`digits`	Só dígitos	`12.345.678-9` vira `123456789`
`alnum`	Só letras e dígitos, em minúsculas. Bom para RG, que pode terminar em X.	`M-123.456` vira `m123456`
`upper`	Maiúsculas, sem espaços nas pontas	`ab-12` vira `AB-12`
`title`	Primeira letra de cada palavra em maiúscula	`ANA SOUZA` vira `Ana Souza`
`text`	Minúsculas, sem espaços nas pontas. É o padrão.	`M-123456` vira `m-123456`
`verbatim`	Só tira os espaços das pontas	`Ab-12` vira `Ab-12`

Exemplo de um cadastro de funcionários em que o CPF está numa coluna chamada documento e a matrícula tem letras:

nodes:
  - label: Employee
    source: clean/hr_staff
    id_field: external_id
    er_fields: [cpf, matricula]
    identifier_columns: {cpf: documento}   # o cpf desta tabela está na coluna documento
    normalizers:
      matricula: alnum                     # cpf já é limpo como CPF pelo nome
    properties: [external_id, documento, matricula, name]

Campos de uma ligação (`edges`)

Cada item de edges liga dois tipos. Cada linha da tabela indicada vira uma ligação.

Campo	Para que serve	Exemplo	Obrigatório
`type`	O nome da ligação, em MAIÚSCULAS com sublinhado. Leia como verbo: o chamado `REQUESTED_BY` o cliente.	`REQUESTED_BY`	sim
`source`	A tabela onde a ligação aparece.	`clean/support_tickets`	sim
`from`	O lado de onde a ligação sai.	veja abaixo	sim
`to`	O lado aonde a ligação chega.	veja abaixo	sim
`properties`	Colunas que viram informação da própria ligação, como o canal ou a data.	`[channel]`	não

Cada lado (from e to) diz qual tipo procurar e como achar a entidade certa:

Campo do lado	Para que serve
`label`	O tipo desse lado. Precisa existir em `nodes`.
`join_key`	A coluna da tabela que traz o `id_field` da entidade desse lado. Use quando a tabela já tem o id do outro sistema, como uma chave estrangeira.
`match_field`	A informação da entidade usada para achá-la, como `email`. Use quando a ligação é por um valor, e não por id.
`source_column`	Com `match_field`, a coluna da tabela que traz esse valor.

Cada lado usa join_key ou match_field, nunca os dois. Exemplo de uma tabela que liga contatos a empresas pelos ids:

edges:
  - type: WORKS_AT
    source: clean/crm_contact_company    # uma linha por contato e empresa
    from:
      label: Customer
      join_key: customer_external_id     # o id do contato
    to:
      label: Company
      join_key: company_external_id      # o id da empresa

Campos de um evento (`timeline`)

Cada item de timeline transforma as linhas de uma tabela em eventos com data na linha do tempo de uma entidade, como reuniões, pedidos ou atividades.

Campo	Para que serve	Exemplo	Obrigatório
`event_type`	O nome do tipo de evento.	`crm_activity`	sim
`source`	A tabela dos eventos.	`clean/crm_activities`	sim
`entity_join`	Qual coluna aponta para a entidade dona do evento, no formato `coluna -> Tipo.id_field`.	`"contact_id -> Customer.external_id"`	sim
`timestamp_field`	A coluna com a data do evento. O padrão é `created_at`.	`created_at`	não
`properties`	Colunas que viram informação do evento.	`[activity_type, notes]`	não

Erros comuns

A mensagem fala de	O que corrigir
`must be PascalCase`	O `label` começa com maiúscula e não tem espaço, acento nem sublinhado: `Customer`, não `customer`.
`must start with 'clean/', 'fed/' or 'raw/'`	Escreva a fonte com o prefixo: `clean/crm_contacts`, não `crm_contacts`.
`must be listed in 'properties'`	Acrescente a coluna citada à lista `properties` do mesmo tipo.
`join_key` ou `match_field`	Cada lado de uma ligação precisa de um dos dois, nunca dos dois juntos.
`sources that cannot converge`	Duas fontes do mesmo tipo não têm identificador em comum. Acrescente a `er_fields` (e a `properties`) a coluna que liga as duas, como o e-mail.
`Tabela não encontrada` (em Verificar schema)	A tabela tratada desse conector ainda não existe. Rode a sincronização do conector, espere terminar e verifique de novo.

A validação mostra um problema por tipo de cada vez. Depois de corrigir, valide de novo para ver se há outro.

Acesso

Dados e ontologia

Modelar a ontologia

Governança

Operação

O jeito recomendado: o Construtor

Fazer à mão

Um exemplo completo

Como o cliente das duas fontes vira um só

Aplicar

Os campos

Campos de um tipo (`nodes`)

Identificadores: `id_field` e `er_fields`

Normalizadores

Campos de uma ligação (`edges`)

Campos de um evento (`timeline`)

Erros comuns

​O jeito recomendado: o Construtor

​Fazer à mão

​Um exemplo completo

​Como o cliente das duas fontes vira um só

​Aplicar

​Os campos

​Campos de um tipo (nodes)

​Identificadores: id_field e er_fields

​Normalizadores

​Campos de uma ligação (edges)

​Campos de um evento (timeline)

​Erros comuns

O jeito recomendado: o Construtor

Fazer à mão

Um exemplo completo

Como o cliente das duas fontes vira um só

Aplicar

Os campos

Campos de um tipo (`nodes`)

Identificadores: `id_field` e `er_fields`

Normalizadores

Campos de uma ligação (`edges`)

Campos de um evento (`timeline`)

Erros comuns