Ligue uma base de dados a um esquema e o Entity Enricher mantém as suas entidades enriquecidas como tabelas relacionais que lhe pertencem: uma tabela company real com uma coluna revenue — não um ficheiro de exportação. Descarregue uma vez um snapshot SQL pronto a executar e depois mantenha a sua base de dados convergente com um feed de deltas incremental de upserts idempotentes.
Armazene uma vez, projete a pedido. Os enriquecimentos escrevem o estado atual da entidade na camada de entidades; cada base de dados associada é uma projeção desse estado, entregue como um snapshot único mais um fluxo de deltas que você confirma. Editar um esquema custa uma reprojeção, nunca uma migração de dados.
database_sync: false); os enriquecimentos de outros utilizadores continuam a ser encaminhados normalmente..sql (tabelas + dados) e aplique-o à sua PostgreSQL. O DDL inclui índices de junção e chaves estrangeiras (as linhas filhas e de ligação são eliminadas em cascata quando uma entidade é eliminada). O cabeçalho do ficheiro indica-lhe a partir de que cursor delta deve retomar.Cada tipo de entidade tem uma chave de base de dados — o conjunto de colunas que as suas tabelas usam como índice único e alvo de conflito no upsert. Quando liga uma base de dados, uma passagem de classificação por IA propõe todo o modelo da base de dados (chaves, tipos de coluna, índices, propriedade) para rever, recorrendo a uma hierarquia simples: o ID semântico do objeto, se existir; caso contrário, um campo do tipo Id (id, product_id, …); caso contrário, as chaves naturais do objeto. Nas suas tabelas, um ID semântico surge como coluna semantic_id — o nome id fica livre para o seu próprio uso. Pode alterá-las a qualquer momento no separador “Modelo” da base de dados — uma alteração ao nível de migração depois de publicada: volte a transferir o snapshot em seguida. Nada chega à sua base de dados enquanto o schema não for publicado a partir desse separador (só a ligação não cria tabelas nem linhas).
Uma chave de base de dados nunca é anulável. Um valor nulo não corresponde a nenhuma linha, por isso, em vez de atualizar a entidade, inseriria um novo duplicado em cada enriquecimento — razão pela qual um enriquecimento cuja chave regressa vazia é rejeitado em vez de guardado. O editor mantém os dois sinalizadores separados, e um esquema que defina ambos é recusado quando o guarda ou associa uma base de dados, indicando as duas formas de o corrigir: tornar a propriedade sempre presente ou basear a chave do tipo numa propriedade diferente.
Quando uma chave de base de dados é um campo de texto enriquecido em vez de um ID semântico, conte com que o valor guardado seja a resposta do modelo — não o texto que enviou. Identificar uma empresa como Embraer no seu pedido não fixa esse campo: o enriquecimento pode responder Embraer S.A. — uma grafia corrigida, um sufixo jurídico expandido, um desambiguador removido — e é isso que passa a ser a chave da linha. Por isso, procurar a linha pelo valor que enviou pode não a encontrar (use as entity_keys devolvidas com cada enriquecimento guardado), e uma execução posterior que a formule de outra forma constitui uma chave diferente — insere uma segunda linha em vez de atualizar a sua. Isto é esperado em qualquer chave composta por texto enriquecido. A solução é um ID semântico nesse tipo: as variantes de um nome resolvem para uma única identidade estável, pelo que a linha sobrevive independentemente da grafia usada pelo modelo. Ative-o ao gerar o esquema — adicioná-lo mais tarde implica editar todos os objetos.
Os objetos aninhados dentro de arrays tornam-se as suas próprias tabelas, com linhas de junção que preservam a ordem; os objetos de valor sem identidade permanecem achatados nas colunas do respetivo objeto pai. Os nomes das propriedades são usados literalmente (entre aspas) — os nomes das suas colunas são os nomes das propriedades do seu schema, encurtados apenas onde um caminho aninhado ultrapassaria o que o PostgreSQL consegue nomear.
A projeção é determinística — o mesmo schema mapeia sempre para as mesmas tabelas e colunas. Os nomes das propriedades tornam-se nomes de colunas verbatim (entre aspas); os nomes de tipos são convertidos para snake_case como nomes de tabelas (VideoGame → video_game). A única exceção é o comprimento: o PostgreSQL não consegue conter um identificador com mais de 63 bytes, pelo que um caminho profundamente aninhado encurta os seus objetos-pai para caber (morphological_description_ → morpdesc_) — o mesmo prefixo para todas as colunas desse objeto, apresentado e editável no separador Modelo antes de ligar. Uma propriedade também pode abdicar totalmente do seu prefixo para corresponder a uma coluna que a sua database já tenha (product_identifiers.stock_keeping_unit → sku) — o alternador de ligação junto ao nome no separador Modelo. Todas as tabelas incluem uma coluna _sync_revision utilizada para manter as reproduções convergentes.
| No seu schema | Na sua base de dados |
|---|---|
| Objeto com identidade (semantic ID ou chaves) | A sua própria tabela; as chaves da base de dados tornam-se o índice único e o alvo do upsert |
| Campo escalar (string, número, booleano) | Uma coluna tipada (TEXT, BIGINT, NUMERIC, BOOLEAN) |
| Conjunto fechado (um campo limitado a uma lista de valores) | Uma simples coluna TEXT — sem CHECK, sem tipo enum na base de dados. A lista é aplicada quando a IA responde, pelo que acrescentar-lhe um valor mais tarde nunca migra a sua base de dados. Adicione a sua própria restrição, se quiser — a sincronização nunca lhe toca |
| Campo anulável ou não anulável | Por predefinição, um campo não anulável torna-se uma coluna NOT NULL, a par da barreira de qualidade abaixo — na barreira mais estrita, as referências obrigatórias também recebem chaves estrangeiras NOT NULL; desative a imposição — no registo ou mais tarde: uma alteração após a primeira sincronização é enviada como uma migração protegida no feed — para manter todas as colunas anuláveis e deixar que só a barreira imponha a completude |
| Campo multilingue | Uma coluna JSONB que contém todos os idiomas |
| Objeto de valor incorporado (sem identidade) | Achatado em colunas com prefixo (dimensions_width) |
| Matriz de objetos de valor | Uma tabela filha indexada pelo pai, ordenada, com eliminação em cascata |
Matriz de entidades / relação $ref | Uma tabela de junção que liga as linhas de origem e de destino, com a ordem preservada |
Campo de chave (identifying) | Um índice secundário para pesquisas rápidas |
| Índice moldado pela consulta (lista ordenada de campos) | Um índice multicoluna por cada forma declarada, ordenado como a consulta do ecrã de lista que serve — primeiro as facetas e os conjuntos fechados, por último a coluna de ordenação ou de intervalo, incluindo os campos multilingues (essa forma é criada uma vez por cada idioma que a sua base de dados recebeu); proposto pela passagem de classificação com uma justificação, curado no separador Modelo, vários por entidade |
| Campo de pesquisa (intenção de índice) | Um índice de trigramas (pg_trgm) sobre texto que as suas caixas de pesquisa correspondem por fragmento — por idioma e sem limite em colunas multilingues; nunca sobre um valor de lista pendente, que pertence antes a um índice moldado pela consulta (incluindo os multilingues — esse índice é criado uma vez por cada idioma que a sua base de dados recebeu); ignorado (sem efeito) em réplicas sem a extensão até que um proprietário da base de dados a instale |
| Par de coordenadas (latitude + longitude) | Um único índice espacial sobre o par (GiST nativo do PostgreSQL, sem extensão) — consultas por raio, de vizinho mais próximo e de viewport do mapa |
| Par de intervalo (limites inicial + final) | Um único índice de intervalo sobre o par — consultas de sobreposição e do tipo "que valor estava em vigor nesta data" |
Uma base de dados pode sincronizar mais do que um esquema. Os tipos de entidade com o mesmo nome nos esquemas associados acabam na mesma tabela, unidos pela respetiva chave de base de dados — os enriquecimentos de cada esquema atualizam apenas as suas próprias colunas, pelo que uma empresa enriquecida por dois esquemas se torna uma única linha com ambos os conjuntos de colunas. Os tipos exclusivos de um esquema adicionam simplesmente as suas próprias tabelas, entregues através de um delta de migração automático no feed — sem necessidade de voltar a descarregar.
Ao associar um esquema, um passo de comparação mostra exatamente que tabelas serão unidas (com as suas chaves e colunas adicionadas) e quais são novas; um esquema que partilha uma tabela adota as chaves de base de dados existentes dessa tabela, apresentadas para a sua revisão. Se os esquemas não partilharem nada, o fluxo sugere antes uma base de dados dedicada. Desassociar um esquema nunca afeta a sua base de dados — as tabelas sincronizadas permanecem.
Desassociar um esquema, ou eliminar uma sincronização, deixa duas coisas para trás do nosso lado: o estado da entidade armazenado que já nada escreve e as propriedades de base de dados que o esquema contém (chaves de base de dados, tipos de coluna, índices, propriedade). Ambas as confirmações oferecem-se para removê-las, e apenas para esquemas que ficam sem qualquer base de dados — um que ainda esteja sincronizado noutro local mantém tudo. O próprio esquema, os seus registos de enriquecimento e os seus custos nunca são afetados.
Um esquema associado tem um contrato publicado: a versão que os seus enriquecimentos e a sua base de dados usam efetivamente. Editar o esquema apenas afeta uma cópia de trabalho — as alterações de texto são aplicadas automaticamente, enquanto as alterações estruturais (novos campos, alterações de tipo ou de chave) aguardam até que carregue em Publicar. Publicar mostra uma pré-visualização do impacto exato e envia a migração correta para o feed de deltas: as novas colunas chegam como deltas ALTER TABLE, e as alterações mais pesadas (uma nova chave de base de dados, uma alteração de tipo) são executadas como migrações protegidas na sua própria base de dados — se os dados as bloquearem (um valor de chave em falta ou duplicado), o feed é pausado com o problema exato e tenta novamente de forma automática assim que o corrigir.
A publicação encontra-se no separador Model da base de dados (o Editor de Fluxo de Trabalho mostra um aviso a apontar para lá enquanto o esquema estiver ligado). Antes de publicar, mostra ambos os lados: o contrato em que a sua base de dados se encontra hoje e um diff de tudo o que a sua cópia de trabalho alteraria. Não está convencido por uma edição? Reverter para publicado repõe o contrato — reversível, e o rascunho que pôs de lado permanece restaurável durante 24 horas.
Reassociar um esquema que foi editado enquanto estava desassociado funciona da mesma forma: a sincronização lembra-se do que a sua base de dados já tem e envia apenas a diferença, mais uma atualização de snapshot para as linhas escritas entretanto. Nunca é preciso um DROP manual.
A mesma promessa abrange as nossas próprias atualizações. Quando uma nova versão melhora a forma como os esquemas se mapeiam em tabelas, a sua sincronização é migrada por si — as alterações aditivas chegam ao feed por conta própria. Se uma atualização remodelar tabelas que já contém, nunca mexemos nos seus dados sem aviso: a entrega pausa e a sua página do Database Sync pede-lhe para a aplicar, mostrando primeiro exatamente o que muda.
O enriquecimento multilingue também é de primeira classe aqui: os valores localizados chegam como colunas JSONB que transportam todos os idiomas do enriquecimento — {"en": "Headache", "fr": "Céphalée"} — para que uma só base de dados sirva todas as suas configurações regionais em simultâneo. Escolha um idioma diretamente nas suas consultas (name->>'fr') e os payloads de delta em JSON transportam os mesmos objetos indexados por idioma.
Cada base de dados responde a uma pergunta no registo: quando um enriquecimento devolve lacunas — campos não anuláveis por preencher —, o que é escrito? As três respostas formam uma escada. Nada: basta uma lacuna em qualquer sítio, incluindo dentro de um objeto aninhado, para a entidade ser rejeitada. A entidade, sem os filhos incompletos (a predefinição): a linha da própria entidade tem de estar completa, mas um filho defeituoso é ignorado e reportado em vez de afundar todo o enriquecimento. Tudo: as lacunas ficam como NULL e nada é rejeitado — mas o estado da entidade segue a regra da última escrita, o enriquecimento mais recente é a linha, pelo que uma execução parcial posterior apaga o que uma anterior preencheu. É precisamente esse apagamento que os dois degraus estritos existem para evitar.
Os enriquecimentos que não passam na validação continuam a ser guardados como registos e continuam a disparar o webhook record.created — com database.saved a false — indicando exatamente que campos obrigatórios faltavam, para que os dados incompletos nunca desapareçam em silêncio. Cada campo em falta indica também se um modelo o declarou desconhecido ou se apenas o omitiu: o primeiro caso pede um modelo mais forte, pesquisa na web ou um documento de origem; o segundo, uma revisão do esquema ou dos dados de entrada. Só os campos da chave de base de dados são sempre obrigatórios: um enriquecimento sem um valor de chave é rejeitado seja qual for o patamar.
Nos degraus estritos, uma caixa de seleção replica o mesmo contrato na sua própria base de dados sob a forma de colunas NOT NULL em todos os campos sempre presentes. No degrau mais estrito, as chaves estrangeiras das referências obrigatórias também são restringidas — nenhuma linha admitida pode ficar sem elas. Em ignorar filhos incompletos, mantêm-se anuláveis, e de forma deliberada: um item de lista a que falte um valor próprio é descartado e uma referência um-para-um partilhada cujo destino esteja incompleto (o estádio cujo ano de inauguração ninguém sabe) é desassociada — esse destino não é escrito nem atualizado e a linha guardada não liga a nada, o que escreve NULL exatamente nessas colunas de chave estrangeira. Ambos os casos são reportados na resposta do enriquecimento, e lacunas em campos de nível superior rejeitam sempre. Alterar a política após a primeira sincronização nunca é trabalho perdido: é enviada como uma migração protegida no feed, validada contra as linhas que a sua base de dados já contém.
Uma segunda barreira deteta identidades duplicadas: quando dois itens da mesma lista resolvem para a mesma chave de base de dados — um modelo que inventa um único id para duas empresas diferentes, ou uma chave que não as distingue — só pode existir uma linha, pelo que é escrita a última e as anteriores são descartadas, a mesma regra de «a última escrita vence» aplicada em todo o lado. Cada colisão é comunicada com os valores identificadores de ambos os itens e um veredicto: um duplicado repetiu os mesmos valores e não perdeu nada; um descarte conflituoso perdeu os valores que indica — ou o modelo repetiu a mesma coisa com ruído, ou trata-se de coisas diferentes e a chave precisa de uma propriedade discriminante (uma região, um ano, uma versão). A lista fica guardada no registo, pelo que uma escrita parcial continua a indicar o que perdeu muito depois de a resposta ter desaparecido.
Algo a saber antes de voltar a enriquecer: para uma lista que pertence ao seu elemento pai, a lista do enriquecimento mais recente é a lista. Uma linha filha que a resposta mais recente não repete é eliminada da sua base de dados — é assim que uma remoção genuína chega até si, e a resposta não a comunica. Isto importa quando a lista é uma que o modelo recorda em vez de enumerar: peça duas vezes os isótopos de um elemento ou os prémios de uma pessoa e a segunda resposta pode ser mais curta, o que remove linhas que eram verdadeiras. Guarde o seu próprio histórico se precisar da união de todas as execuções.
Os enriquecimentos chegam sozinhos a uma base de dados associada. Tudo o resto — um resultado que a porta recusou antes de ter corrigido o esquema, uma execução que deixou deliberadamente de fora ou resultados que quer rever ou corrigir primeiro — passa por enviar registos para a base de dados: selecione-os na página Histórico ou chame a API a partir de um fluxo de trabalho.
A ida e volta. Enriqueça com o Database Sync desativado, reformule ou aprove o resultado no seu próprio fluxo de trabalho e depois envie-o. Aquilo que envia é revalidado face ao contrato publicado do esquema e passa pela mesma porta de admissão por que passa um enriquecimento — uma injeção nunca pode escrever aquilo que um enriquecimento não conseguiu.
Dois pormenores a ter em conta. Enviar um registo sem alterações guarda-o sob esse registo. Enviar um resultado modificado cria um novo registo que remete para o original, porque os registos são uma trilha de auditoria: nunca mudam por baixo dos dados que os citam, pelo que aquilo que a sua base de dados contém é sempre rastreável até um registo com exatamente esses valores. E a validação usa o contrato tal como está hoje — se o esquema evoluiu desde que o registo foi produzido, a página Histórico assinala-o antes de enviar.
A página Histórico mostra também, por registo, se este chegou à base de dados: enviado, parcialmente enviado ou recusado com o respetivo motivo. Disponível a partir da aplicação web, da API, do MCP, do n8n e do Make.
O feed é uma fila FIFO estrita por base de dados: obtenha uma janela (opcionalmente reservada, para que o lote de um worker que falhou seja reentregue antes de qualquer coisa mais recente), aplique e confirme. As notificações de webhook são agrupadas com debounce — cada novo delta reinicia um temporizador de período de inatividade, pelo que uma rajada de enriquecimentos é anunciada uma única vez, um atraso máximo configurável limita a espera e uma página de fetch completa dispara de imediato. Duas opções de purga controlam o que o Entity Enricher guarda: eliminar as cópias dos deltas entregues aquando da confirmação e — por minimização de dados — eliminar o próprio estado da entidade assim que todas as bases de dados associadas ao esquema o tiverem recebido. Cada uma aceita um atraso opcional em dias: as cópias entregues permanecem esse tempo após a confirmação (uma janela de repetição) e uma entidade entregue é mantida até passar esse tempo sem atualizações, com uma purga horária a eliminar o que expirou. Note que a purga de estado é minimização, não eliminação definitiva: os registos de enriquecimento permanecem até os eliminar e a fusão entre enriquecimentos fica desativada para as entidades purgadas.
Um endpoint de checksum por tabela permite-lhe verificar a qualquer momento que a sua réplica convergiu, sem voltar a transferir nada.
Está tudo num só sítio na aplicação — Database Sync, mesmo por baixo de Histórico na barra lateral: registar uma base de dados em qualquer esquema (com a revisão da chave da base de dados), associar ou desassociar esquemas, colocar em pausa o fluxo de enriquecimento de um esquema associado através do respetivo interruptor (sem novos dados nem notificações até ser reativado — as publicações de esquema continuam a enviar o seu DDL, e os enriquecimentos executados durante a pausa só chegam à réplica através de uma nova extração do snapshot), editar as suas opções, ver o endpoint do webhook e revelar a respetiva chave de assinatura, transferir o snapshot, consultar o estado atual das entidades, inspecionar a fila de deltas pendentes (apenas leitura — o cursor do seu fluxo de trabalho nunca é alterado) e ver um diagrama entidade-relação das tabelas geradas, com as suas chaves e junções. Numa sincronização com várias bases de dados, o diagrama pode focar-se num único esquema: as tabelas, colunas e ligações alimentadas pelos outros esquemas ficam a cinzento — continuando visíveis no mesmo local — para que veja exatamente o que cada esquema contribui para as tabelas partilhadas.
Quando várias bases de dados ficam na mesma máquina, o botão Sync hosts da barra de ferramentas elimina a cerimónia de emparelhamento por base de dados: emparelhe essa máquina uma vez e depois atribua-lhe as inscrições. O host reivindica cada uma, cria a base de dados física se não existir e começa a sincronizar — passando o registo de uma base de dados a ser uma decisão que toma aqui, e não uma sessão de terminal no servidor. O emparelhamento é por servidor Entity Enricher, pelo que uma máquina pode servir várias instâncias lado a lado.
Uma instrução que a sua base de dados recuse — a causa habitual são duplicados preexistentes sob um novo índice único — não bloqueia a fila que vem atrás. O lote desse enriquecimento fica em quarentena, o fluxo continua a correr, e o lote é listado no separador Quarentena com a instrução que a sua base de dados rejeitou. Corrija a causa e faça a reinjeção — que reprojeta a entidade a partir do seu estado atual em vez de repetir uma instrução desatualizada — ou elimine-o.
GET /api/databases//changes?since=…&format=sql e depois POST /api/databases//ack.Utiliza o Supabase? A nossa comparação com o Supabase MCP mostra como as regras de relação e de sincronização do EE protegem um catálogo de produtos, com JSON e pequenos diagramas de tabelas.
Nada na sincronização é executado alguma vez no seu servidor de base de dados — cada caminho acima é um consumidor de saída que se liga à DSN que você lhe indicar. Azure Database for PostgreSQL, OVHcloud, AWS RDS, Supabase ou qualquer outra instância gerida funcionam exatamente como uma auto-hospedada: aponte o consumidor para a DSN na cloud (os fornecedores geridos costumam impor TLS, por isso adicione sslmode=require) e aplique.
--dsn para a instância gerida é tudo o que é preciso.delta_available ativa uma Azure Function / AWS Lambda / função OVHcloud que extrai o feed REST, executa o SQL e confirma.Duas regras mantêm seguro qualquer consumidor feito à mão: execute as instruções de cada lote por ordem, dentro de uma única transação, e confirme apenas após o commit. Os deltas são idempotentes e protegidos por revisão, por isso uma falha antes da confirmação significa apenas que o lote é reenviado e voltar a aplicá-lo converge.
As bases de dados estão disponíveis nos planos pagos (o plano define quantas pode registar). O PostgreSQL é o dialeto de lançamento; cada base de dados declara o seu dialeto, estando previstos MySQL / MariaDB, SQL Server e Oracle.