Retrieve a single Metabase collection by ID.

Args: collection_id (int): ID of the collection.

Returns: Dict[str, Any]: Collection metadata.

Create a new Metabase collection.

Args: name (str): Name of the collection. color (str, optional): Hex color code. parent_id (int, optional): ID of the parent collection.

Returns: Dict[str, Any]: Newly created collection metadata.

Update an existing Metabase collection.

Args: collection_id (int): ID of the collection to update. name (str, optional): New name. color (str, optional): New color. parent_id (int, optional): New parent collection ID.

Returns: Dict[str, Any]: Updated collection metadata.

Delete a Metabase collection.

Args: collection_id (int): ID of the collection to delete.

Returns: Dict[str, Any]: Confirmation of the collection deletion.

Get a list of all saved questions (cards).

Returns: Dict[str, Any]: Cards metadata including names, ids, collections.

Get the results of a card's query.

Args: card_id (int): ID of the card.

Returns: Dict[str, Any]: Query result data.

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 )

Update an existing card in Metabase.

Args: card_id (int): ID of the card to update. name (str, optional): New name of the card. dataset_query (Dict[str, Any], optional): Dataset query definition. display (str, optional): Display type. type (str, optional): Card type. visualization_settings (Dict[str, Any], optional): Visualization settings. collection_id (int, optional): ID of the collection. description (str, optional): Description of the card. parameter_mappings (list, optional): Parameter mappings. collection_position (int, optional): Position in the collection. result_metadata (list, optional): Metadata for results. cache_ttl (int, optional): Cache TTL. parameters (list, optional): Query parameters. dashboard_id (int, optional): Dashboard ID. dashboard_tab_id (int, optional): Dashboard tab ID. entity_id (str, optional): Entity ID.

Returns: Dict[str, Any]: Updated card metadata.

Delete a card from Metabase.

Args: card_id (int): ID of the card to delete.

Returns: Dict[str, Any]: Deletion confirmation.

Get a list of dashboards in Metabase.

Returns: Dict[str, Any]: Dashboard metadata including id, name, and cards.

Get a dashboard by ID.

Args: dashboard_id (int): ID of the dashboard.

Returns: Dict[str, Any]: Dashboard metadata including id, name, cards, and tabs.

Get cards in a dashboard.

Args: dashboard_id (int): ID of the dashboard.

Returns: Dict[str, Any]: Cards in the dashboard.

Get all items in a dashboard.

Args: dashboard_id (int): ID of the dashboard.

Returns: Dict[str, Any]: All items in the dashboard.

Create a new dashboard in Metabase.

Args: name (str): Name of the dashboard. description (str, optional): Dashboard description. collection_id (int, optional): Collection ID. parameters (list, optional): Parameters for the dashboard. tabs (list, optional): Tabs for the dashboard (list of {"name": "Tab Name"}). cache_ttl (int, optional): Cache time to live in seconds. collection_position (int, optional): Position in the collection.

Returns: Dict[str, Any]: Created dashboard metadata.

Update an existing dashboard in Metabase using structured inputs and auto-fallback behavior.

This function allows partial updates to a dashboard. If you don't pass optional fields like dashcards or tabs, the current values from the existing dashboard will be fetched and reused.

Args: dashboard_id (int): The ID of the dashboard to update.

name (str, optional):
    New name for the dashboard. If not provided, the current name will be retained.

description (str, optional):
    Updated description for the dashboard.

collection_id (int, optional):
    ID of the collection (folder) to move the dashboard into.
    If not provided, the existing collection is kept. However,
    if a new collection has been created,
    it is mandatory to pass the collection ID.
    Failure to do so will result in the dashboard being moved to the default collection,
    where the chart details may not exist.

parameters (List[dict], optional):
    List of dashboard-level filters (used for interactive filtering).
    If omitted, existing parameters will be preserved.

tabs (List[DashboardTab], optional):
    List of tabs to set on the dashboard.
    If not passed, the current tab configuration is reused.
    Each tab includes:
        - `id`: Tab ID (optional if new)
        - `name`: Display name of the tab

dashcards (List[DashboardCard], optional):
    List of cards to place in the dashboard layout.
    If omitted, the existing card layout is retained.
    Each card requires:
        - `id`: Use negative numbers to auto generate the ids 
            or use any unique value but,
            it must be unique within the dashboard
        - `card_id`: ID of the saved chart
        - `row`, `col`: Grid position (top-left = 0,0)
        - `size_x`, `size_y`: Width/height in grid cells
        - `parameter_mappings`: List of filter mappings

points_of_interest (str, optional):
    Free-text notes that appear in the dashboard as "Points of Interest".

caveats (str, optional):
    Free-text notes that appear in the dashboard as "Caveats".

enable_embedding (bool, optional):
    Whether to enable embedding for this dashboard.
    If omitted, the existing setting is reused.

embedding_params (EmbeddingParams, optional):
    Optional embedding configuration. Includes:
        - `url`: Optional embed URL override
        - `custom_css`: Optional custom styling

archived (bool, optional):
    Whether to archive the dashboard. Defaults to existing value if omitted.

position (int, optional):
    Optional global ordering value (affects dashboard listing).

