Guide for agents
This text is for an AI agent that uses the Metabase MCP server on a database with engine cube. You need no knowledge
of Cube. browse_data with action list_databases returns a short form of this text as the description of the
database.
What the objects are
| You see | It is |
|---|---|
| Table | A cube or a view. A view is a curated set of members. Prefer a view if one fits the question. |
| Field | A dimension. Group and filter by it. |
| Measure | A number with its aggregation in the data model. Do not sum or count its column again. |
| Segment | A saved filter. |
Find data
- Call
searchwith one keyword per entry interm_queries, for example["revenue", "city"], andtype: ["table"]. A live test on a Metabase with a Postgres app database findssalesfirst forrevenue by city. On an H2 app database, the same text finds nothing, because each word must match, alsoby. Keywords work on both. - Read the description of each table. It lists
Measures:,Dimensions:,Segments:andJoins:. Fields have no entry in the search index, so this text is how a search finds a dimension. - A search with
type: ["measure"]showsTable: Sales (sales, id 40).in the description. Many tables can have a measure with the same name, and this text tells them apart. - Call
browse_datawith actionget_fieldsand the table id, to get the ids of the measures, fields and segments.
Query
Use execute_query. Revenue by city, on a table that has both:
{"lib/type": "mbql/query", "stages": [{"lib/type": "mbql.stage/mbql", "source-table": 40,
"aggregation": [["measure", {}, 122]],
"breakout": [["field", {}, 326]]}]}
- Segment:
"filters": [["segment", {}, <segment id>]]. - Column of a table in
related_tables:["field", {}, <field id>]. Callget_fieldson that table to get the id. Metabase adds the join. - Time bucket:
["field", {"temporal-unit": "month"}, <field id>].
Use execute_sql only if the query cannot be a structured query:
SELECT users_city, MEASURE(revenue) FROM sales GROUP BY 1;
SELECT b.city, MEASURE(a.revenue) FROM orders a CROSS JOIN users b WHERE a.__cubeJoinField = b.__cubeJoinField GROUP BY 1;
A join with ON fails. Cube takes the join condition from the data model.
Save
- Run the query with
execute_query. Keepquery_handle. - Call
question_writewithmethod: "create",name,query_handleandcollection_id. An inlinequerymust also havedatabase. - Call
dashboard_writewithmethod: "create"and these operations:
[{"op": "add_card", "id": -1, "card_id": 7, "tab": null, "position": null, "size": null, "series": null, "inline_parameters": null},
{"op": "add_parameter", "parameter_id": "city", "name": "City", "type": "string/=", "sectionId": "location"},
{"op": "wire_parameter", "parameter_id": "city", "dashcard_id": -1, "target_field": 326}]
- Call
get_parameter_valueswithtarget: "dashboard", the dashboard id andparameter_idto get filter values. Addqueryto search.
Errors
| Error text | Next step |
|---|---|
This table has no column with that name |
Call get_fields. Use a view that has the column, or the CROSS JOIN form. |
Cube cannot plan this query |
Use a time bucket in place of EXTRACT. Use the CROSS JOIN form in place of JOIN ... ON. |
This connection gives data per person |
You cannot read as another person. Do not try __user or SET user. |
Your Metabase account has no value for the attribute |
Ask an admin to set the attribute. |
is a rolling window measure |
Group by a time bucket, and use a date filter on whole buckets. This also applies to a column of a model and to native SQL. |
Cube cannot filter on the measure column |
Filter on a dimension, or save a question that aggregates the measure and filter on its result. |
Cube cannot group by the measure |
Use the column as a metric, and group by a dimension. |
through different join paths |
Use one of the two columns in a query, or a view with a join alias for each path. |
Cube reads > on |
In native SQL, write >= with the next second. |
Cube reads the end of BETWEEN |
In native SQL, write the time in the literals, or use >= and <. |
Cube drops the fraction of a second |
Use whole seconds, with >= and <=. |
Numbers that you must not trust
The Cube SQL API has the type Double for numbers, so it rounds a value above 2^53. See How queries reach Cube.
On a connection with per-person data, each person sees different rows. Do not compare a number with the number of another person.