Agent skill

consultando-sql

Executa consultas analiticas SQL no banco de dados via linguagem natural. Use para perguntas ad-hoc sobre rankings, agregacoes, distribuicoes, tendencias, cruzamentos de tabelas. Converte perguntas em SQL, valida com Evaluator-Optimizer, e executa read-only. Cobre 104 tabelas ativas via catalogo dinamico.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/other/consultando-sql

SKILL.md

Consultando SQL - Consultas Analiticas via Linguagem Natural

Skill para consultas analiticas ao banco de dados PostgreSQL via linguagem natural.

ESCOPO: Esta skill converte perguntas em SQL e executa read-only. Para operacoes logisticas (separacao, estoque, disponibilidade), use gerindo-expedicao. Para exportar resultados como Excel/CSV, use exportando-arquivos.

Quando Usar

USE consultando-sql:
├── Rankings e Top N
│   "Top 10 clientes por valor de carteira"
│   "Vendedores com mais pedidos este mes"
│
├── Agregacoes e Estatisticas
│   "Valor medio de pedido por vendedor"
│   "Quantidade total de pedidos por estado"
│
├── Distribuicoes
│   "Distribuicao de pedidos por incoterm"
│   "Pedidos por faixa de valor"
│
├── Tendencias e Periodos
│   "Faturamento dos ultimos 30 dias"
│   "Evolucao de pedidos por mes"
│
├── Cruzamentos entre Tabelas
│   "Produtos sem estoque mas com pedidos pendentes"
│   "Clientes com separacoes pendentes e valor alto"
│
├── Consultas Financeiras
│   "Top 10 clientes por valor de contas a receber vencidas"
│   "Total de titulos a pagar nos proximos 30 dias"
│
├── Analise de Fretes
│   "Valor total de fretes por transportadora nos ultimos 60 dias"
│   "Custo medio de frete por UF de destino"
│
└── Qualquer pergunta analitica/estatistica ad-hoc

Quando NAO Usar

NAO USE consultando-sql (use gerindo-expedicao):
├── Consulta especifica de 1 pedido/cliente
│   "Tem pedido do Atacadao?" -> gerindo-expedicao
│
├── Operacoes com side-effects
│   "Crie separacao" -> gerindo-expedicao
│
├── Projecao de estoque/disponibilidade
│   "Quando VCD123 fica disponivel?" -> gerindo-expedicao
│
└── Consultas que exigem logica complexa de negocio
    "Qual a prioridade P1-P7?" -> subagente analista-carteira

Regras Criticas

  1. Feature Flag: Requer AGENT_TEXT_TO_SQL=true. Se desabilitado, retorna aviso.
  2. Seguranca Multi-Camada:
    • Generator: Apenas SELECT (instruido via prompt)
    • Evaluator: Valida corretude semantica e sintatica com schema detalhado
    • Safety: Regex validator bloqueia DELETE/DROP/INSERT/UPDATE/tabelas proibidas/funcoes perigosas
    • Executor: SET TRANSACTION READ ONLY + timeout 5s
  3. Limites: Max 500 linhas retornadas. Timeout 5 segundos.
  4. Guardrail Anti-Alucinacao: Evaluator recebe schema DETALHADO (campos, tipos, FKs) apenas das tabelas usadas e corrige campos inexistentes.
  5. Tabelas Bloqueadas: usuarios, permissions, agent_sessions, agent_memories, agent_memory_versions, alembic_version, portal_sessoes, tagplus_oauth_token, e 9 outras (17 total)

Script Principal

text_to_sql.py

bash
source .venv/bin/activate && \
AGENT_TEXT_TO_SQL=true python .claude/skills/consultando-sql/scripts/text_to_sql.py --pergunta "PERGUNTA"

Parametros

Parametro Obrigatorio Descricao Exemplo
--pergunta / -p Sim Pergunta em linguagem natural (portugues) --pergunta "Top 10 clientes por valor"
--debug Nao Mostrar detalhes de cada etapa do pipeline --debug

Exemplos de Uso

Ranking de clientes (tabela core)

bash
source .venv/bin/activate && \
AGENT_TEXT_TO_SQL=true python .claude/skills/consultando-sql/scripts/text_to_sql.py \
  --pergunta "Top 10 clientes por valor total na carteira"

Contas a receber vencidas (tabela expandida)

bash
AGENT_TEXT_TO_SQL=true python .../text_to_sql.py \
  --pergunta "Top 10 clientes por valor de contas a receber vencidas"

