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
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.cljindex 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.cljindex 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.cljindex 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.cljindex 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-transformerdiff --git a/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/util.clj b/enterprise/backend/src/metabase_enterprise/metabot_v3/tools/util.cljindex 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.cljindex 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"]})))))))))