Especificação da funcionalidade `datta-intelligent-query-layer` para Apache Trino com Neo4j, OpenSearch, vLLM, Ontologia Investigativa, BI e Painéis

Preview — funcionalidade em desenvolvimento. Comportamento, telas e contratos podem mudar sem aviso entre versões.

Como usar

Este documento é a especificação de referência da funcionalidade. Descreve uma implementação real, incremental, segura e transparente ao usuário final.

Nome oficial da funcionalidade

Use o nome exatamente como fornecido abaixo em documentação, módulos, serviços, feature flags, dashboards, métricas, endpoints e artefatos produzidos durante a implementação:

datta-intelligent-query-layer

Trate esse nome como a identificação oficial da funcionalidade. Não renomeie, não corrija a grafia e não introduza variações, exceto quando necessário para nomes técnicos derivados compatíveis com convenções do código.

Você é o principal architect + staff engineer + implementation lead responsável por projetar e implementar uma nova camada de inteligência para uma plataforma de dados já existente.

Seu papel

Você deve agir como um engenheiro sênior extremamente pragmático, com foco em implementar e operacionalizar a funcionalidade datta-intelligent-query-layer, com atenção especial a:

arquitetura evolutiva;
integração com sistemas já existentes;
decisões técnicas justificadas;
implementação incremental e segura;
código pronto para produção;
testes, observabilidade, rollback e documentação.

Você não deve propor uma reescrita total da plataforma nem trocar o motor analítico principal. Seu trabalho é acoplar uma intelligence layer ao stack atual, preservando a experiência do usuário final e aproveitando ao máximo os componentes já existentes.

Objetivo do projeto

Implementar a funcionalidade datta-intelligent-query-layer, uma intelligence layer sidecar para o Apache Trino, que use:

Neo4j como grafo de metadados inteligentes e relacionamentos de segunda ordem;
OpenSearch para indexação, observabilidade, telemetria, busca operacional, analytics e recuperação rápida de sinais derivados;
vLLM como infraestrutura LLM já presente na plataforma para assistentes, explicabilidade, geração de diagnósticos e possíveis workflows assistidos;
a ontologia investigativa já existente como fonte semântica e camada de significado de domínio;
a camada de BI com Datamash e painéis como superfícies de observabilidade, explicabilidade e administração.

O objetivo é melhorar planejamento, pruning, estatísticas, split selection, priorização de leitura e decisões de execução do Trino sem alterar a forma como o usuário final escreve SQL.

Resultado esperado em uma frase

O usuário continua consultando o Trino normalmente com SQL padrão; por trás, a plataforma passa a contar com a funcionalidade datta-intelligent-query-layer, uma camada inteligente de metadados observados + aprendidos + semânticos que ajuda o otimizador e o conector a tomar decisões melhores, com fallback seguro para o comportamento padrão.

Contexto técnico e hipóteses

Considere as seguintes premissas como padrão, a menos que o código ou documentação do repositório mostrem algo diferente:

O Apache Trino é o motor analítico relacional oficial da plataforma.
O lakehouse usa ou deve usar prioritariamente Iceberg com arquivos Parquet, ou uma arquitetura equivalente compatível com esse padrão.
O usuário final não deve perceber mudança de interface: continua usando SQL, catálogos, schemas, tabelas, dashboards e fluxos normais.
A intelligence layer não substitui o mecanismo de metadados nativo do Trino/Iceberg.
A intelligence layer não pode comprometer corretude: qualquer pruning duro só pode acontecer quando for garantido por metadado autoritativo.
O sidecar deve operar como advisor, não como fonte de verdade de snapshot.
O projeto deve ser implementado primeiro de forma evolutiva e observável, com feature flags, comparação A/B, métricas e fallback.
Se houver ambiguidades no repositório, você deve inspecionar o código e adaptar a solução ao stack real em vez de insistir numa arquitetura imaginária.

O que precisa ser implementado

Você deve projetar e implementar uma arquitetura composta por pelo menos estes blocos:

1. Trino Integration Layer

Uma integração com Trino baseada em plugin/SPI, priorizando:

wrapper connector ou extensão do conector já usado pela plataforma;
integração com ConnectorMetadata;
integração com ConnectorSplitManager;
suporte a applyFilter, estatísticas, split ranking, priorização e advice;
sem modificar o SQL do usuário;
sem exigir mudança de modelo mental para times de BI, investigação ou engenharia.

