Skip to content

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

Semantic layer agent API endpoints (#68260)

Noah Moss6b330140ffdb
diff --git a/enterprise/backend/src/metabase_enterprise/api_routes/routes.clj b/enterprise/backend/src/metabase_enterprise/api_routes/routes.clj
index 94de4477478..6ff938fac84 100644
--- a/enterprise/backend/src/metabase_enterprise/api_routes/routes.clj
+++ b/enterprise/backend/src/metabase_enterprise/api_routes/routes.clj
@@ -51,6 +51,7 @@
(def ^:private required-feature->message
{:advanced-permissions (deferred-tru "Advanced Permissions")
+ :agent-api (deferred-tru "Agent API")
:ai-sql-fixer (deferred-tru "AI SQL Fixer")
:ai-sql-generation (deferred-tru "AI SQL Generation")
:ai-entity-analysis (deferred-tru "AI Entity Analysis")
@@ -89,7 +90,7 @@
`/ee/<feature>/`).
TODO -- Please fix them! See #22687"
- {"/agent" (premium-handler metabase-enterprise.metabot-v3.agent-api.api/routes :metabot-v3)
+ {"/agent" (premium-handler metabase-enterprise.metabot-v3.agent-api.api/routes :agent-api)
"/moderation-review" metabase-enterprise.content-verification.api.routes/routes
"/mt" metabase-enterprise.sandbox.api.routes/sandbox-routes
"/table" metabase-enterprise.sandbox.api.routes/sandbox-table-routes})
diff --git a/enterprise/backend/src/metabase_enterprise/metabot_v3/agent_api/api.clj b/enterprise/backend/src/metabase_enterprise/metabot_v3/agent_api/api.clj
index 8b2bf026baa..4bace99f2dd 100644
--- a/enterprise/backend/src/metabase_enterprise/metabot_v3/agent_api/api.clj
+++ b/enterprise/backend/src/metabase_enterprise/metabot_v3/agent_api/api.clj
@@ -3,13 +3,169 @@
Endpoints are versioned (e.g., /v1/search) and use standard HTTP semantics."
(:require
[clojure.string :as str]
+ [malli.core :as mc]
+ [metabase-enterprise.metabot-v3.tools.api :as tools.api]
+ [metabase-enterprise.metabot-v3.tools.deftool :as deftool]
+ [metabase-enterprise.metabot-v3.tools.entity-details :as entity-details]
+ [metabase-enterprise.metabot-v3.tools.field-stats :as field-stats]
+ [metabase-enterprise.metabot-v3.tools.filters :as metabot-filters]
+ [metabase-enterprise.metabot-v3.tools.search :as metabot-search]
+ [metabase-enterprise.metabot-v3.util :as metabot-v3.u]
+ [metabase.api.common :as api]
[metabase.api.macros :as api.macros]
[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]
[metabase.util :as u]
+ [metabase.util.json :as json]
+ [metabase.util.malli.registry :as mr]
+ [metabase.util.malli.schema :as ms]
[toucan2.core :as t2]))
+;;; ---------------------------------------------------- Helpers ------------------------------------------------------
+
+(defn- check-tool-result
+ "Extract :structured-output from a tool result, or throw 404 with the error message.
+ Tool functions return {:structured-output ...} on success, {:output \"error\"} on failure."
+ [{:keys [structured-output output]}]
+ (or structured-output
+ (api/check false [404 (or output "Not found.")])))
+
+;;; --------------------------------------------------- Schemas ------------------------------------------------------
+
+;; Response schemas for the Agent API.
+;; - Use snake_case keys in schema definitions (JSON convention)
+;; - Use :encode/api transformers to convert kebab-case data from internal functions
+;; - Convert keyword enum values (like :table, :metric) to strings for JSON
+
+(mr/def ::field-type
+ "A data type for a field derived from Metabase's type hierarchy."
+ [:enum :boolean :date :datetime :time :number :string])
+
+(mr/def ::field
+ "A field from a table or metric. The field_id format is '<prefix><entity-id>-<field-index>' where prefix indicates the source (t=table, c=metric) and index is the position in the entity's fields."
+ [:map {:encode/api #(update-keys % metabot-v3.u/safe->snake_case_en)}
+ [:field_id :string]
+ [:name :string]
+ [:type {:optional true} [:maybe ::field-type]]
+ [:description {:optional true} [:maybe :string]]
+ [:database_type {:optional true} [:maybe :string]]
+ [:semantic_type {:optional true} [:maybe :string]]
+ [:field_values {:optional true} [:maybe [:sequential :any]]]])
+
+(mr/def ::entity-type
+ "The type of queryable entity."
+ [:enum :table :metric])
+
+(mr/def ::metric-summary
+ "Summary of a metric associated with a table. Includes the field_id of the default time dimension for temporal breakouts."
+ [:map {:encode/api #(update-keys % metabot-v3.u/safe->snake_case_en)}
+ [:id :int]
+ [:type [:= :metric]]
+ [:name :string]
+ [:description {:optional true} [:maybe :string]]
+ [:default_time_dimension_field_id {:optional true} [:maybe :string]]])
+
+(mr/def ::segment
+ "A predefined filter condition that can be applied to queries via the segment_id in filters."
+ [: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)}
+ [:id :int]
+ [:type [:= :table]]
+ [:name :string]
+ [:display_name {:optional true} [:maybe :string]]
+ [:database_id {:optional true} [:maybe :int]]
+ [:database_engine {:optional true} [:maybe :keyword]]
+ [:database_schema {:optional true} [:maybe :string]]
+ [:description {:optional true} [:maybe :string]]
+ [:fields {:optional true} [:maybe [:sequential ::field]]]
+ [:related_by {:optional true} [:maybe :string]]])
+
+(mr/def ::table
+ "Full details of a table including its fields, related tables, metrics, and segments."
+ [:map {:encode/api #(update-keys % metabot-v3.u/safe->snake_case_en)}
+ [:id :int]
+ [:type ::entity-type]
+ [:name :string]
+ [:display_name :string]
+ [:database_id :int]
+ [:database_engine :keyword]
+ [: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]]]
+ [:segments {:optional true} [:maybe [:sequential ::segment]]]])
+
+(mr/def ::metric
+ "A metric with its queryable dimensions and segments. The default_time_dimension_field_id is the field_id of the recommended time dimension for temporal breakouts."
+ [:map {:encode/api #(update-keys % metabot-v3.u/safe->snake_case_en)}
+ [:id :int]
+ [:type [:= :metric]]
+ [:name :string]
+ [:description {:optional true} [:maybe :string]]
+ [:default_time_dimension_field_id {:optional true} [:maybe :string]]
+ [:verified {:optional true} [:maybe :boolean]]
+ [:queryable_dimensions {:optional true} [:maybe [:sequential ::field]]]
+ [:segments {:optional true} [:maybe [:sequential ::segment]]]])
+
+(mr/def ::statistics
+ "Statistical summary of a field's values computed during database sync. Includes counts, percentages, numeric summaries (min/max/avg/quartiles/sd), and date ranges."
+ [:map {:encode/api #(update-keys % metabot-v3.u/safe->snake_case_en)}
+ [:distinct_count {:optional true} [:maybe :int]]
+ [:percent_null {:optional true} [:maybe number?]]
+ [:min {:optional true} [:maybe number?]]
+ [:max {:optional true} [:maybe number?]]
+ [:avg {:optional true} [:maybe number?]]
+ [:q1 {:optional true} [:maybe number?]]
+ [:q3 {:optional true} [:maybe number?]]
+ [:sd {:optional true} [:maybe number?]]
+ [:percent_json {:optional true} [:maybe number?]]
+ [:percent_url {:optional true} [:maybe number?]]
+ [:percent_email {:optional true} [:maybe number?]]
+ [:percent_state {:optional true} [:maybe number?]]
+ [:average_length {:optional true} [:maybe number?]]
+ [:earliest {:optional true} [:maybe :string]]
+ [:latest {:optional true} [:maybe :string]]])
+
+(mr/def ::field-values
+ "Statistics and sample values for a specific field."
+ [:map {:encode/api #(update-keys % metabot-v3.u/safe->snake_case_en)}
+ [:field_id {:optional true} [:maybe :string]]
+ [:statistics {:optional true} [:maybe ::statistics]]
+ [:values {:optional true} [:maybe [:sequential :any]]]])
+
+(mr/def ::search-result-item
+ "A table or metric returned from search."
+ [:map {:encode/api #(update-keys % metabot-v3.u/safe->snake_case_en)}
+ [:id :int]
+ [:type [:enum "table" "metric"]]
+ [:name :string]
+ [:display_name {:optional true} [:maybe :string]]
+ [:description {:optional true} [:maybe :string]]
+ [:database_id {:optional true} [:maybe :int]]
+ [:database_schema {:optional true} [:maybe :string]]
+ [:verified {:optional true} [:maybe :boolean]]
+ [:updated_at {:optional true} [:maybe :any]]
+ [:created_at {:optional true} [:maybe :any]]])
+
+(mr/def ::search-response
+ "Search results containing tables and metrics matching the query."
+ [:map {:encode/api #(update-keys % metabot-v3.u/safe->snake_case_en)}
+ [:data [:sequential ::search-result-item]]
+ [:total_count :int]])
+
;;; --------------------------------------------------- Endpoints ----------------------------------------------------
(api.macros/defendpoint :get "/v1/ping" :- [:map [:message :string]]
@@ -17,6 +173,204 @@
[]
{:message "pong"})
+(api.macros/defendpoint :get "/v1/table/:id" :- ::table
+ "Get details for a table by ID."
+ [{:keys [id]} :- [:map [:id ms/PositiveInt]]
+ {:keys [with-fields with-field-values with-related-tables with-metrics with-measures with-segments]
+ :or {with-fields true, with-field-values true, with-related-tables true,
+ with-metrics true, with-measures false, with-segments false}}
+ :- [:map
+ [:with-field-values {:optional true} [:maybe :boolean]]
+ [:with-fields {:optional true} [:maybe :boolean]]
+ [:with-related-tables {:optional true} [:maybe :boolean]]
+ [:with-metrics {:optional true} [:maybe :boolean]]
+ [:with-measures {:optional true} [:maybe :boolean]]
+ [:with-segments {:optional true} [:maybe :boolean]]]]
+ (check-tool-result
+ (entity-details/get-table-details
+ {:table-id id
+ :with-fields? with-fields
+ :with-field-values? with-field-values
+ :with-related-tables? with-related-tables
+ :with-metrics? with-metrics
+ :with-measures? with-measures
+ :with-segments? with-segments})))
+
+(api.macros/defendpoint :get "/v1/table/:id/field/:field-id/values" :- ::field-values
+ "Get statistics and sample values for a table field."
+ [{:keys [id field-id]} :- [:map
+ [:id ms/PositiveInt]
+ [:field-id ms/NonBlankString]]]
+ (check-tool-result
+ (field-stats/field-values
+ {:entity-type "table"
+ :entity-id id
+ :field-id field-id
+ :limit (request/limit)})))
+
+(api.macros/defendpoint :get "/v1/metric/:id" :- ::metric
+ "Get details for a metric by ID."
+ [{:keys [id]} :- [:map [:id ms/PositiveInt]]
+ {:keys [with-default-temporal-breakout with-field-values with-queryable-dimensions with-segments]
+ :or {with-default-temporal-breakout true, with-field-values true,
+ with-queryable-dimensions true, with-segments false}}
+ :- [:map
+ [:with-default-temporal-breakout {:optional true} [:maybe :boolean]]
+ [:with-field-values {:optional true} [:maybe :boolean]]
+ [:with-queryable-dimensions {:optional true} [:maybe :boolean]]
+ [:with-segments {:optional true} [:maybe :boolean]]]]
+ (check-tool-result
+ (entity-details/get-metric-details
+ {:metric-id id
+ :with-default-temporal-breakout? with-default-temporal-breakout
+ :with-field-values? with-field-values
+ :with-queryable-dimensions? with-queryable-dimensions
+ :with-segments? with-segments})))
+
+(api.macros/defendpoint :get "/v1/metric/:id/field/:field-id/values" :- ::field-values
+ "Get statistics and sample values for a metric field."
+ [{:keys [id field-id]} :- [:map
+ [:id ms/PositiveInt]
+ [:field-id ms/NonBlankString]]]
+ (check-tool-result
+ (field-stats/field-values
+ {:entity-type "metric"
+ :entity-id id
+ :field-id field-id
+ :limit (request/limit)})))
+
+(api.macros/defendpoint :post "/v1/search" :- ::search-response
+ "Search for tables and metrics.
+
+ Supports both term-based and semantic search queries. Results are ranked using
+ Reciprocal Rank Fusion when both query types are provided."
+ [_route-params
+ _query-params
+ {term-queries :term_queries
+ semantic-queries :semantic_queries}
+ :- [:map
+ [:term_queries {:optional true} [:maybe [:sequential ms/NonBlankString]]]
+ [:semantic_queries {:optional true} [:maybe [:sequential ms/NonBlankString]]]]]
+ (let [results (metabot-search/search
+ {:term-queries (or term-queries [])
+ :semantic-queries (or semantic-queries [])
+ :entity-types ["table" "metric"]
+ :limit (or (request/limit) 50)})]
+ {:data results
+ :total_count (count results)}))
+
+;;; ------------------------------------------------ Construct Query -------------------------------------------------
+
+;; Request schemas for the Agent API.
+;; These use snake_case keys for validation and OpenAPI generation,
+;; with :encode/tool-api-request transformers for converting to the internal format.
+
+(mr/def ::construct-query-table-request
+ "Request schema for constructing a query from a table.
+
+ Query components:
+ - filters: Filter conditions to apply
+ - fields: Specific fields to select (omit for all fields)
+ - aggregations: Aggregation functions (sum, count, avg, etc.). Use sort_order on the aggregation to order by it.
+ - group_by: Fields to group by, with optional temporal granularity
+ - order_by: Order by regular fields only. To order by an aggregation result, use sort_order on the aggregation instead.
+ - limit: Maximum rows to return"
+ [:and
+ [:map
+ [:table_id ms/PositiveInt]
+ [:filters {:optional true} [:maybe [:sequential ::tools.api/filter]]]
+ [:fields {:optional true} [:maybe [:sequential ::tools.api/field]]]
+ [:aggregations {:optional true} [:maybe [:sequential ::tools.api/aggregation]]]
+ [:group_by {:optional true} [:maybe [:sequential ::tools.api/group-by]]]
+ [:order_by {:optional true
+ :description "Order by regular fields only. To order by aggregation results, use sort_order on the aggregation."}
+ [:maybe [:sequential ::tools.api/order-by]]]
+ [:limit {:optional true} [:maybe ms/PositiveInt]]]
+ [:map {:encode/tool-api-request #(update-keys % metabot-v3.u/safe->kebab-case-en)}]])
+
+(mr/def ::construct-query-metric-request
+ "Request schema for constructing a query from a metric.
+ Only supports filters and group_by (aggregation is defined by the metric)."
+ [:and
+ [:map
+ [:metric_id ms/PositiveInt]
+ [:filters {:optional true} [:maybe [:sequential ::tools.api/filter]]]
+ [:group_by {:optional true} [:maybe [:sequential ::tools.api/group-by]]]]
+ [:map {:encode/tool-api-request #(update-keys % metabot-v3.u/safe->kebab-case-en)}]])
+
+(mr/def ::construct-query-request
+ "Request schema for /v1/construct-query. Accepts either table_id or metric_id."
+ [:or ::construct-query-table-request ::construct-query-metric-request])
+
+(mr/def ::construct-query-response
+ "Response containing a base64-encoded MBQL query for use with /v1/execute."
+ [:map
+ [:query ms/NonBlankString]])
+
+(defn- construct-table-query
+ "Build a query from a table using the provided query components."
+ [body]
+ (let [args (mc/encode ::construct-query-table-request body deftool/request-transformer)
+ data (check-tool-result (metabot-filters/query-datasource args))]
+ {:query (-> (:query data)
+ json/encode
+ u/encode-base64)}))
+
+(defn- construct-metric-query
+ "Build a query from a metric using filters and group_by."
+ [body]
+ (let [args (mc/encode ::construct-query-metric-request body deftool/request-transformer)
+ data (check-tool-result (metabot-filters/query-metric args))]
+ {:query (-> (:query data)
+ json/encode
+ u/encode-base64)}))
+
+(api.macros/defendpoint :post "/v1/construct-query" :- ::construct-query-response
+ "Construct an MBQL query from a table or metric.
+
+ Returns a base64-encoded MBQL query that can be used with the query API.
+
+ For tables, supports: filters, fields, aggregations, group_by, order_by, limit.
+ For metrics, supports: filters, group_by (aggregation is defined by the metric)."
+ [_route-params
+ _query-params
+ body :- ::construct-query-request]
+ (if (:table_id body)
+ (construct-table-query body)
+ (construct-metric-query body)))
+
+;;; ------------------------------------------------- Execute Query --------------------------------------------------
+
+(mr/def ::execute-query-request
+ "Request schema for /v1/execute. Accepts a base64-encoded MBQL query."
+ [:map
+ [:query ms/NonBlankString]])
+
+(api.macros/defendpoint :post "/v1/execute"
+ :- (streaming-response/streaming-response-schema ::qp.schema/query-result)
+ "Execute an MBQL query and return results.
+
+ Accepts a base64-encoded MBQL query (as returned by /v1/construct-query) and executes it,
+ returning results with column metadata.
+
+ Response format:
+ - On success: {:data {:cols [...] :rows [...]} :row_count N :status :completed :running_time M}
+ - On failure: {:status :failed :error \"message\" ...}
+
+ Standard userspace query limits are enforced (2000 rows for simple queries, 10000 for aggregated)."
+ [_route-params
+ _query-params
+ {encoded-query :query} :- ::execute-query-request]
+ (let [query (-> encoded-query
+ u/decode-base64
+ json/decode+kw)]
+ (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)
+ rff))))
+
;;; ------------------------------------------------- Authentication -------------------------------------------------
;;
;; The Agent API supports two authentication modes:
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 c6f792b7b1f..ee0c19db8d5 100644
--- a/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/api.clj
+++ b/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/api.clj
@@ -42,9 +42,12 @@
nil)))
;;; ------------------------------------------------ Shared Schemas -------------------------------------------------
+;; NOTE: Some of these schemas are duplicated with small differences in the Agent API
+;; (metabase-enterprise.metabot-v3.agent-api.api). If you update schemas here, check if the
+;; corresponding Agent API schemas need updating too.
(mr/def ::bucket
- (into [:enum {:error/message "Valid bucket"
+ (into [:enum {:error/message "Valid bucket"
:encode/tool-api-request keyword}]
(map name)
lib.schema.temporal-bucketing/ordered-datetime-bucketing-units))
@@ -189,7 +192,12 @@
[:map {:encode/tool-api-request #(update-keys % metabot-v3.u/safe->kebab-case-en)}]])
(mr/def ::field-aggregation
- "Aggregation using a field and function."
+ "Aggregation using a field and function.
+
+ - 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."
[:and
[:map
[:field_id :string]
@@ -218,6 +226,12 @@
[:bucket {:optional true} ::bucket]]
[:map {:encode/tool-api-request #(update-keys % metabot-v3.u/safe->kebab-case-en)}]])
+(mr/def ::order-by
+ "Order by item specifying a field and sort direction."
+ [:map
+ [:field ::field]
+ [:direction [:enum {:encode/tool-api-request keyword} "asc" "desc"]]])
+
(mr/def ::count
[:and
:int
@@ -938,9 +952,7 @@
[:filters {:optional true} [:maybe [:sequential ::filter]]]
[:aggregations {:optional true} [:maybe [:sequential ::aggregation]]]
[:group_by {:optional true} [:maybe [:sequential ::group-by]]]
- [:order_by {:optional true} [:maybe [:sequential [:map
- [:field ::field]
- [:direction [:enum {:encode/tool-api-request keyword} "asc" "desc"]]]]]]
+ [:order_by {:optional true} [:maybe [:sequential ::order-by]]]
[:limit {:optional true} [:maybe :int]]]
[:map {:encode/tool-api-request #(update-keys % metabot-v3.u/safe->kebab-case-en)}]])
@@ -960,9 +972,7 @@
[:filters {:optional true} [:maybe [:sequential ::filter]]]
[:aggregations {:optional true} [:maybe [:sequential ::aggregation]]]
[:group_by {:optional true} [:maybe [:sequential ::group-by]]]
- [:order_by {:optional true} [:maybe [:sequential [:map
- [:field ::field]
- [:direction [:enum {:encode/tool-api-request keyword} "asc" "desc"]]]]]]
+ [:order_by {:optional true} [:maybe [:sequential ::order-by]]]
[:limit {:optional true} [:maybe :int]]]
[:fn {:error/message "Exactly one of table_id and model_id required"}
#(= (count (select-keys % [:table_id :model_id])) 1)]
diff --git a/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/deftool.clj b/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/deftool.clj
index f6d8ee53800..571d289daf1 100644
--- a/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/deftool.clj
+++ b/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/deftool.clj
@@ -16,8 +16,9 @@
[:conversation_id ms/UUIDString]
[:profile_id {:optional true} [:maybe :string]]])
-(def ^:private request-transformer
- "Transformer for encoding tool request arguments (snake_case -> kebab-case)."
+(def request-transformer
+ "Transformer for encoding tool request arguments (snake_case -> kebab-case).
+ Converts snake_case keys to kebab-case and string enum values to keywords."
(mtx/transformer {:name :tool-api-request}))
(def ^:private response-transformer
diff --git a/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/util.clj b/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/util.clj
index ef421a7b495..fc740dfc6e1 100644
--- a/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/util.clj
+++ b/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/util.clj
@@ -86,19 +86,23 @@
- model-id is the numeric ID (for tables/cards) or nano-id (for queries)
- field-index is the index within that model's visible columns
- Returns a map with :model-tag, :model-id, and :field-index keys, or nil if the format is invalid.
+ Returns a map with :model-tag, :model-id, and :field-index keys, or nil if the format is invalid
+ or the input is not a string.
Examples:
(parse-field-id \"t154-1\") => {:model-tag \"t\", :model-id 154, :field-index 1}
- (parse-field-id \"qpuL95JSvym3k23W1UUuog-0\") => {:model-tag \"q\", :model-id \"puL95JSvym3k23W1UUuog\", :field-index 0}"
+ (parse-field-id \"qpuL95JSvym3k23W1UUuog-0\") => {:model-tag \"q\", :model-id \"puL95JSvym3k23W1UUuog\", :field-index 0}
+ (parse-field-id nil) => nil
+ (parse-field-id \"invalid\") => nil"
[field-id]
- (when-let [[_ model-tag model-id field-index] (re-matches #"^([tcq])(.+)-(\d+)$" field-id)]
- {:model-tag model-tag
- ;; For tables and cards, model-id should be numeric; for queries it's a nano-id string
- :model-id (if (= model-tag "q")
- model-id
- (parse-long model-id))
- :field-index (parse-long field-index)}))
+ (when (string? field-id)
+ (when-let [[_ model-tag model-id field-index] (re-matches #"^([tcq])(.+)-(\d+)$" field-id)]
+ {:model-tag model-tag
+ ;; For tables and cards, model-id should be numeric; for queries it's a nano-id string
+ :model-id (if (= model-tag "q")
+ model-id
+ (parse-long model-id))
+ :field-index (parse-long field-index)})))
(defn resolve-column
"Resolve the reference `field-id` in filter `item` by finding the column in `columns` specified by `field-id`.
diff --git a/enterprise/backend/test/metabase_enterprise/metabot_v3/agent_api/api_test.clj b/enterprise/backend/test/metabase_enterprise/metabot_v3/agent_api/api_test.clj
index af737206a32..e5c25e75b43 100644
--- a/enterprise/backend/test/metabase_enterprise/metabot_v3/agent_api/api_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/metabot_v3/agent_api/api_test.clj
@@ -4,11 +4,22 @@
[clojure.test :refer :all]
[environ.core :as env]
[java-time.api :as t]
+ [medley.core :as m]
+ [metabase-enterprise.metabot-v3.settings] ; for setting definitions
+ [metabase-enterprise.metabot-v3.tools.util :as metabot-v3.tools.u]
[metabase-enterprise.sso.test-setup :as sso.test-setup]
+ [metabase.lib.core :as lib]
+ [metabase.lib.metadata :as lib.metadata]
+ [metabase.lib.normalize :as lib.normalize]
+ [metabase.search.ingestion :as search.ingestion]
+ [metabase.search.test-util :as search.tu]
[metabase.session.models.session :as session.models]
[metabase.test :as mt]
[metabase.test.fixtures :as fixtures]
[metabase.test.http-client :as client]
+ [metabase.util :as u]
+ [metabase.util.json :as json]
+ [metabase.warehouse-schema.models.field-values :as field-values]
[toucan2.core :as t2]))
(set! *warn-on-reflection* true)
@@ -29,7 +40,7 @@
Reuses the SSO JWT test setup which handles premium features and settings correctly."
[& body]
`(sso.test-setup/with-jwt-default-setup!
- (mt/with-additional-premium-features #{:metabot-v3}
+ (mt/with-additional-premium-features #{:agent-api :metabot-v3}
~@body)))
(defn- auth-headers
@@ -39,6 +50,24 @@
([email]
{"authorization" (str "Bearer " (sign-jwt {:email email}))}))
+(defn- agent-client
+ "Helper for making authenticated agent API requests, similar to mt/user-http-request.
+ Takes a test user keyword (e.g. :rasta, :crowberto), method, expected status, endpoint,
+ and optional body for POST/PUT requests."
+ [user method expected-status endpoint & [body]]
+ (let [email (:username (mt/user->credentials user))
+ headers (auth-headers email)]
+ (apply client/client method expected-status endpoint
+ {:request-options {:headers headers}}
+ (when body [body]))))
+
+(defn- orders-count-query
+ "Create a simple count query on the orders table using lib functions."
+ []
+ (-> (lib/query (mt/metadata-provider)
+ (lib.metadata/table (mt/metadata-provider) (mt/id :orders)))
+ (lib/aggregate (lib/count))))
+
(deftest agent-api-jwt-auth-test
(with-agent-api-setup!
(testing "Valid JWT with email claim succeeds"
@@ -92,27 +121,26 @@
{:request-options {:headers (auth-headers "[email protected]")}}))))))
(deftest agent-api-session-token-auth-test
- (mt/test-helpers-set-global-values!
- (mt/with-additional-premium-features #{:metabot-v3}
- (testing "Session tokens via X-Metabase-Session header authenticate successfully"
- (let [session-key (session.models/generate-session-key)
- _ (t2/insert! :model/Session
- {:id (session.models/generate-session-id)
- :user_id (mt/user->id :rasta)
- :session_key session-key})
- response (client/client :get 200 "agent/v1/ping"
- {:request-options {:headers {"x-metabase-session" session-key}}})]
- (is (= {:message "pong"} response))))
-
- (testing "Invalid session token returns 401"
- (let [fake-session-key (str (random-uuid))
- response (client/client :get 401 "agent/v1/ping"
- {:request-options {:headers {"x-metabase-session" fake-session-key}}})]
- ;; Invalid session means standard middleware doesn't set metabase-user-id,
- ;; so our middleware sees no auth and returns missing_authorization
- (is (= {:error "missing_authorization"
- :message "Authentication required. Use X-Metabase-Session header or Authorization: Bearer <jwt>."}
- response)))))))
+ (with-agent-api-setup!
+ (testing "Session tokens via X-Metabase-Session header authenticate successfully"
+ (let [session-key (session.models/generate-session-key)
+ _ (t2/insert! :model/Session
+ {:id (session.models/generate-session-id)
+ :user_id (mt/user->id :rasta)
+ :session_key session-key})
+ response (client/client :get 200 "agent/v1/ping"
+ {:request-options {:headers {"x-metabase-session" session-key}}})]
+ (is (= {:message "pong"} response))))
+
+ (testing "Invalid session token returns 401"
+ (let [fake-session-key (str (random-uuid))
+ response (client/client :get 401 "agent/v1/ping"
+ {:request-options {:headers {"x-metabase-session" fake-session-key}}})]
+ ;; Invalid session means standard middleware doesn't set metabase-user-id,
+ ;; so our middleware sees no auth and returns missing_authorization
+ (is (= {:error "missing_authorization"
+ :message "Authentication required. Use X-Metabase-Session header or Authorization: Bearer <jwt>."}
+ response))))))
(deftest agent-api-inactive-user-test
(with-agent-api-setup!
@@ -125,17 +153,264 @@
(deftest agent-api-expired-session-test
(testing "Expired sessions are rejected by the standard session middleware"
- (mt/test-helpers-set-global-values!
- (mt/with-additional-premium-features #{:metabot-v3}
- ;; Set max-session-age to 1 minute for this test
- (with-redefs [env/env (assoc env/env :max-session-age "1")]
- (let [session-key (session.models/generate-session-key)
- old-time (t/minus (t/instant) (t/minutes 2))]
- (mt/with-temp [:model/Session _ {:user_id (mt/user->id :rasta)
- :session_key session-key
- :created_at old-time}]
- (testing "Session older than max-session-age is rejected"
- (is (= {:error "missing_authorization"
- :message "Authentication required. Use X-Metabase-Session header or Authorization: Bearer <jwt>."}
- (client/client :get 401 "agent/v1/ping"
- {:request-options {:headers {"x-metabase-session" session-key}}})))))))))))
+ (with-agent-api-setup!
+ ;; Set max-session-age to 1 minute for this test
+ (with-redefs [env/env (assoc env/env :max-session-age "1")]
+ (let [session-key (session.models/generate-session-key)
+ old-time (t/minus (t/instant) (t/minutes 2))]
+ (mt/with-temp [:model/Session _ {:user_id (mt/user->id :rasta)
+ :session_key session-key
+ :created_at old-time}]
+ (testing "Session older than max-session-age is rejected"
+ (is (= {:error "missing_authorization"
+ :message "Authentication required. Use X-Metabase-Session header or Authorization: Bearer <jwt>."}
+ (client/client :get 401 "agent/v1/ping"
+ {:request-options {:headers {"x-metabase-session" session-key}}}))))))))))
+
+(deftest agent-api-user-binding-test
+ (with-agent-api-setup!
+ (testing "User is correctly bound from JWT - permissions are enforced"
+ ;; Create a metric in a collection, then revoke non-admin access
+ (mt/with-temp [:model/Collection collection {:name "Private Collection"}
+ :model/Card metric {:name "Private Metric"
+ :type :metric
+ :collection_id (:id collection)
+ :database_id (mt/id)
+ :dataset_query (orders-count-query)}]
+ (mt/with-non-admin-groups-no-collection-perms collection
+ (testing "Admin user can access the metric"
+ (is (=? {:type "metric"
+ :id (:id metric)
+ :name "Private Metric"}
+ (agent-client :crowberto :get 200 (str "agent/v1/metric/" (:id metric))))))
+
+ (testing "Non-admin user cannot access the metric"
+ (is (= "You don't have permissions to do that."
+ (agent-client :rasta :get 403 (str "agent/v1/metric/" (:id metric)))))))))))
+
+(deftest get-table-details-test
+ (with-agent-api-setup!
+ (testing "Returns table details for valid table ID"
+ (let [table-id (mt/id :orders)]
+ (is (=? {:type "table"
+ :id table-id
+ :name "ORDERS"
+ :display_name "Orders"
+ :database_id (mt/id)
+ :fields sequential?
+ :related_tables sequential?}
+ (agent-client :rasta :get 200 (str "agent/v1/table/" table-id))))))
+
+ (testing "Returns 404 for non-existent table"
+ (is (= "Not found."
+ (agent-client :rasta :get 404 "agent/v1/table/999999"))))
+
+ (testing "Respects query parameters"
+ (let [table-id (mt/id :orders)]
+ (is (=? {:type "table"
+ :id table-id
+ :fields empty?}
+ (agent-client :rasta :get 200
+ (str "agent/v1/table/" table-id "?with-fields=false&with-related-tables=false"))))))))
+
+(deftest get-metric-details-test
+ (with-agent-api-setup!
+ (mt/with-temp [:model/Card metric {:name "Test Metric"
+ :type :metric
+ :database_id (mt/id)
+ :dataset_query (orders-count-query)}]
+ (testing "Returns metric details for valid metric ID"
+ (is (=? {:type "metric"
+ :id (:id metric)
+ :name "Test Metric"
+ :queryable_dimensions sequential?}
+ (agent-client :rasta :get 200 (str "agent/v1/metric/" (:id metric))))))
+
+ (testing "Respects query parameters"
+ (is (=? {:type "metric"
+ :id (:id metric)}
+ (agent-client :rasta :get 200
+ (str "agent/v1/metric/" (:id metric)
+ "?with-queryable-dimensions=false&with-field-values=false")))))
+
+ (testing "Returns 404 for non-existent metric"
+ (is (= "Not found."
+ (agent-client :rasta :get 404 "agent/v1/metric/999999")))))))
+
+(defn- ensure-fresh-field-values!
+ "Ensure field values exist for a field by deleting any existing ones and recreating them."
+ [field-id]
+ (t2/delete! :model/FieldValues :field_id field-id :type :full)
+ (field-values/get-or-create-full-field-values! (t2/select-one :model/Field :id field-id)))
+
+(defn- visible-field-id
+ "Find the field-id string for a field by display name within a table's visible columns."
+ [table-id field-display-name]
+ (let [mp (mt/metadata-provider)
+ query (lib/query mp (lib.metadata/table mp table-id))
+ field-prefix (metabot-v3.tools.u/table-field-id-prefix table-id)
+ visible-cols (lib/visible-columns query)]
+ (->> (keep-indexed (fn [i col]
+ (when (= (lib/display-name query col) field-display-name)
+ (str field-prefix i)))
+ visible-cols)
+ first)))
+
+(deftest get-table-field-values-test
+ (with-agent-api-setup!
+ ;; Ensure field values exist for the field we'll test
+ (ensure-fresh-field-values! (mt/id :people :state))
+
+ (testing "Returns field statistics and values for a table field"
+ (let [table-id (mt/id :people)
+ field-id (visible-field-id table-id "State")]
+ (is (some? field-id) "Should find the State field")
+ (is (=? {:statistics {:distinct_count 49}
+ :values sequential?}
+ (agent-client :crowberto :get 200
+ (format "agent/v1/table/%d/field/%s/values" table-id field-id))))))
+
+ (testing "Respects limit parameter"
+ (let [table-id (mt/id :people)
+ field-id (visible-field-id table-id "State")
+ result (agent-client :crowberto :get 200
+ (format "agent/v1/table/%d/field/%s/values?limit=5" table-id field-id))]
+ (is (= 5 (count (:values result))) "Should respect limit parameter")))
+
+ (testing "Returns 404 for non-existent table"
+ (is (= "Not found."
+ (agent-client :crowberto :get 404 "agent/v1/table/999999/field/t999999-0/values"))))))
+
+(deftest search-test
+ (with-agent-api-setup!
+ (binding [search.ingestion/*force-sync* true]
+ (search.tu/with-new-search-if-available-otherwise-legacy
+ (mt/with-temp [:model/Table _ {:name "AgentSearchTestTable"}]
+ (testing "Returns search results for term queries"
+ (is (=? {:data [{:type "table" :name "AgentSearchTestTable"}]
+ :total_count 1}
+ (agent-client :rasta :post 200 "agent/v1/search"
+ {:term_queries ["AgentSearchTestTable"]})))))))))
+
+(defn- decode-query
+ "Decode a base64-encoded query response to a Clojure map, then normalize it so lib functions work."
+ [response]
+ (-> response :query u/decode-base64 json/decode+kw lib.normalize/normalize))
+
+(deftest construct-query-test
+ (with-agent-api-setup!
+ (testing "Constructs a simple query from a table"
+ (let [table-id (mt/id :orders)
+ response (agent-client :rasta :post 200 "agent/v1/construct-query"
+ {:table_id table-id})]
+ (is (string? (:query response)) "Response should contain a query string")
+ (let [decoded (decode-query response)]
+ (is (= :mbql/query (lib/normalized-query-type decoded)))
+ (is (= (mt/id) (lib/database-id decoded)))
+ (is (= (mt/id :orders) (lib/source-table-id decoded))))))
+
+ (testing "Constructs a query with a limit"
+ (let [table-id (mt/id :orders)
+ response (agent-client :rasta :post 200 "agent/v1/construct-query"
+ {:table_id table-id
+ :limit 10})
+ decoded (decode-query response)]
+ (is (= 10 (lib/current-limit decoded)))))
+
+ (testing "Returns 404 for non-existent table"
+ (is (= "No table found with table_id 999999"
+ (agent-client :rasta :post 404 "agent/v1/construct-query"
+ {:table_id 999999}))))))
+
+(deftest execute-query-test
+ (with-agent-api-setup!
+ (testing "Executes a query and returns results with column metadata"
+ (let [table-id (mt/id :orders)
+ construct-resp (agent-client :rasta :post 200 "agent/v1/construct-query"
+ {:table_id table-id
+ :limit 5})
+ ;; Streaming response returns 202 (accepted) since it starts streaming before completion
+ execute-resp (agent-client :rasta :post 202 "agent/v1/execute"
+ {:query (:query construct-resp)})
+ cols (get-in execute-resp [:data :cols])
+ rows (get-in execute-resp [:data :rows])]
+ (testing "response structure"
+ (is (= "completed" (:status execute-resp)))
+ (is (= 5 (:row_count execute-resp)))
+ (is (sequential? cols))
+ (is (sequential? rows))
+ (is (= 5 (count rows))))
+ (testing "column metadata"
+ (is (seq cols) "Should have column metadata")
+ (is (every? :name cols) "Each column should have a name")
+ (is (every? :base_type cols) "Each column should have a base_type"))))))
+
+(deftest get-metric-field-values-test
+ (with-agent-api-setup!
+ (ensure-fresh-field-values! (mt/id :orders :quantity))
+ (mt/with-temp [:model/Card metric {:name "Test Metric"
+ :type :metric
+ :database_id (mt/id)
+ :dataset_query (orders-count-query)}]
+ (testing "Returns field statistics for a field that has statistics"
+ (let [metric-details (agent-client :rasta :get 200 (str "agent/v1/metric/" (:id metric)))
+ quantity-field (m/find-first #(= (:name %) "QUANTITY") (:queryable_dimensions metric-details))]
+ (is (some? quantity-field) "Quantity field should be in queryable_dimensions")
+ (when-let [field-id (:field_id quantity-field)]
+ (is (=? {:statistics map?
+ :values sequential?}
+ (agent-client :rasta :get 200
+ (format "agent/v1/metric/%d/field/%s/values" (:id metric) field-id)))))))
+
+ (testing "Returns 404 for non-existent metric"
+ (is (= "Not found."
+ (agent-client :rasta :get 404 "agent/v1/metric/999999/field/c999999-0/values")))))))
+
+(deftest construct-metric-query-test
+ (with-agent-api-setup!
+ (mt/with-temp [:model/Card metric {:name "Test Metric"
+ :type :metric
+ :database_id (mt/id)
+ :dataset_query (orders-count-query)}]
+ (testing "Constructs a query from a metric"
+ (let [response (agent-client :rasta :post 200 "agent/v1/construct-query"
+ {:metric_id (:id metric)})]
+ (is (string? (:query response)) "Response should contain a query string")
+ (let [decoded (decode-query response)]
+ (is (= :mbql/query (lib/normalized-query-type decoded)))
+ (is (= (mt/id) (lib/database-id decoded))))))
+
+ (testing "Returns 404 for non-existent metric"
+ (is (= "No metric found with metric_id 999999"
+ (agent-client :rasta :post 404 "agent/v1/construct-query"
+ {:metric_id 999999})))))))
+
+(deftest construct-query-with-filters-test
+ (with-agent-api-setup!
+ (testing "Constructs a query with filters"
+ (let [table-id (mt/id :orders)
+ ;; Get table details to find a valid field_id
+ 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
+ :filters [{:field_id field-id
+ :operation "is-not-null"}]
+ :limit 10})]
+ (is (string? (:query response)))
+ (let [decoded (decode-query response)]
+ (is (seq (lib/filters decoded)) "Query should have filters"))))))
+
+(deftest search-finds-metrics-test
+ (with-agent-api-setup!
+ (binding [search.ingestion/*force-sync* true]
+ (search.tu/with-new-search-if-available-otherwise-legacy
+ (mt/with-temp [:model/Card _metric {:name "AgentSearchTestMetric"
+ :type :metric
+ :database_id (mt/id)
+ :dataset_query (orders-count-query)}]
+ (testing "Returns metrics in search results"
+ (is (=? {:data [{:type "metric" :name "AgentSearchTestMetric"}]
+ :total_count 1}
+ (agent-client :rasta :post 200 "agent/v1/search"
+ {:term_queries ["AgentSearchTestMetric"]})))))))))