Transforma perguntas de negócio em consultas SQL explicadas, seguras por padrão e prontas para validação em Postgres, BigQuery, MySQL, Snowflake e SQL Server.
Antes → Depois · resultado real
O mesmo pedido, com e sem a skill.
Marketplace de moda rodando em Postgres: a diretoria quer 'o churn mensal de sellers' no Metabase até quinta. O banco não tem dicionário de dados e a última query parecida duplicou receita por causa de um join 1:N — o número errado chegou bonito no dashboard.
Quem manda · Analista de dados que herdou o banco sem documentação — e já foi queimada uma vez por um join.
Antes · pedido improvisado
“me escreve um SQL de churn mensal de sellers”
O que a IA devolve
SELECT * FROM sellers s JOIN payments p ON s.id = p.seller_id WHERE canceled = true GROUP BY month(s.canceled_at); -- Pronto! É só rodar em produção, essa query retorna o churn exato.
Por que é fraco · Mistura dialetos (month() não existe no Postgres), usa SELECT * com join 1:N que duplica pagamentos, inventa a coluna 'canceled' sem ver o schema e manda rodar em produção sem nenhuma validação — receita pra repetir o dashboard errado.
Depois · com a skill
O pedido
Use Gerador de Consultas SQL para BI.
Dialeto: Postgres 15. Destino: Metabase.
Schema real: sellers(id, created_at), subscriptions(seller_id, started_at, canceled_at, status), payments(seller_id, paid_at, amount_cents).
Pergunta: churn mensal de sellers nos últimos 12 meses. Datas gravadas em UTC; relatório em America/Sao_Paulo.
Quero query read-only comentada, premissas explícitas, validações executáveis e notas de performance.
O que a IA devolve
Toca nos 4 pins
Premissas e dúvidas críticas (confirmar antes de quinta):
Churn aqui = % de sellers ativos no início do mês que cancelaram dentro do mês (contagem de sellers, não receita).
Seller com mais de uma assinatura: considero ativo se tiver AO MENOS uma assinatura vigente — validar essa regra com o dono da métrica.
Datas em UTC → convertidas para America/Sao_Paulo na agregação mensal.
Query (read-only, Postgres):
```sql
WITH meses AS (
SELECT generate_series(
date_trunc('month', (now() AT TIME ZONE 'America/Sao_Paulo') - interval '11 months'),
date_trunc('month', now() AT TIME ZONE 'America/Sao_Paulo'),
interval '1 month'
) AS mes
),
-- sellers com assinatura vigente no início de cada mês
ativos AS (
SELECT m.mes, s.seller_id
FROM meses m
JOIN subscriptions s
ON (s.started_at AT TIME ZONE 'America/Sao_Paulo') < m.mes
AND (s.canceled_at IS NULL
OR (s.canceled_at AT TIME ZONE 'America/Sao_Paulo') >= m.mes)
GROUP BY m.mes, s.seller_id -- 1 linha por seller: mata a duplicação do 1:N
),
-- cancelamentos dentro do mês
cancelados AS (
SELECT date_trunc('month', canceled_at AT TIME ZONE 'America/Sao_Paulo') AS mes,
seller_id
FROM subscriptions
WHERE canceled_at IS NOT NULL
GROUP BY 1, 2
)
SELECT a.mes,
COUNT(DISTINCT a.seller_id) AS sellers_ativos,
COUNT(DISTINCT c.seller_id) AS cancelamentos,
ROUND(100.0 * COUNT(DISTINCT c.seller_id)
/ NULLIF(COUNT(DISTINCT a.seller_id), 0), 2) AS churn_pct
FROM ativos a
LEFT JOIN cancelados c USING (mes, seller_id)
GROUP BY a.mes
ORDER BY a.mes;
```
Por que está montada assim: (o clássico join 1:N que já queimou esse dashboard uma vez). `payments` ficou de fora de propósito: churn por contagem não usa receita, e juntar pagamentos aqui duplicaria linhas.
Validações antes do Metabase:
`SELECT seller_id, COUNT() FROM subscriptions GROUP BY 1 HAVING COUNT() > 1;` → mede quantos sellers têm múltiplas assinaturas (se forem muitos, a regra de 'ativo' pesa no número).
Caçar dado sujo: `canceled_at` preenchido com `status` ainda ativo indica inconsistência de origem.
Amostra manual: seguir a linha do tempo de 3 sellers cancelados.
Performance: a janela de 12 meses limita o scan; se `subscriptions` for grande, índices em `(started_at)` e `(canceled_at)` ajudam. Sem `SELECT *` em lugar nenhum.
LGPD: . Ninguém precisa de dado pessoal pra ver churn.
Antes de virar dashboard executivo: a regra de churn (contagem × receita; mês de início × mês de cancelamento) precisa do OK do dono da métrica. Query é ponto de partida testável, não verdade fechada.
Por que ganha · Resolve o problema que já queimou o time: agrega antes do join pra não duplicar, declara a regra de churn como premissa a confirmar, converte timezone explicitamente e entrega 4 validações executáveis — o número chega na diretoria com lastro, não com fé.
O SELECT * que duplicava receita virou CTE comentada com timezone certo, 4 validações — e a pergunta que ninguém tinha feito: churn de contagem ou de MRR?
antes ~3h depurando join errado (e refazendo o número pra diretoria) → depois ~15min rodando as validações antes do Metabase
Consulta SQL somente leitura, comentada, explicada e acompanhada de checklist de validação.
Acelere consultas confiáveis para BI sem perder o controle sobre regras de negócio, validação e LGPD.
Problema: Equipes precisam responder perguntas de negócio rapidamente, mas queries mal definidas geram métricas erradas, duplicidade em joins, problemas de timezone e risco de exposição de dados pessoais.
Fluxo: Criar
Exemplo de pedido pronto
Tenho Postgres com tabelas customers(id, created_at), subscriptions(customer_id, started_at, canceled_at, status) e payments(customer_id, paid_at, amount_cents). Gere uma query de churn mensal dos últimos 12 meses e explique como validar.
⦿ A receita inteira · aberta
sem cadastro · sem pagar
Esta é uma das skills que a gente deixa aberta pra leitura. O arquivo abaixo é exatamente o que quem tem o catálogo completo recebe — entrada, passos, revisão e formato de saída. Use no seu assistente e adapte ao seu contexto.
---
name: "gerador-consultas-sql"
description: "Gera, explica e valida consultas SQL a partir de perguntas de negócio e esquemas de banco, com foco em BI, segurança read-only, LGPD e cenários brasileiros."
---
# Gerador de Consultas SQL para BI
## Quando Usar
Use quando a pessoa tem uma pergunta de negócio e precisa transformá-la em SQL para análise, dashboard ou validação. Casos típicos:
- Dashboard em Metabase, Power BI, Looker ou Tableau.
- Análises de churn, receita, coorte, funil, retenção, inadimplência, DRE gerencial ou conciliação.
- Revisão de query que está duplicando receita, contando clientes errado ou performando mal.
- Exploração inicial de tabelas de ERP, CRM, e-commerce, produto SaaS, pagamentos Pix/boleto ou data warehouse.
Não use como substituto de revisão contábil, fiscal, jurídica, auditoria ou aprovação executiva. A query é ponto de partida e deve ser testada.
## Resultado Esperado
Entregar uma resposta com:
1. Premissas e dúvidas críticas.
2. Consulta SQL preferencialmente somente leitura, comentada e no dialeto correto.
3. Explicação da lógica em português claro.
4. Validações executáveis para contagem, duplicidade, nulos, período e reconciliação.
5. Notas de performance e compatibilidade.
6. Alertas de LGPD, segurança e necessidade de revisão humana quando aplicável.
## Entradas Necessarias
Peça ou confirme antes de gerar a query final:
- Dialeto: Postgres, BigQuery, MySQL, Snowflake, SQL Server etc.
- Objetivo da análise: pergunta de negócio e decisão que será tomada.
- Esquema do banco: tabelas, colunas, tipos, chaves primárias/estrangeiras e cardinalidade dos joins.
- Regra da métrica: definição de receita, churn, cliente ativo, pedido pago, cancelamento, reembolso, competência/caixa.
- Período, granularidade e timezone. Para Brasil, considerar `America/Sao_Paulo` em métricas diárias/mensais.
- Filtros: status, UF, canal, segmento, centro de custo, produto, unidade de negócio.
- Ferramenta de destino: Metabase, Power BI, Looker, dbt, DBeaver, DataGrip, planilha etc.
- Restrições: volume, índices, particionamento, ambiente de produção, limite de custo no BigQuery.
Se faltarem dados críticos, faça perguntas objetivas. Se ainda assim gerar, marque tudo como premissa, nunca como fato.
## Processo
1. **Entender a pergunta**: reescreva a solicitação em uma frase mensurável. Ex.: “churn mensal de clientes ativos nos últimos 12 meses”.
2. **Checar risco e dados sensíveis**: se houver CPF, CNPJ, e-mail, telefone, endereço, dados bancários ou renda, pedir anonimização/minimização.
3. **Confirmar o dialeto**: adaptar funções de data, casts, timezone, janelas e sintaxe ao banco informado.
4. **Mapear tabelas e joins**: identificar chaves e risco de join 1:N. Para métricas financeiras, agregue pagamentos antes de juntar com pedidos/clientes quando necessário.
5. **Definir a regra de negócio**: status elegíveis, datas usadas, competência vs caixa, cancelamentos, reembolsos, pedidos teste, impostos/frete/descontos.
6. **Gerar SQL read-only**: priorizar `SELECT` com CTEs legíveis. Evitar `SELECT *`. Comentar trechos importantes.
7. **Validar**: incluir queries/checks para totais por etapa, duplicidade por chave, nulos em campos críticos, comparação com fonte oficial e amostra manual.
8. **Explicar**: descrever a lógica para analista/gestor brasileiro, sem jargão desnecessário.
9. **Performance**: sugerir filtros por data, índices, particionamento, clustering, pré-agregação ou materialização conforme o banco.
10. **Escalar**: recomendar revisão humana em fechamento financeiro, fiscal, jurídico, relatório ao conselho ou qualquer decisão crítica.
## Ferramentas E Artefatos
Softwares comuns: Postgres, BigQuery, MySQL, Snowflake, SQL Server, Metabase, Power BI, Looker, Tableau, dbt, DBeaver, DataGrip e Google Sheets.
Artefatos aceitos/gerados: `.sql`, schema SQL, dicionário de dados, documentação de tabelas, query para dashboard, script de validação, checklist de qualidade e notas de performance.
Compatibilidade: não execute queries automaticamente. Em assistentes de código, pode ler arquivos de schema locais se o usuário autorizar, mas deve pedir confirmação explícita antes de qualquer execução em banco.
## Exemplo Brasileiro
Pedido: “Tenho um SaaS B2B no Brasil em Postgres. Tabelas `customers(id, created_at)`, `subscriptions(customer_id, started_at, canceled_at, status)` e `payments(customer_id, paid_at, amount_cents)`. Gere churn mensal dos últimos 12 meses em R$.”
Boa resposta deve:
- Confirmar se churn é por clientes ou receita/MRR.
- Usar mês em `America/Sao_Paulo` quando datas estiverem em UTC.
- Criar CTEs para meses, base ativa no início do mês e cancelamentos no mês.
- Converter centavos para reais apenas na apresentação (`amount_cents / 100.0`).
- Validar se um cliente tem múltiplas assinaturas e se pagamentos duplicam valores.
- Alertar que relatório executivo precisa de revisão da regra de churn.
Outro caso: conciliação de pedidos, Pix e boleto vindos de ERP. A query deve comparar pedido aprovado, pagamento liquidado, valor esperado, valor recebido e mês de competência, sem exportar CPF/CNPJ quando não for necessário.
## Criterios De Qualidade
A saída passa se:
- Informa o dialeto SQL ou pergunta quando não foi fornecido.
- Não inventa tabela/coluna/regra crítica sem declarar premissa.
- Usa SQL somente leitura por padrão.
- Evita `SELECT *` e minimiza dados pessoais.
- Trata timezone brasileiro quando a métrica depende de dia/mês.
- Explica joins e agregações de forma auditável.
- Inclui validações específicas: contagem antes/depois do join, duplicidade por chave, nulos, totais por período e comparação com fonte conhecida.
- Aponta riscos de performance: falta de filtro de data, função em coluna indexada, scan caro no BigQuery, join sem chave, ausência de particionamento.
- Se a pergunta for ambígua, faz perguntas de clarificação ou entrega rascunho com premissas explícitas.
Falha se gerar query final inventada, expor dados pessoais sem necessidade, ignorar duplicidade 1:N, misturar dialetos, omitir validação ou sugerir comando destrutivo sem salvaguardas.
## Cuidados, LGPD E Escalacao Humana
- Solicite remoção, máscara ou dados sintéticos quando o usuário colar CPF, CNPJ, e-mail, telefone, endereço, dados bancários, cartão, renda ou dados sensíveis.
- Prefira análises agregadas e campos mínimos necessários. Não ajude a exportar listas pessoais para prospecção, vigilância ou finalidade incompatível.
- Não gere `DELETE`, `DROP`, `TRUNCATE`, `UPDATE`, `MERGE`, alterações de schema ou comandos em produção como resposta padrão. Ofereça alternativa com `SELECT` para identificar registros e recomende backup, transação e revisão humana.
- Para fechamento financeiro, impostos, NF-e, folha, auditoria, jurídico, conselho ou obrigação regulatória, declare que a query precisa de revisão por responsável humano qualificado.
- Não prometa certeza legal, fiscal, financeira ou contábil. Use linguagem de triagem, checklist, validação e revisão.
- Se houver risco de custo alto, lock, vazamento ou impacto em produção, orientar teste em ambiente seguro, limite de período e aprovação do time de dados/engenharia.
## Smoke Test
Prompt de teste: “Tenho Postgres com tabelas `customers(id, created_at)`, `subscriptions(customer_id, started_at, canceled_at, status)` e `payments(customer_id, paid_at, amount_cents)`. Gere uma query de churn mensal dos últimos 12 meses e explique como validar.”
Critérios de aprovação do smoke test:
- Retorna SQL Postgres com CTEs legíveis e comentários.
- Define claramente base ativa, cancelamentos e período.
- Não usa dados pessoais nem comandos destrutivos.
- Inclui validações de contagem, duplicidade e comparação com totais conhecidos.
- Menciona timezone/período e possíveis ambiguidades da regra de churn.
- Explica a lógica em português brasileiro claro e recomenda revisão antes de dashboard executivo.
