O Problema
Natural Language to SQL++ (NL2SQL++) é tão bom quanto o conhecimento de esquema por trás dele. Dê a um modelo de linguagem grande (LLM) uma pergunta como “Quantos clientes com uma solicitação anterior ativa tornaram-se inadimplentes?” e ele precisa saber quais tabelas existem, o que cada coluna significa e como as tabelas se relacionam. A maioria dos sistemas resolve isso incorporar o esquema diretamente no prompt. Isso quebra no momento em que o esquema muda, e desmorona completamente quando os nomes das colunas não carregam nenhum significado por si mesmos – a norma em dados empresariais reais.
Considere as colunas que um modelo realmente enfrenta em um esquema de produção. Alguns nomes são simplesmente opacos: CUST_VAL_04 é a faixa de receita vitalícia de um cliente, mas o nome não diz nada sobre o que ele contém. Outros são piores do que opacos, porque enganam: CLOSE_DT soa como uma data de encerramento de conta, mas armazena uma código de status (0 = aberto, 1 = congelado, 2 = fechado) – um modelo que filtra isso como uma data gerará silenciosamente um SQL++ incorreto. E depois há quase-duplicatas que um nome sozinho não consegue separar: BAL_CUR, BAL_AVG_30 e BAL_AVG_90 parecem “saldo”, mas apenas um é o atual saldo, enquanto as outras são médias de 30 e 90 dias. Perguntar “Qual é o saldo atual do cliente?” e apenas a da coluna descrição – e não o nome dele – revela que BAL_CUR é o correto e que os outros dois são armadilhas. Um analista humano recorre a um dicionário de dados para interpretar colunas como essas. Um LLM precisa da mesma coisa.
Esse dicionário já existe dentro da maioria das organizações, curado em catálogos de dados como DataHub e OpenMetadata: descrições de colunas, tipos de dados e os relacionamentos de chave estrangeira entre as tabelas. O problema é que esse conhecimento vive em um silo, desconectado do banco de dados operacional onde as consultas realmente são executadas.
Este projeto conecta catálogos de dados corporativos ao Couchbase para que o NL2SQL++ possa ler o que as colunas realmente significam em vez de adivinhar pelos seus nomes. Ele extrai metadados de colunas de um catálogo, os incorpora ao Couchbase e recupera o contexto correto no momento da consulta por meio de busca vetorial – de modo que o esquema nunca é fixado no código (hardcoded). E como clientes diferentes usam catálogos diferentes, a integração é construída em torno de uma padrão de provedor plugável: a alternância entre os catálogos compatíveis é uma alteração na configuração, e a adição de um novo catálogo implica a inclusão de um pequeno adaptador independente — sem afetar o restante do sistema.
A Grande Ideia: Uma Interface, Qualquer Catálogo
No coração deste design está um contrato único que todo catálogo de dados implementa. Independentemente da origem, ele expõe as mesmas três capacidades para o resto do pipeline:
- Buscar metadados da coluna – Cada coluna em todas as tabelas no escopo, cada uma com seu nome, descrição, tipo de dado e localização totalmente qualificada.
- Carregar relacionamentos com fetch join – Os vínculos de chave estrangeira ou de linhagem entre tabelas, expressos como predicados de junção reutilizáveis.
- Transmitir alterações ao vivo – Um feed opcional de alterações no esquema, para que você possa manter os metadados atualizados sem precisar fazer uma recarga completa.
Uma única configuração seleciona qual catálogo está ativo. Tudo o que está a jusante – o carregador, o mecanismo de consulta, a sincronização em tempo real – conversa com esse contrato comum e nunca com um catálogo específico. Para dar suporte ao próximo catálogo (Atlan, um data lake S3 ou algo ainda não construído), um adaptador é escrito para atender ao contrato; nada mais muda.
O conjunto de dados utilizado ao longo do texto é o conjunto de dados público Dados sobre o risco de inadimplência da Home Credit do Kaggle: sete tabelas relacionadas – solicitações de empréstimo, registros de órgãos de proteção ao crédito, solicitações anteriores e históricos de saldo mensal – coexistindo no Couchbase.
Como funciona, do início ao fim
Existem dois ciclos de vida. Um único configuração carrega os metadados do catálogo no Couchbase e os torna pesquisáveis. O consulta fluxo e, em seguida, responde a perguntas com base nele. Um ouvinte ao vivo opcional mantém os metadados atualizados à medida que o catálogo evolui.
Configuração: catalog no Couchbase
A instalação ocorre em quatro etapas, todas determinadas pelo catálogo que estiver ativo:
- Obter os metadutos da coluna e armazene um registro por coluna no Couchbase – sua descrição, tipo de dados e localização.
- Inserir a descrição de cada coluna em um vetor de 384 dimensões usando um modelo sentence-transformer. Apenas a descrição é vetorizada, não o nome críptico – é isso que faz uma pergunta em inglês simples corresponder ao significado de uma coluna em vez do seu rótulo.
- Criar um índice vetorial sobre esses embeddings (similaridade de cosseno) para que as buscas sejam rápidas.
- Puxe os relacionamentos de junção e armazene-os como um conjunto de predicados de junção deduplicados, por exemplo: bureau.SK_ID_CURR = application_train.SK_ID_CURR.
Cada catálogo deriva essas junções de seu próprio modelo nativo – o DataHub a partir da linhagem em nível de coluna, o OpenMetadata a partir de restrições de chave estrangeira – mas ambos produzem as strings de predicado idênticas que o mecanismo de consulta espera. Notavelmente, o sistema não pré-computa um grafo de junção rígido; ele retém os predicados brutos e permite que o modelo em tempo de consulta monte o caminho de junção válido mínimo sob demanda.
Consulta para SQL++
Responder a uma pergunta ocorre em três etapas:
- Entendido – A pergunta é dividida em subconsultas focadas para que cada conceito possa ser correspondido independentemente.
- Recuperar – Cada subconsulta é incorporada e executada por meio de uma pesquisa vetorial sobre os metadados de coluna no Couchbase, mantendo apenas as correspondências mais próximas por distância de cosseno. É aqui que EXT_SOURCE_2 aparece para uma pergunta sobre pontuações de risco, puramente porque seu descrição fósforos – nunca o seu nome.
- Refinar – A busca vetorial lança uma rede ampla, de modo que um modelo de linguagem reduz os candidatos às colunas genuinamente necessárias para responder à pergunta, inclinando-se a manter qualquer coisa útil.
- Gerar – Por fim, a pergunta, as colunas escolhidas e os relacionamentos de junção vão para um modelo Claude em AWS Bedrock, que é restrito a usar apenas as junções fornecidas e o caminho mínimo conectando as tabelas necessárias. O resultado é um SQL++ executável.
Como as chaves de junção viajam separadamente como predicados, o gerador ainda pode configurar junções corretas entre várias tabelas, mesmo quando essas colunas identificadoras foram descartadas durante o refinamento.
Mantendo-se atualizado: sincronização de metadados ao vivo
Os catálogos mudam; por exemplo, colunas são renomeadas, descrições são corrigidas e tabelas aparecem e desaparecem. Um ouvinte opcional de longa execução mantém o Couchbase sincronizado sem precisar executar a configuração novamente. Cada catálogo monitora sua origem de maneira nativa — o DataHub consome um fluxo de eventos de registro de alterações, o OpenMetadata pesquisa seu endpoint de eventos — e ambos traduzem o que veem no mesmo seis eventos de alteração normalizados. Um pool de workers compartilhados aplica então cada evento aos metadados armazenados:
| Alterar | O que Acontece no Couchbase | Reincorporar? |
| Nova tabela adicionada | Armazene um registro para cada nova coluna | Sim |
| Coluna adicionada | Armazenar a nova coluna | Sim |
| Descrição atualizada | Atualizar a descrição e é um vetor | Sim |
| Tipo de dado alterado | Atualize apenas o tipo | Não |
| Coluna removida | Exclua o registro daquela coluna | Não |
| Tabela removida | Exclua todos os registros dessa tabela | Não |
Execuções de reincorporação apenas quando o texto atrás do vetor realmente mudar – uma nova coluna ou uma descrição editada. Uma alteração puramente de tipo de dados a ignora, portanto nada é recalculado sem motivo.
Por Que Isso Importa
Os testes com os dados da Home Credit confirmaram a tese central: o NL2SQL++ aprimorado por metadados supera significativamente uma abordagem baseada apenas no esquema. Ao lidar com nomes de colunas opacos, fornecer as descrições do catálogo produzia um SQL++ correto; sem elas, o modelo apresentava erros sistemáticos quanto aos campos mapeados e à forma como era filtrado.
O benefício mais amplo é arquitetônico. Ao separar de onde vem o metadado – o catálogo – de Como é usado – incorporação, pesquisa, geração – qualquer cliente da Couchbase pode integrar seu catálogo existente na geração de consultas baseada em IA e obter resultados compatíveis com o esquema sem precisar manter manualmente o esquema. O design pluggable significa que o próximo catálogo será uma adição pequena e autônoma, em vez de uma reimplantação.
Duas imagens, lado a lado
Essa diferença é mais fácil de perceber no SQL++. As duas consultas abaixo são: Sintaticamente válido e executável sem problemas – a versão apenas de esquema simplesmente retorna o resposta errada, Porque o modelo deduziu o significado de uma coluna a partir do seu nome.
Exemplo A – Um valor que o nome não pode revelar: ESTADO
“Quais os registros mensais do banco que mostram um empréstimo que foi cancelado ou que está com mais de 120 dias de atraso?”
O campo STATUS no arquivo bureau_balance é bastante explícito, mas ele armazena apenas um caractere. códigos, Etiquetas não legíveis. A descrição do catálogo explica a codificação: “C significa fechado, X significa status desconhecido, 0 significa ausência de DPD, 1 significa máximo de did durante o mês entre 1-30, 2 significa DPD de 31-60, 5 significa DPD de 120+ ou vendido ou cancelado.” “Isento de pagamento ou com atraso superior a 120 dias” é o código ‘5’ – e não há como saber isso apenas pelo nome.
Sem o catálogo, o modelo inventa valores de string com aparência plausível que não correspondem a nada nos dados:
– Sem catálogo: funciona perfeitamente, retorna 0 — as etiquetas conjecturadas não existem
SELECT COUNT(*) AS num_records
A partir do crédito_risco.sampleScope.bureau_balance como bb
WHERE bb.STATUS IN ['WRITTEN_OFF', 'DPD_120_PLUS', 'desativado'];
Com o catálogo, a codificação está na descrição, portanto, corresponde ao código real:
– Com catálogo: correto — '5' = DPD 120+ / vendido / cancelado SELECT COUNT(*) AS num_records
A partir do atributo creditrisk.sampleScope.bureau_balance AS bb WHERE bb.STATUS = '5';
Exemplo B – um sufixo que não significa nada por si só: SK_DPD vs SK_DPD_DEF
“Quais empréstimos de caixa/POS estavam em atraso durante um mês, ignorando dívidas triviais e pequenas?”
Duas colunas quase idênticas estão lado a lado no campo POS_CASH_balance. O SK_DPD é “DPD (Dias atrasados) durante o mês de crédito anterior.” SK_DPD_DEF é “DPD durante o mês com tolerância (dívidas com valores de empréstimo baixos são ignoradas).” A única pista é o sufixo _DEF – sem sentido em si mesmo. “Ignorando dívidas triviais e pequenas” é exatamente SK_DPD_DEF, mas nada no nome diz isso.
Sem o catálogo, o modelo seleciona a coluna com nome mais simples e conta discretamente as dívidas que a pergunta questiona para excluí-las:
– Sem catálogo: funciona perfeitamente, mas o SK_DPD NÃO ignora dívidas de valor baixo.
SELECT pc.SK_ID_PREV,
pc.MONTHS_BALANCE,
pc.SK_DPD
A partir do parâmetro creditrisk.sampleScope.POS_CASH_balance como pc
WHERE pc.SK_DPD > 0;
Com o catálogo, a cláusula de tolerância na descrição aponta para a coluna direita:
– Com catálogo: correto — O SK_DPD_DEF aplica a tolerância de valor baixo
SELECT pc.SK_ID_PREV,
pc.MONTHS_BALANCE,
pc.SK_DPD_DEF
A partir do parâmetro creditrisk.sampleScope.POS_CASH_balance como pc
WHERE pc.SK_DPD_DEF > 0;
Em ambos os casos, a falha é invisível no nível do SQL – nada produz erros e nada parece estar errado. Só a coluna descrição distinge uma consulta correta de uma que está seguramente errada.
Os metadados ricos já estão presentes na empresa; este projeto apenas ensina a base de dados a interpretá-los. Quer saber para onde isso vai levar? Entre em contato com a Couchbase para conversar sobre consultas conversacionais com seus dados.
Deixe um comentário
Você precisa fazer o login para publicar um comentário.