collection_position (int, optional):
    Sort order inside its collection folder.

cache_ttl (int, optional):
    Result caching time in seconds (e.g., 3600 = 1 hour). 0 disables caching.

width (str, optional):
    Dashboard layout mode: "fixed" (grid) or "full" (fluid width).
    Defaults to existing setting if omitted.

show_in_getting_started (bool, optional):
    Whether to show this dashboard in Metabase’s “Getting Started” view.

Returns: Dict[str, Any]: JSON object containing updated dashboard metadata from Metabase. Includes fields like: - id, name, description - dashcards, tabs, parameters - updated_at, created_at, etc.

Behavior: - If dashcards is omitted, the existing layout will be preserved. - If dashcards are passed without an id, id = -1 will be set automatically. - If tabs are omitted, current dashboard tabs are reused. - All unspecified fields fall back to the dashboard's current value.

Example: >>> await update_metabase_dashboard( dashboard_id=1, name="Updated Flight Dashboard", dashcards=[ DashboardCard(card_id=123, row=0, col=0, size_x=4, size_y=3), DashboardCard(card_id=124, row=0, col=4, size_x=4, size_y=3) ], tabs=[DashboardTab(name="Overview")], width="fixed" )

Delete a dashboard from Metabase.

Args: dashboard_id (int): ID of the dashboard to delete.

Returns: Dict[str, Any]: Deletion confirmation.

Copy a dashboard.

Args: from_dashboard_id (int): ID of the source dashboard to copy. name (str): Name for the new dashboard. description (str, optional): Description for the new dashboard. collection_id (int, optional): Collection ID for the new dashboard. is_deep_copy (bool, optional): Whether to perform a deep copy (copy linked cards too). collection_position (int, optional): Position in the collection.

Returns: Dict[str, Any]: New dashboard metadata.

Get a list of connected databases in Metabase.

Returns: Dict[str, Any]: List of database metadata.

Create a new database connection in Metabase.

Args: name (str): Name of the database. engine (str): Database engine. details (Dict[str, Any]): Connection details. auto_run_queries (bool, optional): Enable auto run. cache_ttl (int, optional): Cache time-to-live. is_full_sync (bool, optional): Whether to perform full sync. schedule (Dict[str, Any], optional): Sync schedule. timezone (str, optional): Timezone for the database. metadata_sync (bool, optional): Enable metadata sync.

Returns: Dict[str, Any]: Created database metadata.

Update an existing database connection in Metabase.

Args: database_id (int): ID of the database to update. name (str, optional): Name of the database. details (Dict[str, Any], optional): Connection details. auto_run_queries (bool, optional): Enable auto run. cache_ttl (int, optional): Cache time-to-live. is_full_sync (bool, optional): Whether to perform full sync. schedule (Dict[str, Any], optional): Sync schedule. timezone (str, optional): Timezone for the database. metadata_sync (bool, optional): Enable metadata sync.

Returns: Dict[str, Any]: Updated database metadata.

Delete a database connection from Metabase.

Args: database_id (int): ID of the database to delete.

Returns: Dict[str, Any]: Deletion confirmation.

Get a list of users in Metabase.

Returns: Dict[str, Any]: User metadata including id, email, groups, etc.

Create a new user in Metabase.

Args: first_name (str): User's first name. last_name (str): User's last name. email (str): Email address. password (str): Account password. login_attributes (dict, optional): Additional login metadata. group_ids (list, optional): List of group IDs to assign the user. is_superuser (bool, optional): Whether the user is a superuser.

Returns: Dict[str, Any]: Created user metadata.

Update an existing user in Metabase.

Args: user_id (int): ID of the user to update. first_name (str, optional): Updated first name. last_name (str, optional): Updated last name. email (str, optional): Updated email address. password (str, optional): Updated password. login_attributes (dict, optional): Updated login metadata. group_ids (list, optional): Updated group IDs. is_superuser (bool, optional): Updated superuser flag.

Returns: Dict[str, Any]: Updated user metadata.

Delete a user from Metabase.

Args: user_id (int): ID of the user to delete.

Returns: Dict[str, Any]: Deletion confirmation.

Get current logged-in user info from Metabase.

Returns: Dict[str, Any]: User details like id, email, groups, etc.

Get a list of groups (roles) in Metabase.

Returns: Dict[str, Any]: Group metadata including id, name, etc.

Create a new group (role) in Metabase.

Args: name (str): Name of the group to create. ldap_dn (str, optional): LDAP Distinguished Name if applicable.

Returns: Dict[str, Any]: Created group metadata.

Delete a group (role) from Metabase.

Args: group_id (int): ID of the group to delete.

Returns: Dict[str, Any]: Deletion confirmation.

Execute a native SQL query through Metabase.

Args: database_id (int): ID of the database to execute the query on. native_query (str): The SQL query to execute. parameters (list, optional): Query parameters.

Returns: Dict[str, Any]: Query execution result.

Notes: - For PostgreSQL databases, column names are be case-sensitive - Use double quotes around column names with mixed case (e.g., "columnName") - Example with quoted column names: SELECT "userId", "orderDate", COUNT(*) FROM "Orders" GROUP BY "userId", "orderDate"