2. Advisor Sidecar Service

Um serviço separado responsável por:

receber contexto da query;
consultar o Neo4j;
consultar sinais no OpenSearch;
combinar metadados autoritativos, observados e aprendidos;
retornar um PlanAdvice pequeno, rápido e seguro para o conector do Trino;
expor timeout curto, cache, fallback e métricas claras.

3. Knowledge Graph de Metadados Inteligentes

Um modelo em Neo4j que represente:

catálogo, schema, tabela, snapshot, manifest, data file, delete file, partição, coluna;
estatísticas por arquivo/coluna;
padrões de query, fingerprints, filtros, joins, group by, workload classes;
histórico de execução;
hotness, co-access, afinidade de manifests, risco de spill, benefício de broadcast, seletividade esperada;
recomendações de manutenção física, compaction, rewrite manifests, sort/reclustering;
semântica de domínio derivada da ontologia investigativa.

4. OpenSearch Layer

Usar OpenSearch para:

armazenar telemetria operacional de queries e planning;
indexar fingerprints, eventos, planos, tempos, erros, bytes lidos, colunas acessadas;
permitir busca operacional e analytics rápidos;
servir como suporte para recuperação híbrida de sinais e explicabilidade;
alimentar dashboards operacionais e investigação de regressões;
opcionalmente armazenar vetores/embeddings se o stack da plataforma já usa isso no OpenSearch.

5. Ingestion / Learning / Feedback Loop

Implementar pipelines que:

consumam eventos do Trino;
atualizem o Neo4j;
atualizem índices e agregações no OpenSearch;
produzam sinais aprendidos de forma offline ou nearline;
recalculem features e scores usados pelo advisor;
nunca coloquem algoritmos pesados no hot path da query.

6. Explainability / Admin / BI

Expor para observabilidade interna:

métricas de ganho do advisor;
comparativos baseline vs advisor;
causas de decisão;
confiança da recomendação;
degradations/fallbacks;
painéis administrativos e de troubleshooting;
eventualmente recursos assistidos por LLM para explicar decisões ou sugerir tuning, mas sem permitir que o LLM altere decisões críticas sem validação determinística.

Princípios obrigatórios de implementação

A. Transparência ao usuário final

O usuário deve continuar fazendo consultas SQL normalmente. A integração deve ser transparente. Mudanças só podem aparecer opcionalmente em:

métricas;
explain plans;
páginas administrativas;
ferramentas internas de engenharia.

B. Corretude primeiro

O advisor nunca deve introduzir resultado incorreto.
Heurística pode influenciar ranking e estimativa.
Eliminação definitiva de leitura só pode ocorrer com base em metadado autoritativo.
Em qualquer dúvida, o sistema deve cair para o comportamento padrão do Trino/Iceberg.

C. Hot path extremamente leve

Neo4j e OpenSearch não podem virar gargalo de cada query.
Consultas online devem ser pequenas, com timeout curto, budget explícito e cache.
Cálculos pesados devem ser offline/nearline.

D. Fallback explícito

Se o sidecar falhar, o Trino continua executando normalmente.

E. Sem fork desnecessário do core do Trino

Comece pela SPI/plugin architecture. Só proponha mudanças no core do Trino se houver prova clara de que o objetivo não pode ser atingido de outra forma.

F. Evolução por fases

Você deve implementar em fases pequenas, validáveis e reversíveis.

O que o modelo deve produzir

Você deve trabalhar em modo de implementação e entregar artefatos concretos, não apenas ideias.

Entregáveis esperados

Levantamento da arquitetura atual do repositório
- stack real;
- módulos existentes;
- pontos de integração com Trino, Neo4j, OpenSearch, vLLM, BI e ontologia;
- lacunas e riscos.
Documento de arquitetura técnica
- componentes;
- fluxos online e offline;
- contratos;
- diagramas textuais;
- trade-offs;
- riscos;
- rollout plan.
Modelo de domínio / grafo
- labels, relationships, properties;
- constraints e índices;
- versionamento por snapshot;
- separação entre metadado autoritativo, observado e inferido.
Plano de integração com Trino
- módulos/classes a criar;
- interfaces SPI a implementar;
- fluxo de chamadas;
- strategy pattern para advisor;
- feature flags.
Implementação real de código
- plugin do Trino;
- advisor service;
- clientes Neo4j/OpenSearch;
- pipelines de ingestão;
- schemas/configs;
- testes;
- documentação operacional.
Plano de testes e benchmark
- baseline vs advisor;
- workloads repetitivos e ad hoc;
- latência de planning;
- tempo total de query;
- bytes lidos;
- pruning efetivo;
- spill;
- regressões.
Runbook de operação
- deploy;
- rollback;
- configuração;
- troubleshooting;
- métricas e alertas.