Fretes por transportadora (tabela expandida)

bash
AGENT_TEXT_TO_SQL=true python .../text_to_sql.py \
  --pergunta "Valor total de fretes por transportadora nos ultimos 60 dias"

Cross-domain (carteira + faturamento)

bash
AGENT_TEXT_TO_SQL=true python .../text_to_sql.py \
  --pergunta "Clientes com pedidos pendentes mas sem faturamento nos ultimos 30 dias"

Distribuicao por estado

bash
AGENT_TEXT_TO_SQL=true python .../text_to_sql.py \
  --pergunta "Quantos pedidos pendentes por estado?"

Debug detalhado

bash
AGENT_TEXT_TO_SQL=true python .../text_to_sql.py \
  --pergunta "Top 5 vendedores por valor total" --debug

Retorno JSON

Sucesso

json
{
  "sucesso": true,
  "pergunta": "Top 10 clientes por valor total na carteira",
  "sql": "SELECT cnpj_cpf, raz_social, ROUND(SUM(qtd_saldo_produto_pedido * preco_produto_pedido)::numeric, 2) AS valor_total FROM carteira_principal WHERE ativo = True AND qtd_saldo_produto_pedido > 0 GROUP BY cnpj_cpf, raz_social ORDER BY valor_total DESC LIMIT 10",
  "sql_original": "SELECT ...",
  "dados": [
    {"cnpj_cpf": "75.315.333/0183-18", "raz_social": "ATACADAO S.A.", "valor_total": 5228553.10}
  ],
  "colunas": ["cnpj_cpf", "raz_social", "valor_total"],
  "total_linhas": 10,
  "aviso": "SQL corrigida pelo evaluator (tentativa 1): ...",
  "tabelas_usadas": ["carteira_principal"],
  "etapas": {
    "generator_ms": 1800,
    "evaluator_ms": 2200,
    "safety": {"safe": true, "concerns": []},
    "executor_ms": 2000
  },
  "tempo_total_ms": 6000
}

Erro (seguranca)

json
{
  "sucesso": false,
  "pergunta": "DELETE FROM carteira_principal",
  "sql": null,
  "aviso": "Query bloqueada por seguranca: Keywords proibidas: DELETE"
}

Feature flag desabilitada

json
{
  "sucesso": false,
  "pergunta": "Top 10 clientes",
  "aviso": "Text-to-SQL desabilitado. Ative com AGENT_TEXT_TO_SQL=true"
}

Arquitetura B: Catalogo Completo + Retrieval em 2 Fases

Pergunta do usuario
    |
    v
[GENERATOR] Haiku recebe CATALOGO LEVE (104 tabelas, ~2.7K tokens)
    |         Gera SQL com nomes de tabela corretos, campos aproximados
    v
[RETRIEVAL] Extrai tabelas do SQL (regex FROM/JOIN)
    |         Carrega schemas DETALHADOS apenas das tabelas usadas (2-4 tipicamente)
    v
[EVALUATOR] Haiku recebe SCHEMA DETALHADO (campos, tipos, FKs, regras)
    |         Valida campos, corrige nomes, adiciona filtros
    |-- Aprovado? -> Safety
    |-- Corrigido? -> Usa SQL corrigida -> Safety
    |-- Reprovado? -> Re-gera com feedback (max 2 tentativas)
    |
    v
[SAFETY] Regex validator (keywords, funcoes, tabelas bloqueadas)
    |-- Seguro? -> Executor
    |-- Bloqueado? -> Retorna erro
    |
    v
[EXECUTOR] SET TRANSACTION READ ONLY + timeout 5s + LIMIT 500
    |
    v
JSON com dados + SQL usada + tabelas_usadas + metricas de tempo

Vantagem da Arquitetura B

  • Generator ve TODAS as 104 tabelas ativas (nome + descricao) → encontra qualquer tabela relevante
  • Evaluator recebe schema DETALHADO apenas das 2-4 tabelas usadas → validacao precisa
  • 2 chamadas LLM (mesmo que antes) → sem overhead de latencia
  • Cross-domain nativo: sem barreira de dominios, JOIN entre financeiro + logistica funciona

Cobertura de Tabelas

Metrica Valor
Total de tabelas no banco ~196
Tabelas bloqueadas (auth, agent, etc.) 17
Tabelas mortas (0 registros em prod) 57
Tabelas irrelevantes (curadoria manual) 18
Tabelas no catalogo 104
Tabelas core (schema manual curado) 9
Tabelas auto-geradas 95
Cobertura (tabelas analiticas relevantes) 100%

