claude-plugins/metabase/skills/query/SKILL.md

name, description

name	description
query	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:

## 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:

SELECT campo, COUNT(*) as total
FROM tabela
GROUP BY campo
ORDER BY total DESC
LIMIT 10;

Evolução temporal:

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:

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

---

Healing Log

Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.

{"date":"","issue":"","fix":"","source":"user|auto"}

Adicionar nova linha após cada erro corrigido.