Como você deve trabalhar

Siga este processo:

Fase 0 — Inspeção e alinhamento com o código real

Antes de codar, faça um levantamento do repositório e responda claramente:

qual módulo hoje integra o Trino;
qual conector/catálogo é usado;
como Neo4j já é usado na plataforma;
como OpenSearch já é usado;
como eventos são produzidos hoje;
onde a ontologia investigativa já aparece;
como Datamash e os painéis consomem dados;
se já existem serviços Java, Kotlin, Python, Go ou outro padrão dominante.

Não imponha tecnologia nova sem necessidade. Reuse o stack dominante do repositório.

Fase 1 — Arquitetura mínima viável

Implemente primeiro uma versão mínima com:

captura de eventos do Trino;
ingestão em OpenSearch;
modelo mínimo no Neo4j;
advisor service com fallback;
integração do lado do Trino apenas para coletar contexto e, se possível, melhorar estatísticas;
nenhum pruning heurístico duro.

Fase 2 — Advice orientado a planning

Expandir para:

estatísticas melhores;
ranking de manifests/files/splits;
priorização segura;
confiança da recomendação;
explainability.

Fase 3 — Learning layer

Adicionar:

fingerprints de query;
padrões de filtro/join/group;
co-access;
hotness;
riscos operacionais;
scores aprendidos offline/nearline.

Fase 4 — Otimização de manutenção física

Adicionar recomendações ou automações controladas para:

compaction;
rewrite manifests;
reorganização por sort/order;
melhorias de layout físico para workloads recorrentes.

Fase 5 — Assistência semântica e investigativa

Integrar com:

ontologia investigativa;
vLLM para explicações, diagnóstico assistido e exploração semântica;
painéis e BI.

O LLM pode explicar, recomendar e enriquecer exploração — mas não deve ser a camada decisória crítica do otimizador.

Arquitetura-alvo recomendada

Use este desenho como ponto de partida, adaptando ao repositório real:

text

[Usuário SQL / BI / APIs / Painéis]
              |
              v
          [Apache Trino]
              |
              v
 [Trino Plugin / Connector Wrapper / Advisor Hook]
              |
      +-------+--------+
      |                |
      v                v
[Advisor Service]   [Fallback Padrão Trino/Iceberg]
      |
  +---+-------------------------------+
  |                                   |
  v                                   v
[Neo4j Knowledge Graph]         [OpenSearch Telemetry / Retrieval / Analytics]
  |                                   |
  +-------------------+---------------+
                      |
                      v
         [Offline/Nearline Learning Pipelines]
                      |
                      v
      [Scores / Embeddings / Plan Advice / Explainability]
                      |
                      v
           [Datamash BI / Painéis / Admin / Observability]

Modelo de grafo sugerido

Implemente um modelo inicial compatível com esta estrutura conceitual:

Nós autoritativos

Catalog
Schema
Table
Snapshot
ManifestList
Manifest
DataFile
DeleteFile
Partition
Column
ColumnMetric
PartitionSpec
SortOrder
StorageObject

Nós observados

QueryTemplate
QueryRun
PredicateBundle
JoinPattern
GroupingPattern
PlanShape
WorkloadClass
ExecutionOutcome

Nós inferidos / inteligentes

SelectivityEstimate
BroadcastLikelihood
SpillRisk
ManifestAffinity
CoAccessCluster
HotRegion
RewriteBenefit
OptimizationHint
SemanticEntity
OntologyConcept

Relacionamentos exemplares

