Skip to content

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

Metabot: read_resource navigation primitives (#74238)

Mihael Konjevićd5a6fb9c5f54
diff --git a/resources/metabot/prompts/tools/read_resource.md b/resources/metabot/prompts/tools/read_resource.md
index 6d9db3e17d5..701421405db 100644
--- a/resources/metabot/prompts/tools/read_resource.md
+++ b/resources/metabot/prompts/tools/read_resource.md
@@ -1,69 +1,152 @@
-When using the read_resource tool, you have access to a unified interface for retrieving data about various Metabase resources using URI patterns.
-The URI pattern determines what information is returned - from basic summaries to detailed field-level data.
+When using the read_resource tool, you have access to a unified interface for navigating the Metabase instance and retrieving data about its resources via URI patterns.
-You can request multiple resources in a single call by providing a list of URIs, up to a maximum of 5 at a time.
+The URI pattern determines what is returned — from top-level lists (databases, collections) to a single entity, to its sub-resources (fields, items, sources, derived items).
+
+You can request multiple resources in one call by providing a list of URIs (max 5). Lists are capped at 25 items per response — when truncated, the response includes `truncated="true"` and `total="N"` so you know more exist; drill into specific items via their URIs (each list item carries a `uri="..."` attribute) or refine via `search`.
+
+# When to Use read_resource vs search
+
+**Use `read_resource` when you already know the structure** to enumerate.
+- "List all databases" → `metabase://databases` (NOT an empty/generic search)
+- "What's in this collection?" → `metabase://collection/{id}/items`
+- "What cards does this dashboard have?" → `metabase://dashboard/{id}/items`
+- "What schemas does this database have?" → `metabase://database/{id}/schemas`
+
+**Use `search` when you don't know what or where** something lives — open-ended discovery by topic.
+
+**The exploration loop**:
+1. `search` for a topic → every result carries a `uri` attribute.
+2. If a top hit is a container (look for `is_container="true"` — collections and dashboards), `read_resource` on its URI to enumerate members instead of re-searching.
+3. Drill into specific items via `read_resource` for fields, sources, or details.
+4. Walk lineage when needed: `metabase://table/{id}/derived`, `metabase://model/{id}/sources`, `metabase://transform/{id}/sources` or `/target`.
+
+**Anti-pattern**: searching for empty-string or generic terms ("all tables", "everything") to "list everything" — use the navigation URIs above.
# Supported URI Patterns
+## Navigation (top-level lists, no id)
+
+- `metabase://databases` — all databases readable by you
+- `metabase://collections` — root collections (children of "/")
+- `metabase://collections?tree=true` — flat list of all collections; use `:location` (e.g. `/12/34/`) and `:path` to understand hierarchy
+- `metabase://user/recent-items` — your recently-viewed items
+
+**Examples:**
+- User asks "what databases do we have?" → `metabase://databases`
+- User asks "what have I been looking at?" → `metabase://user/recent-items`
+- Need to map out the whole instance before drilling in → `metabase://collections?tree=true`
+
+## Database resources
+
+- `metabase://database/{id}` — basic database info
+- `metabase://database/{id}/tables` — tables in the database
+- `metabase://database/{id}/models` — models targeting the database
+- `metabase://database/{id}/schemas` — schemas in the database (each one carries a URI you can drill into)
+- `metabase://database/{id}/schemas/{schemaName}/tables` — tables in a specific schema
+
+**Examples:**
+- Want to see warehouse layout before writing SQL? → `metabase://database/1/schemas` then `metabase://database/1/schemas/PUBLIC/tables`
+- Want curated models in a specific warehouse? → `metabase://database/1/models`
+
+**Best Practices:**
+- For a high-cardinality database, prefer schema → tables drill-down over fetching every table at once.
+- Pair with the `database_id` argument on `search` when you want to topic-search within a specific warehouse.
+
+## Collection resources
+
+- `metabase://collection/{id}` — basic collection info
+- `metabase://collection/{id}/items` — direct children (mix of subcollections, cards, models, metrics, dashboards)
+- `metabase://collection/{id}/subcollections` — only the subcollections (useful for orientation in deep trees)
+
+**Examples:**
+- "What's in the Marketing collection?" → `metabase://collection/{id}/items`
+- Need to navigate a deep tree without enumerating every leaf? → `metabase://collection/{id}/subcollections`
+
+**Best Practices:**
+- When a `search` returns a collection result with `is_container="true"`, prefer `read_resource` on its URI over re-searching the same concept.
+- Pair with the `collection_id` argument on `search` (descendant scope) when you want to topic-search inside one part of the instance.
+
## Table resources
-- metabase://table/{id} - Get basic table info
-- metabase://table/{id}/fields - Get table details with available fields
-- metabase://table/{id}/fields/{field_id} - Get detailed field information with sample values and metadata
+
+- `metabase://table/{id}` — basic table info
+- `metabase://table/{id}/fields` — table with fields
+- `metabase://table/{id}/fields/{field_id}` — specific field with sample values and stats
+- `metabase://table/{id}/derived` — cards (questions/models) and transforms built on this table
**Examples:**
- Want table structure (fields without value information)? → `metabase://table/123/fields`
- Want detailed field information (sample values for format patterns)? → `metabase://table/123/fields/1`
+- "What's already built on this table?" before suggesting a new query → `metabase://table/123/derived`
+**Best Practices:**
+- Before recommending raw-table SQL, check `/derived` — there may be a curated model or saved question that already answers the user's need.
## Model resources
-- metabase://model/{id} - Get basic model info
-- metabase://model/{id}/fields - Get model details with available fields
-- metabase://model/{id}/fields/{field_id} - Get detailed field information with sample values and metadata
+
+- `metabase://model/{id}` — basic model info
+- `metabase://model/{id}/fields` — model with fields
+- `metabase://model/{id}/fields/{field_id}` — detailed field info with sample values
+- `metabase://model/{id}/sources` — tables/cards this model is derived from (FK-resolved: database, source table, and source card if any)
**Examples:**
-- Want model structure (fields without value information)? → `metabase://model/456/fields`
-- Want detailed field information (sample values for format patterns)? → `metabase://model/456/fields/1`
+- Want model structure? → `metabase://model/456/fields`
+- Want sample values for format patterns? → `metabase://model/456/fields/1`
+- Need to understand a model's lineage before editing or chaining off it? → `metabase://model/456/sources`
## Question resources
-- metabase://question/{id} - Get basic question info
-- metabase://question/{id}/fields - Get question details with available fields
-- metabase://question/{id}/fields/{field_id} - Get detailed field information with sample values and metadata
+
+- `metabase://question/{id}` — basic question info
+- `metabase://question/{id}/fields` — question with fields
+- `metabase://question/{id}/fields/{field_id}` — detailed field info with sample values
+- `metabase://question/{id}/sources` — tables/cards this question references (FK-resolved)
**Examples:**
-- Want question structure (fields without value information)? → `metabase://question/456/fields`
-- Want detailed field information (sample values for format patterns)? → `metabase://question/456/fields/1`
+- "What does this question return?" → `metabase://question/456/fields`
+- "What's the data source behind this saved question?" → `metabase://question/456/sources`
## Metric resources
-- metabase://metric/{id} - Get basic metric info
-- metabase://metric/{id}/dimensions - Get metric with queryable dimensions (fields you can filter/group by)
-- metabase://metric/{id}/dimensions/{dimension_id} - Get specific dimension with sample values
+
+- `metabase://metric/{id}` — basic metric info
+- `metabase://metric/{id}/dimensions` — metric with queryable dimensions (fields you can filter/group by)
+- `metabase://metric/{id}/dimensions/{dimension_id}` — specific dimension with sample values
**Examples:**
- Want metric dimensions? → `metabase://metric/789/dimensions`
-- Want dimension values (sample values for format patterns)? → `metabase://metric/789/dimensions/1`
-
+- Want sample values for a dimension? → `metabase://metric/789/dimensions/1`
## Transform resources
-- metabase://transform/{id} - Get transform details and configuration
+
+- `metabase://transform/{id}` — transform details and configuration
+- `metabase://transform/{id}/sources` — source database and tables this transform reads from
+- `metabase://transform/{id}/target` — target database and table this transform writes to
**Examples:**
- Want to inspect a transform's SQL or Python source before editing it? → `metabase://transform/42`
-- User references a transform link in their message? → fetch its URI to get full context before making changes
+- "What does this transform read?" → `metabase://transform/42/sources`
+- "Where does this transform write?" → `metabase://transform/42/target`
**Best Practices:**
-
- Fetch a transform's details before modifying it so you have the current source query and target configuration.
- Use the returned source type (`query` or `python`) to decide which write tool to call (`write_transform_sql` or `write_transform_python`).
-
+- Walk `/sources` and `/target` to understand lineage before recommending downstream changes.
## Dashboard resources
-- metabase://dashboard/{id} - Get dashboard details
+
+- `metabase://dashboard/{id}` — dashboard details
+- `metabase://dashboard/{id}/items` — cards on the dashboard (each rendered as a `metabase://question/{id}` URI you can drill into)
**Examples:**
- Want to understand what a dashboard contains before recommending it? → `metabase://dashboard/158`
-- User asks about a specific dashboard by name? → search first, then fetch its URI to confirm it matches
+- User asks "what's on this dashboard?" → `metabase://dashboard/158/items`
**Best Practices:**
-
+- Treat dashboards as containers — when search returns a dashboard hit (`is_container="true"`), use `/items` to list its cards instead of re-searching for the same concept.
- Fetch dashboard details to confirm it contains the information the user is looking for before recommending it.
- Prefer verified dashboards when they match the user's request.
+
+# General Best Practices
+
+- **Drill, don't re-search.** If a `search` result is a container or you need more detail on a specific item, feed its `uri` back into `read_resource` — don't issue another search for the same concept.
+- **Batch read URIs** (up to 5 at a time) when you need parallel context, e.g. fetching `/sources` for several candidate models at once.
+- **Honor truncation.** If a list response carries `truncated="true"`, the most-relevant items are not guaranteed to be in the first 25 — consider scoping (`metabase://database/{id}/...`) or refining via `search` with `database_id`/`collection_id` instead of paging blindly.
+- **Curation matters.** Search results carry `is_verified`, `is_official`, and `is_library_member` flags — when you have a choice, drill into the curated item rather than the raw one.
diff --git a/src/metabase/metabot/tools/resources.clj b/src/metabase/metabot/tools/resources.clj
index 8e76fcbdc58..53382b12d0a 100644
--- a/src/metabase/metabot/tools/resources.clj
+++ b/src/metabase/metabot/tools/resources.clj
@@ -5,28 +5,67 @@
token-efficient references to resources that can be fetched on-demand at the
appropriate level of detail.
+ URI dispatch uses [[metabase.util.match/match-one]] — every supported URI shape lives
+ in the [[dispatch]] match table, and each fetch-* handler takes only the IDs/names it
+ needs. Adding a new URI = adding one match clause + one focused fn.
+
Supported URI patterns:
- - metabase://table/{id} - Basic table info
- - metabase://table/{id}/fields - Table with fields
- - metabase://table/{id}/fields/{field_id} - Specific field details
- - metabase://model/{id} - Basic model info
- - metabase://model/{id}/fields - Model with fields
- - metabase://model/{id}/fields/{field_id} - Specific field details
- - metabase://metric/{id} - Basic metric info
- - metabase://metric/{id}/dimensions - Metric with dimensions
- - metabase://metric/{id}/dimensions/{dimension_id} - Specific dimension details
- - metabase://transform/{id} - Transform details
- - metabase://dashboard/{id} - Dashboard details"
+
+ Navigation (top-level lists, no id):
+ - metabase://databases - list databases
+ - metabase://collections - list root collections
+ - metabase://collections?tree=true - flat list of all collections (hierarchy via :location)
+ - metabase://user/recent-items - current user's recent items
+
+ Database drill-down:
+ - metabase://database/{id} - one database
+ - metabase://database/{id}/tables - tables in the database
+ - metabase://database/{id}/models - models targeting the database
+ - metabase://database/{id}/schemas - schemas in the database
+ - metabase://database/{id}/schemas/{schemaName}/tables - tables in a schema
+
+ Collection drill-down:
+ - metabase://collection/{id} - one collection
+ - metabase://collection/{id}/items - direct children (subcollections + leaves)
+ - metabase://collection/{id}/subcollections - just subcollections
+
+ Entity drill-down:
+ - metabase://table/{id} - basic table info
+ - metabase://table/{id}/fields - table with fields
+ - metabase://table/{id}/fields/{field_id} - specific field details
+ - metabase://table/{id}/derived - cards/transforms derived from this table
+ - metabase://model/{id} - basic model info
+ - metabase://model/{id}/fields - model with fields
+ - metabase://model/{id}/fields/{field_id} - specific field details
+ - metabase://model/{id}/sources - tables/models this model is derived from
+ - metabase://question/{id} - basic question info
+ - metabase://question/{id}/fields - question with fields
+ - metabase://question/{id}/fields/{field_id} - specific field details
+ - metabase://question/{id}/sources - tables/models this question references
+ - metabase://metric/{id} - basic metric info
+ - metabase://metric/{id}/dimensions - metric with dimensions
+ - metabase://metric/{id}/dimensions/{dimension_id} - specific dimension details
+ - metabase://transform/{id} - transform details
+ - metabase://transform/{id}/sources - tables/databases this transform reads from
+ - metabase://transform/{id}/target - table this transform writes to
+ - metabase://dashboard/{id} - dashboard details
+ - metabase://dashboard/{id}/items - cards on the dashboard"
(:require
[clojure.string :as str]
+ [metabase.activity-feed.core :as activity-feed]
+ [metabase.api.common :as api]
[metabase.metabot.scope :as scope]
[metabase.metabot.tools.entity-details :as entity-details]
[metabase.metabot.tools.field-stats :as field-stats]
[metabase.metabot.tools.shared.instructions :as instructions]
[metabase.metabot.tools.shared.llm-representations :as llm-rep]
+ [metabase.models.interface :as mi]
[metabase.transforms.core :as transforms]
[metabase.util.log :as log]
- [metabase.util.malli :as mu]))
+ [metabase.util.malli :as mu]
+ [metabase.util.match :as match]
+ [ring.util.codec :as codec]
+ [toucan2.core :as t2]))
(set! *warn-on-reflection* true)
@@ -34,168 +73,545 @@
"Maximum number of URIs that can be fetched in a single call."
5)
+(def ^:private max-list-items
+ "Maximum number of items returned in a single list response. When exceeded the response
+ includes :truncated true and :total so the agent knows there are more items it can drill into."
+ 25)
+
+(defn- truncate-list
+ "Cap a sequence of items at `max-list-items`, returning {:items :total :truncated}."
+ [items]
+ (let [items (vec items)
+ total (count items)]
+ {:items (vec (take max-list-items items))
+ :total total
+ :truncated (> total max-list-items)}))
+
+(defn- list-result
+ "Build a structured-output map for a list of items.
+ `list-type` is a keyword like :databases, :collection-items, :recents, etc."
+ [list-type items]
+ (let [{:keys [items total truncated]} (truncate-list items)]
+ {:structured-output
+ {:result-type :metabot-list
+ :list-type list-type
+ :items items
+ :total total
+ :truncated truncated}}))
+
+(defn- entity-result
+ "Build a structured-output map for a single entity (databases, collections, etc.)."
+ [item]
+ {:structured-output (assoc item :result-type :metabot-entity)})
+
+(defn- parse-query-string
+ "Parse a URI query string like \"tree=true&foo=bar\" into a keyword-keyed map.
+ Returns nil for empty or nil input."
+ [qs]
+ (when (and qs (not (str/blank? qs)))
+ (->> (str/split qs #"&")
+ (keep (fn [pair]
+ (when-not (str/blank? pair)
+ (let [[k v] (str/split pair #"=" 2)]
+ (when k [(keyword k) (or v "")])))))
+ (into {}))))
+
(defn- parse-uri
- "Parse a metabase:// URI into components.
+ "Parse a metabase:// URI into a vector of path segments and a query-params map.
- Returns a map with:
- - :resource-type - The type (table, model, metric, etc.)
- - :resource-id - The ID of the resource
- - :sub-resource - Optional sub-resource type (fields, dimensions)
- - :sub-resource-id - Optional sub-resource ID"
+ Each segment is URL-decoded after splitting on `/`, so encoded values like
+ `weird%2Fname` (a database schema with a literal `/`) round-trip correctly
+ from `metabase-uri` back into the matched pattern.
+
+ Returns:
+ - :segments - vector of non-empty path segments (e.g. [\"database\" \"1\" \"tables\"])
+ - :query-params - {keyword string} map (e.g. {:tree \"true\"}), or nil if no query string"
[uri]
(when-not (str/starts-with? uri "metabase://")
(throw (ex-info (str "Invalid URI scheme. Expected 'metabase://' but got: " uri)
{:uri uri})))
-
- (let [path (subs uri 11) ; Remove "metabase://"
- parts (str/split path #"/")
- parts (remove str/blank? parts)]
-
- (when (< (count parts) 2)
- (throw (ex-info
- (str "Invalid URI format: " uri ". "
- "Expected: metabase://{type}/{id}[/{sub_resource}[/{sub_resource_id}]]")
- {:uri uri :parts parts})))
-
- {:resource-type (first parts)
- :resource-id (second parts)
- :sub-resource (nth parts 2 nil)
- :sub-resource-id (when (> (count parts) 3)
- ;; Handle field IDs with slashes (e.g., c75/17)
- (str/join "/" (drop 3 parts)))}))
-
-(defn- fetch-table-resource
- "Fetch table resource based on URI components."
- [{:keys [resource-id sub-resource sub-resource-id]}]
- (let [table-id (parse-long resource-id)]
- (cond
- ;; metabase://table/123/fields/FIELD_ID
- (and (= sub-resource "fields") sub-resource-id)
- (field-stats/field-values {:entity-type "table"
- :entity-id table-id
- :field-id sub-resource-id
- :limit 30})
-
- ;; metabase://table/123/fields
- (= sub-resource "fields")
- (entity-details/get-table-details {:entity-type :table
- :entity-id table-id
- :with-fields? true
- :with-field-values? false
- :with-related-tables? true
- :with-measures? true
- :with-segments? true})
-
- ;; metabase://table/123
- (nil? sub-resource)
- (entity-details/get-table-details {:entity-type :table
- :entity-id table-id
- :with-fields? false
- :with-field-values? false
- :with-related-tables? true
- :with-measures? true
- :with-segments? true})
-
- :else
- (throw (ex-info (str "Unsupported sub-resource '" sub-resource "' for table. Supported: fields")
- {:resource-id resource-id :sub-resource sub-resource})))))
-
-(defn- fetch-model-or-card-resource
- "Fetch model resource based on URI components."
- [{:keys [resource-id resource-type sub-resource sub-resource-id]}]
- (let [resource-id* (parse-long resource-id)
- resource-type* (keyword resource-type)]
- (assert (#{:question :model} resource-type*))
- (cond
- ;; metabase://<model,question>/123/fields/FIELD_ID
- (and (= sub-resource "fields") sub-resource-id)
- ;; field-values takes type as string and id as integer
- (field-stats/field-values {:entity-type resource-type
- :entity-id resource-id*
- :field-id sub-resource-id
- :limit 30})
-
- ;; metabase://<model,question>/123/fields
- (= sub-resource "fields")
- ;; get-table-details takes type as kw and id as integer
- (entity-details/get-table-details {:entity-type resource-type*
- :entity-id resource-id*
- :with-fields? true
- :with-field-values? false
- :with-related-tables? false
- :with-measures? true
- :with-segments? true})
-
- ;; metabase://<model,question>/123
- (nil? sub-resource)
- (entity-details/get-table-details {:entity-type resource-type*
- :entity-id resource-id*
- :with-fields? false
- :with-field-values? false
- :with-related-tables? false
- :with-measures? true
- :with-segments? true})
-
- :else
- (throw (ex-info (str "Unsupported sub-resource '" sub-resource "' for model. Supported: fields")
- {:resource-id resource-id :sub-resource sub-resource})))))
-
-(defn- fetch-metric-resource
- "Fetch metric resource based on URI components."
- [{:keys [resource-id sub-resource sub-resource-id]}]
- (let [metric-id (parse-long resource-id)]
- (cond
- ;; metabase://metric/123/dimensions/DIMENSION_ID
- (and (= sub-resource "dimensions") sub-resource-id)
- (field-stats/field-values {:entity-type "metric"
- :entity-id metric-id
- :field-id sub-resource-id
- :limit 30})
-
- ;; metabase://metric/123/dimensions
- (= sub-resource "dimensions")
- (entity-details/get-metric-details {:metric-id metric-id
- :with-queryable-dimensions true
- :with-field-values false})
-
- ;; metabase://metric/123
- (nil? sub-resource)
- (entity-details/get-metric-details {:metric-id metric-id
- :with-queryable-dimensions false
- :with-field-values false})
-
- :else
- (throw (ex-info (str "Unsupported sub-resource '" sub-resource "' for metric. Supported: dimensions")
- {:resource-id resource-id :sub-resource sub-resource})))))
-
-(defn- fetch-transform-resource
- "Fetch transform resource."
- [{:keys [resource-id sub-resource]}]
- (when sub-resource
- (throw (ex-info (str "Transforms do not support sub-resources. Got: " sub-resource)
- {:resource-id resource-id :sub-resource sub-resource})))
- {:structured-output (-> (transforms/get-transform (parse-long resource-id))
+ (let [stripped (subs uri 11)
+ [path qs] (str/split stripped #"\?" 2)
+ segments (->> (str/split path #"/")
+ (remove str/blank?)
+ (mapv codec/url-decode))]
+ (when (zero? (count segments))
+ (throw (ex-info (str "Invalid URI: " uri " — empty path")
+ {:uri uri})))
+ {:segments segments
+ :query-params (parse-query-string qs)}))
+
+;; ----- Item presenters (list-row shapes) -----
+
+(defn- present-database
+ "Trim a database row to a token-frugal item map for list responses."
+ [{:keys [id name engine description]}]
+ {:type "database"
+ :id id
+ :name name
+ :engine (some-> engine clojure.core/name)
+ :description description
+ :uri (llm-rep/metabase-uri :database id)})
+
+(defn- present-collection
+ "Trim a collection row to an item map. `path-name` may be supplied if the caller pre-computed it."
+ ([coll] (present-collection coll nil))
+ ([{:keys [id name location authority_level description personal_owner_id]} path-name]
+ {:type "collection"
+ :id id
+ :name name
+ :path (or path-name name)
+ :location location
+ :authority_level authority_level
+ :is_personal (boolean personal_owner_id)
+ :description description
+ :uri (llm-rep/metabase-uri :collection id)}))
+
+(defn- present-table
+ [{:keys [id name display_name schema db_id description]}]
+ {:type "table"
+ :id id
+ :name name
+ :display_name display_name
+ :schema schema
+ :database_id db_id
+ :description description
+ :uri (llm-rep/metabase-uri :table id)})
+
+(defn- present-card
+ "Cards (questions or models) — :type on a Card is :question / :model / :metric."
+ [{:keys [id name type collection_id description database_id table_id]}]
+ (let [model-type (case type
+ :model "model"
+ :metric "metric"
+ :question "question"
+ "question")]
+ {:type model-type
+ :id id
+ :name name
+ :collection_id collection_id
+ :database_id database_id
+ :table_id table_id
+ :description description
+ :uri (llm-rep/metabase-uri (keyword model-type) id)}))
+
+(defn- present-dashboard
+ [{:keys [id name collection_id description]}]
+ {:type "dashboard"
+ :id id
+ :name name
+ :collection_id collection_id
+ :description description
+ :uri (llm-rep/metabase-uri :dashboard id)})
+
+(defn- present-transform
+ [{:keys [id name description source_database_id]}]
+ {:type "transform"
+ :id id
+ :name name
+ :database_id source_database_id
+ :description description
+ :uri (llm-rep/metabase-uri :transform id)})
+
+(defn- present-source-card
+ "Resolve a source-card id to a typed item map (model / metric / question)."
+ [source-card-id]
+ (let [src-card (t2/select-one [:model/Card :id :type :card_schema] :id source-card-id)
+ src-type (case (:type src-card)
+ :model "model"
+ :metric "metric"
+ "question")]
+ {:type src-type
+ :id source-card-id
+ :uri (llm-rep/metabase-uri (keyword src-type) source-card-id)}))
+
+;; ----- Lineage helpers -----
+
+(defn- card-sources-items
+ "Build URI list for the entities a card references, FK-only (database_id, table_id, source_card_id)."
+ [{:keys [database_id table_id source_card_id]}]
+ (cond-> []
+ database_id (conj {:type "database"
+ :id database_id
+ :uri (llm-rep/metabase-uri :database database_id)})
+ table_id (conj {:type "table"
+ :id table_id
+ :uri (llm-rep/metabase-uri :table table_id)})
+ source_card_id (conj (present-source-card source_card_id))))
+
+(defn- transform-source-table-ids
+ "FK-only source tables for a transform: walks (:source :source-tables) entries when present."
+ [transform]
+ (->> (get-in transform [:source :source-tables])
+ (keep :table_id)))
+
+;; ----- Fetch handlers (one per URI shape) -----
+
+(defn- fetch-databases-list []
+ (let [dbs (->> (t2/select [:model/Database :id :name :engine :description :is_audit]
+ :is_audit false
+ {:order-by [[:%lower.name :asc]]})
+ (filter mi/can-read?)
+ (mapv present-database))]
+ (list-result :databases dbs)))
+
+(defn- fetch-collections-list
+ "metabase://collections (root only) and metabase://collections?tree=true (flat list of all)."
+ [{:keys [tree] :as _query-params}]
+ (let [tree? (= "true" tree)
+ where (cond-> [:and
+ [:= :archived false]
+ [:= :namespace nil]
+ ;; Exclude the system Trash collection from navigation listings.
+ [:or [:= :type nil] [:!= :type "trash"]]]
+ (not tree?) (conj [:= :location "/"]))
+ colls (->> (t2/select [:model/Collection :id :name :location :authority_level
+ :description :personal_owner_id]
+ {:where where
+ :order-by [[:location :asc] [:%lower.name :asc]]})
+ (filter mi/can-read?))
+ ;; For tree mode, compute path names by chaining ancestor names.
+ id->name (when tree? (into {} (map (juxt :id :name)) colls))
+ ancestors (fn [{:keys [location]}]
+ (when (and location (not= "/" location))
+ (->> (str/split location #"/")
+ (remove str/blank?)
+ (keep parse-long))))
+ path-of (fn [coll]
+ (str/join "/" (concat (keep id->name (ancestors coll))
+ [(:name coll)])))
+ items (mapv (fn [c] (present-collection c (when tree? (path-of c)))) colls)]
+ (list-result (if tree? :collections-tree :collections-root) items)))
+
+(defn- fetch-user-recents []
+ (let [recents (or (-> (activity-feed/get-recents api/*current-user-id* [:views])
+ :recents)
+ [])
+ items (mapv (fn [{:keys [id name model timestamp]}]
+ (let [type (case model
+ "card" "question"
+ "dataset" "model"
+ (or model "item"))]
+ {:type type
+ :id id
+ :name name
+ :timestamp timestamp
+ :uri (llm-rep/metabase-uri (keyword type) id)}))
+ recents)]
+ (list-result :recent-items items)))
+
+;; ----- Database drill-down -----
+
+(defn- fetch-database [id-str]
+ (let [db (api/read-check :model/Database (parse-long id-str))]
+ (entity-result (present-database db))))
+
+(defn- fetch-database-tables [id-str]
+ (let [db-id (parse-long id-str)
+ _ (api/read-check :model/Database db-id)
+ tables (->> (t2/select [:model/Table :id :name :display_name :schema :db_id :description]
+ :db_id db-id
+ :active true
+ {:order-by [[:%lower.schema :asc] [:%lower.name :asc]]})
+ (filter mi/can-read?)
+ (mapv present-table))]
+ (list-result :database-tables tables)))
+
+(defn- fetch-database-models [id-str]
+ (let [db-id (parse-long id-str)
+ _ (api/read-check :model/Database db-id)
+ models (->> (t2/select [:model/Card :id :name :type :description :card_schema
+ :collection_id :database_id :table_id]
+ :type :model
+ :database_id db-id
+ :archived false
+ {:order-by [[:%lower.name :asc]]})
+ (filter mi/can-read?)
+ (mapv present-card))]
+ (list-result :database-models models)))
+
+(defn- fetch-database-schemas [id-str]
+ (let [db-id (parse-long id-str)
+ _ (api/read-check :model/Database db-id)
+ rows (t2/query
+ {:select-distinct [:schema]
+ :from [:metabase_table]
+ :where [:and [:= :db_id db-id] [:= :active true]]
+ :order-by [[:schema :asc]]})
+ schemas (->> rows
+ (keep :schema)
+ (mapv (fn [s]
+ {:type "schema"
+ :name s
+ :database_id db-id
+ :uri (llm-rep/metabase-uri :database db-id "schemas" s "tables")})))]
+ (list-result :database-schemas schemas)))
+
+(defn- fetch-database-schema-tables [id-str schema-name]
+ (let [db-id (parse-long id-str)
+ _ (api/read-check :model/Database db-id)
+ tables (->> (t2/select [:model/Table :id :name :display_name :schema :db_id :description]
+ :db_id db-id
+ :schema schema-name
+ :active true
+ {:order-by [[:%lower.name :asc]]})
+ (filter mi/can-read?)
+ (mapv present-table))]
+ (list-result :database-schema-tables tables)))
+
+;; ----- Collection drill-down -----
+
+(defn- fetch-collection [id-str]
+ (let [coll (api/read-check :model/Collection (parse-long id-str))]
+ (entity-result (present-collection coll))))
+
+(defn- fetch-collection-items [id-str]
+ (let [coll-id (parse-long id-str)
+ coll (api/read-check :model/Collection coll-id)
+ cards (->> (t2/select [:model/Card :id :name :type :description :card_schema
+ :collection_id :database_id :table_id]
+ {:where [:and [:= :collection_id coll-id] [:= :archived false]]
+ :order-by [[:%lower.name :asc]]})
+ (filter mi/can-read?))
+ dashboards (->> (t2/select [:model/Dashboard :id :name :description :collection_id]
+ :collection_id coll-id
+ :archived false
+ {:order-by [[:%lower.name :asc]]})
+ (filter mi/can-read?))
+ subcollections (->> (t2/select [:model/Collection :id :name :location :authority_level
+ :description :personal_owner_id]
+ :location (str (:location coll) coll-id "/")
+ :archived false
+ {:order-by [[:%lower.name :asc]]})
+ (filter mi/can-read?))
+ items (concat (map present-collection subcollections)
+ (map present-card cards)
+ (map present-dashboard dashboards))]
+ (list-result :collection-items items)))
+
+(defn- fetch-collection-subcollections [id-str]
+ (let [coll-id (parse-long id-str)
+ coll (api/read-check :model/Collection coll-id)
+ subs (->> (t2/select [:model/Collection :id :name :location :authority_level
+ :description :personal_owner_id]
+ :location (str (:location coll) coll-id "/")
+ :archived false
+ {:order-by [[:%lower.name :asc]]})
+ (filter mi/can-read?)
+ (mapv present-collection))]
+ (list-result :collection-subcollections subs)))
+
+;; ----- Table -----
+
+(defn- table-details
+ "Shared `entity-details/get-table-details` call for both /table/{id} and /table/{id}/fields.
+ `entity-type` is :table, :model, or :question."
+ [entity-type id with-fields?]
+ (entity-details/get-table-details {:entity-type entity-type
+ :entity-id id
+ :with-fields? with-fields?
+ :with-field-values? false
+ :with-related-tables? (= entity-type :table)
+ :with-measures? true
+ :with-segments? true}))
+
+(defn- fetch-table [id-str]
+ (table-details :table (parse-long id-str) false))
+
+(defn- fetch-table-fields [id-str]
+ (table-details :table (parse-long id-str) true))
+
+(defn- fetch-table-field [id-str field-id]
+ (field-stats/field-values {:entity-type "table"
+ :entity-id (parse-long id-str)
+ :field-id field-id
+ :limit 30}))
+
+(defn- fetch-table-derived [id-str]
+ (let [table-id (parse-long id-str)
+ table (api/read-check :model/Table table-id)
+ db-id (:db_id table)
+ cards (->> (t2/select [:model/Card :id :name :type :description :card_schema
+ :collection_id :database_id :table_id]
+ :table_id table-id
+ :archived false
+ {:order-by [[:%lower.name :asc]]})
+ (filter mi/can-read?)
+ (mapv present-card))
+ ;; SQL-narrow transforms by source_database_id (a transform can only reference
+ ;; tables in its source DB). Pull `:source` in the same select to extract source
+ ;; table ids in memory — no per-row re-fetch. Apply the can-read? check last,
+ ;; on the already-narrowed candidate set.
+ transforms (when db-id
+ (->> (t2/select [:model/Transform :id :name :description
+ :source_database_id :source]
+ :source_database_id db-id
+ {:order-by [[:%lower.name :asc]]})
+ (filter (fn [t] (some #{table-id} (transform-source-table-ids t))))
+ (filter mi/can-read?)
+ (mapv present-transform)))]
+ (list-result :table-derived (concat cards transforms))))
+
+;; ----- Card (model / question) -----
+
+(defn- fetch-card
+ "type-str is \"model\" or \"question\"."
+ [type-str id-str]
+ (table-details (keyword type-str) (parse-long id-str) false))
+
+(defn- fetch-card-fields [type-str id-str]
+ (table-details (keyword type-str) (parse-long id-str) true))
+
+(defn- fetch-card-field [type-str id-str field-id]
+ (field-stats/field-values {:entity-type type-str
+ :entity-id (parse-long id-str)
+ :field-id field-id
+ :limit 30}))
+
+(defn- fetch-card-sources [id-str]
+ (let [card (api/read-check :model/Card (parse-long id-str))]
+ (list-result :card-sources (card-sources-items card))))
+
+;; ----- Metric -----
+
+(defn- fetch-metric [id-str]
+ (entity-details/get-metric-details {:metric-id (parse-long id-str)
+ :with-queryable-dimensions false
+ :with-field-values false}))
+
+(defn- fetch-metric-dimensions [id-str]
+ (entity-details/get-metric-details {:metric-id (parse-long id-str)
+ :with-queryable-dimensions true
+ :with-field-values false}))
+
+(defn- fetch-metric-dimension [id-str dim-id]
+ (field-stats/field-values {:entity-type "metric"
+ :entity-id (parse-long id-str)
+ :field-id dim-id
+ :limit 30}))
+
+;; ----- Transform -----
+
+(defn- fetch-transform [id-str]
+ {:structured-output (-> (transforms/get-transform (parse-long id-str))
(assoc :result-type :entity :type :transform))})
-(defn- fetch-dashboard-resource
- "Fetch dashboard resource."
- [{:keys [resource-id sub-resource]}]
- (when sub-resource
- (throw (ex-info (str "Dashboards do not support sub-resources. Got: " sub-resource)
- {:resource-id resource-id :sub-resource sub-resource})))
- (let [result (entity-details/get-dashboard-details {:dashboard-id (parse-long resource-id)})]
+(defn- fetch-transform-sources [id-str]
+ (let [transform (transforms/get-transform (parse-long id-str))
+ source-table-ids (transform-source-table-ids transform)
+ source-tables (when (seq source-table-ids)
+ (->> (t2/select [:model/Table :id :name :display_name :schema :db_id :description]
+ :id [:in (set source-table-ids)])
+ (filter mi/can-read?)
+ (mapv present-table)))
+ db-id (:source_database_id transform)
+ items (cond-> []
+ db-id (conj {:type "database"
+ :id db-id
+ :uri (llm-rep/metabase-uri :database db-id)})
+ source-tables (into source-tables))]
+ (list-result :transform-sources items)))
+
+(defn- fetch-transform-target [id-str]
+ (let [transform (transforms/get-transform (parse-long id-str))
+ ;; The target table is hydrated by `transforms/get-transform` without a per-table
+ ;; permission check (the read-check on the Transform itself only verifies *source*
+ ;; tables are readable). Gate it here so users who can read the transform definition
+ ;; but lack perms on the target database don't see the target's name/schema.
+ target-table (when-let [tt (:table transform)]
+ (when (mi/can-read? tt) tt))
+ db-id (:target_db_id transform)
+ items (cond-> []
+ db-id (conj {:type "database"
+ :id db-id
+ :uri (llm-rep/metabase-uri :database db-id)})
+ target-table (conj (present-table target-table)))]
+ (list-result :transform-target items)))
+
+;; ----- Dashboard -----
+
+(defn- fetch-dashboard [id-str]
+ (let [result (entity-details/get-dashboard-details {:dashboard-id (parse-long id-str)})]
(if-let [dashboard (:structured-output result)]
{:structured-output (assoc dashboard :result-type :entity)}
{:status-code 404 :output (:output result)})))
-(def ^:private resource-handlers
- "Map of resource type to handler function."
- {"table" fetch-table-resource
- "model" fetch-model-or-card-resource
- "question" fetch-model-or-card-resource
- "metric" fetch-metric-resource
- "transform" fetch-transform-resource
- "dashboard" fetch-dashboard-resource})
+(defn- fetch-dashboard-items [id-str]
+ (let [dashboard-id (parse-long id-str)
+ _ (api/read-check :model/Dashboard dashboard-id)
+ cards (->> (t2/select [:model/Card :id :name :type :description :card_schema
+ :collection_id :database_id :table_id]
+ {:where [:and
+ [:= :archived false]
+ [:exists {:select 1
+ :from [[:report_dashboardcard :dc]]
+ :where [:and
+ [:= :dc.card_id :report_card.id]
+ [:= :dc.dashboard_id dashboard-id]]}]]
+ :order-by [[:%lower.name :asc]]})
+ (filter mi/can-read?)
+ (mapv present-card))]
+ (list-result :dashboard-items cards)))
+
+;; ----- Dispatch -----
+
+(defn- dispatch
+ "Route a parsed URI to the right fetch handler. The match-one table is the canonical
+ list of supported URI shapes — adding a new URI = adding a clause here + a handler.
+
+ Pattern ordering: more-specific patterns (no rest-binding) must come before less-specific
+ ones (with rest-binding) so the exact-length match wins for the no-extra-segments case."
+ [uri]
+ (let [{:keys [segments query-params]} (parse-uri uri)]
+ (match/match-one segments
+ ;; Navigation
+ ["databases"] (fetch-databases-list)
+ ["collections"] (fetch-collections-list query-params)
+ ["user" "recent-items"] (fetch-user-recents)
+
+ ;; Database drill-down
+ ["database" id] (fetch-database id)
+ ["database" id "tables"] (fetch-database-tables id)
+ ["database" id "models"] (fetch-database-models id)
+ ["database" id "schemas"] (fetch-database-schemas id)
+ ["database" id "schemas" schema "tables"] (fetch-database-schema-tables id schema)
+
+ ;; Collection drill-down
+ ["collection" id] (fetch-collection id)
+ ["collection" id "items"] (fetch-collection-items id)
+ ["collection" id "subcollections"] (fetch-collection-subcollections id)
+
+ ;; Table
+ ["table" id] (fetch-table id)
+ ["table" id "fields"] (fetch-table-fields id)
+ ["table" id "fields" & rst] (fetch-table-field id (str/join "/" rst))
+ ["table" id "derived"] (fetch-table-derived id)
+
+ ;; Card (model / question — share handlers, dispatch on the type segment)
+ [(t :guard #{"model" "question"}) id] (fetch-card t id)
+ [(t :guard #{"model" "question"}) id "fields"] (fetch-card-fields t id)
+ [(t :guard #{"model" "question"}) id "fields" & rst] (fetch-card-field t id (str/join "/" rst))
+ [(t :guard #{"model" "question"}) id "sources"] (fetch-card-sources id)
+
+ ;; Metric
+ ["metric" id] (fetch-metric id)
+ ["metric" id "dimensions"] (fetch-metric-dimensions id)
+ ["metric" id "dimensions" & rst] (fetch-metric-dimension id (str/join "/" rst))
+
+ ;; Transform
+ ["transform" id] (fetch-transform id)
+ ["transform" id "sources"] (fetch-transform-sources id)
+ ["transform" id "target"] (fetch-transform-target id)
+
+ ;; Dashboard
+ ["dashboard" id] (fetch-dashboard id)
+ ["dashboard" id "items"] (fetch-dashboard-items id)
+
+ ;; Default — required to make match non-recursive
+ _ (throw (ex-info (str "Unsupported URI: " uri)
+ {:uri uri :segments segments})))))
+
+;; ----- Tool entry points -----
(defn- fetch-single-uri
"Fetch a single URI and return formatted content.
@@ -205,19 +621,10 @@
- {:uri uri :error error-message}"
[uri]
(try
- (let [parsed (parse-uri uri)
- {:keys [resource-type]} parsed
- handler (get resource-handlers resource-type)]
-
- (when-not handler
- (throw (ex-info (str "Unknown resource type '" resource-type "'. "
- "Supported: " (str/join ", " (keys resource-handlers)))
- {:resource-type resource-type :supported (keys resource-handlers)})))
-
- (let [result (handler parsed)]
- (if (:status-code result)
- {:uri uri :error (or (:output result) result)}
- {:uri uri :content result})))
+ (let [result (dispatch uri)]
+ (if (:status-code result)
+ {:uri uri :error (or (:output result) result)}
+ {:uri uri :content result}))
(catch Exception e
(log/warn "Error fetching resource" {:uri uri :error (ex-message e)})
{:uri uri :error (or (ex-message e) "Unknown error")})))
@@ -240,6 +647,8 @@
(llm-rep/field-metadata->xml structured)
instructions/field-metadata-instructions)
:entity (llm-rep/entity->xml structured)
+ :metabot-list (llm-rep/metabot-list->xml structured)
+ :metabot-entity (llm-rep/metabot-entity->xml structured)
;; fallback — should not happen, but better than EDN
(llm-rep/entity->xml structured))
;; error case — :output is already a string
@@ -290,14 +699,38 @@
(mu/defn ^{:tool-name "read_resource"
:scope scope/agent-resource-read}
read-resource-tool
- "Read detailed information about Metabase resources via URI patterns.
-
- Supports fetching multiple resources in parallel using metabase:// URIs:
- - metabase://table/{id}/fields - Get table structure with fields
- - metabase://model/{id}/fields/{field_id} - Get specific field details
- - metabase://metric/{id}/dimensions - Get metric dimensions
- - metabase://transform/{id} - Get transform details
- - metabase://dashboard/{id} - Get dashboard details"
+ "Read detailed information about Metabase resources via URI patterns. Use this to navigate
+ the instance and drill into specific entities. URIs returned by `search` and other
+ read_resource calls can be fed directly back here.
+
+ Up to 5 URIs may be requested in one call. List responses are capped at 25 items; if
+ truncated, drill into individual items via their URIs or refine via `search`.
+
+ NAVIGATION (top-level lists):
+ - metabase://databases - all databases
+ - metabase://collections - root collections
+ - metabase://collections?tree=true - flat list of all collections (use :location for hierarchy)
+ - metabase://user/recent-items - your recently-viewed items
+
+ DATABASE DRILL-DOWN:
+ - metabase://database/{id}
+ - metabase://database/{id}/tables
+ - metabase://database/{id}/models
+ - metabase://database/{id}/schemas
+ - metabase://database/{id}/schemas/{schemaName}/tables
+
+ COLLECTION DRILL-DOWN:
+ - metabase://collection/{id}
+ - metabase://collection/{id}/items - subcollections + leaves
+ - metabase://collection/{id}/subcollections
+
+ ENTITY DRILL-DOWN:
+ - metabase://table/{id}[/fields[/{field_id}]] [/derived]
+ - metabase://model/{id}[/fields[/{field_id}]] [/sources]
+ - metabase://question/{id}[/fields[/{field_id}]] [/sources]
+ - metabase://metric/{id}[/dimensions[/{dim_id}]]
+ - metabase://transform/{id}[/sources|/target]
+ - metabase://dashboard/{id}[/items]"
[{:keys [uris]} :- [:map {:closed true}
[:uris [:sequential [:string {:description "Metabase resource URIs to fetch"}]]]]]
(try
diff --git a/src/metabase/metabot/tools/shared/llm_representations.clj b/src/metabase/metabot/tools/shared/llm_representations.clj
index 08e6c020de7..763aff56409 100644
--- a/src/metabase/metabot/tools/shared/llm_representations.clj
+++ b/src/metabase/metabot/tools/shared/llm_representations.clj
@@ -8,13 +8,45 @@
[metabase.metabot.tmpl :as te]
[metabase.util :as u]
[metabase.util.log :as log]
+ [ring.util.codec :as codec]
[selmer.parser :as selmer]))
(set! *warn-on-reflection* true)
(def ^:private llm-template-name "llm_representations.selmer")
-(defn- escape-xml
+(defn- encode-uri-segment
+ "URL-encode a single URI path segment. Coerces keywords/numbers to strings first.
+ Per-segment encoding (vs encoding the whole URI) lets us preserve the literal `/`
+ between segments while still protecting against `/` characters inside a segment
+ value — e.g. a database schema name like `weird/name` that would otherwise
+ collide with the path separator and corrupt downstream URI parsing."
+ [s]
+ (codec/url-encode (cond
+ (keyword? s) (name s)
+ :else (str s))))
+
+(defn metabase-uri
+ "Build a metabase:// URI for an entity. Optional trailing path segments append to the URI.
+
+ Each segment is URL-encoded so values containing `/`, `?`, `%`, etc. survive a
+ round-trip through `parse-uri`.
+
+ Examples:
+ (metabase-uri :table 5) => \"metabase://table/5\"
+ (metabase-uri :table 5 \"fields\") => \"metabase://table/5/fields\"
+ (metabase-uri :collection 7 \"items\") => \"metabase://collection/7/items\"
+ (metabase-uri :databases) => \"metabase://databases\"
+ (metabase-uri :database 1 \"schemas\" \"weird/name\" \"tables\")
+ => \"metabase://database/1/schemas/weird%2Fname/tables\""
+ ([type]
+ (str "metabase://" (encode-uri-segment type)))
+ ([type id & path-segments]
+ (str "metabase://" (encode-uri-segment type) "/" (encode-uri-segment id)
+ (when (seq path-segments)
+ (str "/" (str/join "/" (map encode-uri-segment path-segments)))))))
+
+(defn escape-xml
"Escape XML special characters in a string.
Only needed for content that bypasses Selmer's auto-escaping (marked with |safe)."
[s]
@@ -580,3 +612,66 @@
(do
(log/warn "Unknown entity type" {:type (:type entity)})
(pr-str entity))))
+
+;; ----- Generic list / entity renderers used by the read-resource navigation tools -----
+
+(def ^:private item-attr-keys
+ "Attributes rendered as XML attrs on each <item> element. Order matters for stable output."
+ [:type :id :name :uri :database_id :collection_id :table_id
+ :schema :display_name :authority_level :is_personal :path :location
+ :engine :timestamp])
+
+(defn- item-attrs->xml
+ [item]
+ (->> item-attr-keys
+ (keep (fn [k]
+ (when-let [v (get item k)]
+ (str (clojure.core/name k) "=\"" (escape-xml v) "\""))))
+ (str/join " ")))
+
+(defn- list-item->xml
+ "Render one item from a metabot-list response."
+ [{:keys [description] :as item}]
+ (let [attrs (item-attrs->xml item)]
+ (if description
+ (str "<item " attrs ">" (escape-xml description) "</item>")
+ (str "<item " attrs "/>"))))
+
+(defn metabot-list->xml
+ "Render a list-shaped read-resource response.
+
+ Input shape:
+ {:list-type :databases ; keyword, becomes the type attribute
+ :items [{:type \"database\" :id 1 :name \"Sample\" :uri \"...\" :description \"...\"} ...]
+ :total 5
+ :truncated false}
+
+ Output shape:
+ <list type=\"databases\" total=\"5\" truncated=\"false\">
+ <item type=\"database\" id=\"1\" name=\"Sample\" uri=\"metabase://database/1\">Description</item>
+ ...
+ </list>"
+ [{:keys [list-type items total truncated]}]
+ (let [type-attr (clojure.core/name (or list-type :items))
+ item-xml (str/join "\n" (map list-item->xml items))
+ showing (count items)
+ note (when truncated
+ (str "<truncation-note>Showing " showing " of " total ". "
+ "More items exist — read individual items via their URIs above "
+ "or refine via search.</truncation-note>"))]
+ (str "<list type=\"" type-attr "\" total=\"" total
+ "\" showing=\"" showing
+ "\" truncated=\"" (boolean truncated) "\">\n"
+ (when (seq items) (str item-xml "\n"))
+ (when note (str note "\n"))
+ "</list>")))
+
+(defn metabot-entity->xml
+ "Render a single entity as a flat XML element with attrs and an optional description body."
+ [{:keys [type description] :as entity}]
+ (let [tag (clojure.core/name (or type :entity))
+ attrs (item-attrs->xml entity)]
+ (if description
+ (str "<" tag (when-not (str/blank? attrs) (str " " attrs)) ">"
+ (escape-xml description) "</" tag ">")
+ (str "<" tag (when-not (str/blank? attrs) (str " " attrs)) "/>"))))
diff --git a/test/metabase/metabot/tools/resources_test.clj b/test/metabase/metabot/tools/resources_test.clj
index e313fbe451b..d5e33709172 100644
--- a/test/metabase/metabot/tools/resources_test.clj
+++ b/test/metabase/metabot/tools/resources_test.clj
@@ -7,66 +7,72 @@
[metabase.lib.core :as lib]
[metabase.lib.metadata :as lib.metadata]
[metabase.metabot.tools.resources :as read-resource]
+ [metabase.metabot.tools.shared.llm-representations :as llm-rep]
+ [metabase.models.interface :as mi]
[metabase.query-processor :as qp]
- [metabase.test :as mt]))
+ [metabase.test :as mt]
+ [metabase.transforms.core :as transforms.core]
+ [toucan2.core :as t2]))
(deftest parse-uri-test
- (testing "parses table URI"
- (is (= {:resource-type "table"
- :resource-id "123"
- :sub-resource nil
- :sub-resource-id nil}
- (#'read-resource/parse-uri "metabase://table/123"))))
-
- (testing "parses table with fields sub-resource"
- (is (= {:resource-type "table"
- :resource-id "123"
- :sub-resource "fields"
- :sub-resource-id nil}
- (#'read-resource/parse-uri "metabase://table/123/fields"))))
-
- (testing "parses table with specific field"
- (is (= {:resource-type "table"
- :resource-id "123"
- :sub-resource "fields"
- :sub-resource-id "456"}
- (#'read-resource/parse-uri "metabase://table/123/fields/456"))))
-
- (testing "parses field ID with slash"
- (is (= {:resource-type "table"
- :resource-id "123"
- :sub-resource "fields"
- :sub-resource-id "c75/17"}
- (#'read-resource/parse-uri "metabase://table/123/fields/c75/17"))))
+ (testing "parses single-segment URIs (top-level lists)"
+ (is (= {:segments ["databases"] :query-params nil}
+ (#'read-resource/parse-uri "metabase://databases")))
+ (is (= {:segments ["collections"] :query-params nil}
+ (#'read-resource/parse-uri "metabase://collections"))))
- (testing "parses model URI"
- (is (= {:resource-type "model"
- :resource-id "456"
- :sub-resource nil
- :sub-resource-id nil}
- (#'read-resource/parse-uri "metabase://model/456"))))
-
- (testing "parses question URI"
- (is (= {:resource-type "question"
- :resource-id "456"
- :sub-resource nil
- :sub-resource-id nil}
+ (testing "parses entity URIs into [type id] segments"
+ (is (= {:segments ["table" "123"] :query-params nil}
+ (#'read-resource/parse-uri "metabase://table/123")))
+ (is (= {:segments ["model" "456"] :query-params nil}
+ (#'read-resource/parse-uri "metabase://model/456")))
+ (is (= {:segments ["question" "456"] :query-params nil}
(#'read-resource/parse-uri "metabase://question/456"))))
- (testing "parses metric with dimensions"
- (is (= {:resource-type "metric"
- :resource-id "789"
- :sub-resource "dimensions"
- :sub-resource-id nil}
+ (testing "parses entity sub-resources"
+ (is (= {:segments ["table" "123" "fields"] :query-params nil}
+ (#'read-resource/parse-uri "metabase://table/123/fields")))
+ (is (= {:segments ["table" "123" "fields" "456"] :query-params nil}
+ (#'read-resource/parse-uri "metabase://table/123/fields/456")))
+ (is (= {:segments ["metric" "789" "dimensions"] :query-params nil}
(#'read-resource/parse-uri "metabase://metric/789/dimensions"))))
+ (testing "parses field IDs that contain slashes (e.g. c75/17)"
+ (is (= {:segments ["table" "123" "fields" "c75" "17"] :query-params nil}
+ (#'read-resource/parse-uri "metabase://table/123/fields/c75/17"))))
+
+ (testing "parses deep paths"
+ (is (= {:segments ["database" "1" "schemas" "PUBLIC" "tables"] :query-params nil}
+ (#'read-resource/parse-uri "metabase://database/1/schemas/PUBLIC/tables"))))
+
+ (testing "parses query strings into :query-params"
+ (is (= {:tree "true"}
+ (:query-params (#'read-resource/parse-uri "metabase://collections?tree=true"))))
+ (is (= {:tree "true" :foo "bar"}
+ (:query-params (#'read-resource/parse-uri "metabase://collections?tree=true&foo=bar")))))
+
+ (testing "parses user URIs"
+ (is (= {:segments ["user" "recent-items"] :query-params nil}
+ (#'read-resource/parse-uri "metabase://user/recent-items"))))
+
(testing "rejects invalid scheme"
(is (thrown? Exception
(#'read-resource/parse-uri "https://example.com"))))
- (testing "rejects incomplete URI"
+ (testing "rejects empty path"
(is (thrown? Exception
- (#'read-resource/parse-uri "metabase://table")))))
+ (#'read-resource/parse-uri "metabase://"))))
+
+ (testing "URL-decodes path segments — schema names containing '/' round-trip"
+ ;; An encoded URI like /schemas/weird%2Fname/tables splits into 5 segments,
+ ;; with the schema segment decoded back to its literal form (containing '/').
+ (let [parsed (#'read-resource/parse-uri "metabase://database/1/schemas/weird%2Fname/tables")]
+ (is (= ["database" "1" "schemas" "weird/name" "tables"] (:segments parsed))))
+ (testing "round-trips through metabase-uri"
+ (let [uri (llm-rep/metabase-uri :database 1 "schemas" "weird/name" "tables")
+ parsed (#'read-resource/parse-uri uri)]
+ (is (= "metabase://database/1/schemas/weird%2Fname/tables" uri))
+ (is (= ["database" "1" "schemas" "weird/name" "tables"] (:segments parsed)))))))
(deftest read-resource-validation-test
(testing "rejects too many URIs"
@@ -74,6 +80,123 @@
(is (thrown-with-msg? Exception #"Too many URIs"
(read-resource/read-resource {:uris uris}))))))
+;; ===== Dispatch routing — every URI pattern routes to the expected handler =====
+
+(def ^:private dispatch-cases
+ "Each row: [uri expected-handler-tag expected-handler-args]. Adding a new URI pattern
+ to the dispatch should mean adding one row here. Args are positional and string-typed
+ the way the dispatch passes them to the handler."
+ [;; ----- Top-level navigation -----
+ ["metabase://databases" :databases-list []]
+ ["metabase://collections" :collections-list [nil]]
+ ["metabase://collections?tree=true" :collections-list [{:tree "true"}]]
+ ["metabase://collections?tree=true&foo=bar" :collections-list [{:tree "true" :foo "bar"}]]
+ ["metabase://user/recent-items" :user-recents []]
+
+ ;; ----- Database drill-down -----
+ ["metabase://database/1" :database ["1"]]
+ ["metabase://database/1/tables" :database-tables ["1"]]
+ ["metabase://database/1/models" :database-models ["1"]]
+ ["metabase://database/1/schemas" :database-schemas ["1"]]
+ ["metabase://database/1/schemas/PUBLIC/tables" :database-schema-tables ["1" "PUBLIC"]]
+ ["metabase://database/1/schemas/lower_case/tables" :database-schema-tables ["1" "lower_case"]]
+
+ ;; ----- Collection drill-down -----
+ ["metabase://collection/2" :collection ["2"]]
+ ["metabase://collection/2/items" :collection-items ["2"]]
+ ["metabase://collection/2/subcollections" :collection-subcollections ["2"]]
+
+ ;; ----- Table -----
+ ["metabase://table/3" :table ["3"]]
+ ["metabase://table/3/fields" :table-fields ["3"]]
+ ["metabase://table/3/fields/42" :table-field ["3" "42"]]
+ ["metabase://table/3/fields/c75/17" :table-field ["3" "c75/17"]]
+ ["metabase://table/3/derived" :table-derived ["3"]]
+
+ ;; ----- Model (a card type) -----
+ ["metabase://model/4" :card ["model" "4"]]
+ ["metabase://model/4/fields" :card-fields ["model" "4"]]
+ ["metabase://model/4/fields/99" :card-field ["model" "4" "99"]]
+ ["metabase://model/4/fields/c75/17" :card-field ["model" "4" "c75/17"]]
+ ["metabase://model/4/sources" :card-sources ["4"]]
+
+ ;; ----- Question (a card type) -----
+ ["metabase://question/5" :card ["question" "5"]]
+ ["metabase://question/5/fields" :card-fields ["question" "5"]]
+ ["metabase://question/5/fields/99" :card-field ["question" "5" "99"]]
+ ["metabase://question/5/sources" :card-sources ["5"]]
+
+ ;; ----- Metric -----
+ ["metabase://metric/6" :metric ["6"]]
+ ["metabase://metric/6/dimensions" :metric-dimensions ["6"]]
+ ["metabase://metric/6/dimensions/dim-1" :metric-dimension ["6" "dim-1"]]
+
+ ;; ----- Transform -----
+ ["metabase://transform/7" :transform ["7"]]
+ ["metabase://transform/7/sources" :transform-sources ["7"]]
+ ["metabase://transform/7/target" :transform-target ["7"]]
+
+ ;; ----- Dashboard -----
+ ["metabase://dashboard/8" :dashboard ["8"]]
+ ["metabase://dashboard/8/items" :dashboard-items ["8"]]])
+
+(deftest dispatch-routing-test
+ (testing "every supported URI pattern routes to the expected handler with the expected args"
+ (let [calls (atom nil)
+ spy (fn [tag] (fn [& args] (reset! calls [tag (vec args)]) :spied))]
+ (with-redefs [read-resource/fetch-databases-list (spy :databases-list)
+ read-resource/fetch-collections-list (spy :collections-list)
+ read-resource/fetch-user-recents (spy :user-recents)
+ read-resource/fetch-database (spy :database)
+ read-resource/fetch-database-tables (spy :database-tables)
+ read-resource/fetch-database-models (spy :database-models)
+ read-resource/fetch-database-schemas (spy :database-schemas)
+ read-resource/fetch-database-schema-tables (spy :database-schema-tables)
+ read-resource/fetch-collection (spy :collection)
+ read-resource/fetch-collection-items (spy :collection-items)
+ read-resource/fetch-collection-subcollections (spy :collection-subcollections)
+ read-resource/fetch-table (spy :table)
+ read-resource/fetch-table-fields (spy :table-fields)
+ read-resource/fetch-table-field (spy :table-field)
+ read-resource/fetch-table-derived (spy :table-derived)
+ read-resource/fetch-card (spy :card)
+ read-resource/fetch-card-fields (spy :card-fields)
+ read-resource/fetch-card-field (spy :card-field)
+ read-resource/fetch-card-sources (spy :card-sources)
+ read-resource/fetch-metric (spy :metric)
+ read-resource/fetch-metric-dimensions (spy :metric-dimensions)
+ read-resource/fetch-metric-dimension (spy :metric-dimension)
+ read-resource/fetch-transform (spy :transform)
+ read-resource/fetch-transform-sources (spy :transform-sources)
+ read-resource/fetch-transform-target (spy :transform-target)
+ read-resource/fetch-dashboard (spy :dashboard)
+ read-resource/fetch-dashboard-items (spy :dashboard-items)]
+ (doseq [[uri expected-handler expected-args] dispatch-cases]
+ (testing uri
+ (reset! calls nil)
+ (#'read-resource/dispatch uri)
+ (is (= [expected-handler expected-args] @calls))))))))
+
+(deftest dispatch-rejects-unknown-uri-test
+ (testing "unknown top-level resource type throws"
+ (is (thrown-with-msg? Exception #"Unsupported URI"
+ (#'read-resource/dispatch "metabase://nonsense/1"))))
+ (testing "known type with unknown sub-resource throws"
+ (is (thrown-with-msg? Exception #"Unsupported URI"
+ (#'read-resource/dispatch "metabase://table/1/nonsense"))))
+ (testing "deep path that doesn't match any pattern throws"
+ (is (thrown-with-msg? Exception #"Unsupported URI"
+ (#'read-resource/dispatch "metabase://database/1/schemas/PUBLIC/cards"))))
+ (testing "extra-deep collection path throws"
+ (is (thrown-with-msg? Exception #"Unsupported URI"
+ (#'read-resource/dispatch "metabase://collection/1/items/extra"))))
+ (testing "user URI with unknown sub throws"
+ (is (thrown-with-msg? Exception #"Unsupported URI"
+ (#'read-resource/dispatch "metabase://user/bookmarks"))))
+ (testing "non-metabase scheme throws via parse-uri"
+ (is (thrown? Exception
+ (#'read-resource/dispatch "https://example.com")))))
+
(comment
(mt/with-current-user (mt/user->id :crowberto)
(read-resource/read-resource
@@ -146,6 +269,354 @@
(is (=? {:resources [{:error string?}]}
(read-resource/read-resource {:uris ["metabase://transform/99999"]}))))))))
+;; ===== Permission coverage — every branch =====
+;;
+;; Two patterns:
+;; 1. Single-entity reads (and their sub-resources) call `api/read-check` first, which
+;; throws when `mi/can-read?` returns false. The handler should error out.
+;; 2. List handlers run `(filter mi/can-read?)` over their results. Items the user
+;; can't read should silently disappear from the output.
+;;
+;; Strategy: stub `mi/can-read?` and assert the corresponding response shape.
+
+(defn- error?
+ "Whether a read-resource response carries an error for its first URI."
+ [result]
+ (some? (-> result :resources first :error)))
+
+(deftest read-check-throws-on-missing-perm-test
+ (testing "every single-entity URI errors when user lacks read perms on the entity"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table {table-id :id} {:db_id db-id :active true :schema "PUBLIC"}
+ :model/Card {model-id :id} {:type :model :database_id db-id}
+ :model/Card {q-id :id} {:type :question :database_id db-id}
+ :model/Card {metric-id :id} {:type :metric :database_id db-id}
+ :model/Collection {coll-id :id} {}
+ :model/Dashboard {dash-id :id} {}]
+ (let [uris [;; Database family — api/read-check on the DB
+ (str "metabase://database/" db-id)
+ (str "metabase://database/" db-id "/tables")
+ (str "metabase://database/" db-id "/models")
+ (str "metabase://database/" db-id "/schemas")
+ (str "metabase://database/" db-id "/schemas/PUBLIC/tables")
+ ;; Collection family — api/read-check on the Collection
+ (str "metabase://collection/" coll-id)
+ (str "metabase://collection/" coll-id "/items")
+ (str "metabase://collection/" coll-id "/subcollections")
+ ;; Table family — api/read-check via metabot.tools.util/get-table
+ (str "metabase://table/" table-id)
+ (str "metabase://table/" table-id "/fields")
+ (str "metabase://table/" table-id "/fields/42")
+ (str "metabase://table/" table-id "/derived")
+ ;; Card (model) — api/read-check via get-card
+ (str "metabase://model/" model-id)
+ (str "metabase://model/" model-id "/fields")
+ (str "metabase://model/" model-id "/fields/42")
+ (str "metabase://model/" model-id "/sources")
+ ;; Card (question)
+ (str "metabase://question/" q-id)
+ (str "metabase://question/" q-id "/fields")
+ (str "metabase://question/" q-id "/fields/42")
+ (str "metabase://question/" q-id "/sources")
+ ;; Metric — api/read-check via get-card
+ (str "metabase://metric/" metric-id)
+ (str "metabase://metric/" metric-id "/dimensions")
+ (str "metabase://metric/" metric-id "/dimensions/42")
+ ;; Dashboard — api/read-check via get-dashboard-details
+ (str "metabase://dashboard/" dash-id)
+ (str "metabase://dashboard/" dash-id "/items")]]
+ (with-redefs [mi/can-read? (constantly false)]
+ (doseq [uri uris]
+ (testing uri
+ (is (error? (read-resource/read-resource {:uris [uri]}))
+ (str uri " should return an :error response when user lacks read perms"))))))))))
+
+(deftest read-check-throws-on-missing-perm-transform-test
+ (testing "transform URIs error when the transform itself is unreadable"
+ (mt/with-premium-features #{:transforms}
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Transform {transform-id :id}
+ {:name "Permission test transform"
+ :source {:type "query"
+ :query (lib/native-query (mt/metadata-provider) "SELECT 1")}}]
+ (with-redefs [mi/can-read? (constantly false)]
+ (doseq [uri [(str "metabase://transform/" transform-id)
+ (str "metabase://transform/" transform-id "/sources")
+ (str "metabase://transform/" transform-id "/target")]]
+ (testing uri
+ (is (error? (read-resource/read-resource {:uris [uri]}))
+ (str uri " should return an :error response when user can't read transform"))))))))))
+
+(deftest list-filters-databases-by-can-read-test
+ (testing "metabase://databases hides DBs the user can't read"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Database _ {:name "VISIBLE-DB"}
+ :model/Database {hidden-id :id} {:name "HIDDEN-DB"}]
+ (let [orig mi/can-read?]
+ (with-redefs [mi/can-read? (fn
+ ([instance]
+ (if (= hidden-id (:id instance)) false (orig instance)))
+ ([model id]
+ (if (= hidden-id id) false (orig model id))))]
+ (let [{:keys [output]} (read-resource/read-resource {:uris ["metabase://databases"]})]
+ (is (str/includes? output "VISIBLE-DB"))
+ (is (not (str/includes? output "HIDDEN-DB"))
+ "unreadable database must not appear in the list"))))))))
+
+(deftest list-filters-collections-by-can-read-test
+ (testing "metabase://collections hides collections the user can't read"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Collection _ {:name "VISIBLE-COLL" :location "/"}
+ :model/Collection {hidden-id :id} {:name "HIDDEN-COLL" :location "/"}]
+ (let [orig mi/can-read?]
+ (with-redefs [mi/can-read? (fn
+ ([instance]
+ (if (= hidden-id (:id instance)) false (orig instance)))
+ ([model id]
+ (if (= hidden-id id) false (orig model id))))]
+ (let [{:keys [output]} (read-resource/read-resource {:uris ["metabase://collections"]})]
+ (is (str/includes? output "VISIBLE-COLL"))
+ (is (not (str/includes? output "HIDDEN-COLL"))
+ "unreadable collection must not appear in the list"))))))))
+
+(deftest list-filters-collection-items-by-can-read-test
+ (testing "metabase://collection/{id}/items hides individual items the user can't read"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Collection {coll-id :id} {:name "Mixed Coll" :location "/"}
+ :model/Card _ {:name "VISIBLE-CARD" :collection_id coll-id}
+ :model/Card {hidden-card :id} {:name "HIDDEN-CARD" :collection_id coll-id}
+ :model/Dashboard _ {:name "VISIBLE-DASH" :collection_id coll-id}
+ :model/Dashboard {hidden-dash :id} {:name "HIDDEN-DASH" :collection_id coll-id}]
+ (let [orig mi/can-read?
+ hidden-cards #{hidden-card}
+ hidden-dashes #{hidden-dash}]
+ (with-redefs [mi/can-read?
+ (fn
+ ([instance]
+ (cond
+ (and (= :model/Card (t2/model instance)) (hidden-cards (:id instance))) false
+ (and (= :model/Dashboard (t2/model instance)) (hidden-dashes (:id instance))) false
+ :else (orig instance)))
+ ([model id] (orig model id)))]
+ (let [{:keys [output]} (read-resource/read-resource
+ {:uris [(str "metabase://collection/" coll-id "/items")]})]
+ (is (str/includes? output "VISIBLE-CARD"))
+ (is (str/includes? output "VISIBLE-DASH"))
+ (is (not (str/includes? output "HIDDEN-CARD"))
+ "unreadable card must not appear in collection items")
+ (is (not (str/includes? output "HIDDEN-DASH"))
+ "unreadable dashboard must not appear in collection items"))))))))
+
+(deftest list-filters-database-tables-by-can-read-test
+ (testing "metabase://database/{id}/tables hides tables the user can't read"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table _ {:db_id db-id :name "VISIBLE-TBL" :active true}
+ :model/Table {hidden-tbl :id} {:db_id db-id :name "HIDDEN-TBL" :active true}]
+ (let [orig mi/can-read?]
+ (with-redefs [mi/can-read? (fn
+ ([instance]
+ (if (and (= :model/Table (t2/model instance))
+ (= hidden-tbl (:id instance)))
+ false
+ (orig instance)))
+ ([model id] (orig model id)))]
+ (let [{:keys [output]} (read-resource/read-resource
+ {:uris [(str "metabase://database/" db-id "/tables")]})]
+ (is (str/includes? output "VISIBLE-TBL"))
+ (is (not (str/includes? output "HIDDEN-TBL"))
+ "unreadable table must not appear in the database tables list"))))))))
+
+(deftest list-filters-dashboard-items-by-can-read-test
+ (testing "metabase://dashboard/{id}/items hides cards the user can't read"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Dashboard {dash-id :id} {}
+ :model/Card {visible-card :id} {:name "VISIBLE-DASHCARD"}
+ :model/Card {hidden-card :id} {:name "HIDDEN-DASHCARD"}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id visible-card}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id hidden-card}]
+ (let [orig mi/can-read?]
+ (with-redefs [mi/can-read? (fn
+ ([instance]
+ (if (and (= :model/Card (t2/model instance))
+ (= hidden-card (:id instance)))
+ false
+ (orig instance)))
+ ([model id] (orig model id)))]
+ (let [{:keys [output]} (read-resource/read-resource
+ {:uris [(str "metabase://dashboard/" dash-id "/items")]})]
+ (is (str/includes? output "VISIBLE-DASHCARD"))
+ (is (not (str/includes? output "HIDDEN-DASHCARD"))
+ "unreadable card must not appear in dashboard items"))))))))
+
+(deftest read-transform-target-authorization-test
+ (testing "fetch-transform-target gates the target table by mi/can-read?"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table {target-id :id :as target-table}
+ {:db_id db-id :name "TARGET-TABLE" :schema "PUBLIC" :active true}]
+ (let [stub-transform {:id 999
+ :name "Stub Transform"
+ :source_database_id db-id
+ :target_db_id db-id
+ :table target-table}]
+
+ (testing "when user CAN read the target, it appears in the output"
+ (with-redefs [transforms.core/get-transform (constantly stub-transform)]
+ (let [{:keys [output]} (read-resource/read-resource
+ {:uris ["metabase://transform/999/target"]})]
+ (is (str/includes? output "TARGET-TABLE")
+ "target table name should appear when user has read perms")
+ (is (str/includes? output (str "uri=\"metabase://table/" target-id "\""))
+ "target table URI should appear when user has read perms"))))
+
+ (testing "when user CANNOT read the target, it's filtered out"
+ (with-redefs [transforms.core/get-transform (constantly stub-transform)
+ mi/can-read? (constantly false)]
+ (let [{:keys [output]} (read-resource/read-resource
+ {:uris ["metabase://transform/999/target"]})]
+ (is (not (str/includes? output "TARGET-TABLE"))
+ "target table name must NOT appear when user lacks read perms")
+ (is (not (str/includes? output (str "uri=\"metabase://table/" target-id "\"")))
+ "target table URI must NOT appear when user lacks read perms")
+ ;; The target *database* URI is still surfaced — that's intentional, the
+ ;; URI carries no extra metadata and any read_resource call on it will
+ ;; enforce its own auth.
+ (is (str/includes? output (str "uri=\"metabase://database/" db-id "\""))
+ "target database URI is informational and remains visible")))))))))
+
+(deftest read-databases-list-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Database {db-id :id} {:name "Test DB"}]
+ (testing "metabase://databases returns the database with its drill-in URI"
+ (let [{:keys [output]} (read-resource/read-resource {:uris ["metabase://databases"]})]
+ (is (str/includes? output "Test DB"))
+ (is (str/includes? output (str "uri=\"metabase://database/" db-id "\""))))))))
+
+(deftest read-database-tables-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table {t-id :id} {:db_id db-id :name "ORDERS" :active true}]
+ (testing "metabase://database/{id}/tables lists tables with drill-in URIs"
+ (let [{:keys [output]} (read-resource/read-resource {:uris [(str "metabase://database/" db-id "/tables")]})]
+ (is (str/includes? output "ORDERS"))
+ (is (str/includes? output (str "uri=\"metabase://table/" t-id "\""))))))))
+
+(deftest read-collections-and-collection-items-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Collection {coll-id :id} {:name "Marketing" :location "/"}
+ :model/Card {card-id :id} {:name "Sales report" :collection_id coll-id}]
+ (testing "metabase://collections lists root collections (excluding trash)"
+ (let [{:keys [output]} (read-resource/read-resource {:uris ["metabase://collections"]})]
+ (is (str/includes? output "Marketing"))))
+
+ (testing "metabase://collection/{id}/items lists members with drill-in URIs"
+ (let [{:keys [output]} (read-resource/read-resource {:uris [(str "metabase://collection/" coll-id "/items")]})]
+ (is (str/includes? output "Sales report"))
+ (is (str/includes? output (str "uri=\"metabase://question/" card-id "\""))))))))
+
+(deftest read-table-derived-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table {table-id :id} {:db_id db-id}
+ :model/Card {card-id :id}
+ {:name "Derived"
+ :type :model
+ :database_id db-id
+ :table_id table-id}]
+ (testing "metabase://table/{id}/derived returns cards built on the table"
+ (let [{:keys [output]} (read-resource/read-resource {:uris [(str "metabase://table/" table-id "/derived")]})]
+ (is (str/includes? output "Derived"))
+ (is (str/includes? output (str "uri=\"metabase://model/" card-id "\""))))))))
+
+(deftest read-table-derived-narrows-transforms-by-source-db-test
+ (testing "transform candidates are SQL-filtered by source_database_id (no full Transform table scan)"
+ (mt/with-premium-features #{:transforms}
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Database {db1 :id} {:name "DB1"}
+ :model/Database {db2 :id} {:name "DB2"}
+ :model/Table {tbl1-id :id} {:db_id db1}
+ :model/Transform {tx-other-db :id}
+ {:name "Other-DB Transform"
+ :source_database_id db2
+ :source {:type "query"
+ :query (lib/native-query (mt/metadata-provider) "SELECT 1")}}]
+ (testing "/derived for a table in db1 must exclude transforms whose source is in db2"
+ (let [{:keys [output]} (read-resource/read-resource
+ {:uris [(str "metabase://table/" tbl1-id "/derived")]})]
+ (is (not (str/includes? output "Other-DB Transform"))
+ "transforms not sourced from this table's database must not appear")
+ (is (not (str/includes? output (str "uri=\"metabase://transform/" tx-other-db "\"")))))))))))
+
+(deftest read-card-sources-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table {table-id :id} {:db_id db-id}
+ :model/Card {card-id :id} {:type :model :database_id db-id :table_id table-id}]
+ (testing "metabase://model/{id}/sources returns the FK-resolved sources"
+ (let [{:keys [output]} (read-resource/read-resource {:uris [(str "metabase://model/" card-id "/sources")]})]
+ (is (str/includes? output (str "uri=\"metabase://database/" db-id "\""))
+ "should include the database URI")
+ (is (str/includes? output (str "uri=\"metabase://table/" table-id "\""))
+ "should include the source-table URI"))))))
+
+(deftest read-card-sources-source-card-type-test
+ (testing "source-card resolution preserves the card type — metric must not collapse to question"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table {table-id :id} {:db_id db-id}
+ :model/Card {metric-id :id} {:type :metric
+ :database_id db-id
+ :table_id table-id}
+ :model/Card {model-id :id} {:type :model
+ :database_id db-id
+ :table_id table-id}
+ :model/Card {q-id :id} {:type :question
+ :database_id db-id
+ :table_id table-id
+ :source_card_id metric-id}
+ :model/Card {q-from-model-id :id} {:type :question
+ :database_id db-id
+ :table_id table-id
+ :source_card_id model-id}]
+ (testing "source_card_id pointing at a :metric emits a metric URI"
+ (let [{:keys [output]} (read-resource/read-resource
+ {:uris [(str "metabase://question/" q-id "/sources")]})]
+ (is (str/includes? output (str "uri=\"metabase://metric/" metric-id "\""))
+ "should resolve source-card of type :metric to a metric URI, not question")
+ (is (not (str/includes? output (str "uri=\"metabase://question/" metric-id "\"")))
+ "must NOT collapse the metric source-card to a question URI")))
+ (testing "source_card_id pointing at a :model still emits a model URI (regression)"
+ (let [{:keys [output]} (read-resource/read-resource
+ {:uris [(str "metabase://question/" q-from-model-id "/sources")]})]
+ (is (str/includes? output (str "uri=\"metabase://model/" model-id "\"")))))))))
+
+(deftest read-dashboard-items-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Dashboard {dash-id :id} {}
+ :model/Card {card-id :id} {:name "Dash card"}
+ :model/DashboardCard _ {:dashboard_id dash-id :card_id card-id}]
+ (testing "metabase://dashboard/{id}/items returns cards on the dashboard"
+ (let [{:keys [output]} (read-resource/read-resource {:uris [(str "metabase://dashboard/" dash-id "/items")]})]
+ (is (str/includes? output "Dash card"))
+ (is (str/includes? output (str "uri=\"metabase://question/" card-id "\""))))))))
+
+(deftest read-user-recents-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (testing "metabase://user/recent-items returns a list shape (possibly empty)"
+ (let [{:keys [output]} (read-resource/read-resource {:uris ["metabase://user/recent-items"]})]
+ (is (str/includes? output "<list type=\"recent-items\""))))))
+
+(deftest read-list-shape-test
+ (testing "list responses always carry total/showing/truncated attrs in the rendered XML"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (let [{:keys [output]} (read-resource/read-resource {:uris ["metabase://databases"]})]
+ (is (str/includes? output "<list type=\"databases\""))
+ (is (str/includes? output "total="))
+ (is (str/includes? output "showing="))
+ (is (str/includes? output "truncated="))))))
+
(deftest format-resources-test
(testing "formats resources with content"
(let [resources [{:uri "metabase://table/123"
@@ -163,6 +634,125 @@
formatted (#'read-resource/format-resources resources)]
(is (str/includes? formatted "**Error:** Table not found")))))
+;; ===== Behavioral tests for patterns where the dispatch contract isn't enough =====
+
+(deftest read-database-detail-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Database {db-id :id} {:name "Detail DB" :engine :h2}]
+ (testing "metabase://database/{id} returns single-entity output with engine + uri"
+ (let [{:keys [output]} (read-resource/read-resource
+ {:uris [(str "metabase://database/" db-id)]})]
+ (is (str/includes? output "Detail DB"))
+ (is (str/includes? output (str "uri=\"metabase://database/" db-id "\"")))
+ (is (str/includes? output "engine=\"h2\"")))))))
+
+(deftest read-database-models-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Card {model-id :id} {:type :model :database_id db-id :name "M-One"}
+ :model/Card _ {:type :question :database_id db-id :name "Q-Skip"}]
+ (testing "metabase://database/{id}/models lists models only (not questions)"
+ (let [{:keys [output]} (read-resource/read-resource
+ {:uris [(str "metabase://database/" db-id "/models")]})]
+ (is (str/includes? output "M-One"))
+ (is (str/includes? output (str "uri=\"metabase://model/" model-id "\"")))
+ (is (not (str/includes? output "Q-Skip"))))))))
+
+(deftest read-database-schemas-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table _ {:db_id db-id :schema "PUBLIC" :name "t1" :active true}
+ :model/Table _ {:db_id db-id :schema "PRIVATE" :name "t2" :active true}]
+ (testing "metabase://database/{id}/schemas emits a drill-in URI per schema"
+ (let [{:keys [output]} (read-resource/read-resource
+ {:uris [(str "metabase://database/" db-id "/schemas")]})]
+ (is (str/includes? output "PUBLIC"))
+ (is (str/includes? output "PRIVATE"))
+ (is (str/includes? output (str "uri=\"metabase://database/" db-id "/schemas/PUBLIC/tables\"")))
+ (is (str/includes? output (str "uri=\"metabase://database/" db-id "/schemas/PRIVATE/tables\""))))))))
+
+(deftest read-database-schema-tables-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table {pub-id :id} {:db_id db-id :schema "PUBLIC" :name "PUB-TABLE" :active true}
+ :model/Table _ {:db_id db-id :schema "PRIVATE" :name "PRIV-TABLE" :active true}]
+ (testing "metabase://database/{id}/schemas/{name}/tables filters by schema"
+ (let [{:keys [output]} (read-resource/read-resource
+ {:uris [(str "metabase://database/" db-id "/schemas/PUBLIC/tables")]})]
+ (is (str/includes? output "PUB-TABLE"))
+ (is (str/includes? output (str "uri=\"metabase://table/" pub-id "\"")))
+ (is (not (str/includes? output "PRIV-TABLE"))))))))
+
+(deftest read-database-schema-tables-with-slash-in-schema-name-test
+ (testing "schema names containing '/' (which Postgres/Snowflake/etc. allow) survive URI round-trip"
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Table {weird-id :id} {:db_id db-id :schema "weird/name" :name "WEIRD-TABLE" :active true}
+ :model/Table _ {:db_id db-id :schema "other" :name "OTHER-TABLE" :active true}]
+ (let [emitted-uri (llm-rep/metabase-uri :database db-id "schemas" "weird/name" "tables")]
+ (testing "the URI builder emits an encoded segment"
+ (is (str/includes? emitted-uri "weird%2Fname")))
+ (testing "the encoded URI dispatches and filters to the right schema"
+ (let [{:keys [output]} (read-resource/read-resource {:uris [emitted-uri]})]
+ (is (str/includes? output "WEIRD-TABLE"))
+ (is (str/includes? output (str "uri=\"metabase://table/" weird-id "\"")))
+ (is (not (str/includes? output "OTHER-TABLE"))))))))))
+
+(deftest read-collection-detail-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Collection {coll-id :id} {:name "Detail Coll" :location "/"}]
+ (testing "metabase://collection/{id} returns single-entity output with name + uri"
+ (let [{:keys [output]} (read-resource/read-resource
+ {:uris [(str "metabase://collection/" coll-id)]})]
+ (is (str/includes? output "Detail Coll"))
+ (is (str/includes? output (str "uri=\"metabase://collection/" coll-id "\""))))))))
+
+(deftest read-collection-subcollections-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Collection {parent-id :id} {:name "Parent" :location "/"}
+ :model/Collection {child-id :id} {:name "Child" :location (str "/" parent-id "/")}]
+ (testing "metabase://collection/{id}/subcollections lists direct children only"
+ (let [{:keys [output]} (read-resource/read-resource
+ {:uris [(str "metabase://collection/" parent-id "/subcollections")]})]
+ (is (str/includes? output "Child"))
+ (is (str/includes? output (str "uri=\"metabase://collection/" child-id "\"")))
+ (is (not (str/includes? output "Parent"))))))))
+
+(deftest read-collections-tree-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Collection {parent-id :id} {:name "P" :location "/"}
+ :model/Collection _ {:name "C" :location (str "/" parent-id "/")}]
+ (testing "metabase://collections?tree=true returns all collections with full path strings"
+ (let [{:keys [output]} (read-resource/read-resource
+ {:uris ["metabase://collections?tree=true"]})]
+ (is (str/includes? output "<list type=\"collections-tree\""))
+ (is (str/includes? output "P"))
+ ;; child path is rendered as "P/C" (parent name + child name)
+ (is (str/includes? output "P/C")
+ "child collection should carry path=\"P/C\" computed from ancestor names"))))))
+
+(deftest read-table-field-with-slash-test
+ (testing "field IDs containing slashes (e.g. composite ids c75/17) are preserved through dispatch"
+ (let [calls (atom nil)]
+ (with-redefs [read-resource/fetch-table-field
+ (fn [& args] (reset! calls args) {:structured-output {:result-type :metabot-entity :type :stub}})]
+ (#'read-resource/dispatch "metabase://table/3/fields/c75/17")
+ (is (= ["3" "c75/17"] @calls))))))
+
+(deftest read-card-question-vs-model-test
+ (mt/with-current-user (mt/user->id :crowberto)
+ (mt/with-temp [:model/Database {db-id :id} {}
+ :model/Card {q-id :id} {:type :question :database_id db-id :name "Q-card"}
+ :model/Card {m-id :id} {:type :model :database_id db-id :name "M-card"}]
+ (testing "metabase://question/{id}/sources discriminates from model"
+ (let [{:keys [output]} (read-resource/read-resource
+ {:uris [(str "metabase://question/" q-id "/sources")]})]
+ (is (str/includes? output (str "uri=\"metabase://database/" db-id "\"")))))
+ (testing "metabase://model/{id}/sources for a model card"
+ (let [{:keys [output]} (read-resource/read-resource
+ {:uris [(str "metabase://model/" m-id "/sources")]})]
+ (is (str/includes? output (str "uri=\"metabase://database/" db-id "\""))))))))
+
(deftest read-question-resource-test
(let [mp (mt/metadata-provider)
query (as-> (lib/query mp (lib.metadata/table mp (mt/id :products))) $