De planilhas dispersas a SQL conversacional — com confiabilidade autêntica

Por que “conversar com planilhas” geralmente decepciona

As planilhas são a interface universal dos dados comerciais. As equipes os usam para orçamentos, inventário, rastreamento de vendas e até mesmo como bancos de dados ad-hoc. No entanto, a mesma flexibilidade que os torna indispensáveis também os torna complicados para a automação.

As interfaces de linguagem natural para planilhas geralmente falham porque esperam que o LLM adivinhe o significado de um caos não estruturado: cabeçalhos inconsistentes, linhas ocultas, células mescladas, formatos de data ambíguos e fórmulas quebradas silenciosamente.

Na prática, isso acontece quando os usuários fazem o upload de um arquivo de planilha (como um Excel ou Google Sheet) diretamente em um LLM de uso geral, como ChatGPT, Gemini ou Claude, esperando que ele “entenda” o conteúdo do arquivo. O modelo recebe somente uma representação de texto achatada da planilha, perdendo sua estrutura tabular, fórmulas e contexto. Sem um esquema definido ou uma camada de validação, o LLM é forçado a inferir significado a partir de dados brutos confusos, o que leva a raciocínios não confiáveis e respostas inconsistentes

O que as pessoas imaginam é: “Pergunte em inglês, obtenha uma resposta”.

O que realmente acontece é: “O modelo alucinou uma coluna que não existe”.

Antes que um modelo possa raciocinar de forma confiável, ele precisa da mesma coisa que os analistas e as ferramentas de BI precisam: um esquema. Definir esse esquema (tabelas explícitas, tipos claros, dados de amostra) é a diferença entre demonstrações de brinquedos e confiabilidade de produção. Somente quando os dados tiverem um contrato estruturado, podemos anexar uma camada conversacional que pareça inteligente em vez de frágil.

A falha não é o LLM, é a estrutura e as grades de proteção que faltam. Conversar com planilhas só se torna viável quando trate-os como um banco de dados primeiro e deixe o LLM operar dentro de um ambiente controlado e validado.

O upload de planilhas diretamente para o ChatGPT ou Claude geralmente decepciona porque essas ferramentas enfrentam limites técnicos e estruturais rígidos. Ambos limitam o tamanho dos arquivos (cerca de 30 a 50 MB) e enfrentam dificuldades com arquivos grandes, com várias folhas ou com muitas fórmulas, às vezes truncando o conteúdo para caber em suas janelas de contexto. Eles também interpretam erroneamente recursos complexos de planilhas, como linhas ocultas, células mescladas ou fórmulas, já que esses modelos extraem texto simples em vez de preservar a estrutura dos dados. Mesmo quando os uploads são bem-sucedidos, os limites de contexto ou token significam que apenas parte dos dados é analisada, resultando em respostas incompletas ou enganosas. Problemas frequentes, como desempenho lento, falhas ou falhas no modelo, prejudicam ainda mais a confiabilidade.

Fundamentalmente, isso acontece porque os LLMs operam semanticamente, não estruturalmente. Eles entendem a linguagem natural, não a lógica relacional das tabelas de dados. O novo modos de agente no ChatGPT e Claude tentam compensar por gerando e executando código Python para inspecionar e interpretar planilhas, mas essa abordagem permanece propensa a erros e não determinística, pois o modelo deve primeiro inferir a estrutura dos dados e depois escrever o código para analisá-los corretamente. Em contraste, um Agente SQL funciona em um esquema explícito e validado em que o raciocínio é baseado em consultas estruturadas em vez de scripts improvisados. Isso permite uma computação segura, auditável e precisa, transformando a intenção semântica em resultados determinísticos em vez de adivinhação por meio da geração de código ad-hoc.

Então, como podemos realmente fazer isso funcionar?

Depois de entender por que “conversar com planilhas” geralmente falha, a próxima pergunta é óbvia: como podemos fazer isso funcionar?

Em vez de enviar arquivos brutos do Excel ou do Google Sheets para o ChatGPT, Claude ou Gemini e esperar que o modelo possa interpretar o caos, podemos criar um agente confiável que realmente raciocinam sobre nossos dados.

A chave não é mágica, é engenharia... A ideia é transformar planilhas em esquemas relacionais, carregue-os em um ambiente validado e deixe um modelo operar dentro de restrições claras e auditáveis. Ao contrário do ChatGPT ou do Claude modos de agente, que deve primeiro gerar e executar o código Python para “adivinhar” a estrutura de uma planilha, um Agente SQL opera em um esquema explícito e validado. Isso permite raciocínio determinístico, execução mais segura e rastreabilidade total.

