feat(metabase): adiciona plugin metabase (agents, skills, knowledge e metadados do projeto)

2026-10-28 16:09:18 +00:00
parent 13c39d8000
commit 3b59df032b
22 changed files with 733 additions and 0 deletions
@@ -0,0 +1,161 @@
+---
+name: query
+description: Execução de queries SQL no Metabase com linguagem natural. Explorar tabelas, extrair métricas e criar relatórios ad-hoc.
+layer: wiki
+---
+
+# 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`
+
+---
+
+## Healing Log
+
+Registo de erros conhecidos e como evitá-los. Lido automaticamente antes de executar.
+
+```jsonl
+{"date":"","issue":"","fix":"","source":"user|auto"}
+```
+
+*Adicionar nova linha após cada erro corrigido.*