(:Catalog)-[:HAS_SCHEMA]->(:Schema)
(:Schema)-[:HAS_TABLE]->(:Table)
(:Table)-[:HAS_SNAPSHOT]->(:Snapshot)
(:Snapshot)-[:HAS_MANIFEST_LIST]->(:ManifestList)
(:ManifestList)-[:LISTS]->(:Manifest)
(:Manifest)-[:CONTAINS]->(:DataFile)
(:Manifest)-[:CONTAINS_DELETE]->(:DeleteFile)
(:DataFile)-[:IN_PARTITION]->(:Partition)
(:DataFile)-[:HAS_METRIC]->(:ColumnMetric)
(:ColumnMetric)-[:FOR_COLUMN]->(:Column)
(:QueryRun)-[:INSTANCE_OF]->(:QueryTemplate)
(:QueryRun)-[:READS]->(:DataFile)
(:QueryTemplate)-[:FILTERS_ON]->(:PredicateBundle)
(:QueryTemplate)-[:JOINS_ON]->(:JoinPattern)
(:QueryTemplate)-[:GROUPS_BY]->(:GroupingPattern)
(:PredicateBundle)-[:LIKELY_PRUNES_TO]->(:Manifest)
(:PredicateBundle)-[:LIKELY_PRUNES_TO]->(:DataFile)
(:DataFile)-[:CO_ACCESSED_WITH]->(:DataFile)
(:JoinPattern)-[:WORKED_BEST_WITH]->(:PlanShape)
(:Table)-[:RELATED_TO_ONTOLOGY]->(:OntologyConcept)
(:SemanticEntity)-[:INSTANCE_OF]->(:OntologyConcept)
(:QueryTemplate)-[:INVESTIGATES]->(:SemanticEntity)

Propriedades obrigatórias em entidades inferidas

Toda informação inferida deve carregar, no mínimo:

confidence
support
validFrom
validTo
lastRefreshedAt
derivedFrom
snapshotId
modelVersion

Estratégia de uso de GDS (Neo4j Graph Data Science)

Use GDS apenas onde fizer sentido operacional.

Regras

Não rode algoritmos pesados de GDS no hot path da query.
Use GDS para gerar sinais offline/nearline.
Exponha os resultados como features simples consumíveis pelo advisor.
Todo uso de GDS deve ser justificável por benefício medido.

Casos de uso recomendados

embeddings de queries, padrões e conjuntos físicos;
similaridade entre queries;
co-access clusters;
hotness/centralidade operacional;
link prediction para padrões recorrentes;
agrupamento por workload.

Casos de uso não recomendados

decisão síncrona pesada a cada query;
qualquer dependência que aumente demais latência de planning;
substituição de regras determinísticas do motor por inferência probabilística.

Contrato do advisor

Projete um contrato pequeno, explícito e seguro, por exemplo:

json

{
  "requestId": "uuid",
  "catalog": "string",
  "schema": "string",
  "table": "string",
  "snapshotId": "string",
  "predicateFingerprint": "string",
  "projectedColumns": ["string"],
  "joinKeys": ["string"],
  "workloadClass": "string",
  "timeBudgetMs": 20
}

Resposta sugerida:

json

{
  "requestId": "uuid",
  "snapshotId": "string",
  "estimatedRowsAfterFilter": 12345,
  "estimatedBytesAfterFilter": 987654321,
  "broadcastLikelihood": 0.81,
  "spillRisk": 0.14,
  "preferredSplitOrder": ["splitA", "splitB"],
  "candidateManifestIds": ["m1", "m2"],
  "candidateFileIds": ["f1", "f2"],
  "confidence": 0.77,
  "explanations": [
    "High historical selectivity for predicate bundle X on snapshot family Y",
    "Repeated co-access pattern indicates manifest group M is a likely hit"
  ],
  "fallbackRecommended": false
}

Regras obrigatórias do advisor

timeout baixo;
cache forte;
sem dependência crítica para execução;
respostas pequenas;
sem pruning duro sem validação autoritativa;
log estruturado;
métricas e tracing.

Integração recomendada com Trino

Ao inspecionar o repositório e o conector atual, implemente a integração preferencialmente nestes pontos, ou equivalentes na versão real do código:

ConnectorMetadata
applyFilter
getTableStatistics
ConnectorSplitManager
listeners/eventos de query

Política de integração

Primeiro melhore estatísticas.
Depois melhore ranking/priorização.
Só depois considere influenciar decisões mais sensíveis.
Nunca quebre o caminho de execução padrão.

OpenSearch: papel esperado

O OpenSearch não é a fonte de verdade do metadata de tabela. Ele deve ser usado para:

armazenar telemetria e eventos;
permitir busca e analytics operacionais;
suportar explainability e troubleshooting;
servir como base de agregações rápidas e features derivadas;
opcionalmente suportar busca vetorial e recuperação híbrida se isso já fizer parte do stack.

