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
Add endpoint for native query construction in expected format (#76717)
lbrdnkfe2715ef6b96
diff --git a/.clj-kondo/config/modules/config.edn b/.clj-kondo/config/modules/config.ednindex 7e12acd0841..6bed3024718 100644--- a/.clj-kondo/config/modules/config.edn+++ b/.clj-kondo/config/modules/config.edn@@ -180,6 +180,7 @@:model/Collection:model/Dashboard:model/DashboardCard+ :model/Database:model/Table:model/User}}diff --git a/src/metabase/agent_api/api.clj b/src/metabase/agent_api/api.cljindex 3b4db193e55..f419c849ad8 100644--- a/src/metabase/agent_api/api.clj+++ b/src/metabase/agent_api/api.clj@@ -306,6 +306,48 @@(cond-> {:query (-> query json/encode u/encode-base64)}prompt (assoc :prompt prompt))))+;;; --------------------------------------------- Construct Native Query ---------------------------------------------++(mr/def ::construct-native-query-request+ "Request body for /v1/construct-native-query: a target database and a raw SQL string."+ [:map {:closed true}+ [:database_id {:tool/description "Numeric id of the database to run the SQL against."}+ ms/PositiveInt]+ [:sql {:tool/description "The raw SQL query text."}+ ms/NonBlankString]])++(api.macros/defendpoint :post "/v1/construct-native-query" :- ::construct-query-response+ "Construct a native (raw SQL) query against a database.++ Wraps `sql` into a serialized native query and returns it base64-encoded — the same+ `{\"query\": <base64>}` shape as /v2/construct-query — so it can be saved as a question via+ /v1/question (the MCP layer swaps the base64 for a `query_handle`).++ This endpoint does NOT execute the SQL; to run native SQL ad hoc use /v1/execute-sql. The+ MBQL execution endpoints (/v1/execute, /v2/query) reject native queries by design, so a+ handle produced here is for saving, not for /v2/query execution."+ {:scope metabot/agent-sql-construct+ :tool {:name "construct_native_query"+ :description (str "Construct a native (raw SQL) query for the given database. Returns "+ "`{\"query_handle\": \"<uuid>\"}` to feed `create_question` and save it "+ "as a question. Use this ONLY for native SQL — for MBQL use "+ "`construct_query`. This does NOT run the SQL; to execute SQL ad hoc "+ "use `execute_sql`. Saving the resulting question requires native-query "+ "permission on the target database.")+ :annotations {:read-only? true :idempotent? true}}}+ [_route-params+ _query-params+ {:keys [database_id sql]} :- ::construct-native-query-request]+ ;; Construction does not run the query, but require the caller to at least be able to see the+ ;; target database so a bogus/inaccessible database_id fails here rather than at save time.+ (api/read-check :model/Database database_id)+ ;; Emit MBQL 5 (via `lib/native-query` + `prepare-for-serialization`, same as `construct_query`)+ (let [mp (lib-be/application-database-metadata-provider database_id)]+ {:query (-> (lib/native-query mp sql)+ lib/prepare-for-serialization+ json/encode+ u/encode-base64)}))+;;; ------------------------------------------------- Combined Query -------------------------------------------------(defn- generate-continuation-token@@ -762,16 +804,20 @@(api.macros/defendpoint :post "/v1/question" :- ::create-question-response"Save a previously constructed query as a named question (card).- The `query` parameter accepts a `query_handle` (UUID) returned by `construct_query`,- or a base64-encoded MBQL string. MCP callers should always use the handle.+ The `query` parameter accepts a `query_handle` (UUID) returned by `construct_query` (MBQL) or+ `construct_native_query` (native SQL), or a base64-encoded query string. MCP callers should+ always use the handle.Optionally specify display type, description, collection, and visualization settings.If `collection_id` is omitted the question is saved to the caller's personal collection.Pass an explicit `null` to save it to the root collection.- The response `collection_path` is the saved location."+ The response `collection_path` is the saved location.++ Saving a native (raw SQL) query requires native-query permission on the target database."{:scope metabot/agent-question-create:tool {:name "create_question":description (str "Save a query as a named question in Metabase. "- "Pass the `query_handle` returned by `construct_query`. "+ "Pass the `query_handle` returned by `construct_query` (MBQL) or "+ "`construct_native_query` (native SQL). ""Optionally set display type (table, bar, line, pie, etc.), ""description, and target collection. ""If you omit collection_id it's saved to the user's personal collection; "@@ -850,13 +896,15 @@"Update a saved question (card). Patch semantics - only fields that you pass are changed.Set `collection_id` to move the card to a different collection. Set `archived: true` to archive.- Pass `query` (a query_handle from construct_query, or a base64 MBQL string) to replace the underlying query."+ Pass `query` (a query_handle from construct_query or construct_native_query, or a base64 query+ string) to replace the underlying query. Replacing it with a native (raw SQL) query requires+ native-query permission on the target database."{:scope metabot/agent-question-update:tool {:name "update_question":description (str "Update a saved question (card). Patch semantics - only fields you pass are changed. ""To move a card to a different collection, set collection_id. ""To archive, set archived true. To replace the underlying query, pass query "- "(a query_handle from construct_query).")}}+ "(a query_handle from construct_query or construct_native_query).")}}[{:keys [id]} :- [:map [:id ms/PositiveInt]]_query-paramsbody :- ::update-question-request]diff --git a/src/metabase/mcp/README.md b/src/metabase/mcp/README.mdindex 4a6444a29ac..42b857474dc 100644--- a/src/metabase/mcp/README.md+++ b/src/metabase/mcp/README.md@@ -59,6 +59,7 @@ Access tokens are scoped to limit what tools a client can use:| `agent:query:construct` | `construct_query` || `agent:query` | `query` || `agent:query:execute` | `execute_query` |+| `agent:sql:construct` | `construct_native_query` || `agent:sql:execute` | `execute_sql` || `agent:question:create` | `create_question` || `agent:question:update` | `update_question` (also covers "move card to collection") |@@ -92,6 +93,7 @@ The MCP server exposes these tools, dynamically generated from the Agent API end| Tool | Description || ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || `construct_query` | Construct a query against a table or metric. Accepts the user's original `prompt` when available. Returns an opaque `query_handle` for use with `execute_query` or `visualize_query`. |+| `construct_native_query` | Construct a native (raw SQL) query for a database. Returns an opaque `query_handle` to feed `create_question` and save it. Does not execute the SQL; native handles are rejected by `execute_query`/`query` (use `execute_sql` to run raw SQL). || `query` | Query a table or metric directly. Supports pagination via continuation tokens. || `execute_query` | Execute a previously constructed query and return results with column metadata. || `execute_sql` | Execute a raw SQL query against a database. Requires the user to have native-query permission on the target database. Can be disabled instance-wide via the `mcp-execute-sql-enabled` setting. |@@ -100,8 +102,8 @@ The MCP server exposes these tools, dynamically generated from the Agent API end| Tool | Description || ------------------- | ----------------------------------------------------------------------------------------------------------------- |-| `create_question` | Save a query as a named question (card). Accepts a `query_handle` from `construct_query`. |-| `update_question` | Update a saved question. Patch semantics. Setting `collection_id` moves the card. Setting `archived` archives it. |+| `create_question` | Save a query as a named question (card). Accepts a `query_handle` from `construct_query` (MBQL) or `construct_native_query` (native SQL). Saving native requires native-query DB permission. |+| `update_question` | Update a saved question. Patch semantics. Setting `collection_id` moves the card. Setting `archived` archives it. Replacing the query accepts a `construct_query` or `construct_native_query` handle. || `create_dashboard` | Create a new dashboard, optionally populated with saved questions (auto-positioned on the grid). || `update_dashboard` | Update a dashboard's metadata (name, description, collection, archived). || `create_collection` | Create a new collection. Optionally nested under a `parent_collection_id`. |diff --git a/src/metabase/mcp/tools.clj b/src/metabase/mcp/tools.cljindex 1331d78a3b7..7e61432e03d 100644--- a/src/metabase/mcp/tools.clj+++ b/src/metabase/mcp/tools.clj@@ -120,8 +120,11 @@"execute_query" execute-query-mcp-input-malli})(def ^:private mcp-output-overrides- "tool-name → Malli schema. Replaces the manifest's derived `:outputSchema`."- {"construct_query" construct-query-mcp-output-malli})+ "tool-name → Malli schema. Replaces the manifest's derived `:outputSchema`.+ Both construct tools emit `{:query_handle}` via the body transform (see+ [[tools-storing-query-handle]]), so they share the same output schema."+ {"construct_query" construct-query-mcp-output-malli+ "construct_native_query" construct-query-mcp-output-malli})(defn- override->input-json-schema [malli tool-name](tools-manifest/assert-optional-fields-nullable! malli tool-name)@@ -301,7 +304,7 @@(mr/validator construct-query-mcp-output-malli))(defn- make-store-construct-query-result- "Build a body-transform fn for construct_query.+ "Build a body-transform fn for the construct tools (`construct_query`, `construct_native_query`).The fn stores the base64 payload server-side under the calling user (with the current MCP session idrecorded for cleanup) and returns {:query_handle uuid} instead of {:query base64}, so the LLM carriesa short opaque UUID rather than the full base64 string.@@ -329,6 +332,11 @@(def ^:private tools-accepting-query-handle#{"execute_query" "query" "create_question" "update_question"})+;; Tools whose 200 body is `{:query base64}` and gets stored as a handle, returning `{:query_handle}`.+;; `construct_query` (MBQL) and `construct_native_query` (native SQL) both follow this contract.+(def ^:private tools-storing-query-handle+ #{"construct_query" "construct_native_query"})+;;; ------------------------------------------------- Tool Dispatch -------------------------------------------------(defn- text-content@@ -446,7 +454,7 @@[resolved-pathremaining-args] (interpolate-path path arguments)api-path (strip-api-prefix resolved-path)- body-transform-fn (when (= tool-name "construct_query")+ body-transform-fn (when (tools-storing-query-handle tool-name)(make-store-construct-query-resultsession-id api/*current-user-id*))](invoke-agent-api method api-path token-scopes remaining-argsdiff --git a/src/metabase/metabot/core.clj b/src/metabase/metabot/core.cljindex 3dffd95f9ed..523d6eba7b6 100644--- a/src/metabase/metabot/core.clj+++ b/src/metabase/metabot/core.clj@@ -22,6 +22,8 @@agent-question-updateagent-resource-readagent-search+ agent-sql-construct+ agent-sql-createagent-sql-execute][metabase.metabot.search-modelsentity-type->search-modeldiff --git a/src/metabase/metabot/scope.clj b/src/metabase/metabot/scope.cljindex c20703a7d92..9a71f7b6521 100644--- a/src/metabase/metabot/scope.clj+++ b/src/metabase/metabot/scope.clj@@ -17,6 +17,8 @@;;; ──────────────────────────────────────────────────────────────────;; SQL+(api-scope/defscope agent-sql-construct "agent:sql:construct"+ (deferred-tru "Construct SQL queries"))(api-scope/defscope agent-sql-create "agent:sql:create"(deferred-tru "Create SQL queries"))(api-scope/defscope agent-sql-edit "agent:sql:edit"diff --git a/test/metabase/agent_api/api_test.clj b/test/metabase/agent_api/api_test.cljindex 14238d31b40..ff09b8ad620 100644--- a/test/metabase/agent_api/api_test.clj+++ b/test/metabase/agent_api/api_test.clj@@ -636,6 +636,51 @@:query (:query construct-resp):collection_id locked-id}))))))+;;; ----------------------------------------- Construct / Save Native Query ------------------------------------------++(deftest construct-native-query-test+ (testing "Wraps SQL into a base64-encoded MBQL 5 native query (same shape as /v2/construct-query output)"+ (let [resp (mt/user-http-request :crowberto :post 200 "agent/v1/construct-native-query"+ {:database_id (mt/id)+ :sql "SELECT 1 AS n"})+ decoded (-> resp :query u/decode-base64 json/decode+kw)]+ (is (=? {:database (mt/id)+ :lib/type "mbql/query"+ :stages [{:lib/type "mbql.stage/native" :native "SELECT 1 AS n"}]}+ decoded))))+ (testing "Returns 403 when the caller cannot access the target database"+ (mt/with-no-data-perms-for-all-users!+ (mt/user-http-request :rasta :post 403 "agent/v1/construct-native-query"+ {:database_id (mt/id)+ :sql "SELECT 1"})))+ (testing "Returns 404 for a non-existent database"+ (mt/user-http-request :crowberto :post 404 "agent/v1/construct-native-query"+ {:database_id Integer/MAX_VALUE+ :sql "SELECT 1"})))++(deftest create-native-question-test+ (testing "Saves a native SQL query (from construct_native_query) as a question"+ (let [construct-resp (mt/user-http-request :crowberto :post 200 "agent/v1/construct-native-query"+ {:database_id (mt/id)+ :sql "SELECT 1 AS n"})+ create-resp (mt/user-http-request :crowberto :post 200 "agent/v1/question"+ {:name "Native Agent Question"+ :query (:query construct-resp)})]+ (is (=? {:id pos? :name "Native Agent Question" :display "table"} create-resp))+ (let [card (t2/select-one :model/Card :id (:id create-resp))]+ (is (= :native (:query_type card)))+ (is (=? {:stages [{:lib/type :mbql.stage/native :native "SELECT 1 AS n"}]}+ (:dataset_query card))))+ (t2/delete! :model/Card :id (:id create-resp))))+ (testing "Returns 403 when the caller lacks native-query permission"+ (let [construct-resp (mt/user-http-request :crowberto :post 200 "agent/v1/construct-native-query"+ {:database_id (mt/id)+ :sql "SELECT 1 AS n"})]+ (mt/with-no-data-perms-for-all-users!+ (mt/user-http-request :rasta :post 403 "agent/v1/question"+ {:name "Should Not Save Native"+ :query (:query construct-resp)})))))+(deftest create-question-explicit-null-collection-test(testing "An explicit null collection_id saves to the root collection, not the personal default"(let [construct-resp (mt/user-http-request :rasta :post 200 "agent/v2/construct-query"diff --git a/test/metabase/mcp/api_test.clj b/test/metabase/mcp/api_test.cljindex 2ab14571033..f2320458439 100644--- a/test/metabase/mcp/api_test.clj+++ b/test/metabase/mcp/api_test.clj@@ -271,6 +271,7 @@(def ^:private all-tool-names#{"construct_query"+ "construct_native_query""create_collection""create_dashboard""create_question"@@ -658,7 +659,7 @@below) — the test compares this set against the Agent API-backed tools andfails when they diverge, ensuring no Agent API tool ships without a basicinvocation check."- #{"search" "construct_query" "query" "execute_query" "execute_sql"+ #{"search" "construct_query" "construct_native_query" "query" "execute_query" "execute_sql""read_resource""create_question" "create_dashboard""update_question" "update_dashboard" "create_collection"})@@ -694,6 +695,10 @@_ (call-tool session-id "search" {:term_queries ["orders"]});; Query construction + executionconstruct-data (call-tool session-id "construct_query" {:query orders-query})+ native-data (call-tool session-id "construct_native_query"+ {:database_id (mt/id)+ :sql "SELECT 1"})+ _ (is (uuid? (parse-uuid (:query_handle native-data))))_ (call-tool session-id "query" {:query orders-query})_ (call-tool session-id "execute_query"{:query_handle (:query_handle construct-data)})