The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
Misc agent API improvements + llms-agent-api.txt (#68914)
Noah Moss3192d0161237
diff --git a/docs/agent-api/reference.md b/docs/agent-api/reference.mdnew file mode 100644index 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.cljindex 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-queryu/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.cljindex 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.cljindex 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.cljindex 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-querydiff --git a/enterprise/backend/test/metabase_enterprise/agent_api/api_test.clj b/enterprise/backend/test/metabase_enterprise/agent_api/api_test.cljindex 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.cljindex 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 1diff --git a/src/metabase/lib/schema/info.cljc b/src/metabase/lib/schema/info.cljcindex 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