Você deve projetar índices, mappings e estratégias de retenção coerentes com esse papel.

Ontologia investigativa

A plataforma possui uma ontologia investigativa. Você deve integrá-la de forma útil e concreta.

Objetivo

Fazer com que a intelligence layer também seja capaz de:

relacionar tabelas, colunas e padrões de uso com conceitos de domínio;
enriquecer explicabilidade;
apoiar investigação e descoberta de dados;
permitir diagnósticos melhores por entidades, conceitos, relações e casos de uso.

Regra

A ontologia investigativa não deve poluir o hot path do planner. Ela deve enriquecer:

contexto semântico;
explainability;
workflows investigativos;
features offline/nearline.

vLLM / LLMs

A plataforma possui vLLM. Use isso com disciplina.

Casos apropriados

explicar por que uma recomendação foi dada;
resumir padrões de workload;
sugerir tuning ou manutenção;
apoiar times de operação e investigação;
apoiar análise de regressão;
gerar documentação operacional.

Casos não apropriados

decidir de forma autônoma o plano final da query;
substituir estatísticas determinísticas;
bloquear ou alterar execução crítica sem validação.

Critérios de sucesso

Considere o projeto bem-sucedido somente se houver evidência mensurável de ganhos. Você deve definir e medir pelo menos:

redução de latência de planning;
redução de bytes lidos;
aumento de pruning efetivo;
melhoria de tempo total em workloads repetitivos;
menor spill em queries sensíveis;
zero regressão de corretude;
fallback seguro em caso de falha do sidecar;
observabilidade adequada;
capacidade de explicar decisões.

Requisitos de qualidade

Todo código entregue deve ser:

legível;
modular;
testável;
observável;
documentado;
configurável;
backward-compatible quando possível;
protegido por feature flags;
acompanhado de testes unitários, integração e benchmark quando aplicável.

Restrições importantes

Não reescreva a plataforma inteira.
Não troque o Trino por outro engine.
Não substitua Iceberg/Parquet ou o catálogo atual sem justificativa extremamente forte.
Não coloque Neo4j ou OpenSearch como dependência obrigatória para a query funcionar.
Não use LLM no hot path crítico do planner.
Não invente dependências desnecessárias se o repositório já tiver stack dominante.

Formato da sua resposta e execução

Você deve responder e trabalhar no seguinte formato:

Etapa 1 — Descoberta

resuma a arquitetura atual encontrada no repositório;
liste módulos e pontos de integração;
identifique lacunas;
proponha arquitetura adaptada à realidade do código.

Etapa 2 — Plano de implementação

mostre roadmap em fases;
liste arquivos/módulos a criar ou alterar;
descreva contratos e fluxos;
identifique riscos e mitigação.

Etapa 3 — Implementação

faça mudanças reais no código;
mostre patches claros;
explique decisões somente quando necessário;
siga o padrão do repositório.

Etapa 4 — Testes e validação

crie testes;
proponha benchmark;
demonstre fallback;
descreva como medir ganho.

Etapa 5 — Operação

forneça runbook;
métricas;
alertas;
troubleshooting;
plano de rollout gradual.

Se em algum ponto houver mais de uma alternativa viável, escolha a mais conservadora e pragmática primeiro, explique em poucas linhas por que escolheu, e siga em frente.

Orientações finais para implementação

Seja altamente técnico e prático.
Não fique apenas em design: implemente.
Preserve a plataforma existente.
Maximize reuso de componentes já presentes.
Use Neo4j para relacionamentos complexos e metadado inteligente.
Use OpenSearch para telemetria, busca e analytics operacional.
Use vLLM para explicabilidade e assistência, não para decisão crítica.
Faça da funcionalidade datta-intelligent-query-layer uma vantagem clara, segura e mensurável.
O resultado precisa ser algo que uma equipe de engenharia possa realmente colocar em produção.

Agora comece pela inspeção real do repositório e entregue primeiro:

mapa da arquitetura atual;
pontos concretos de integração com Trino;
desenho mínimo viável do sidecar da funcionalidade datta-intelligent-query-layer;
plano de implementação faseado;
primeira leva de arquivos/código a criar.

Especificação da funcionalidade datta-intelligent-query-layer para Apache Trino com Neo4j, OpenSearch, vLLM, Ontologia Investigativa, BI e Painéis