1. Modele os dados → Planilha (s) → Esquema relacional (tabelas, colunas, chaves, descrições, alguns exemplos de linhas por tabela)‍
2. Carregar e validar → ETL/ELT para um depósito (por exemplo, Postgres/BigQuery/Snowflake)‍
3. Fundamento do LLM → RAG/esquema vinculado a selecione somente tabelas/colunas relevantes‍
4. Gerar SQL → O LLM propõe uma consulta (poucas fotos + contexto de negócios)‍
5. Validação de pré-execução → Analisador SQL + verificações de política (somente SELECT, LIMIT, verificações de existência)‍
6. Execute com o mínimo de privilégios → Usuário de banco de dados somente para leitura‍
7. Resposta → Transforme linhas em uma resposta concisa e ideal para negócios

Etapa 1 — De planilhas a um esquema confiável

Antes que qualquer agente possa “conversar” com os dados, ele deve primeiro entenda sua estrutura. Imagine herdar uma dúzia de planilhas confusas, colunas com nomes vagos, totais aleatórios e linhas ocultas. O primeiro passo é transformar esse caos em uma história clara que o modelo possa seguir. Projete um esquema onde cada nome de coluna fala por si, cada tabela tem um propósito e as relações são explícitas. Adicionar descrições curtas e um alguns exemplos linhas para dar contexto, muito parecido com uma cena rápida em um filme. A normalização evita a duplicação, enquanto um pouco de desnormalização facilita a resposta às perguntas frequentes. Uma vez que essa base exista, o agente finalmente tem algo confiável sobre o qual raciocinar.

Em resumo:

• As colunas devem ser descritivo: id_do_cliente, data_do_pedido, valor_bruto_usd
• Adicionar descrições de tabela/coluna que usam termos comerciais
• Incluir 3 linhas de amostras sintéticas como comentários por tabela (ajuda na fundamentação de poucos)
• Normalize o suficiente para evitar a duplicação; desnormalize com moderação para consultas comuns

Exemplo de esqueleto DDL

-- Customers
CREATE TABLE dim_customer (
  customer_id SERIAL PRIMARY KEY,
  full_name TEXT NOT NULL, -- e.g., legal or preferred name
  email TEXT, -- unique if enforced upstream
  created_at TIMESTAMP NOT NULL
);
-- Example rows (for the agent; do not load in prod)
-- INSERT INTO dim_customer (customer_id, full_name, email, created_at) VALUES
-- (101, 'Ana Pereira', '[email protected]', '2024-01-04 09:12:00'),
-- (102, 'Carlos Méndez', '[email protected]', '2024-01-12 15:33:00'),
-- (103, 'Lucía Díaz', '[email protected]', '2024-02-01 11:05:00');

-- Orders
CREATE TABLE fct_order (
  order_id SERIAL PRIMARY KEY,
  customer_id INT NOT NULL REFERENCES dim_customer(customer_id),
  order_date DATE NOT NULL,
  gross_amount_usd NUMERIC(12,2) NOT NULL,
  channel TEXT CHECK (channel IN ('web','store','partner'))
);
-- Example rows
-- INSERT INTO fct_order (order_id, customer_id, order_date, gross_amount_usd, channel) VALUES
-- (5001, 101, '2024-03-01', 120.00, 'web'),
-- (5002, 102, '2024-03-02', 60.50, 'store'),
-- (5003, 101, '2024-03-05', 240.00, 'partner');

Etapa 2 — Pipeline ETL (das planilhas ao banco de dados)

É aqui que a disciplina encontra os dados. O objetivo é pegar cada planilha e movê-la por um fluxo: extração, validação, e carregando. Usando ferramentas como pandas e SQLAlchemy, os dados são lidos, limpos e gravados no depósito com tipos consistentes e integridade referencial. Pense nisso como treinar funcionários da alfândega para seus dados. Cada arquivo deve passar por uma inspeção antes de entrar no banco de dados. O pipeline não apenas estrutura o fluxo (Stage → Clean → Dim/Facts), mas também garante que as tabelas resultantes reflitam o DDL que você definiu anteriormente. Depois de validado, o banco de dados se torna uma fonte única de verdade que seu agente pode explorar com segurança.

• Extrair: Leia .xlsx/.csv do drive/SharePoint/S3 (por exemplo, pandas em Python)
• Validar: Tipos, nulidade, integridade referencial‍
• Carregar: Armazém de sua escolha; execute o DDL acima primeiro
• ‍Transformar: Stage → Clean → Dim/Facts (use scripts dbt ou SQL)

