---
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`