create_metabase_card
Create visual charts and tables in Metabase using SQL or MBQL queries to display data insights through various visualization types.
Instructions
Create a new card (chart or table) in Metabase via the /api/card endpoint.
This function creates a visual card using either SQL or MBQL queries and supports all chart types including pie, donut, bar, table, and KPI-style metrics.
Args: name (str): Display name of the card in Metabase.
dataset_query (dict):
Defines the query behind the chart.
Required structure:
- "type": "native" or "query"
- "native": { "query": "..." }, for SQL
- "query": {...}, for MBQL
- "database": database ID
display (str):
Visualization type. Common values:
- "table", "bar", "line", "pie", "area", "scatter", "funnel", "pivot-table", "map"
type (str, optional):
Card type, defaults to "question".
- "question": general chart or table
- "metric": for KPI display
- "model": reserved/legacy
visualization_settings (dict, optional):
Controls chart appearance and formatting. Structure varies by chart type.
── 📊 Bar / Line / Area ──
{
"graph": {
"x_axis": "destination",
"y_axis": ["seatsSold"],
"series": "flightType",
"metrics": ["seatsSold"],
"x_axis_label": "Destination",
"y_axis_label": "Seats Sold",
"x_axis_formatting": {
"scale": "ordinal",
"label_rotation": 45
},
"y_axis_formatting": {
"number_style": "decimal",
"suffix": " pax"
}
},
"show_legend": true,
"legend_position": "bottom"
}
── 🥧 Pie / Donut Charts ──
{
"pie": {
"category": "destination", # Label or group for slices
"metric": "seatsSold", # Size of each slice
"labels": true, # Show category names
"show_values": true, # Show numeric values inside slices
"inner_radius": 0.6, # Enables donut (0 = full pie)
"outer_radius": 0.95, # Size scaling (0.0 to 1.0)
"outer_ring": true # Enables dual-ring charts
},
"show_legend": true,
"legend_position": "right"
}
Notes on ring options:
- `inner_radius` creates a donut shape. Recommended: 0.5–0.8.
- `outer_radius` controls the size of the entire chart area.
- `outer_ring` enables comparison across rings, useful when the query returns multiple groupings/metrics.
── 📋 Table ──
{
"table.pivot_column": "flightType",
"column_settings": {
"seatsSold": {
"number_style": "decimal",
"suffix": " pax"
}
}
}
collection_id (int, optional):
Save card into a specific Metabase collection (folder).
description (str, optional):
Description or help text for the card.
parameter_mappings (list, optional):
Used when linking dashboard filters to this card.
Example:
[
{
"parameter_id": "flightType",
"card_id": 123,
"target": ["dimension", ["template-tag", "flightType"]]
}
]
collection_position (int, optional):
Optional order in the collection.
result_metadata (list, optional):
Optional field metadata describing result set.
cache_ttl (int, optional):
Cache duration (in seconds). 0 disables caching.
parameters (list, optional):
List of query parameters for SQL or MBQL filters.
Example: [{"name": "region", "type": "category", "slug": "region"}]
dashboard_id (int, optional):
Adds this card to an existing dashboard.
dashboard_tab_id (int, optional):
If the dashboard has tabs, specify the tab ID to attach the card to.
entity_id (str, optional):
External or custom ID for embedding/syncing cards.Returns: Dict[str, Any]: A dictionary representing the created card including: - id (int) - name (str) - dataset_query (dict) - visualization_settings (dict) - created_at, updated_at, etc.
Example: >>> await create_metabase_card( name="Seats Sold by Destination (Donut with Outer Ring)", display="pie", dataset_query={ "type": "native", "native": { "query": "SELECT destination, SUM("seatsSold") AS total_seats_sold FROM "Flight" GROUP BY destination" }, "database": 2 }, visualization_settings={ "pie": { "category": "destination", "metric": "total_seats_sold", "labels": true, "inner_radius": 0.6, "outer_radius": 0.95, "show_values": true, "outer_ring": true }, "show_legend": true, "legend_position": "right" }, collection_id=3 )
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| dataset_query | Yes | ||
| display | Yes | ||
| type | No | question | |
| visualization_settings | No | ||
| collection_id | No | ||
| description | No | ||
| parameter_mappings | No | ||
| collection_position | No | ||
| result_metadata | No | ||
| cache_ttl | No | ||
| parameters | No | ||
| dashboard_id | No | ||
| dashboard_tab_id | No | ||
| entity_id | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||