Emanuel Almeida
6b3a6f2698
- All SKILL.md files now <500 lines (avg reduction 69%) - Detailed content extracted to references/ subdirectories - Frontmatter standardised: only name + description (Anthropic standard) - New skills: brand-guidelines, spec-coauthor, report-templates, skill-creator - Design skills: anti-slop guidelines, premium-proposals reference - Removed non-standard frontmatter fields (triggers, version, author, category) Plugins affected: infraestrutura, marketing, dev-tools, crm-ops, gestao, core-tools, negocio, perfex-dev, wordpress, design-media Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
149 lines
3.4 KiB
Markdown
149 lines
3.4 KiB
Markdown
---
|
|
name: query
|
|
description: Execução de queries SQL no Metabase com linguagem natural. Explorar tabelas, extrair métricas e criar relatórios ad-hoc.
|
|
---
|
|
|
|
# Skill /query - Metabase SQL Query Assistant
|
|
|
|
Executar queries SQL no Metabase com assistência AI. Traduz perguntas em linguagem natural para SQL, explora tabelas e extrai métricas.
|
|
|
|
## Sintaxe
|
|
|
|
```
|
|
/query [pergunta em linguagem natural ou SQL]
|
|
```
|
|
|
|
**Exemplos:**
|
|
- `/query quantos clientes temos activos?`
|
|
- `/query total facturado em Janeiro 2026`
|
|
- `/query top 10 produtos mais vendidos`
|
|
- `/query SELECT COUNT(*) FROM customers WHERE active = true`
|
|
|
|
## Quando usar
|
|
|
|
- Extrair dados específicos das bases de dados
|
|
- Responder perguntas de negócio com dados reais
|
|
- Análise ad-hoc rápida
|
|
- Validar hipóteses com números concretos
|
|
- Criar queries para futuros cards/questions
|
|
|
|
---
|
|
|
|
## Protocolo de execução
|
|
|
|
### 1. Carregar MCP
|
|
|
|
```
|
|
ToolSearch("metabase")
|
|
```
|
|
|
|
### 2. Compreender o pedido
|
|
|
|
**Se linguagem natural:**
|
|
1. Identificar a pergunta de negócio
|
|
2. Determinar database e tabelas relevantes
|
|
3. Usar AI SQL generation do MCP se disponível
|
|
|
|
**Se SQL directo:**
|
|
1. Validar syntax
|
|
2. Verificar que tabelas existem
|
|
3. Executar
|
|
|
|
### 3. Explorar schema (se necessário)
|
|
|
|
```
|
|
1. mcp__metabase__list_databases → identificar database
|
|
2. mcp__metabase__get_database_tables → listar tabelas
|
|
3. mcp__metabase__get_table_fields → ver campos disponíveis
|
|
```
|
|
|
|
### 4. Construir e executar query
|
|
|
|
```
|
|
1. Construir SQL baseado no schema real
|
|
2. Executar via mcp__metabase__execute_sql
|
|
3. Validar resultados (nulls, zeros, outliers)
|
|
4. Formatar output
|
|
```
|
|
|
|
### 5. Apresentar resultados
|
|
|
|
**Output format:**
|
|
|
|
```markdown
|
|
## Query: [Descrição da pergunta]
|
|
|
|
**Database:** [nome] | **Tabelas:** [lista]
|
|
|
|
### Resultados
|
|
|
|
| Col1 | Col2 | Col3 |
|
|
|------|------|------|
|
|
| ... | ... | ... |
|
|
|
|
**Total registos:** N
|
|
|
|
### Insight
|
|
[Interpretação breve dos dados]
|
|
```
|
|
|
|
## Boas práticas SQL
|
|
|
|
### Performance
|
|
- Usar `LIMIT` em queries exploratórias (default: 100)
|
|
- Evitar `SELECT *` - especificar campos necessários
|
|
- Usar `WHERE` para filtrar antes de agregar
|
|
- Indexes: verificar campos indexados para JOINs
|
|
|
|
### Segurança
|
|
- **Read-only**: o MCP opera em modo read-only por defeito
|
|
- Nunca executar DDL (CREATE, ALTER, DROP) sem confirmação
|
|
- Nunca executar DML (INSERT, UPDATE, DELETE) sem confirmação
|
|
|
|
### Padrões comuns
|
|
|
|
**Contagem com agrupamento:**
|
|
```sql
|
|
SELECT campo, COUNT(*) as total
|
|
FROM tabela
|
|
GROUP BY campo
|
|
ORDER BY total DESC
|
|
LIMIT 10;
|
|
```
|
|
|
|
**Evolução temporal:**
|
|
```sql
|
|
SELECT DATE_TRUNC('month', created_at) as mes,
|
|
COUNT(*) as total,
|
|
SUM(valor) as valor_total
|
|
FROM tabela
|
|
WHERE created_at >= NOW() - INTERVAL '12 months'
|
|
GROUP BY mes
|
|
ORDER BY mes;
|
|
```
|
|
|
|
**Comparação período actual vs anterior:**
|
|
```sql
|
|
SELECT
|
|
SUM(CASE WHEN created_at >= DATE_TRUNC('month', NOW()) THEN valor END) as mes_actual,
|
|
SUM(CASE WHEN created_at >= DATE_TRUNC('month', NOW() - INTERVAL '1 month')
|
|
AND created_at < DATE_TRUNC('month', NOW()) THEN valor END) as mes_anterior
|
|
FROM tabela;
|
|
```
|
|
|
|
## Guardar query como question
|
|
|
|
Se o utilizador quiser reutilizar a query:
|
|
```
|
|
1. Confirmar nome e descrição
|
|
2. Criar question/card no Metabase
|
|
3. Associar a collection adequada
|
|
4. Retornar URL directa
|
|
```
|
|
|
|
## Notas
|
|
|
|
- Resultados limitados a 2000 linhas por defeito pelo MCP
|
|
- Para datasets grandes, usar agregações
|
|
- Queries complexas: delegar ao agente `metabase-analyst`
|