Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Misc agent API improvements + llms-agent-api.txt (#68914)

Noah Moss3192d0161237
diff --git a/docs/agent-api/reference.md b/docs/agent-api/reference.md
new file mode 100644
index 00000000000..bd5ae46cb48
--- /dev/null
+++ b/docs/agent-api/reference.md
@@ -0,0 +1,573 @@
+# Metabase Agent API - Complete Reference
+
+The Agent API is a REST API for building headless, agentic BI applications on
+top of Metabase's semantic layer. It supports discovering tables and metrics,
+inspecting their fields, constructing queries, and executing them — all scoped
+to the authenticated user's permissions.
+
+Base path: /api/agent
+
+Requires: Metabase Pro/Enterprise with the `agent-api` feature enabled.
+
+## Key concepts
+
+- **Tables**: Database tables visible to the user.
+- **Metrics**: Standalone saved queries that represent pre-defined aggregations
+ (e.g., "Total Revenue"). Metrics are stored in collections and can be used
+ as a data source in the API. They have a fixed aggregation, but can be
+ filtered and grouped by their queryable dimensions. Use /v1/metric/{id} to
+ inspect a metric's dimensions, and POST /v1/construct-query with `metric_id`
+ to query one.
+- **Measures**: Lightweight, reusable aggregation expressions (e.g.,
+ `SUM(total)`) associated with a specific table. Unlike metrics, measures are
+ not standalone queries — they are building blocks that can be referenced in
+ table queries via `measure_id` in the aggregations array. Discover available
+ measures for a table via GET /v1/table/{id}?with-measures=true.
+- **Segments**: Pre-defined filter conditions (e.g., "Active Users") that can
+ be applied to queries by referencing their segment_id.
+- **Field IDs**: Opaque string identifiers for columns, formatted as
+ `<prefix><entity-id>-<column-index>`. Prefix is `t` for table fields and
+ `c` for metric fields. Example: `t42-3` means the column at index 3 of table 42.
+ Field IDs are returned by the table/metric detail endpoints and must be used
+ as-is in query construction. They are positional — always fetch current
+ entity details before constructing queries.
+
+## Authentication
+
+Two modes, both requiring JWT to be configured in Metabase admin settings
+(Admin > Settings > Authentication > JWT):
+
+### 1. Stateless JWT (recommended for agents)
+
+Pass a signed JWT directly in each request:
+
+```
+Authorization: Bearer <jwt>
+```
+
+The JWT must be signed with the shared secret configured in Metabase. Required
+claims:
+
+| Claim | Type | Required | Description |
+|---------|--------|----------|--------------------------------------|
+| iat | int | Yes | Issued-at time (Unix seconds). JWT |
+| | | | must be <180 seconds old. |
+| email | string | Yes | Email matching a Metabase user. The |
+| | | | claim name is configurable via the |
+| | | | jwt-attribute-email admin setting |
+| | | | (default: "email"). |
+
+Optional claims: first_name, last_name, groups (for group sync).
+
+Example JWT payload:
+
+```json
+{
+ "iat": 1706640000,
+ "email": "[email protected]"
+}
+```
+
+### 2. Session-based
+
+Exchange a JWT at `POST /auth/sso` to get a session token, then pass it via:
+
+```
+X-Metabase-Session: <session-token>
+```
+
+### Error responses (401)
+
+```json
+{"error": "missing_authorization", "message": "Authentication required. Use X-Metabase-Session header or Authorization: Bearer <jwt>."}
+{"error": "invalid_authorization_format", "message": "Authorization header must use Bearer scheme: Authorization: Bearer <jwt>"}
+{"error": "invalid_jwt", "message": "Invalid or expired JWT token."}
+{"error": "jwt_not_configured", "message": "JWT authentication is not configured. Set the JWT shared secret in admin settings."}
+```
+
+## Permissions
+
+All endpoints enforce the authenticated user's data permissions. If the user
+lacks access to a table or metric, the API returns 403.
+
+## Parameter naming conventions
+
+Query parameters on GET endpoints use kebab-case (e.g., `with-fields`,
+`with-related-tables`). JSON request and response bodies use snake_case (e.g.,
+`table_id`, `field_id`, `field_granularity`). This applies consistently across
+all endpoints.
+
+## Endpoints
+
+### GET /v1/ping
+
+Health check.
+
+Response: `{"message": "pong"}`
+
+### GET /v1/table/{id}
+
+Get details for a table including fields, related tables, metrics, and
+segments.
+
+Query parameters (all boolean, all optional):
+
+| Parameter | Default | Description |
+|---------------------|---------|-----------------------------------------|
+| with-fields | true | Include field metadata |
+| with-field-values | true | Include sample values on each field |
+| with-related-tables | true | Include FK-related tables |
+| with-metrics | true | Include metrics defined on this table |
+| with-measures | false | Include measures |
+| with-segments | false | Include segments defined on this table |
+
+Response:
+
+```json
+{
+ "type": "table",
+ "id": 42,
+ "name": "ORDERS",
+ "display_name": "Orders",
+ "database_id": 1,
+ "database_engine": "postgres",
+ "database_schema": "PUBLIC",
+ "description": "All customer orders",
+ "fields": [
+ {
+ "field_id": "t42-0",
+ "name": "ID",
+ "type": "number",
+ "description": "Primary key",
+ "database_type": "BIGINT",
+ "semantic_type": "type/PK",
+ "field_values": [1, 2, 3]
+ }
+ ],
+ "related_tables": [
+ {
+ "id": 43,
+ "type": "table",
+ "name": "PRODUCTS",
+ "display_name": "Products",
+ "database_id": 1,
+ "related_by": "PRODUCT_ID"
+ }
+ ],
+ "metrics": [
+ {
+ "id": 10,
+ "type": "metric",
+ "name": "Total Revenue",
+ "default_time_dimension_field_id": "c10-2"
+ }
+ ],
+ "measures": [
+ {"id": 5, "name": "Sum of Total", "description": "Sum of the total column"}
+ ],
+ "segments": [
+ {"id": 1, "name": "Active Users", "description": "Users who logged in within 30 days"}
+ ]
+}
+```
+
+### GET /v1/metric/{id}
+
+Get details for a metric including its queryable dimensions.
+
+Query parameters (all boolean, all optional):
+
+| Parameter | Default | Description |
+|---------------------------------|---------|---------------------------------------|
+| with-default-temporal-breakout | true | Include default time dimension |
+| with-field-values | true | Include sample values on dimensions |
+| with-queryable-dimensions | true | Include dimensions for group_by |
+| with-segments | false | Include applicable segments |
+
+Response:
+
+```json
+{
+ "type": "metric",
+ "id": 10,
+ "name": "Total Revenue",
+ "description": "Sum of order totals",
+ "default_time_dimension_field_id": "c10-2",
+ "verified": true,
+ "queryable_dimensions": [
+ {
+ "field_id": "c10-0",
+ "name": "CREATED_AT",
+ "type": "datetime"
+ }
+ ],
+ "segments": []
+}
+```
+
+### GET /v1/table/{id}/field/{field-id}/values
+### GET /v1/metric/{id}/field/{field-id}/values
+
+Get statistics and sample values for a field. Accepts optional `limit` query
+parameter.
+
+Response:
+
+```json
+{
+ "field_id": "t42-3",
+ "statistics": {
+ "distinct_count": 200,
+ "percent_null": 0.02,
+ "min": 1.5,
+ "max": 500.0,
+ "avg": 75.3,
+ "q1": 25.0,
+ "q3": 120.0,
+ "sd": 45.2,
+ "earliest": "2020-01-01T00:00:00Z",
+ "latest": "2024-12-31T23:59:59Z"
+ },
+ "values": ["Gadget", "Widget", "Doohickey"]
+}
+```
+
+Statistics fields vary by field type. Numeric fields include min/max/avg/q1/q3/sd.
+Date fields include earliest/latest. String fields include average_length and
+percent_email/percent_url/percent_state/percent_json.
+
+### POST /v1/search
+
+Search for tables and metrics. Supports keyword and semantic search. Results
+are ranked using Reciprocal Rank Fusion when both query types are provided.
+
+Request:
+
+```json
+{
+ "term_queries": ["revenue", "orders"],
+ "semantic_queries": ["how much money did we make"]
+}
+```
+
+At least one of `term_queries` or `semantic_queries` should be provided. Both
+are arrays of strings. Results are limited to 50 by default.
+
+Response:
+
+```json
+{
+ "data": [
+ {
+ "type": "table",
+ "id": 42,
+ "name": "ORDERS",
+ "display_name": "Orders",
+ "description": "All customer orders",
+ "database_id": 1,
+ "database_schema": "PUBLIC",
+ "verified": false
+ },
+ {
+ "type": "metric",
+ "id": 10,
+ "name": "Total Revenue",
+ "verified": true
+ }
+ ],
+ "total_count": 2
+}
+```
+
+### POST /v1/construct-query
+
+Construct a query from a table or metric. Returns a base64-encoded query to
+pass to /v1/execute.
+
+**Important**: Field IDs used here must come from the detail endpoints
+(/v1/table/{id} or /v1/metric/{id}). Always fetch entity details first.
+
+#### Table query request
+
+All fields except `table_id` are optional:
+
+```json
+{
+ "table_id": 42,
+ "filters": [],
+ "fields": [{"field_id": "t42-0"}, {"field_id": "t42-1"}],
+ "aggregations": [{"field_id": "t42-3", "function": "sum"}],
+ "group_by": [{"field_id": "t42-5", "field_granularity": "month"}],
+ "order_by": [{"field": {"field_id": "t42-1"}, "direction": "desc"}],
+ "limit": 100
+}
+```
+
+#### Metric query request
+
+Metrics have a pre-defined aggregation, so only filters and group_by are
+supported:
+
+```json
+{
+ "metric_id": 10,
+ "filters": [{"field_id": "c10-2", "operation": "greater-than", "value": "2024-01-01"}],
+ "group_by": [{"field_id": "c10-2", "field_granularity": "month"}]
+}
+```
+
+#### Response
+
+```json
+{"query": "eyJkYXRhYmFzZSI6MSwi..."}
+```
+
+#### Filter types
+
+Filters are polymorphic. The required fields depend on the operation.
+
+**Segment filter** — apply a pre-defined segment:
+
+```json
+{"segment_id": 5}
+```
+
+**Existence filters** — no value needed:
+
+| Operation | Description |
+|----------------------|------------------------|
+| is-null | Field is null |
+| is-not-null | Field is not null |
+| string-is-empty | String is empty |
+| string-is-not-empty | String is not empty |
+| is-true | Boolean is true |
+| is-false | Boolean is false |
+
+```json
+{"field_id": "t42-0", "operation": "is-not-null"}
+```
+
+**Temporal filters** — for date/datetime fields. Optional `bucket` specifies
+temporal bucketing granularity for the comparison. Accepts both truncation
+units (`minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`) and
+extraction units (`day-of-week`, `day-of-month`, `day-of-year`,
+`week-of-year`, `month-of-year`, `quarter-of-year`, `hour-of-day`,
+`minute-of-hour`, `second-of-minute`). Note: this is a broader set of
+values than `field_granularity` in group_by, which only accepts truncation
+units.
+
+| Operation | Description |
+|-----------------------|---------------------------------|
+| equals | Equals value |
+| not-equals | Does not equal value |
+| greater-than | After (dates) / greater than |
+| greater-than-or-equal | On or after / greater or equal |
+| less-than | Before (dates) / less than |
+| less-than-or-equal | On or before / less or equal |
+
+```json
+{"field_id": "t42-5", "operation": "greater-than", "value": "2024-01-01"}
+```
+
+For multiple values, use `values` (array) instead of `value`:
+
+```json
+{"field_id": "t42-5", "operation": "equals", "values": ["2024-01-01", "2024-06-01"]}
+```
+
+**Temporal extraction filters** — filter by date component:
+
+| Operation | Value type |
+|------------------------|------------|
+| year-equals | int |
+| year-not-equals | int |
+| quarter-equals | int (1-4) |
+| quarter-not-equals | int |
+| month-equals | int (1-12) |
+| month-not-equals | int |
+| day-of-week-equals | int (1-7) |
+| day-of-week-not-equals | int |
+| hour-equals | int (0-23) |
+| hour-not-equals | int |
+| minute-equals | int (0-59) |
+| minute-not-equals | int |
+| second-equals | int (0-59) |
+| second-not-equals | int |
+
+```json
+{"field_id": "t42-5", "operation": "month-equals", "value": 12}
+```
+
+For multiple values: `{"field_id": "t42-5", "operation": "month-equals", "values": [1, 2, 3]}`
+
+**String filters**:
+
+| Operation | Description |
+|---------------------|--------------------------------------|
+| equals | Exact match |
+| not-equals | Does not match |
+| string-contains | Contains substring |
+| string-not-contains | Does not contain substring |
+| string-starts-with | Starts with prefix |
+| string-ends-with | Ends with suffix |
+
+```json
+{"field_id": "t42-2", "operation": "string-contains", "value": "acme"}
+```
+
+For multiple values: `{"field_id": "t42-2", "operation": "equals", "values": ["A", "B"]}`
+
+**Numeric filters**:
+
+| Operation | Description |
+|-----------------------|------------------------|
+| equals | Equals value |
+| not-equals | Does not equal value |
+| greater-than | Greater than |
+| greater-than-or-equal | Greater than or equal |
+| less-than | Less than |
+| less-than-or-equal | Less than or equal |
+
+```json
+{"field_id": "t42-3", "operation": "greater-than", "value": 100}
+```
+
+For multiple values: `{"field_id": "t42-3", "operation": "equals", "values": [10, 20, 30]}`
+
+#### Aggregations
+
+Field-based aggregation — `function` is required:
+
+| Function | Description |
+|----------------|----------------------------|
+| avg | Average |
+| count | Count of rows |
+| count-distinct | Count of distinct values |
+| max | Maximum value |
+| min | Minimum value |
+| sum | Sum |
+
+```json
+{"field_id": "t42-3", "function": "sum"}
+```
+
+For `count`, omit `field_id` (count operates on rows, not a specific field):
+
+```json
+{"function": "count"}
+```
+
+To sort by an aggregation result, use `sort_order` on the aggregation itself
+(not `order_by`):
+
+```json
+{"field_id": "t42-3", "function": "sum", "sort_order": "desc"}
+```
+
+Measure-based aggregation — uses a pre-defined measure:
+
+```json
+{"measure_id": 5, "sort_order": "asc"}
+```
+
+#### Group by
+
+```json
+{"field_id": "t42-5", "field_granularity": "month"}
+```
+
+`field_granularity` is optional and controls temporal grouping granularity.
+Valid values: `minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`,
+`day-of-week`. Note: this is a smaller set than the `bucket` field on
+filters, which also accepts extraction units like `day-of-month` and
+`hour-of-day`.
+
+#### Order by
+
+Order by a field (not an aggregation — use `sort_order` for that):
+
+```json
+{"field": {"field_id": "t42-1"}, "direction": "desc"}
+```
+
+### POST /v1/execute
+
+Execute a query returned by /v1/construct-query.
+
+**Important: streaming response.** This endpoint streams results, so the HTTP
+status code (202) is sent before query execution completes. A 202 status does
+NOT guarantee the query succeeded — you must check the `status` field in the
+response body. If the query fails mid-execution, the response body will contain
+`"status": "failed"` with an error message, even though the HTTP status was 202.
+
+Request:
+
+```json
+{"query": "eyJkYXRhYmFzZSI6MSwi..."}
+```
+
+Response (HTTP 202):
+
+The response body may contain additional fields beyond those documented here.
+Ignore any fields not listed below — they are internal metadata and not part of
+the stable API contract.
+
+On success:
+
+```json
+{
+ "status": "completed",
+ "data": {
+ "cols": [
+ {"name": "CREATED_AT", "base_type": "type/DateTime", "effective_type": "type/DateTime", "display_name": "Created At"},
+ {"name": "sum", "base_type": "type/Float", "effective_type": "type/Float", "display_name": "Sum of Total"}
+ ],
+ "rows": [
+ ["2024-01-01T00:00:00Z", 15234.50],
+ ["2024-02-01T00:00:00Z", 18102.75]
+ ]
+ },
+ "row_count": 2,
+ "running_time": 142
+}
+```
+
+| Field | Description |
+|--------------|-----------------------------------------------------------------|
+| status | `"completed"` on success, `"failed"` on error |
+| data.cols | Column metadata (name, base_type, effective_type, display_name) |
+| data.rows | Array of row arrays, in the same order as cols |
+| row_count | Number of rows returned |
+| running_time | Query execution time in milliseconds |
+
+On failure:
+
+```json
+{"status": "failed", "error": "Query error message"}
+```
+
+Row limits are enforced automatically:
+- Simple queries (no aggregation): 2000 rows max
+- Aggregated queries: 10000 rows max
+
+## Typical workflow
+
+1. **Search** — POST /v1/search to find relevant tables or metrics
+2. **Inspect** — GET /v1/table/{id} or /v1/metric/{id} to get field IDs and
+ understand the schema
+3. **Explore field values** — GET /v1/table/{id}/field/{field-id}/values if
+ you need to know valid filter values or field statistics
+4. **Build query** — POST /v1/construct-query with filters, aggregations,
+ group_by, etc.
+5. **Execute** — POST /v1/execute with the base64-encoded query
+6. **Iterate** — Adjust filters/aggregations and repeat steps 4-5
+
+## Error handling
+
+| HTTP Status | Meaning |
+|-------------|------------------------------------------|
+| 200 | Success (GET endpoints, construct-query) |
+| 202 | Success (execute — streaming response) |
+| 401 | Authentication failure |
+| 403 | Insufficient permissions |
+| 404 | Entity not found |
diff --git a/enterprise/backend/src/metabase_enterprise/agent_api/api.clj b/enterprise/backend/src/metabase_enterprise/agent_api/api.clj
index 97c5014e867..c8b33ea38f5 100644
--- a/enterprise/backend/src/metabase_enterprise/agent_api/api.clj
+++ b/enterprise/backend/src/metabase_enterprise/agent_api/api.clj
@@ -16,7 +16,6 @@
[metabase.api.routes.common :as api.routes.common]
[metabase.auth-identity.core :as auth-identity]
[metabase.query-processor :as qp]
- [metabase.query-processor.schema :as qp.schema]
[metabase.query-processor.streaming :as qp.streaming]
[metabase.request.core :as request]
[metabase.server.streaming-response :as streaming-response]
@@ -80,6 +79,14 @@
[:display_name {:optional true} [:maybe :string]]
[:description {:optional true} [:maybe :string]]])
+(mr/def ::measure
+ "A reusable aggregation expression associated with a table. Reference via measure_id in the aggregations array."
+ [:map {:encode/api #(update-keys % metabot-v3.u/safe->snake_case_en)}
+ [:id :int]
+ [:name :string]
+ [:display_name {:optional true} [:maybe :string]]
+ [:description {:optional true} [:maybe :string]]])
+
(mr/def ::related-table
"A table related to the queried entity via foreign key. The related_by field indicates the FK field name."
[:map {:encode/api #(update-keys % metabot-v3.u/safe->snake_case_en)}
@@ -88,7 +95,7 @@
[:name :string]
[:display_name {:optional true} [:maybe :string]]
[:database_id {:optional true} [:maybe :int]]
- [:database_engine {:optional true} [:maybe :keyword]]
+ [:database_engine {:optional true} [:maybe :string]]
[:database_schema {:optional true} [:maybe :string]]
[:description {:optional true} [:maybe :string]]
[:fields {:optional true} [:maybe [:sequential ::field]]]
@@ -102,12 +109,13 @@
[:name :string]
[:display_name :string]
[:database_id :int]
- [:database_engine :keyword]
+ [:database_engine :string]
[:database_schema {:optional true} [:maybe :string]]
[:description {:optional true} [:maybe :string]]
[:fields [:sequential ::field]]
[:related_tables {:optional true} [:maybe [:sequential ::related-table]]]
[:metrics {:optional true} [:maybe [:sequential ::metric-summary]]]
+ [:measures {:optional true} [:maybe [:sequential ::measure]]]
[:segments {:optional true} [:maybe [:sequential ::segment]]]])
(mr/def ::metric
@@ -348,8 +356,29 @@
[:map
[:query ms/NonBlankString]])
+(mr/def ::column-metadata
+ "Metadata for a single result column."
+ [:map
+ [:name :string]
+ [:base_type :string]
+ [:effective_type {:optional true} [:maybe :string]]
+ [:display_name :string]])
+
+(mr/def ::execute-query-response
+ "Response from query execution. The HTTP status is always 202 because results are streamed —
+ check the `status` field to determine success or failure."
+ [:map
+ [:status [:enum :completed :failed]]
+ [:data {:optional true}
+ [:map
+ [:cols [:sequential ::column-metadata]]
+ [:rows [:sequential [:sequential :any]]]]]
+ [:row_count {:optional true} :int]
+ [:running_time {:optional true} :int]
+ [:error {:optional true} :string]])
+
(api.macros/defendpoint :post "/v1/execute"
- :- (streaming-response/streaming-response-schema ::qp.schema/query-result)
+ :- (streaming-response/streaming-response-schema ::execute-query-response)
"Execute an MBQL query and return results.
Accepts a base64-encoded MBQL query (as returned by /v1/construct-query) and executes it,
@@ -365,12 +394,15 @@
{encoded-query :query} :- ::execute-query-request]
(let [query (-> encoded-query
u/decode-base64
- json/decode+kw)]
+ json/decode+kw)
+ info {:executed-by api/*current-user-id*
+ :context :agent}]
(qp.streaming/streaming-response [rff :api]
(qp/process-query
(-> query
(update-in [:middleware :js-int-to-string?] (fnil identity true))
- qp/userland-query-with-default-constraints)
+ qp/userland-query-with-default-constraints
+ (update :info merge info))
rff))))
;;; ------------------------------------------------- Authentication -------------------------------------------------
diff --git a/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/api.clj b/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/api.clj
index 4a596904b70..55c4a205249 100644
--- a/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/api.clj
+++ b/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/api.clj
@@ -100,10 +100,7 @@
[:operation [:enum {:encode/tool-api-request keyword}
"equals" "not-equals"
"greater-than" "greater-than-or-equal"
- "less-than" "less-than-or-equal"
- "date-equals" "date-not-equals"
- "date-before" "date-on-or-before"
- "date-after" "date-on-or-after"]]
+ "less-than" "less-than-or-equal"]]
[:value [:or :string :int]]]
[:map {:encode/tool-api-request #(update-keys % metabot-v3.u/safe->kebab-case-en)}]])
@@ -125,7 +122,6 @@
[:field_id :string]
[:operation [:enum {:encode/tool-api-request keyword}
"equals" "not-equals"
- "string-equals" "string-not-equals"
"string-contains" "string-not-contains"
"string-starts-with" "string-ends-with"]]
[:value :string]]
@@ -147,12 +143,9 @@
[:map
[:field_id :string]
[:operation [:enum {:encode/tool-api-request keyword}
- "equals" "not-equals"
- "greater-than" "greater-than-or-equal"
- "less-than" "less-than-or-equal"
- "number-equals" "number-not-equals"
- "number-greater-than" "number-greater-than-or-equal"
- "number-less-than" "number-less-than-or-equal"]]
+ "equals" "not-equals"
+ "greater-than" "greater-than-or-equal"
+ "less-than" "less-than-or-equal"]]
[:value [:or :int :double]]]
[:map {:encode/tool-api-request #(update-keys % metabot-v3.u/safe->kebab-case-en)}]])
@@ -161,8 +154,7 @@
[:map
[:field_id :string]
[:operation [:enum {:encode/tool-api-request keyword}
- "equals" "not-equals"
- "number-equals" "number-not-equals"]]
+ "equals" "not-equals"]]
[:values [:sequential [:or :int :double]]]]
[:map {:encode/tool-api-request #(update-keys % metabot-v3.u/safe->kebab-case-en)}]])
@@ -191,20 +183,26 @@
"minute", "hour" "day" "week" "month" "quarter" "year" "day-of-week"]]]]
[:map {:encode/tool-api-request #(update-keys % metabot-v3.u/safe->kebab-case-en)}]])
-(mr/def ::field-aggregation
- "Aggregation using a field and function.
+(mr/def ::count-aggregation
+ "Count aggregation — counts rows, no field_id needed.
+ Use sort_order to order results by this aggregation ('asc' or 'desc')."
+ [:and
+ [:map
+ [:function [:= {:encode/tool-api-request keyword} "count"]]
+ [:bucket {:optional true} ::bucket]
+ [:sort_order {:optional true} [:maybe [:enum {:encode/tool-api-request keyword} "asc" "desc"]]]]
+ [:map {:encode/tool-api-request #(update-keys % metabot-v3.u/safe->kebab-case-en)}]])
- - field_id: Required. For 'count', any valid field_id can be provided (the value is ignored since count operates on rows).
- - function: The aggregation function to apply.
- - sort_order: Optional. Use this to order results by this aggregation ('asc' or 'desc').
- This is the correct way to sort by aggregation results - do NOT use order_by for aggregations."
+(mr/def ::field-aggregation
+ "Aggregation using a field and function. field_id is required.
+ Use sort_order to order results by this aggregation ('asc' or 'desc')."
[:and
[:map
[:field_id :string]
[:bucket {:optional true} ::bucket]
[:sort_order {:optional true} [:maybe [:enum {:encode/tool-api-request keyword} "asc" "desc"]]]
[:function [:enum {:encode/tool-api-request keyword}
- "avg" "count" "count-distinct" "max" "min" "sum"]]]
+ "avg" "count-distinct" "max" "min" "sum"]]]
[:map {:encode/tool-api-request #(update-keys % metabot-v3.u/safe->kebab-case-en)}]])
(mr/def ::measure-aggregation
@@ -216,8 +214,8 @@
[:map {:encode/tool-api-request #(update-keys % metabot-v3.u/safe->kebab-case-en)}]])
(mr/def ::aggregation
- "Aggregation - either field-based or measure-based."
- [:or ::field-aggregation ::measure-aggregation])
+ "Aggregation — count (field optional), field-based (field required), or measure-based."
+ [:or ::count-aggregation ::field-aggregation ::measure-aggregation])
(mr/def ::field
[:and
@@ -343,7 +341,7 @@
[:name :string]
[:display_name :string]
[:database_id :int]
- [:database_engine :keyword]
+ [:database_engine :string]
[:database_schema {:optional true} [:maybe :string]] ; Schema name, if applicable
[:fields ::columns]
[:related_tables {:optional true} [:sequential [:ref ::table-result]]]
diff --git a/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/entity_details.clj b/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/entity_details.clj
index 5ec6159d95d..5e50002b6d4 100644
--- a/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/entity_details.clj
+++ b/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/entity_details.clj
@@ -176,9 +176,10 @@
(metabot-v3.tools.u/get-table id :db_id :description :name :schema))]
(let [query-needed? (or with-fields? with-related-tables? with-metrics? with-measures? with-segments?)
db-id (if metadata-provider (:db-id base) (:db_id base))
- db-engine (:engine (if metadata-provider
- (lib.metadata/database metadata-provider)
- (metabot-v3.tools.u/get-database db-id :engine)))
+ db-engine (some-> (if metadata-provider
+ (lib.metadata/database metadata-provider)
+ (metabot-v3.tools.u/get-database db-id :engine))
+ :engine name)
mp (when query-needed?
(or metadata-provider
(lib-be/application-database-metadata-provider db-id)))
@@ -268,7 +269,7 @@
:as options}]
(let [id (:id base)
database-id (:database_id base)
- database-engine (:engine (lib.metadata/database metadata-provider))
+ database-engine (some-> (lib.metadata/database metadata-provider) :engine name)
card-metadata (lib.metadata/card metadata-provider id)
dataset-query (get card-metadata :dataset-query)
query-needed? (or with-fields? with-related-tables? with-metrics? with-measures? with-segments?)
diff --git a/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/filters.clj b/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/filters.clj
index 5ca5aadcc95..231e0bf5450 100644
--- a/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/filters.clj
+++ b/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/filters.clj
@@ -217,17 +217,27 @@
:status-code 404
:measure-id measure-id})))
;; Field-based aggregation
- (let [expr (bucketed-column aggregation)
- agg-expr (case (:function aggregation)
- :count (lib/count)
- :count-distinct (lib/distinct expr)
- :sum (lib/sum expr)
- :min (lib/min expr)
- :max (lib/max expr)
- :avg (lib/avg expr))]
+ (let [agg-expr (if (= :count (:function aggregation))
+ (lib/count)
+ (let [expr (bucketed-column aggregation)]
+ (case (:function aggregation)
+ :count-distinct (lib/distinct expr)
+ :sum (lib/sum expr)
+ :min (lib/min expr)
+ :max (lib/max expr)
+ :avg (lib/avg expr))))]
(lib/aggregate query agg-expr)))]
(apply-aggregation-sort-order query-with-aggregation sort-order)))
+(defn- resolve-aggregation-column
+ "Resolve the column for an aggregation, skipping measures and field-less counts."
+ [resolve-visible-column aggregation]
+ (if (or (:measure-id aggregation)
+ (and (= :count (:function aggregation))
+ (not (:field-id aggregation))))
+ aggregation
+ (resolve-visible-column aggregation)))
+
(defn- expression?
[expr-or-column]
(vector? expr-or-column))
@@ -265,8 +275,7 @@
(lib/display-name base-query -1 column :long))))
resolve-visible-column)
fields)
- ;; Measures and segments don't require column resolution
- resolved-aggregations (map #(if (:measure-id %) % (resolve-visible-column %)) aggregations)
+ resolved-aggregations (map (partial resolve-aggregation-column resolve-visible-column) aggregations)
resolved-filters (map #(if (:segment-id %) % (resolve-visible-column %)) filters)
reduce-query (fn [query f coll] (reduce f query coll))
query (-> base-query
@@ -340,8 +349,7 @@
(lib/display-name base-query -1 column :long))))
resolve-visible-column)
fields)
- ;; Measures and segments don't require column resolution
- all-aggregations (map #(if (:measure-id %) % (resolve-visible-column %)) aggregations)
+ all-aggregations (map (partial resolve-aggregation-column resolve-visible-column) aggregations)
all-filters (map #(if (:segment-id %) % (resolve-visible-column %)) filters)
reduce-query (fn [query f coll] (reduce f query coll))
query (-> base-query
diff --git a/enterprise/backend/test/metabase_enterprise/agent_api/api_test.clj b/enterprise/backend/test/metabase_enterprise/agent_api/api_test.clj
index c92ba34adb3..3f22fa0b35f 100644
--- a/enterprise/backend/test/metabase_enterprise/agent_api/api_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/agent_api/api_test.clj
@@ -17,6 +17,7 @@
[metabase.test :as mt]
[metabase.test.fixtures :as fixtures]
[metabase.test.http-client :as client]
+ [metabase.test.util :as tu]
[metabase.util :as u]
[metabase.util.json :as json]
[metabase.warehouse-schema.models.field-values :as field-values]
@@ -350,6 +351,23 @@
(is (every? :name cols) "Each column should have a name")
(is (every? :base_type cols) "Each column should have a base_type"))))))
+(deftest execute-query-records-query-execution-test
+ (with-agent-api-setup!
+ (testing "Executed queries are recorded with :agent context"
+ (mt/with-temp [:model/User {user-id :id email :email} {:is_superuser true}]
+ (let [table-id (mt/id :orders)
+ headers (auth-headers email)
+ construct-resp (client/client :post 200 "agent/v1/construct-query"
+ {:request-options {:headers headers}}
+ {:table_id table-id :limit 5})
+ _ (client/client :post 202 "agent/v1/execute"
+ {:request-options {:headers headers}}
+ {:query (:query construct-resp)})
+ ;; QueryExecution is saved asynchronously, so poll for it
+ query-execution (tu/poll-until 2000
+ (t2/select-one :model/QueryExecution :executor_id user-id))]
+ (is (= :agent (:context query-execution))))))))
+
(deftest get-metric-field-values-test
(with-agent-api-setup!
(ensure-fresh-field-values! (mt/id :orders :quantity))
@@ -395,6 +413,30 @@
(agent-client :rasta :post 404 "agent/v1/construct-query"
{:metric_id 999999})))))))
+(deftest construct-query-with-count-aggregation-test
+ (with-agent-api-setup!
+ (testing "Count aggregation without field_id produces a valid query"
+ (let [table-id (mt/id :orders)
+ response (agent-client :rasta :post 200 "agent/v1/construct-query"
+ {:table_id table-id
+ :aggregations [{:function "count"}]
+ :limit 10})]
+ (is (string? (:query response)))
+ (let [decoded (decode-query response)]
+ (is (= 1 (count (lib/aggregations decoded)))))))
+
+ (testing "Count aggregation with field_id still works"
+ (let [table-id (mt/id :orders)
+ table (agent-client :rasta :get 200 (str "agent/v1/table/" table-id))
+ field-id (-> table :fields first :field_id)
+ response (agent-client :rasta :post 200 "agent/v1/construct-query"
+ {:table_id table-id
+ :aggregations [{:function "count" :field_id field-id}]
+ :limit 10})]
+ (is (string? (:query response)))
+ (let [decoded (decode-query response)]
+ (is (= 1 (count (lib/aggregations decoded)))))))))
+
(deftest construct-query-with-filters-test
(with-agent-api-setup!
(testing "Constructs a query with filters"
@@ -411,6 +453,26 @@
(let [decoded (decode-query response)]
(is (seq (lib/filters decoded)) "Query should have filters"))))))
+(deftest get-table-details-with-measures-test
+ (with-agent-api-setup!
+ (let [measure-def (-> (lib/query (mt/metadata-provider)
+ (lib.metadata/table (mt/metadata-provider) (mt/id :orders)))
+ (lib/aggregate (lib/sum (lib.metadata/field (mt/metadata-provider) (mt/id :orders :total)))))]
+ (mt/with-temp [:model/Measure {measure-id :id} {:name "Total Revenue"
+ :table_id (mt/id :orders)
+ :definition measure-def}]
+ (testing "with-measures=false (default) does not include measures"
+ (let [table (agent-client :rasta :get 200 (str "agent/v1/table/" (mt/id :orders)))]
+ (is (nil? (:measures table)))))
+
+ (testing "with-measures=true includes measures for the table"
+ (let [table (agent-client :rasta :get 200
+ (str "agent/v1/table/" (mt/id :orders) "?with-measures=true"))]
+ (is (sequential? (:measures table)))
+ (is (=? [{:id measure-id
+ :name "Total Revenue"}]
+ (:measures table)))))))))
+
(deftest search-finds-metrics-test
(with-agent-api-setup!
(binding [search.ingestion/*force-sync* true]
diff --git a/enterprise/backend/test/metabase_enterprise/metabot_v3/tools/api_test.clj b/enterprise/backend/test/metabase_enterprise/metabot_v3/tools/api_test.clj
index 81b4dd4793c..d9e5f07bb82 100644
--- a/enterprise/backend/test/metabase_enterprise/metabot_v3/tools/api_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/metabot_v3/tools/api_test.clj
@@ -198,7 +198,7 @@
:query-id output
:query {}
:result-columns []}})]
- (let [filters [{:field_id "c2-7", :operation "number-greater-than", :value 50}
+ (let [filters [{:field_id "c2-7", :operation "greater-than", :value 50}
{:field_id "c2-3", :operation "equals", :values ["3" "4"]}
{:field_id "c2-5", :operation "not-equals", :values [3 4]}
{:field_id "c2-6", :operation "month-equals", :values [4 5 9]}
@@ -235,7 +235,7 @@
:type :metric}]
(mt/with-temp [:model/Card {metric-id :id} metric-data]
(let [fid #(format "c%d-%d" metric-id %)
- filters [{:field_id (fid 0), :operation "number-greater-than", :value 50} ; ID
+ filters [{:field_id (fid 0), :operation "greater-than", :value 50} ; ID
{:field_id (fid 2), :operation "equals", :values ["3" "4"]} ; Title
{:field_id (fid 6), :operation "not-equals", :values [3 4]} ; Rating
{:field_id (fid 7), :operation "month-equals", :values [4 5 9]} ; Created At
@@ -308,7 +308,7 @@
:result-columns []}})]
(let [fields [{:field_id "c2-8", :bucket "year-of-era"}
{:field_id "c2-9"}]
- filters [{:field_id "c2-7", :operation "number-greater-than", :value 50}
+ filters [{:field_id "c2-7", :operation "greater-than", :value 50}
{:field_id "c2-3", :operation "equals", :values ["3" "4"]}
{:field_id "c2-5", :operation "not-equals", :values [3 4]}
{:field_id "c2-6", :operation "month-equals", :values [4 5 9]}
@@ -350,7 +350,7 @@
(swap! tool-requests conj arguments)
{:structured-output output})]
(let [fields []
- filters [{:field_id "c2-7", :operation "number-greater-than", :value 50}]
+ filters [{:field_id "c2-7", :operation "greater-than", :value 50}]
response (mt/user-http-request :rasta :post 200 "ee/metabot-tools/query-model"
{:request-options {:headers {"x-metabase-session" ai-token}}}
{:arguments {:model_id 1
diff --git a/src/metabase/lib/schema/info.cljc b/src/metabase/lib/schema/info.cljc
index 5ad54586bf5..0e9a99c346e 100644
--- a/src/metabase/lib/schema/info.cljc
+++ b/src/metabase/lib/schema/info.cljc
@@ -15,6 +15,7 @@
{:decode/normalize identity}
:action
:ad-hoc
+ :agent
:cache-refresh
:collection
:map-tiles