Metabase

Metabase

This connector works with a Metabase instance (self-hosted or Metabase Cloud) through its REST API: databases and their tables and fields, saved questions, models and metrics, dashboards, collections, search, recent and popular items, people and groups. It runs saved questions, dashboard cards and ad hoc SQL or MBQL queries, and creates or updates questions, dashboards and collections.

Setup (3 minutes)

1. METABASE_URL: the address you open Metabase at, e.g. https://metabase.example.com or https://yourcompany.metabaseapp.com, without /api.
2. As an admin open Admin settings, Settings, Authentication, API keys, click Create API key, give it a name and a group. The key acts with that group's permissions: a group with view access to collections and query access to the databases you want is enough for reading; curate access is needed for creating and changing content. Admin-only reads (metabase_list_users) need the Administrators group.
3. Copy the key (shown once) into METABASE_API_KEY. It is sent in the x-api-key header.
4. Run metabase_get_current_user to check it.

Workflow

• Find content: metabase_search (questions, dashboards, tables, ...), metabase_list_collections, metabase_get_collection, metabase_list_collection_items, metabase_list_cards, metabase_list_dashboards, metabase_get_recent_items, metabase_get_popular_items.
• Answer with saved work first: metabase_get_card shows what a question computes, metabase_run_card runs it (with parameters for its filters). For a dashboard, metabase_get_dashboard then metabase_run_dashboard_card per card.
• Explore data: metabase_list_databases, metabase_get_database, metabase_list_database_schemas, metabase_list_schema_tables, metabase_get_table_metadata, metabase_get_database_metadata, metabase_get_field_values (category values for filters).
• Ad hoc queries: metabase_run_native_query with SQL in the database's dialect, or metabase_run_query with an MBQL query built from table and field ids. Aggregate in the query and keep results small.
• Build: metabase_create_card, metabase_update_card, metabase_create_dashboard, metabase_update_dashboard (add cards by sending the full dashcards list), metabase_create_collection, metabase_update_collection. Archiving through the update tools moves items to the trash, where they can be restored.
• People: metabase_get_current_user, metabase_list_users, metabase_list_permission_groups.

Reading the answers: query results are data.cols (name, display_name, base_type such as type/Integer, type/DateTime) and data.rows (arrays in column order), with row_count. Dates are ISO 8601 in the report time zone of the instance. Ids of databases, tables, fields, questions and dashboards are integers; the top collection is root. type on a card is question, model or metric; in search and collection items a model shows as dataset.

Paging: metabase_search, metabase_list_collection_items and metabase_list_users take limit and offset and return total. The other lists return everything.

Limits: query tools return at most 2,000 rows (the API's limit for ad hoc results); aggregate or filter instead of paging through raw rows. A native query runs with the database connection Metabase uses, so use a read-only database user in Metabase for connections that should never change.

Errors: a query that fails comes back with status: failed and the database's message in error (reported as a failed call). 401 means a wrong or deleted key, 403 a key whose group lacks the permission (data access, curate or admin), 404 a wrong id or an address without /api routes (check METABASE_URL).