The Complete Production SOP: How to Deploy and Run Metabase BI Data Modeling & Interactive Questions in Autonomous AI Agents

---
name: "metabase-bi-data-model-questions"
description: "Model data schemas, foreign keys, and self-service visual questions in Metabase."
metadata:
  author: "Metabase"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "create metabase field filter"
  - "model data relationships metabase"
  - "embed metabase dashboard"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# Metabase BI Data Modeling & Interactive Questions

Configures Metabase data models: defining metadata types, configuring entity relationships and foreign keys, authoring visual query questions, writing native SQL with Field Filters ({{field_filter}}), and embedding dashboards.

## When to Invoke
Invoke this skill whenever you need to:
- create metabase field filter
- model data relationships metabase
- embed metabase dashboard

## Execution SOP & Rules
1. In Admin -> Data Model, set column types (Entity Key, Category, Description) and map Foreign Keys.
2. Write native SQL queries with Field Filters: WHERE {{created_at}} linked directly to table timestamp column.
3. Combine questions into a Dashboard and add interactive dropdown filters mapped to query parameters.
4. Configure Embedding settings with secret key and sign JWT payloads in application backend routes.

## Verification Checklist
- Run local linting, syntax validation, and type-checks before reporting completion.
- Ensure all created or modified files adhere to workspace boundaries and avoid uncommitted secrets.
- Verify tests or build commands exit cleanly with return code 0.

import jwt from 'jsonwebtoken';

interface EmbedParams {
  dashboardId: number;
  userOrgId: string;
}

export function generateMetabaseDashboardUrl({ dashboardId, userOrgId }: EmbedParams): string {
  const secretKey = process.env.METABASE_SECRET_KEY;
  const siteUrl = process.env.METABASE_SITE_URL;

  if (!secretKey || !siteUrl) {
    throw new Error('Missing METABASE_SECRET_KEY or METABASE_SITE_URL configuration.');
  }

  const payload = {
    resource: { dashboard: dashboardId },
    params: {
      org_id: userOrgId
    },
    exp: Math.round(Date.now() / 1000) + (10 * 60) // 10 minute expiration
  };

  const token = jwt.sign(payload, secretKey);
  return `${siteUrl}/embed/dashboard/${token}#bordered=true&titled=true`;
}

-- Correct: Field filter handles column name and operators implicitly
SELECT
  org.id AS organization_id,
  org.name AS organization_name,
  COUNT(e.id) AS event_count
FROM organizations org
LEFT JOIN app_events e ON e.org_id = org.id
WHERE {{event_date}}
  [[AND {{organization_category}}]]
GROUP BY org.id, org.name
ORDER BY event_count DESC;

import { describe, it, expect } from 'vitest';
import jwt from 'jsonwebtoken';
import { generateMetabaseDashboardUrl } from '../server/api/metabase-token';

describe('generateMetabaseDashboardUrl', () => {
  process.env.METABASE_SECRET_KEY = 'test_secret_key_1234567890123456';
  process.env.METABASE_SITE_URL = 'https://analytics.test.internal';

  it('generates a valid signed JWT containing dashboard id and params', () => {
    const url = generateMetabaseDashboardUrl({ dashboardId: 42, userOrgId: 'org_abc123' });
    expect(url).toContain('https://analytics.test.internal/embed/dashboard/');
    
    const token = url.split('/embed/dashboard/')[1].split('#')[0];
    const decoded = jwt.verify(token, process.env.METABASE_SECRET_KEY!) as any;
    expect(decoded.resource.dashboard).toBe(42);
    expect(decoded.params.org_id).toBe('org_abc123');
    expect(decoded.exp).toBeGreaterThan(Math.floor(Date.now() / 1000));
  });
});