Etapa 3 — Aterramento e recuperação (Schema Linking/Mini‑RAG)

Se o esquema do banco de dados for pequeno o suficiente, você poderá incluir todas as descrições de tabelas e colunas diretamente no prompt do sistema do LLM; caso contrário, você precisará de uma camada de aterramento e recuperação para evitar sobrecarregar o modelo com contexto irrelevante.

Essa etapa garante que o LLM veja apenas as partes do esquema que importam para cada pergunta, melhorando a precisão e reduzindo as alucinações. O processo funciona indexando metadados leves do esquema (como nomes de tabelas e colunas, descrições, valores de amostra e relações entre chaves) e recuperando os fragmentos mais relevantes usando a pesquisa vetorial ou por palavra-chave.

Quando um usuário faz uma pergunta, o sistema a analisa, recupera as tabelas e colunas relevantes e constrói um contexto compacto e focado para que o modelo gere consultas SQL com segurança. Resumindo, o grounding atua como o mapa do LLM para seu banco de dados, escalando de um único esquema pequeno incorporado no prompt para uma abordagem orientada à recuperação para armazéns maiores, garantindo a geração de consultas eficiente, precisa e confiável.

Objetos de recuperação

• Nomes de tabelas, descrição de tabelas, nomes de colunas, descrições, casos de uso de tabelas
• Opcional: amostras de valor máximo por coluna (por exemplo, canais comuns), exemplos de consulta

Loop de recuperação

1. Analise a pergunta do usuário
2. Recuperar tabelas/colunas candidatas (pesquisa vetorial ou por palavra-chave)
3. Crie o contexto do modelo: apenas essas tabelas e alguns exemplos

Etapa 4 — Garantindo confiabilidade (poucas fotos + política)

Agora, o agente precisa aprender a “falar SQL” com responsabilidade. Por meio do design rápido, você não está apenas dando instruções, está moldando seus hábitos de raciocínio. O prompt do sistema fornece o tom, o contexto e as regras de engajamento: ele deve sempre limitar os resultados, verificar a sintaxe e nunca modificar os dados. Alguns exemplos funcionam como experiências anteriores que orientam o agente em direção a respostas seguras e estruturadas. Políticas como as cláusulas SELECT only e LIMIT transformam a solicitação de uma conversa casual em um contrato de confiança entre humano e modelo.

Trecho de aviso do sistema

You are an agent designed to interact with a SQL database.
Given an input question, create a syntactically correct {db.dialect} query to run, then look at the results of the query and return the answer. Unless the user specifies a specific number of examples they wish to obtain, always limit your query to at most 5 results.

You can order the results by a relevant column to return the most interesting examples in the database. Never query for all the columns from a specific table, only ask for the relevant columns given the question.

You MUST double check your query before executing it. If you get an error while executing a query, rewrite the query and try again.

DO NOT make any DML statements (INSERT, UPDATE, DELETE, DROP etc.) to the
database.

# DATABASE SCHEMA

Below is the complete database schema for the Zonamerica database:

## Master Tables (edificios, locales, clientes)
{master_tables_sql}

## Secondary Tables
{secondary_tables_sql}

## Indexes
{indexes_sql}

# EXAMPLE QUERIES

Below are example queries that demonstrate that solve a set of questions. You can use this same queries:

{example_queries_sql}

Use these schemas and examples to guide your query construction.

Na variável example_queries_sql é importante adicionar alguns exemplos reais de consultas que o agente precisa responder.

Etapa 5 — Crie o agente (LangChain v1 + SQL Toolkit)

Abaixo está um padrão compacto que você pode adaptar. Se o contexto completo do esquema se encaixar no prompt, o tabelas de listas, esquema, verificador de consultas, e executar as ferramentas são suficientes. (Agente SQL Langchain)

from langchain_openai import ChatOpenAI
from langchain_community.agent_toolkits import SQLDatabaseToolkit
from langchain_community.utilities import SQLDatabase
from langchain.agents import create_sql_agent

# 1) DB with READ-ONLY user
sql_db = SQLDatabase.from_uri("postgresql+psycopg2://agent_ro:***@host:5432/warehouse")

# 2) LLM
llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)

# 3) Toolkit exposes: list tables, get schema, check query, run query
toolkit = SQLDatabaseToolkit(db=sql_db, llm=llm)
tools = toolkit.get_tools()

# 4) Create the agent with built-in SQL tools
agent = create_agent(
    llm=llm,
    tools=tools,
    system_prompt=system_prompt,
)

