Skip to content

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

Fix agent api `/query` pagination (#76013)

lbrdnk748eeb1ce778
diff --git a/src/metabase/agent_api/api.clj b/src/metabase/agent_api/api.clj
index a895522eea0..d7ffc95d0df 100644
--- a/src/metabase/agent_api/api.clj
+++ b/src/metabase/agent_api/api.clj
@@ -41,10 +41,6 @@
;;; --------------------------------------------------- Defaults ------------------------------------------------------
-(def ^:private ^:const default-query-row-limit
- "Default row cap when :limit is omitted from a table query request."
- 200)
-
(def ^:private ^:const page-size
"Rows returned per page when paginating the combined query endpoint via continuation tokens.
Also used as the query processor's per-call row constraint."
@@ -340,11 +336,11 @@
decoded))
(defn- clamp-total-limit
- "Default a missing :limit and cap it at the combined endpoint's hard maximum.
- This is the app-level total-row budget enforced across paginated responses; each page's QP-level
- cap comes from `:page.items`, which `remaining-page-rows` clamps to respect this total."
+ "Cap `limit` at the combined endpoint's hard maximum.
+ A nil `limit` (no explicit limit in the query) defaults to the full 2000-row budget so that
+ omitting :limit doesn't silently collapse pagination to a single page."
[limit]
- (min (or limit default-query-row-limit) max-total-row-limit))
+ (min (or limit max-total-row-limit) max-total-row-limit))
(defn- total-row-limit
"The user's requested :limit read from a resolved lib query, defaulted and capped."
@@ -534,11 +530,16 @@
:tool {:name "query"
:title "Query Tables and Metrics"
:description (str "Execute a Metabase query and return results with column "
- "metadata. If more rows are available, the response includes a "
- "continuation_token — pass it back to get the next page.\n\n"
- "Provide one of: a `query_handle` returned by construct_query "
- "(preferred when you have one); a `{\"query\": <object>}` body "
- "(same shape as construct_query; see the `construct_notebook_query` "
+ "metadata, paginating automatically up to 2,000 rows total.\n\n"
+ "Results are returned in pages of 200 rows. When more pages remain "
+ "within the 2,000-row budget, the response includes a "
+ "continuation_token — pass it back to fetch the next page. A missing "
+ "continuation_token means the budget is exhausted or the table has "
+ "fewer rows than the page size. If the table is larger than 2,000 "
+ "rows and you need more, add a filter or aggregation to narrow "
+ "the result set.\n\n Provide one of: a `query_handle` returned "
+ "by construct_query (preferred when you have one); a `{\"query\": <object>}` "
+ "body (same shape as construct_query; see the `construct_notebook_query` "
"tool for the format reference); or a `{\"continuation_token\": "
"\"...\"}` from a previous response.")
:annotations {:read-only? true}}}
diff --git a/test/metabase/agent_api/api_test.clj b/test/metabase/agent_api/api_test.clj
index 3fb5f8ca59b..6758c8b1338 100644
--- a/test/metabase/agent_api/api_test.clj
+++ b/test/metabase/agent_api/api_test.clj
@@ -399,7 +399,23 @@
(is (=? {:status "completed"
:row_count (fn [n] (<= n 200))}
(mt/user-http-request :rasta :post 202 "agent/v2/query"
- {:query (orders-query :limit 1000)})))))
+ {:query (orders-query :limit 1000)}))))
+ (testing "No explicit :limit defaults to a 2000-row budget, emitting a continuation token for large tables"
+ ;; Regression: previously the default budget equalled the page size (both 200), so the first
+ ;; page exhausted the budget and no continuation token was ever emitted, causing agents to
+ ;; report a false \"200-row hard cap\". The default budget is now 2000.
+ (let [page1 (mt/user-http-request :rasta :post 202 "agent/v2/query"
+ {:query (orders-query :order-by [["asc" {} (orders-field-ref "ID")]])})]
+ (is (=? {:status "completed"
+ :row_count 200
+ :continuation_token string?}
+ page1)
+ "first page should include a continuation token when more data exists within the 2000-row budget")
+ (is (=? {:status "completed"
+ :data {:rows sequential?}}
+ (mt/user-http-request :rasta :post 202 "agent/v2/query"
+ {:continuation_token (:continuation_token page1)}))
+ "continuation token should successfully fetch the next page"))))
(deftest combined-query-accepts-resolved-handle-test
(testing "`/v2/query` executes a base64 `:query` string (a resolved query_handle) directly,