Tabelas Core (schema manual com regras de negocio)

Tabela Descricao
carteira_principal Pedidos com saldo pendente. Fonte da verdade para demanda.
separacao Itens separados para expedicao. Projeta saidas de estoque.
movimentacao_estoque Movimentos de estoque: entradas, saidas, ajustes, producao.
programacao_producao Producao programada por data e linha.
cadastro_palletizacao Cadastro de produtos com peso, pallet, conversoes.
faturamento_produto NFs emitidas por produto. Registros de faturamento.
embarques Embarques que agrupam separacoes para transporte.
embarque_itens Itens individuais dentro de um embarque.
saldo_standby Pedidos em espera: saldo, comercial ou PCP.

Dominios Expandidos

  • Financeiro: contas_a_receber, contas_a_pagar, extrato_item, baixa_pagamento_item, baixa_titulo_item, cnab_retorno_item, comprovante_*
  • Fretes: fretes, faturas_frete, despesas_extras, conhecimento_transporte, tabelas_frete, aprovacoes_frete
  • Devolucoes: nf_devolucao, nf_devolucao_linha, ocorrencia_devolucao, frete_devolucao
  • Recebimento: validacao_fiscal_dfe, match_nf_po_, divergencia_nf_po, picking_recebimento_
  • Rastreamento: entregas_monitoradas, entregas_rastreadas, agendamentos_entrega, eventos_entrega
  • Cadastros: transportadoras, cidades, cadastro_rota, grupo_empresarial, depara_produto_cliente

Geracao de Schemas

Os schemas sao auto-gerados a partir dos modelos SQLAlchemy:

bash
source .venv/bin/activate && \
python .claude/skills/consultando-sql/scripts/generate_schemas.py

Opcoes

bash
# Apenas estatisticas (nao gera arquivos)
python .../generate_schemas.py --stats

Arquivos Gerados

Arquivo Descricao
schemas/catalog.json Catalogo leve: nome + descricao + 3 campos-chave por tabela (~25KB)
schemas/tables/{tabela}.json Schema detalhado por tabela: campos, tipos, FKs, indices (104 arquivos)
schemas/relationships.json Mapa de ForeignKeys entre tabelas (171 relacionamentos)
schemas/schema.json Schema manual curado das 9 tabelas core (mantido como referencia)

Quando Regenerar

Regenere schemas quando:

  • Novas tabelas forem adicionadas ao sistema
  • Campos forem alterados em modelos existentes
  • Novas descricoes forem adicionadas ao TABLE_DESCRIPTIONS em generate_schemas.py

Tratamento de Erros

Erro Causa Comportamento
Feature flag desabilitada AGENT_TEXT_TO_SQL=false Retorna aviso, pipeline nao executa
ANTHROPIC_API_KEY ausente Env var nao configurada Retorna aviso
Schema nao encontrado catalog.json ou schema.json faltando RuntimeError
SQL bloqueada (safety) DELETE, DROP, tabela proibida sucesso=false, aviso com motivo
Timeout (>5s) Query muito pesada RuntimeError com sugestao de simplificar
Campo/tabela inexistente Haiku alucionou campo nao corrigido pelo Evaluator Erro PostgreSQL capturado

Notas

  • Custo estimado: ~$0.010/query (2 chamadas Haiku)
  • Tempo medio: 6-10 segundos (cold start + LLM + DB)
  • Catalogo dinamico: 104 tabelas ativas, ~2.700 tokens no prompt do Generator
  • Tabelas mortas (0 registros) excluidas via DEAD_TABLES
  • Tabelas irrelevantes (curadoria manual) excluidas via IRRELEVANT_TABLES
  • Evaluator focado: recebe schema detalhado apenas das 2-4 tabelas usadas
  • Retry loop: Evaluator re-gera SQL com feedback se reprovada (max 2 tentativas)
  • Todos os valores monetarios em BRL (R$)
  • Datas retornadas em ISO 8601 (YYYY-MM-DD)

Relacionado

Skill Uso
gerindo-expedicao Consultas operacionais (pedido especifico, separacao, estoque)
exportando-arquivos Exportar resultado como Excel/CSV para download
lendo-arquivos Processar planilhas enviadas pelo usuario

NOTA: Esta skill e para consultas ANALITICAS ao banco de dados. Para operacoes logisticas do dia-a-dia, use gerindo-expedicao. Para exportar os resultados, combine com exportando-arquivos.

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results