# 5) Ask a question
question = "Show total sales by channel last month"
for step in agent.stream(
	{"messages": [{"role": "user", "content": question}]},
	stream_mode="values",
):
	step["messages"][-1].pretty_print()

Caminho de atualização: para esquemas maiores, vá para um Gráfico Lang máquina de estados: nós para (listar tabelas → escolher → buscar esquema → gerar → verificar → executar → refinar). Adicione novas tentativas nas mensagens de erro do banco de dados.

Se o esquema do seu banco de dados com alguns exemplos resumidos couber no prompt do sistema, você poderá ignorar as seguintes ferramentas do SQL Toolkit: sql_db_list_tables e sql_db_schema.

Etapa 6 — Validação e segurança antes da execução

Antes de qualquer SQL entrar em contato com o banco de dados, cada consulta deve passar por um camada de validação e política. Essa etapa garante que o agente nunca execute comandos inseguros, sem sentido ou que aumentem os privilégios. LangChain v1 apresenta o middleware conceito, que se encaixa perfeitamente aqui: você pode anexar uma lógica que inspeciona, modifica ou bloqueia uma chamada de ferramenta antes que ela seja executada.

Nessa camada, você pode:‍

• Aplique políticas. Permita somente instruções SELECT, exija cláusulas LIMIT, restrinja o acesso a esquemas ou tabelas específicos e bloqueie palavras-chave perigosas, como DELETE, DROP, ALTER ou UPDATE. ‍
• Consultas de análise e lint. Execute o SQL gerado pelo LLM por meio de um analisador para verificar a sintaxe e garantir que os nomes das tabelas e colunas existam no esquema. Essa etapa também pode normalizar a capitalização ou a formatação para fins de rastreabilidade.‍
• Execute a análise estática. Detecte uniões cartesianas, escaneamentos excessivos ou agregações não filtradas que podem retornar grandes conjuntos de resultados.‍
• Valide de acordo com as regras de negócios. Por exemplo, rejeite consultas que exponham campos confidenciais (PII) ou violem as políticas de segurança em nível de linha.
• Opcionalmente, envolva um mecanismo humano ou político. O middleware pode interromper a execução para solicitar confirmação ou aprovação para determinados tipos de consulta, permitindo um fluxo de trabalho interativo na produção.

Ao centralizar essas verificações no interior middleware, você dissocia a lógica de validação do fluxo de raciocínio do agente. O modelo pode gerar SQL livremente, mas a execução real só acontece se o middleware o considerar compatível com as políticas organizacionais e de segurança. Combinado com um usuário de banco de dados somente para leitura, isso cria um forte limite de defesa profunda entre a geração de linguagem e o acesso aos dados.

Etapa 7 — Observabilidade e rastreabilidade

Você precisa ver o que é o agente pensei e fez (Lang Smith):

• Traços de LLM (entradas, chamadas de ferramentas, saídas)
• Registros de consultas (SQL validado, tempo de execução, contagem de linhas)
• Análise de erros (principais modos de falha: coluna desconhecida, junção incorreta, conjunto vazio)
• Corrimãos PII (mascarar, redigir em traços)

Possíveis melhorias e próximas etapas

Sua arquitetura atual (esquema ⇒ ETL ⇒ aterramento ⇒ geração SQL ⇒ validação ⇒ execução ⇒ refinar) é uma base sólida para enviar um piloto interno. Abaixo estão as atualizações concretas que fortalecem a escala de produção e os dados corporativos confusos.

Base mais sólida: esquema-rag e links com reconhecimento de valor

• Esquema RAG em grande escala. Descrições da tabela/coluna de índice, gráfico PK/FK e valores principais, recupere somente o que é relevante por pergunta. Isso reduz as alucinações e melhora a precisão da junção. Pesquisas recentes destacam a recuperação/vinculação de esquemas como a maior vitória ao passar de demonstrações para produções. (arXiv)
• Vinculação robusta de esquemas. Prefira vinculadores que sejam resistentes à deriva de nomenclatura e aos sinônimos e trate a vinculação como um problema de recuperação de primeira classe. (arXiv)

Decodificação restrita + lint/validação de SQL

• Geração segura de sintaxe (PICARD). Restrinja a decodificação para que o modelo não pode emite SQL inválido. Isso aumenta de forma mensurável o sucesso da execução. (aclanthology.org)
• Corrimãos programáticos. Analise e linte com um analisador real (por exemplo, SQLGLOT) e adicione políticas de permitir/negar (somente SELEÇÃO, LIMITE obrigatório, lista de permissões do esquema). Você também pode adotar validadores prontos (por exemplo, valid_sql do Guardrails) no middleware de chamada de ferramenta. (GitHub)
• Caminho de exceções de política. Quando as regras são acionadas (colunas de PII, risco de contagem de linhas), encaminhe para aprovação (consulte § 4). (Combina naturalmente com sua etapa de “validação de pré-execução”.)

