/data-write-query

name: data-write-query
description: Escreve SQL otimizado para o stack Evolution (PostgreSQL primário) com boas práticas. Use quando precisar traduzir uma necessidade de dados em SQL, construir uma query com múltiplas CTEs, joins e agregações, otimizar uma query contra tabelas grandes, ou obter sintaxe específica para consultas no banco do Evo CRM, Evo AI, ou qualquer serviço do stack Evolution. Dialetos secundários disponíveis: Snowflake, BigQuery, MySQL, DuckDB.
argument-hint: "<descrição do que você precisa consultar>"

data-write-query — Escrever SQL Otimizado

Escreve uma query SQL a partir de uma descrição em linguagem natural, otimizada para o dialeto PostgreSQL (stack padrão Evolution) e seguindo boas práticas.

Uso

/data-write-query <descrição do que você precisa consultar>

Fluxo de Trabalho

1. Entender a Requisição

Analisar a descrição do usuário para identificar:

• **Colunas de saída**: Quais campos devem estar no resultado?
• **Filtros**: Quais condições limitam os dados (intervalos de tempo, segmentos, status)?
• **Agregações**: Há operações GROUP BY, contagens, somas, médias?
• **Joins**: É necessário combinar múltiplas tabelas?
• **Ordenação**: Como os resultados devem ser classificados?
• **Limites**: Há um requisito de top-N ou amostragem?

2. Determinar o Dialeto SQL

**Dialeto primário do workspace:**

• **PostgreSQL** — padrão para todo o stack Evolution (Evo CRM, Evo AI, serviços internos, Aurora RDS, Supabase, Neon)

**Dialetos secundários (se explicitamente solicitados):**

• Snowflake
• BigQuery (Google Cloud)
• Redshift (Amazon)
• Databricks SQL
• MySQL / Aurora MySQL
• DuckDB
• SQLite

Se o usuário não especificar, assumir **PostgreSQL** como padrão.

3. Descobrir o Schema (Se Conectado)

Se a fonte de dados estiver disponível via MCP ou CLI:

1. Buscar tabelas relevantes com base na descrição do usuário 2. Inspecionar nomes de colunas, tipos e relacionamentos 3. Verificar índices, particionamento ou clustering que afetam a performance 4. Procurar views ou views materializadas que possam simplificar a query

**Queries de exploração de schema (PostgreSQL):**

-- Listar todas as tabelas no schema
SELECT table_name, table_type
FROM information_schema.tables
WHERE table_schema = 'public'
ORDER BY table_name;

-- Detalhes das colunas de uma tabela
SELECT column_name, data_type, is_nullable, column_default
FROM information_schema.columns
WHERE table_name = 'nome_da_tabela'
ORDER BY ordinal_position;

-- Tamanho das tabelas
SELECT relname AS tabela,
       pg_size_pretty(pg_total_relation_size(relid)) AS tamanho_total
FROM pg_catalog.pg_statio_user_tables
ORDER BY pg_total_relation_size(relid) DESC;

-- Índices de uma tabela
SELECT indexname, indexdef
FROM pg_indexes
WHERE tablename = 'nome_da_tabela';

4. Escrever a Query

Seguir estas boas práticas:

**Estrutura:**

• Usar CTEs (cláusulas WITH) para legibilidade quando queries têm múltiplos passos lógicos
• Uma CTE por transformação lógica ou fonte de dados
• Nomear CTEs de forma descritiva (ex: `novos_clientes_diarios`, `usuarios_ativos`, `receita_por_plano`)

**Performance:**

• Nunca usar `SELECT *` em queries de produção — especificar apenas as colunas necessárias
• Filtrar cedo (push de cláusulas WHERE o mais próximo possível das tabelas base)
• Usar filtros de partição quando disponíveis (especialmente partições de data)
• Preferir `EXISTS` sobre `IN` para subconsultas com grandes conjuntos de resultados
• Usar os tipos corretos de JOIN (não usar LEFT JOIN quando INNER JOIN é o correto)
• Evitar subconsultas correlacionadas quando um JOIN ou window function funciona
• Atenção a joins explosivos (many-to-many)

**Legibilidade:**

• Adicionar comentários explicando o "porquê" para lógica não óbvia
• Usar indentação e formatação consistentes
• Criar aliases de tabelas com nomes abreviados significativos (não apenas `a`, `b`, `c`)
• Colocar cada cláusula principal em sua própria linha

**Otimizações específicas do PostgreSQL:**

-- Usar EXPLAIN ANALYZE para entender o plano de execução
EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT ...;

-- Usar LIMIT + OFFSET para paginação
SELECT * FROM tabela
ORDER BY criado_em DESC
LIMIT 50 OFFSET 0;

-- Window functions eficientes no PostgreSQL
SELECT
    cliente_id,
    valor,
    SUM(valor) OVER (PARTITION BY cliente_id ORDER BY data_pagamento) AS valor_acumulado,
    ROW_NUMBER() OVER (PARTITION BY cliente_id ORDER BY data_pagamento DESC) AS rn
FROM pagamentos;

-- DISTINCT ON (específico do PostgreSQL) — mais eficiente que ROW_NUMBER
SELECT DISTINCT ON (cliente_id)
    cliente_id, plano, criado_em
FROM assinaturas
ORDER BY cliente_id, criado_em DESC;

-- Funções de data no PostgreSQL
DATE_TRUNC('month', criado_em)           -- Início do mês
EXTRACT(DOW FROM criado_em)              -- Dia da semana (0=domingo)
NOW() AT TIME ZONE 'America/Sao_Paulo'  -- Hora atual em BRT
criado_em AT TIME ZONE 'UTC' AT TIME ZONE 'America/Sao_Paulo' -- Converter para BRT
INTERVAL '30 days'                       -- Subtração de intervalo
DATE_PART('epoch', fim - inicio)        -- Diferença em segundos

-- JSON/JSONB (comum no stack Evolution)
dados->>'campo'                          -- Extrair como texto
dados->'campo'                           -- Extrair como JSON
jsonb_array_elements(dados->'lista')    -- Expandir array JSON
dados @> '{"status": "active"}'::jsonb  -- Contém (usa índice GIN)

-- Array operations
ANY(ARRAY['active', 'trial'])           -- In array
array_agg(campo ORDER BY data)          -- Agregar em array
unnest(tags)                            -- Expandir array em linhas

**Padrões de query para as fontes do workspace:**

-- Padrão: Análise de MRR mensal (típico para dados exportados do Stripe)
WITH receita_mensal AS (
    SELECT
        DATE_TRUNC('month', data_pagamento) AS mes,
        SUM(valor_cents) / 100.0 AS receita_total,
        COUNT(DISTINCT cliente_id) AS clientes_pagantes
    FROM pagamentos