Autocorreção e planejamento com reconhecimento de erros

• Ciclos de feedback de execução. Em caso de erros de banco de dados (coluna desconhecida, junção incorreta), reparo automático a consulta usando a mensagem de erro + o contexto do esquema; mantenha um orçamento limitado para novas tentativas. Padrões do setor e artigos recentes mostram grandes ganhos com esse ciclo de “refletir → reparar → reexecutar”. (Amazon Web Services, Inc.)
• Andaimes de raciocínio. Use um planejamento leve (esboço → rascunho SQL → verificação) e algumas fotos dinâmicas extraídas de consultas anteriores bem-sucedidas contra as mesmas tabelas. Pesquisas observam que isso ajuda consistentemente em esquemas reais. (arXiv)

Human-in-the-Loop (HITL) onde é importante

• Análise baseada em riscos. Aprove automaticamente padrões seguros e exija aprovação humana para consultas relacionadas a tabelas confidenciais, de alto custo ou com intenções ambíguas.
• Feedback → dados de treinamento. Capture as edições/aprovações do usuário e as extraia em novas fotos ou exemplos de treinamento sintético; os pipelines HITL agora são padrão para aumentar a precisão de seu próprio cargas de trabalho. (arXiv)

Observabilidade e governança

• Traços nos quais você pode confiar. Solicitações de log, fragmentos de esquema recuperados, SQL gerado, decisões de política, tempo de execução, contagem de linhas e tags de feedback do usuário.
• Benchmarks que refletem a realidade. Rastreamento precisão de execução e resposta: utilidade em seus registros; opcionalmente, adicione avaliações no estilo Bird/Spider para capturar regressões. (Médio)
• Taxonomia de falhas. Classifique os principais modos de falha (vinculação, sintaxe, conjunto vazio, consulta lenta) e direcione-os com testes.
• Menor privilégio por design. Função somente para leitura, lista de permissões de esquema, segurança em nível de linha e mascaramento de coluna para PII; remova PII a partir de rastreamentos.
• Estrutura de guardrail. Centralize a validação de entrada/saída (filtros de prompt, validadores de esquema/SQL, limites de tamanho de resultados, verificações de jailbreak). Veja pesquisas/padrões recentes de guardrails. (arXiv)

Lista de verificação de produção

Antes de enviar seu agente SQL para produção, é útil fazer uma verificação rápida de integridade, uma pequena lista de itens não negociáveis que garantem que seu sistema se comporte de forma previsível em condições reais.

A lista de verificação a seguir destila tudo o que foi discutido nesta postagem em etapas concretas e verificáveis.

• Função de banco de dados somente para leitura para agente (privilégio mínimo)
• Analisador SQL + verificações de políticas (regras SELECT‑ONLY, LIMIT, WHERE)
• Contexto de esquema com escopo definido ou RAG
• Alguns exemplos alinhados às questões de negócios
• ETL com verificações de tipo e chaves primárias/estrangeiras
• Observabilidade (rastreamentos LLM, registros de consultas, taxonomia de erros)
• Segurança em nível de linha /escopo do inquilino, se necessário
• Elimine a alternativa quando a pergunta for ambígua (faça uma pergunta esclarecedora)

Conclusão

“Falar” com planilhas não significa fazer com que os modelos de linguagem entendam magicamente o caos, mas sim dar a eles uma estrutura, barreiras e ciclos de feedback que reflitam o funcionamento de sistemas de software confiáveis. Quando uma planilha se torna um esquema e as consultas fluem por canais validados e observáveis, a conversa deixa de ser frágil e começa a se tornar produtiva.

A mensagem principal é simples: trate sua planilha como um banco de dados e seu LLM como um analista que precisa de contexto e supervisão. Com um mínimo de ETL, recuperação com reconhecimento de esquema, validação de SQL e execução com menos privilégios, você pode passar da cópia e colagem de CSVs para o chat para uma camada conversacional que pode ser mantida e escalável.

Essa é a direção que a próxima geração de agentes SQL está tomando: fundamentada, governável e mensurável. Se você está testando uma pequena ferramenta interna ou projetando uma interface de dados corporativa, a confiabilidade não é um recurso adicional, é a base. Crie essa base uma vez e seu LLM finalmente começará a conversar com seus dados, não apenas sobre eles.