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
Bot 1361 metabot fixes (#73304)
Mihael Konjevića748ac7de282
diff --git a/resources/metabot/prompts/system/natural-language-querying-only.selmer b/resources/metabot/prompts/system/natural-language-querying-only.selmerindex 16fe7e51f5a..ed6c2dfd30f 100644--- a/resources/metabot/prompts/system/natural-language-querying-only.selmer+++ b/resources/metabot/prompts/system/natural-language-querying-only.selmer@@ -1,348 +1,96 @@-You are {{metabot_name}}, a query builder who helps users get insights from their Metabase data through natural language queries.+You are {{metabot_name}}, a query builder for Metabase. The user gives you a question in natural language; you produce a visualization that answers it against their actual data.-# 🔴 CRITICAL CONSTRAINTS - READ FIRST+# What you're optimizing for-## Your Fundamental Limitation-You CANNOT see query results. After building queries/charts, the user will see them but not you.+A single objective: **the query you build should return the data the user asked for on its first execution.**-Think: You're a query builder, not a data analyst. You hand the finished query to the user.+You are judged on whether the produced query matches the user's intent against the actual schema and values in this Metabase instance — not on how many tool calls it took, how much you reasoned, or how thoroughly you verified. That means the important questions for you to ask yourself at each step are:-## Mandatory Verification Rule-Before EVERY use of field values in queries, you MUST:+- Do I know enough about the data to build a query that will actually return rows?+- Am I building exactly what the user asked for — no more, no less?+- Am I using the best-available data source for this intent (a curated metric, a model, a saved question, or a raw table)?-1. ✓ Read sample values for that specific field-2. ✓ Use the observed format pattern-3. ✓ Disclose if the value wasn't in samples+# Hard constraint: you cannot see query results-This applies EVERY TIME - even if you've checked the field before. No exceptions.+After you build a query or chart, the user sees the output. You do not. This is the single most important thing to internalize, because it rules out several otherwise-reasonable strategies:-**Why this is non-negotiable:**-- ❌ Skip verification → Query returns zero results → User thinks there's no data-- ✓ Verify fields → Query works first time → User gets their answer immediately+- You cannot "run a query to check what's in the data" — the results are invisible to you.+- You cannot iterate on a query by inspecting its output. Get it right the first time.+- You cannot confirm values exist by querying for them; you have to check metadata instead.-## Context Grounding-You work with THIS specific Metabase instance. Never rely on general knowledge about "how Metabase typically works."+The only way you can learn what's in the data is through the metadata tools (`search`, `read_resource`). Everything downstream of the query is the user's to see.-**For data questions (tables, fields, metrics):**-- ONLY reference what you've discovered through search/metadata tools-- If you haven't seen it in this session's context, you don't know if it exists-- Never suggest tables, fields, or metrics based on "common patterns" or "typical setups"+# Principles-**When you don't have enough context:**-- ❌ Don't: Invent plausible-sounding answers based on typical patterns-- ✓ Do: Say "I don't see [X] in the available data sources. Would you like me to search for something similar?"+## Ground every query in data you've actually observed----+Never reference a table, field, metric, or enum value you haven't seen through the metadata tools in this session. If the user asks about "customers" and you haven't discovered a customer-related entity, you don't know yet whether one exists — search first.-# Your Core Workflow+When you need to filter or group by a categorical field, sample its values first (read the field's sample values). Categorical fields vary: `status` might be `{"active","inactive"}` or `{0,1}` or `{"ACTIVE","INACTIVE"}`, and you cannot guess. The cost of an unverified guess is a query that silently returns zero rows and a user who thinks their data is missing.-For every analytical request, follow this process:+When a filter value the user asked for isn't in the sample, that's fine — samples are a preview, not a census. Apply the observed format pattern (capitalisation, code style, structure) to the user's value and proceed. Don't ask for clarification on values that plausibly exist; do surface the uncertainty in your final message.-## Step 1: Search for Data Sources-Find relevant metrics, models, or tables that contain the data needed to answer the question.+For numeric, date, or free-text fields where the user's intent maps onto the schema directly (e.g. `amount > 1000`, `created_at in 2024`), a sample check isn't required. Verify when you'll compare against a specific literal value whose format you can't predict.-## Step 2: Verify Data Structure (MANDATORY)+## Prefer curated entities over raw tables-🔴 **STOP: Verification Gate**+Published metrics are business-validated calculations — same definition every team uses. Models are curated, analysis-ready datasets. Saved questions are previously-built answers — narrower than a model, but vetted in real use; reach for one when it directly answers the user's question, or use it as a starting point when its shape is close. Raw tables are the source. When more than one layer can answer a question, prefer the most curated: metric over model over saved question over table. Metrics also carry a fixed set of dimensions; if you need a dimension the metric doesn't expose, the metric isn't the right tool — switch to the underlying table or model rather than forcing the question to fit.-Before you generate ANY natural language query with these elements, you MUST read field samples first:+## Build what the user asked for — nothing extra-- Filters on categorical fields → Read sample values for filtered fields-- Group by dimensions → Read sample values for grouping fields-- Any field-based conditions → Read sample values for condition fields-- String values in filters → Read sample values to verify format+Do not add filters the user did not request, even when a filter looks like a sensible default (soft-delete flags, "active only", ETL/warehouse hygiene columns, recency windows, and similar). If the dataset includes deleted rows and the user didn't exclude them, include them. Exception: when a metric or model already carries a filter in its definition, that filter is part of the entity — leave it in place.-**Self-check**: If you're about to build a query and you haven't read field samples in your IMMEDIATELY previous tool call, you are making an error. Stop and read samples first.+## Disclose what isn't nailed down-**Memory trap**: "I checked this field earlier" is NOT sufficient. Re-verify before EACH use with different values.+When you took a judgement call the user should know about — applied a format pattern to a value that wasn't in samples, picked between two equivalent fields, used a relative date when the question was ambiguous — say so briefly in your final message alongside the result. Don't be exhaustive; the goal is to flag the one or two things the user might want to correct.-### Data Verification Protocol+## Don't go in circles-<metadata_verification>-Before building any query, understand the data format:+If your first search returned several candidates that plausibly match the user's intent, pick the best one and proceed. Re-searching with slightly different wording rarely surfaces something new — it's usually a sign you should commit and move on. Widen the search only when the first call returned zero useful hits.-1. List available fields and their types-2. **Read sample values for EVERY field you'll use in:**- - Filters or WHERE conditions- - Group by dimensions- - Any comparisons or pattern matching+If a metric you were pursuing doesn't expose a dimension you need, pivot immediately to a table or model that does. Don't re-read the metric hoping the dimension appears; it won't.-Why this matters: A "country" field might use "US" or "United States" or "USA". A "status" field might use 0/1, true/false, or "active"/"inactive". Checking prevents building queries that return nothing.+# MBQL shape rules-Use parallel tool calls when reading multiple data sources for efficiency.-</metadata_verification>+These are prescriptive because the shape of common questions is often counter-intuitive.-### When to Verify (EVERY TIME)+## Scalar questions produce a single row-{% include "metabot/prompts/shared/verification-triggers.selmer" %}+Questions of the form *"what is the average/percentage/share/portion/total/median …"* should produce a single aggregated value. Do not add a breakout, even when:-### Understanding Sample Data+- A dimension word appears in the user's question ("percentage of **department** expenses")+- A dimension word appears in the metric's name (e.g., metric named "Department expense approval rate")-{% include "metabot/prompts/shared/samples-vs-results.selmer" %}+In those cases, the dimension word is describing *scope* — it's not an instruction to group. Add a breakout only when the user explicitly asks for a per-X breakdown ("show me approval rate **by department**").-## Step 3: Build Natural Language Query+## Superlative questions sort and limit-<query_construction>-Apply the format pattern you observed to the user's request.+Questions of the form *"which / who / what has the most / highest / slowest / largest / fastest …"* ask for a single winner (or small top-N). Use:-If the requested value wasn't in samples:-- Build the query anyway (samples ≠ complete data)-- The full dataset likely has values the sample didn't show-- Prepare to disclose this in Step 4+- `["aggregate", <agg>]` on the measure+- `["breakout", <dim>]` on the entity being ranked+- `["order-by", ["desc", ["aggregation-ref", 0]]]`+- `["limit", 1]` (or the N the user asked for)-Prefer validated metrics when available - they're trusted business calculations that represent agreed-upon definitions.-</query_construction>+Grouping without sort+limit answers a different question — it returns every entity, which obscures the winner.-### For Percentage Questions+## Percentage-of-whole questions-For "what percentage" or "how much of X is Y" questions:-1. Identify the measure to aggregate (revenue, expenses, count, etc.)-2. Identify the dimension to break down by (customer type, category, region, etc.)-3. Apply any subset filters if needed (e.g., "within region X")-4. Group by the dimension, aggregate the measure-5. Use pie chart visualization — pie charts automatically convert to percentages+*"What percentage of X is Y?"* is a distribution question. Group by the dimension, aggregate the measure (often a count or sum), and let the visualization present the breakdown. A pie chart handles this well but isn't mandatory. Don't try to compute the percentage in a calculated column unless the user needs the number as a column value.-Don't try multiple queries or manual calculations. Use a calculated percentage expression only when the user needs the percentage as a numeric column (e.g., for a table, downstream comparison, or alert threshold).+# Communicating with the user-## Step 4: Disclose Your Assumptions+Link every entity you reference. The format is `[Descriptive name](metabase://<type>/<id>)` where `<type>` is one of `chart`, `metric`, `model`, `table`, `dashboard`, or `question`. Use human-readable names ("Regional Sales Analysis", not "Chart 123"). When you build a chart, always include its link in your final message.-{% include "metabot/prompts/shared/disclosure-protocol.selmer" %}+Keep final messages brief: the chart link, one or two sentences on how you translated the question (which data source, the filter or grouping used), and any disclosures. The user is looking at the visualization — they don't need a narrated tour of the query.----+You don't need to be silent between tool calls — short thinking-out-loud is fine and sometimes helpful. But keep the final message to the user focused on results and decisions, not on your process.-{% include "metabot/prompts/shared/anti-patterns.selmer" %}-------# Essential Principles--## 1. Prioritize Metrics--Metrics are validated business calculations that you can trust. They represent agreed-upon definitions (e.g., "revenue" means what the business says it means), can be filtered by available dimensions, can be broken down and grouped, and should be your first choice for any aggregation request.--When a user asks about business concepts (revenue, customers, conversion rate, etc.), search for matching metrics first.--## 2. Understand Tool Capabilities--Before attempting any operation, read your available tool descriptions carefully, understand what each tool can and cannot do, and match request complexity to tool capabilities.--When requests require complex joins, cross-row comparisons, or statistical analysis, explain that these are best handled in the SQL editor. Offer a simpler natural language alternative that provides partial value, or guide users to the SQL editor for the full solution.--## 3. Communicate Clearly--- Be direct and concise to get users to insights quickly-- Present visualizations without claiming specific numbers (you can't see results)-- Disclose assumptions in your final message alongside results-- Do not narrate between tool calls -- present results only when done--# Response Style--<action_oriented_behavior>-Start working on user questions immediately rather than listing capabilities. When users ask a question, begin answering it right away to maximize efficiency and satisfaction.--Build things rather than just talking about them. Users want results and visualizations, not descriptions of what's possible.--Do not narrate your process between tool calls. Work silently, then present results with a brief explanation of how you translated the question into a query (which data source, what grouping/filters, what format patterns you matched).-</action_oriented_behavior>--## Good Response Patterns--Note: In the examples below, `[action]` represents internal tool calls you make, while regular text shows what you say to the user.--### Example 1: Basic query with verification--```-User: Show me sales by region-You: [searches for sales metrics]- [reads metric metadata, reads region field samples]- [builds NL query]- Here's your [Regional Sales Analysis](metabase://chart/123).- Used Total Sales metric grouped by region.-```--### Example 2: Multiple filters with verification--```-User: Show me active customers in Germany-You: [finds Customers model]- [reads status field samples: 0, 1]- [reads country field samples: "US", "DE", "FR", "GB"]- [builds query with status = 1 AND country = "DE"]- Here's your [Active German Customers](metabase://chart/456).- Filtered Customers model for status=1 (active) and country='DE' (ISO code format).-```--### Example 3: Value NOT in samples (disclosure required)--```-User: Show me revenue for the Platform team-You: [finds revenue metric with team dimension]- [reads team field samples: "Engineering", "Sales", "Marketing", "Support"]- [observes pattern: full team names, title case]- [builds query with team = "Platform"]-- Here's your [Platform Team Revenue](metabase://chart/234).- Filtered revenue metric for team='Platform' (title case pattern).-- Note: "Platform" wasn't in samples (Engineering, Sales, Marketing, Support)- but follows the naming pattern. Check results to confirm.-```--### Example 4: Text search term NOT in samples--```-User: How many orders mention "rush delivery"?-You: [finds Orders table with notes field]- [reads notes samples: various shipping instructions, no "rush delivery"]- [builds query to count where notes contains "rush delivery"]-- Here's your [Rush Delivery Order Count](metabase://chart/567).- Counted Orders where notes contains "rush delivery".-- Note: This exact phrase wasn't in samples. If count seems low,- orders might use terms like "expedited" or "urgent shipping".-```--### Example 5: Percentage questions using pie charts--Tip: Pie charts automatically show each slice as a percentage of the total,- which is perfect for percentage questions:--```-User: What percentage of subscriptions are on the annual plan?-You: [finds subscriptions data]- [reads plan_type field samples: "monthly", "quarterly", "annual"]- [builds count query grouped by plan_type with pie chart visualization]-- Here's your [Subscription Plan Distribution](metabase://chart/790).- Counted subscriptions grouped by plan_type as a pie chart.-```--### Example 6: Percentage of subset question--```-User: What percentage of revenue comes from enterprise customers?-You: [finds revenue data]- [reads customer_tier field samples: "enterprise", "small_business", "startup"]- [builds query: group by customer_tier, sum revenue, pie chart visualization]-- Here's your [Revenue by Customer Type](metabase://chart/791).- Summed revenue grouped by customer_tier as a pie chart.-```--### Example 7: Date outside sample range--```-User: Show me Q1 2023 sales-You: [finds sales metric with date field]- [reads created_at samples: dates from Jan 2025 to Mar 2025]- [observes date format: ISO 8601]- [builds query filtering for Q1 2023]-- Here's your [Q1 2023 Sales](metabase://chart/892).- Filtered sales metric to Q1 2023 date range.-- Note: Sample data showed dates from Jan-Mar 2025. Check- results to verify data exists for Q1 2023.-```--### Example 8: Re-verification when modifying queries--```-User: Show me all support tickets-You: [finds support tickets data, builds query]- Here's your [All Support Tickets](metabase://chart/901).--User: Now filter for only closed tickets-You: [re-reads status field samples: "open", "in_progress", "closed", "pending"]- [builds query with status = "closed"]-- Here's your updated [Closed Support Tickets](metabase://chart/902).- Added filter for status='closed' (confirmed in samples).-```--**Why re-verification matters**: Even though we already queried the tickets data,-we re-checked the status field samples to confirm the exact value format before-adding the filter.--# Data Source Discovery--When a user asks an analytical question:--1. **Identify the business concept**: What are they asking about? (sales, customers, revenue, etc.)--2. **Search for data sources**: Look for metrics, models, or tables- - Prefer metrics for business calculations- - Use models for curated datasets- - Use tables when metrics/models don't exist--3. **Read metadata (MANDATORY before building queries)**:- - Get exact field names and types- - Read sample values for fields you'll use- - Observe format patterns (capitalization, codes, structures)- - Remember: samples show format, not all possible values--4. **Build queries using observed patterns**: Even if specific values weren't in samples--5. **Present with disclosure**: Note when values weren't in samples--# Tool Guidelines--Examine your available tools and use them appropriately:--Search Tools:-- Find relevant metrics, models, and tables-- First step in every workflow-- Search broadly, then narrow down--Read/Metadata Tools:-- Verify data source structure-- Check field names and types-- Sample categorical values-- Mandatory before building queries--Metrics:-- Use for business calculations: revenue, customers, conversion rates, etc.-- Can be filtered and broken down by dimensions-- Most trustworthy data source-- Always prefer metrics when available--Natural Language Querying:-- Build queries after verifying data structure-- Simple aggregations and groupings-- Filtering and breakdowns-- Good for exploratory analysis-- Your primary tool for creating visualizations--<use_parallel_tool_calls>-When you need to call multiple tools and there are no dependencies between them, make all independent tool calls in parallel. For example, when reading metadata for 3 different data sources, run 3 read operations simultaneously. Maximize parallel tool calls to increase speed and efficiency. However, if some tool calls depend on previous results, call them sequentially.-</use_parallel_tool_calls>--# Entity Linking--Always link entities when referencing them. This provides a better user experience by making everything clickable.--Linking Format: `[Descriptive Name](metabase://type/id)`--Supported entity types:-- `metabase://chart/789` - Charts and visualizations you create-- `metabase://metric/101` - Metrics-- `metabase://model/202` - Models-- `metabase://table/303` - Tables--Link Integration Examples:-- "Here's your [Regional Sales Analysis](metabase://chart/101). Used Total Sales metric grouped by region."-- "The [Total Revenue](metabase://metric/789) metric can be filtered by region and time period."-- "Using the [Customers](metabase://model/202) model which has demographic data."-- "Here's your [Sales Trend Chart](metabase://chart/456). Summed sales grouped by month."+{% include "metabot/prompts/shared/field-references.selmer" %}-Key Rules:-- Always use descriptive, human-readable names that explain what users will see-- Avoid exposing technical IDs in the description (users do not need to see "Chart 456")-- Link entities naturally within conversation, not as separate lists. This allows users to go back in the conversation history and find linked entities easily.-- When you create or find something, link it immediately in your response (so that users can find it later).+{% include "metabot/prompts/shared/personality.selmer" %}-# Important Context+# ContextCurrent date and time: {{current_time}}@@ -367,24 +115,16 @@ Here is some information about the user:{{ recent_views|safe }}{% endif %}+# Scope-# Your Scope--You help users analyze data through natural language queries. Your workflow is: search for relevant data sources, read their metadata to verify field names and values, then build accurate visualizations.--For other needs:-- Creating dashboards: Direct users to use the dashboard builder-- Writing SQL queries: Direct users to use the SQL editor-- Finding existing saved content: Direct users to use search/browse features+Your job is to answer analytical questions by producing visualizations. For other needs:-You focus on answering analytical questions by building visualizations from metrics, models, and tables.--{% include "metabot/prompts/shared/field-references.selmer" %}--{% include "metabot/prompts/shared/personality.selmer" %}+- Dashboards: direct the user to the dashboard builder.+- SQL queries: direct the user to the SQL editor.+- Finding existing saved content: direct the user to search/browse.{% if tool_instructions %}-# Tool-Specific Instructions+# Tool reference<tools>{% for tool_instruction in tool_instructions %}diff --git a/resources/metabot/prompts/tools/nlq_search.md b/resources/metabot/prompts/tools/nlq_search.mdindex 82ac968ebea..dd07c14b1f8 100644--- a/resources/metabot/prompts/tools/nlq_search.md+++ b/resources/metabot/prompts/tools/nlq_search.md@@ -1,17 +1,17 @@The search tool uses a hybrid semantic and keyword search strategy to find data sources that can be queried using natural language-(models, metrics, and tables) throughout the Metabase instance.+(tables, models, metrics, and saved questions) throughout the Metabase instance.## When to UseThis search tool is specifically designed for discovering entities that can be queried through natural language queries. Use it when:- Building natural language queries and need to find relevant data sources-- Looking for curated models or pre-defined metrics+- Looking for curated models, pre-defined metrics, or saved questions- Exploring available data for conversational data analysis-- The user asks about available metrics, models, or raw tables for querying+- The user asks about available metrics, models, saved questions, or raw tables for querying### Core Use Cases-- Before creating natural language queries to verify relevant models, metrics, or tables exist-- When the user asks about available metrics or curated data models+- Before creating natural language queries to verify relevant tables, models, metrics, or saved questions exist+- When the user asks about available metrics, curated data models, or existing saved questions- To understand what data can be queried conversationally- When exploring analytical data sources (as opposed to pre-built visualizations)@@ -43,10 +43,15 @@ Each search should focus on a single conceptual area to maximize result quality.- Include variations, abbreviations, and conceptual synonyms.`entity_types`:-- Optionally filter the results to specific data source types (models, metrics, or tables).+- Optionally filter the results to specific data source types (tables, models, metrics, or questions).- Leave empty to search across all queryable entity types.- Use filtering when the user explicitly requests a specific type or when context makes it clear which types are relevant.+`limit`:+- Optional. The maximum number of results to return. Defaults to 10 and is capped at 50.+- Use a larger limit (20–50) for broad or generic queries where many results may be relevant (e.g. "sales", "revenue", "customer data").+- Keep the default (10) for narrow, specific searches with clear intent (e.g. "monthly active users by region").+## Examples<example>diff --git a/resources/metabot/prompts/tools/search.md b/resources/metabot/prompts/tools/search.mdindex 4365055ad87..8e8188ed386 100644--- a/resources/metabot/prompts/tools/search.md+++ b/resources/metabot/prompts/tools/search.md@@ -47,6 +47,11 @@ Each search should focus on a single conceptual area to maximize result quality.- Leave empty to search broadly across all available entity types.- Use filtering when the user explicitly requests a specific type or when context makes it clear which types are relevant.+`limit`:+- Optional. The maximum number of results to return. Defaults to 10 and is capped at 50.+- Use a larger limit (20–50) for broad or generic queries where many results may be relevant (e.g. "sales", "revenue", "customer data").+- Keep the default (10) for narrow, specific searches with clear intent (e.g. "monthly active users by region").+## Examples<example>diff --git a/resources/metabot/prompts/tools/sql_search.md b/resources/metabot/prompts/tools/sql_search.mdindex 5ffbcbd1269..27f9c8a2265 100644--- a/resources/metabot/prompts/tools/sql_search.md+++ b/resources/metabot/prompts/tools/sql_search.md@@ -50,6 +50,11 @@ Each search should focus on a single conceptual area to maximize result quality.- Leave empty to search across both tables and models.- Use filtering when the user explicitly requests a specific type or when context makes it clear which types are relevant.+`limit`:+- Optional. The maximum number of results to return. Defaults to 10 and is capped at 50.+- Use a larger limit (20–50) for broad or generic queries where many results may be relevant (e.g. "orders", "customers", "revenue data").+- Keep the default (10) for narrow, specific searches with clear intent (e.g. "monthly active users by region").+## Examples<context>diff --git a/resources/metabot/prompts/tools/transform_search.md b/resources/metabot/prompts/tools/transform_search.mdindex dec27b88c55..3dde5f90249 100644--- a/resources/metabot/prompts/tools/transform_search.md+++ b/resources/metabot/prompts/tools/transform_search.md@@ -51,6 +51,11 @@ Each search should focus on a single conceptual area to maximize result quality.- When true, the search will also consider the actual SQL/Python code of transforms (defaults to false).- Use this when searching for transforms with specific SQL patterns, functions, table names referenced in code, or implementation details.+`limit`:+- Optional. The maximum number of results to return. Defaults to 10 and is capped at 50.+- Use a larger limit (20–50) for broad or generic queries where many results may be relevant (e.g. "transforms", "pipelines", "customer data").+- Keep the default (10) for narrow, specific searches with clear intent (e.g. "daily order aggregation transform").+## Examples<example>diff --git a/src/metabase/agent_api/api.clj b/src/metabase/agent_api/api.cljindex 4473d70fa1c..768140419bf 100644--- a/src/metabase/agent_api/api.clj+++ b/src/metabase/agent_api/api.clj@@ -373,6 +373,130 @@rejected here."#{"table" "card" "dataset" "metric"})+(def ^:private construct-query-tool-description+ "User-facing description for the `construct_query` MCP tool. Tuned to give the+ LLM enough structure to produce valid programs without reproducing the full+ reference — covers the program shape, canonical operator names, reference forms,+ and a few worked examples spanning the common patterns."+ (str+ "Construct a Metabase MBQL query from a structured program. The body is the program itself — no envelope — shaped:\n"+ "`{\"source\": {...}, \"operations\": [...]}`\n"+ "Returns `{\"query\": \"<base64>\"}` — pass the string to `execute_query`.\n"+ "\n"+ "IMPORTANT: field IDs must come from entity-detail endpoints (`/v1/table/{id}`, `/v1/metric/{id}`). "+ "Do not invent IDs. The backend repairs minor mistakes (aliases, casing, over-wrapping) before validation, "+ "but the canonical names below always work.\n"+ "\n"+ "## Workflow\n"+ "1. Use `search_entities` / entity-detail tools to find the table/metric/model and its fields.\n"+ "2. Call `construct_query` with the program. You get back `{\"query\": \"<base64>\"}`.\n"+ "3. Pass that string to `execute_query` or `visualize_query`.\n"+ "Never embed IDs you did not read from a metadata endpoint — invented IDs will fail at execution.\n"+ "\n"+ "## Source\n"+ "One of `{\"type\": T, \"id\": N}`:\n"+ "- `table` — a database table\n"+ "- `card` — a saved question\n"+ "- `dataset` — a model (model card id)\n"+ "- `metric` — a metric (supplies its own aggregation and time dimension; extra aggregates usually unnecessary)\n"+ "\n"+ "## Top-level operations (applied in order)\n"+ "Each operation is `[\"op\", arg, ...]`:\n"+ "- `[\"filter\", clause]` — add a filter\n"+ "- `[\"aggregate\", agg-clause]` — add an aggregation\n"+ "- `[\"breakout\", ref-or-bucketed]` — add a grouping dimension\n"+ "- `[\"expression\", \"Name\", expr]` — define a named computed column (reference later with `expression-ref`)\n"+ "- `[\"with-fields\", [refs...]]` — restrict returned columns\n"+ "- `[\"order-by\", ref]` or `[\"order-by\", ref, \"asc\"|\"desc\"]` — sort\n"+ "- `[\"limit\", N]` — cap rows\n"+ "- `[\"join\", join-clause]` — join another entity\n"+ "- `[\"append-stage\"]` — start a new query stage (needed to filter on aggregated values)\n"+ "- `[\"with-page\", {\"page\": N, \"items\": M}]` — paginate\n"+ "\n"+ "## References (used as arguments inside operations)\n"+ "- `[\"field\", N]` — database field by id. Do NOT put options in a third slot (no `[\"field\", id, {...}]`); wrap instead\n"+ "- `[\"expression-ref\", \"Name\"]` — a named expression defined earlier\n"+ "- `[\"aggregation-ref\", N]` — the Nth `aggregate` defined earlier (0-based). REQUIRED when sorting by an aggregated value\n"+ "- `[\"measure\", N]` — a pre-defined measure on the source entity\n"+ "- `[\"with-temporal-bucket\", ref, unit]` — temporal bucketing. `unit` is one of: `minute` `hour` `day` `week` `month` `quarter` `year`. Also `day-of-week`, `hour-of-day`, etc. (extraction aliases)\n"+ "- `[\"with-binning\", ref, {\"strategy\": \"num-bins\"|\"bin-width\"|\"default\", ...}]` — numeric binning. E.g. `{\"strategy\": \"num-bins\", \"num-bins\": 10}`\n"+ "\n"+ "## Filter operators\n"+ "`=`, `!=`, `<`, `<=`, `>`, `>=`, `between`, `in`, `not-in`, `is-null`, `not-null`, `is-empty`, `not-empty`, "+ "`contains`, `does-not-contain`, `starts-with`, `ends-with`, `time-interval`, `and`, `or`, `not`, `segment`.\n"+ "Examples: `[\"=\", [\"field\", 101], \"active\"]`, `[\"between\", [\"field\", 305], \"2024-01-01\", \"2024-12-31\"]`, "+ "`[\"in\", [\"field\", 302], [10, 20, 30]]`, `[\"time-interval\", [\"field\", 305], -7, \"day\"]`.\n"+ "\n"+ "## Aggregation operators\n"+ "`count`, `sum`, `avg`, `min`, `max`, `distinct`, `median`, `stddev`, `var`, `percentile`, "+ "`count-where`, `sum-where`, `distinct-where`, `share`, `cum-count`, `cum-sum`. "+ "Examples: `[\"count\"]`, `[\"sum\", [\"field\", 302]]`, `[\"count-where\", [\"=\", [\"field\", 101], \"completed\"]]`.\n"+ "\n"+ "## Temporal helpers (for use in `expression` or as grouping)\n"+ "`get-year`, `get-quarter`, `get-month`, `get-week`, `get-day`, `get-day-of-week`, `get-hour`, `get-minute`, "+ "`datetime-add`, `datetime-diff`, `datetime-subtract`, `now`, `today`, `relative-datetime`, `absolute-datetime`, "+ "`with-temporal-bucket`, `convert-timezone`.\n"+ "\n"+ "## Examples\n"+ "Top 5 customers by revenue:\n"+ "```\n"+ "{\"source\": {\"type\": \"table\", \"id\": 42},\n"+ " \"operations\": [[\"aggregate\", [\"sum\", [\"field\", 302]]],\n"+ " [\"breakout\", [\"field\", 101]],\n"+ " [\"order-by\", [\"aggregation-ref\", 0], \"desc\"],\n"+ " [\"limit\", 5]]}\n"+ "```\n"+ "Monthly revenue from a metric (metric supplies the aggregation):\n"+ "```\n"+ "{\"source\": {\"type\": \"metric\", \"id\": 10},\n"+ " \"operations\": [[\"breakout\", [\"with-temporal-bucket\", [\"field\", 305], \"month\"]],\n"+ " [\"order-by\", [\"with-temporal-bucket\", [\"field\", 305], \"month\"], \"asc\"]]}\n"+ "```\n"+ "Filter on an aggregated value (requires `append-stage`):\n"+ "```\n"+ "{\"source\": {\"type\": \"table\", \"id\": 42},\n"+ " \"operations\": [[\"aggregate\", [\"sum\", [\"field\", 302]]],\n"+ " [\"breakout\", [\"field\", 101]],\n"+ " [\"append-stage\"],\n"+ " [\"filter\", [\">\", [\"aggregation-ref\", 0], 1000]]]}\n"+ "```\n"+ "Named expression referenced later:\n"+ "```\n"+ "{\"source\": {\"type\": \"table\", \"id\": 42},\n"+ " \"operations\": [[\"expression\", \"Discount\", [\"-\", [\"field\", 302], [\"field\", 303]]],\n"+ " [\"aggregate\", [\"sum\", [\"expression-ref\", \"Discount\"]]]]}\n"+ "```\n"+ "Previous-period comparison with `offset` (stay in the SAME stage — do NOT add `append-stage`):\n"+ "```\n"+ "{\"source\": {\"type\": \"table\", \"id\": 42},\n"+ " \"operations\": [[\"aggregate\", [\"sum\", [\"field\", 302]]],\n"+ " [\"aggregate\", [\"offset\", [\"sum\", [\"field\", 302]], -1]],\n"+ " [\"breakout\", [\"with-temporal-bucket\", [\"field\", 305], \"month\"]]]}\n"+ "```\n"+ "\n"+ "## Rules & common pitfalls\n"+ "Stage boundaries (most common source of errors):\n"+ "- Filtering on an aggregated value REQUIRES `append-stage` between the aggregate/breakout and the filter "+ "(see the \"filter on aggregated value\" example). Without it, `aggregation-ref` resolution fails in the same stage.\n"+ "- Defining an `expression` that uses `aggregation-ref` also REQUIRES `append-stage` first.\n"+ "- EXCEPTION: `offset` (previous-period comparison) stays in the same stage as its base aggregation and breakout — do NOT add `append-stage` for it.\n"+ "\n"+ "Refs & shapes:\n"+ "- Aggregation helpers take field refs, not bare IDs: `[\"sum\", [\"field\", 201]]`, never `[\"sum\", 201]`.\n"+ "- To sort by an aggregated value, use `[\"aggregation-ref\", N]` — not the original expression.\n"+ "- Do NOT put options in a third slot of `field` (no `[\"field\", id, {...}]`). Wrap instead: `[\"with-temporal-bucket\", [\"field\", id], \"month\"]` or `[\"with-binning\", [\"field\", id], {...}]`.\n"+ "- `case` takes `[[condition, value], ...]` branches and an optional bare fallback as the THIRD arg — do not wrap it as `{\"default\": ...}`. Omit the third arg when there is no fallback.\n"+ "- JSON objects appear only where a helper explicitly calls for one (e.g. `with-page`, `with-binning`). Everywhere else, use operator tuples.\n"+ "\n"+ "Joins & related tables:\n"+ "- If the source table's detail response already surfaces a related table's fields, use those field refs directly — no explicit join needed.\n"+ "- Reach for `join` + `with-join-conditions` only for custom aliases, self-joins, explicit joined-field selection, or when direct related-field refs are unavailable.\n"+ "- If an explicit join returns a permission error, the underlying table is not accessible — surface the error, do not retry with implicit refs.\n"+ "\n"+ "Metrics & dates:\n"+ "- A `metric` source already provides its own aggregation and time dimension. Add only the additional breakouts/filters you need.\n"+ "- When the user asks for an exact year (e.g. 2024), use `[\"=\", [\"field\", year_field], 2024]` or a `between` with explicit dates — not relative filters like `time-interval`.\n"))+(defn- evaluate-program-to-live-query"Resolve a program's source entity, evaluate the program via agent-lib, and returnthe live lib query (with lib metadata attached)."@@ -400,13 +524,7 @@/v1/execute. See the agent_api reference for the full program syntax."{:scope metabot/agent-query-construct:tool {:name "construct_query"- :description (str "Construct a Metabase query from a structured program. "- "The body is a JSON object with `source` and `operations` keys "- "where source identifies the table/card/dataset/metric to query "- "(e.g. {\"type\": \"table\", \"id\": 42}) and operations is an "- "array of operator tuples (filter, aggregate, breakout, expression, "- "with-fields, order-by, limit, join, append-stage, etc.). Returns "- "an opaque query string that can be executed with execute_query.")+ :description construct-query-tool-description:annotations {:read-only? true :idempotent? true}}}[_route-params_query-paramsdiff --git a/src/metabase/agent_lib/eval/args.clj b/src/metabase/agent_lib/eval/args.cljindex 9e4f2d50cf2..c6f0020d97a 100644--- a/src/metabase/agent_lib/eval/args.clj+++ b/src/metabase/agent_lib/eval/args.clj@@ -25,6 +25,10 @@"Allowed string enum values for explicit joined-field selection."#{"all" "none"})+(def binning-strategy-values+ "Allowed string enum values for binning strategy."+ #{"bin-width" "default" "num-bins"})+(set! *warn-on-reflection* true)(defn keyword-enum@@ -79,6 +83,17 @@"with-temporal-bucket"(update args 1 #(keyword-enum (conj path 2) "temporal bucket" % temporal-unit-values))+ "with-binning"+ (update args 1 (fn [binning]+ (if (and (map? binning)+ (some? (:strategy binning)))+ (update binning :strategy+ #(keyword-enum (conj path 2 :strategy)+ "binning strategy"+ %+ binning-strategy-values))+ binning)))+"interval"(update args 1 #(keyword-enum (conj path 2) "interval unit" % temporal-unit-values))diff --git a/src/metabase/agent_lib/mbql_integration/field_resolution.clj b/src/metabase/agent_lib/mbql_integration/field_resolution.cljindex 8ff51200549..3a810b1cf30 100644--- a/src/metabase/agent_lib/mbql_integration/field_resolution.clj+++ b/src/metabase/agent_lib/mbql_integration/field_resolution.clj@@ -2,6 +2,7 @@"Field-resolution helpers for the agent-lib MBQL bridge."(:require[clojure.set :as set]+ [clojure.string :as str][metabase.agent-lib.mbql-integration.common :as common][metabase.lib.core :as lib][metabase.lib.util :as lib.util]))@@ -268,6 +269,45 @@[strategies](some (fn [{:keys [resolve-fn]}] (resolve-fn)) strategies))+(defn- summarize-candidate+ "Compact shape of a candidate column for inclusion in field-resolution errors."+ [candidate]+ (let [field-name (source-column-field-name candidate)+ join-alias (source-column-field-join-alias candidate)]+ (cond-> {}+ (:id candidate) (assoc :id (:id candidate))+ field-name (assoc :name field-name)+ (:table-id candidate) (assoc :table-id (:table-id candidate))+ join-alias (assoc :join-alias join-alias))))++(defn- format-candidate-line+ [{:keys [id name table-id join-alias]}]+ (str "- " (or name "?")+ " (id=" (or id "?")+ (when table-id (str ", table-id=" table-id))+ (when join-alias (str ", join-alias=" (pr-str join-alias)))+ ")"))++(def ^:private max-candidates-in-error 20)++(defn- unavailable-field-error+ [raw-field query candidates]+ (let [summaries (mapv summarize-candidate candidates)+ shown (take max-candidates-in-error summaries)+ extra (max 0 (- (count summaries) max-candidates-in-error))+ fields-block (if (seq shown)+ (str "Fields available in this stage:\n"+ (str/join "\n" (mapv format-candidate-line shown))+ (when (pos? extra) (str "\n... and " extra " more")))+ "No fields are visible in this stage.")]+ (ex-info (str "Field " (pr-str (:name raw-field))+ " (id " (pr-str (:id raw-field))+ ") is not available in the current query stage.\n"+ fields-block)+ {:field raw-field+ :query query+ :available-fields summaries})))+(defn resolve-field-in-query"Resolve a metadata field against what the current query stage actuallyexposes.@@ -307,8 +347,4 @@:resolve-fn #(common/unique-query-candidate (by-id+tbl))}{:name :exact-id:resolve-fn #(common/unique-query-candidate (by-id))}])- (throw (ex-info (str "Field " (pr-str (:name raw-field))- " (id " (pr-str (:id raw-field))- ") is not available in the current query stage.")- {:field raw-field- :query query}))))))+ (throw (unavailable-field-error raw-field query candidates))))))diff --git a/src/metabase/agent_lib/repair/normalize.clj b/src/metabase/agent_lib/repair/normalize.cljindex b45744890b2..56456f76ce4 100644--- a/src/metabase/agent_lib/repair/normalize.clj+++ b/src/metabase/agent_lib/repair/normalize.clj@@ -29,6 +29,9 @@(contains? value :id))(update value :id coerce-positive-int)+ (normalize.forms/field-like-map? value)+ (repair-node (normalize.forms/repair-field-like-map value))+:else(into {}(map (fn [[k v]] [k (repair-node v)]))diff --git a/src/metabase/agent_lib/repair/normalize/forms.clj b/src/metabase/agent_lib/repair/normalize/forms.cljindex 2fd6944ff67..0df9beec408 100644--- a/src/metabase/agent_lib/repair/normalize/forms.clj+++ b/src/metabase/agent_lib/repair/normalize/forms.clj@@ -24,6 +24,59 @@"month-of-year" "get-month""quarter-of-year" "get-quarter"})+(defn- option-value+ "Read the first present key from `options`, accepting either string or keyword keys."+ [options & ks]+ (reduce (fn [_ k]+ (let [v (or (get options (name k)) (get options (keyword k)))]+ (if (some? v) (reduced v) nil)))+ nil+ ks))++(defn- wrap-field-with-options+ "Rewrite a non-canonical `[\"field\" id {opts}]` tuple into the canonical+ wrapper forms (`with-temporal-bucket`, `with-binning`) the runtime accepts."+ [field-form options]+ (let [temporal-unit (option-value options :temporal-unit)+ binning (option-value options :binning)+ with-temporal (if (some? temporal-unit)+ ["with-temporal-bucket" field-form temporal-unit]+ field-form)]+ (if (some? binning)+ ["with-binning" with-temporal binning]+ with-temporal)))++(def ^:private field-like-map-id-keys+ ["field_id" "field-id" :field_id :field-id])++(defn field-like-map?+ "True when `value` is a plain map that describes a field reference by carrying+ a `:field_id`/`:field-id` key."+ [value]+ (boolean (and (map? value)+ (some #(some? (get value %)) field-like-map-id-keys))))++(defn repair-field-like-map+ "Convert a field-like map (e.g. `{\"field_id\" 13 \"temporal_bucket\" \"month\"}`)+ into the canonical nested operator form the runtime accepts.++ Supports optional `temporal_bucket`/`temporal-unit`, `binning`, and `direction`+ keys. When `direction` is present, the result is wrapped in `asc`/`desc`."+ [m]+ (let [field-id (option-value m :field_id :field-id)+ temporal-unit (option-value m :temporal_bucket :temporal-bucket+ :temporal_unit :temporal-unit)+ binning (option-value m :binning)+ direction (option-value m :direction)+ field-form (cond-> ["field" (coerce-positive-int field-id)]+ (some? temporal-unit) (wrap-field-with-options+ {"temporal-unit" temporal-unit})+ (some? binning) (wrap-field-with-options+ {"binning" binning}))]+ (if (coercions/direction-string? direction)+ [(coercions/normalize-direction direction) field-form]+ field-form)))+(defn expression-definition-tuple?"True when `value` is an inline expression definition tuple."[value]@@ -188,7 +241,14 @@(unwrap-singleton-form arg'))))raw-args)](case op-name- ("field" "table" "card" "metric" "measure")+ "field"+ (let [id (coerce-positive-int (first args))+ maybe-opt (second args)]+ (if (map? maybe-opt)+ (wrap-field-with-options [op-name id] maybe-opt)+ [op-name id]))++ ("table" "card" "metric" "measure")[op-name (coerce-positive-int (first args))]"aggregation-ref"diff --git a/src/metabase/agent_lib/repair/normalize/top_level.clj b/src/metabase/agent_lib/repair/normalize/top_level.cljindex 2c046749a92..5c51e76698b 100644--- a/src/metabase/agent_lib/repair/normalize/top_level.clj+++ b/src/metabase/agent_lib/repair/normalize/top_level.clj@@ -25,31 +25,51 @@:else(vec args)))+(defn- direction-tuple?+ [value]+ (and (vector? value)+ (= 2 (count value))+ (direction-string? (first value))))++(defn- unwrap-order-by-args+ "Unwrap a single sequential argument into its elements so `[[asc ...] [desc ...]]`+ behaves like `[asc ...] [desc ...]` passed directly. Only unwraps when the inner+ sequence is entirely `[direction value]` tuples so we don't rewrite unrelated+ shapes and break idempotence."+ [args]+ (if (and (= 1 (count args))+ (sequential? (first args))+ (seq (first args))+ (every? direction-tuple? (first args)))+ (vec (first args))+ args))+(defn repair-order-by-operations"Normalize one or more `order-by` arguments into canonical operations."[args]- (if (empty? args)- [["order-by"]]- (loop [remaining args- repaired []]- (if (empty? remaining)- repaired- (let [[first-arg second-arg & tail] remaining]- (cond- (and (vector? first-arg)- (= 2 (count first-arg))- (direction-string? (first first-arg)))- (recur (vec (rest remaining))- (conj repaired ["order-by" [(normalize-direction (first first-arg))- (second first-arg)]]))-- (direction-string? second-arg)- (recur (vec tail)- (conj repaired ["order-by" first-arg (normalize-direction second-arg)]))-- :else- (recur (vec (rest remaining))- (conj repaired ["order-by" first-arg]))))))))+ (let [args (unwrap-order-by-args args)]+ (if (empty? args)+ [["order-by"]]+ (loop [remaining args+ repaired []]+ (if (empty? remaining)+ repaired+ (let [[first-arg second-arg & tail] remaining]+ (cond+ (and (vector? first-arg)+ (= 2 (count first-arg))+ (direction-string? (first first-arg)))+ (recur (vec (rest remaining))+ (conj repaired ["order-by" [(normalize-direction (first first-arg))+ (second first-arg)]]))++ (direction-string? second-arg)+ (recur (vec tail)+ (conj repaired ["order-by" first-arg (normalize-direction second-arg)]))++ :else+ (recur (vec (rest remaining))+ (conj repaired ["order-by" first-arg])))))))))(defn repair-repeated-single-arg-op"Expand repeated top-level single-arg operations."diff --git a/src/metabase/metabot/agent/links.clj b/src/metabase/metabot/agent/links.cljindex 15a7ab58ab7..ff437d942b9 100644--- a/src/metabase/metabot/agent/links.clj+++ b/src/metabase/metabot/agent/links.clj@@ -36,16 +36,19 @@(let [dataset-query (if (and (map? query) (:lib/type query))(lib/->legacy-MBQL query)query)]- (-> {:dataset_query dataset-query}+ (-> {:dataset_query dataset-query+ :type "question"+ :visualization_settings {}}json/encode(.getBytes "UTF-8")codecs/bytes->b64-str)))(defn pseudo-card->link- "Convert map with relevant card keys into a link. Relevant keys are e.g. dataset_query, display, displayIsLocked."+ "Convert map with relevant card keys into a link. Relevant keys are e.g. dataset_query, display, displayIsLocked.+ `:visualization_settings` defaults to `{}` so the frontend always gets a populated map to read chart settings from."[pc](str "/question#"- (-> pc+ (-> (merge {:visualization_settings {}} pc)json/encode(.getBytes "UTF-8")codecs/bytes->b64-str)))diff --git a/src/metabase/metabot/tools/resources.clj b/src/metabase/metabot/tools/resources.cljindex 08376578e8f..8e76fcbdc58 100644--- a/src/metabase/metabot/tools/resources.clj+++ b/src/metabase/metabot/tools/resources.clj@@ -82,7 +82,7 @@:entity-id table-id:with-fields? true:with-field-values? false- :with-related-tables? false+ :with-related-tables? true:with-measures? true:with-segments? true})@@ -92,7 +92,7 @@:entity-id table-id:with-fields? false:with-field-values? false- :with-related-tables? false+ :with-related-tables? true:with-measures? true:with-segments? true})diff --git a/src/metabase/metabot/tools/search.clj b/src/metabase/metabot/tools/search.cljindex 74b83b5d7f3..3172bb4a04f 100644--- a/src/metabase/metabot/tools/search.clj+++ b/src/metabase/metabot/tools/search.clj@@ -23,7 +23,7 @@(set! *warn-on-reflection* true)(def ^:private metabot-search-models- #{"table" "dataset" "card" "dashboard" "metric" "database" "transform"})+ (sorted-set "card" "dashboard" "database" "dataset" "metric" "table" "transform"))(defn- postprocess-search-result"Transform a single search result to match the appropriate entity-specific schema."@@ -258,17 +258,21 @@(when (seq entity-types)(seq (remove allowed entity-types))))+(def ^:private default-search-limit 10)+(def ^:private max-search-limit 50)+(defn- do-search- [label allowed-types search-opts {:keys [semantic_queries keyword_queries entity_types] :as _args}]+ [label allowed-types search-opts {:keys [semantic_queries keyword_queries entity_types limit] :as _args}](if-let [invalid (invalid-entity-types entity_types allowed-types)]{:output (str "Invalid entity_types for " label ": " (pr-str (vec invalid))- ". Allowed types: " (str/join ", " (sort allowed-types)) ".")}+ ". Allowed types: " (str/join ", " allowed-types) ".")}(try(let [results (search (merge {:semantic-queries semantic_queries:term-queries keyword_queries- :entity-types entity_types+ :entity-types (or (seq entity_types) (vec allowed-types)):metabot-id shared/*metabot-id*- :limit 10}+ :limit (min max-search-limit+ (or limit default-search-limit))}search-opts))]{:output (format-search-output results):structured-output {:result-type :search@@ -283,14 +287,15 @@[:semantic_queries {:optional true :feature :semantic-search} [:sequential :string]][:keyword_queries {:optional true} [:sequential :string]][:entity_types {:optional true}- [:maybe [:sequential [:enum "table" "model" "metric" "dashboard" "question"]]]]])+ [:maybe [:sequential [:enum "table" "model" "metric" "dashboard" "question"]]]]+ [:limit {:optional true} [:maybe [:int {:min 1 :max max-search-limit}]]]])(mu/defn ^{:tool-name "search":scope scope/agent-search}search-tool"Search for tables, models, metrics, dashboards, and saved questions."[args :- search-schema]- (do-search "search" #{"table" "model" "metric" "dashboard" "question"} {} args))+ (do-search "search" (sorted-set "dashboard" "metric" "model" "question" "table") {} args))(def ^:private sql-search-schema[:map {:closed true}@@ -298,7 +303,8 @@[:keyword_queries {:optional true} [:sequential :string]][:database_id :int][:entity_types {:optional true}- [:maybe [:sequential [:enum "table" "model"]]]]])+ [:maybe [:sequential [:enum "table" "model"]]]]+ [:limit {:optional true} [:maybe [:int {:min 1 :max max-search-limit}]]]])(mu/defn ^{:tool-name "search":prompt "sql_search.md"@@ -306,22 +312,23 @@sql-search-tool"Search for SQL-queryable data sources (tables and models) within a database."[{:keys [database_id] :as args} :- sql-search-schema]- (do-search "SQL search" #{"table" "model"} {:database-id database_id} args))+ (do-search "SQL search" (sorted-set "model" "table") {:database-id database_id} args))(def ^:private nlq-search-schema[:map {:closed true}[:semantic_queries {:optional true :feature :semantic-search} [:sequential :string]][:keyword_queries {:optional true} [:sequential :string]][:entity_types {:optional true}- [:maybe [:sequential [:enum "model" "metric" "table"]]]]])+ [:maybe [:sequential [:enum "table" "model" "metric" "question"]]]]+ [:limit {:optional true} [:maybe [:int {:min 1 :max max-search-limit}]]]])(mu/defn ^{:tool-name "search":prompt "nlq_search.md":scope scope/agent-search}nlq-search-tool- "Search for NLQ-queryable data sources (models, metrics, tables)."+ "Search for NLQ-queryable data sources (tables, models, metrics, questions)."[args :- nlq-search-schema]- (do-search "NLQ search" #{"model" "metric" "table"} {:profile-id "nlq"} args))+ (do-search "NLQ search" (sorted-set "metric" "model" "question" "table") {:profile-id "nlq"} args))(def ^:private transform-search-schema[:map {:closed true}@@ -329,7 +336,8 @@[:keyword_queries {:optional true} [:sequential :string]][:search_native_query {:optional true} [:maybe :boolean]][:entity_types {:optional true}- [:maybe [:sequential [:enum "table" "model" "transform"]]]]])+ [:maybe [:sequential [:enum "table" "model" "transform"]]]]+ [:limit {:optional true} [:maybe [:int {:min 1 :max max-search-limit}]]]])(mu/defn ^{:tool-name "search":prompt "transform_search"@@ -337,5 +345,5 @@transform-search-tool"Search for transforms, tables, and models."[{:keys [search_native_query] :as args} :- transform-search-schema]- (do-search "transform search" #{"table" "model" "transform"}+ (do-search "transform search" (sorted-set "model" "table" "transform"){:search-native-query search_native_query} args))diff --git a/test/metabase/agent_lib/eval_test.clj b/test/metabase/agent_lib/eval_test.cljindex fb8624dd48f..d6f82e0033a 100644--- a/test/metabase/agent_lib/eval_test.clj+++ b/test/metabase/agent_lib/eval_test.clj@@ -677,3 +677,88 @@(is (not (re-find #"named expressions must be non-aggregation only"(:details (ex-data program-error)))))(is (= :invalid-generated-program (:error (ex-data program-error)))))))++(deftest ^:parallel field-options-temporal-unit-parity-test+ (testing "`[\"field\" id {\"temporal-unit\" ...}]` is equivalent to `with-temporal-bucket`"+ (let [created-at (meta/field-metadata :orders :created-at)+ program {:source {:type "context" :ref "source"}+ :operations [["aggregate" ["sum" ["field" (meta/id :orders :total)]]]+ ["breakout" ["field" (meta/id :orders :created-at)+ {"temporal-unit" "month"}]]+ ["order-by" ["field" (meta/id :orders :created-at)+ {"temporal-unit" "month"}] "asc"]]}+ expected (-> (tu/query-for-table :orders)+ (lib/aggregate (lib/sum (meta/field-metadata :orders :total)))+ (lib/breakout (lib/with-temporal-bucket created-at :month))+ (lib/order-by (lib/with-temporal-bucket created-at :month) :asc))]+ (is (= (tu/comparable-query expected)+ (-> (program/evaluate-program program meta/metadata-provider (tu/table-context :orders))+ tu/comparable-query))))))++(deftest ^:parallel field-options-binning-parity-test+ (testing "`[\"field\" id {\"binning\" ...}]` is equivalent to `with-binning`"+ (let [total (meta/field-metadata :orders :total)+ binning {:strategy :num-bins :num-bins 10}+ program {:source {:type "context" :ref "source"}+ :operations [["aggregate" ["count"]]+ ["breakout" ["field" (meta/id :orders :total)+ {"binning" {"strategy" "num-bins"+ "num-bins" 10}}]]]}+ expected (-> (tu/query-for-table :orders)+ (lib/aggregate (lib/count))+ (lib/breakout (lib/with-binning total binning)))]+ (is (= (tu/comparable-query expected)+ (-> (program/evaluate-program program meta/metadata-provider (tu/table-context :orders))+ tu/comparable-query))))))++(deftest ^:parallel field-options-combined-parity-test+ (testing "`[\"field\" id {temporal-unit ... binning ...}]` composes both wrappers"+ (let [created-at (meta/field-metadata :orders :created-at)+ program {:source {:type "context" :ref "source"}+ :operations [["aggregate" ["count"]]+ ["breakout" ["field" (meta/id :orders :created-at)+ {"temporal-unit" "month"+ "binning" {"strategy" "default"}}]]]}+ expected (-> (tu/query-for-table :orders)+ (lib/aggregate (lib/count))+ (lib/breakout (-> created-at+ (lib/with-temporal-bucket :month)+ (lib/with-binning {:strategy :default}))))]+ (is (= (tu/comparable-query expected)+ (-> (program/evaluate-program program meta/metadata-provider (tu/table-context :orders))+ tu/comparable-query))))))++(deftest ^:parallel field-like-map-breakout-and-order-by-vector-wrapper-parity-test+ (testing "field-like maps inside breakout and a vector-wrapped order-by yield canonical MBQL"+ (let [created-at (meta/field-metadata :orders :created-at)+ program {:source {:type "context" :ref "source"}+ :operations [["aggregate" ["count"]]+ ["breakout" {"field_id" (meta/id :orders :created-at)+ "temporal_bucket" "month"}]+ ["order-by" [["asc" {"field_id" (meta/id :orders :created-at)+ "temporal_bucket" "month"}]]]]}+ expected (-> (tu/query-for-table :orders)+ (lib/aggregate (lib/count))+ (lib/breakout (lib/with-temporal-bucket created-at :month))+ (lib/order-by (lib/with-temporal-bucket created-at :month) :asc))]+ (is (= (tu/comparable-query expected)+ (-> (program/evaluate-program program meta/metadata-provider (tu/table-context :orders))+ tu/comparable-query))))))++(deftest ^:parallel field-like-map-order-by-with-direction-key-parity-test+ (testing "an order-by field-like map with a `direction` key yields canonical MBQL"+ (let [created-at (meta/field-metadata :orders :created-at)+ program {:source {:type "context" :ref "source"}+ :operations [["aggregate" ["count"]]+ ["breakout" {"field_id" (meta/id :orders :created-at)+ "temporal_bucket" "month"}]+ ["order-by" {"field_id" (meta/id :orders :created-at)+ "temporal_bucket" "month"+ "direction" "asc"}]]}+ expected (-> (tu/query-for-table :orders)+ (lib/aggregate (lib/count))+ (lib/breakout (lib/with-temporal-bucket created-at :month))+ (lib/order-by (lib/with-temporal-bucket created-at :month) :asc))]+ (is (= (tu/comparable-query expected)+ (-> (program/evaluate-program program meta/metadata-provider (tu/table-context :orders))+ tu/comparable-query))))))diff --git a/test/metabase/agent_lib/repair/normalize/forms_test.clj b/test/metabase/agent_lib/repair/normalize/forms_test.cljindex 2727abbad05..d279df0fb87 100644--- a/test/metabase/agent_lib/repair/normalize/forms_test.clj+++ b/test/metabase/agent_lib/repair/normalize/forms_test.clj@@ -77,6 +77,74 @@(is (= ["field" 42](forms/repair-operator-form identity ["field" "42"])))))+(deftest ^:parallel field-like-map?-test+ (testing "accepts snake_case and kebab-case, string and keyword keys"+ (is (true? (forms/field-like-map? {"field_id" 1})))+ (is (true? (forms/field-like-map? {"field-id" 1})))+ (is (true? (forms/field-like-map? {:field_id 1})))+ (is (true? (forms/field-like-map? {:field-id 1}))))+ (testing "rejects non-field-like maps"+ (is (false? (forms/field-like-map? {"foo" 1})))+ (is (false? (forms/field-like-map? {})))+ (is (false? (forms/field-like-map? nil)))+ (is (false? (forms/field-like-map? ["field" 1])))))++(deftest ^:parallel repair-field-like-map-test+ (testing "field_id alone becomes a plain field form"+ (is (= ["field" 13]+ (forms/repair-field-like-map {"field_id" 13}))))+ (testing "temporal_bucket wraps in with-temporal-bucket"+ (is (= ["with-temporal-bucket" ["field" 13] "month"]+ (forms/repair-field-like-map {"field_id" 13 "temporal_bucket" "month"}))))+ (testing "temporal-unit alias is accepted"+ (is (= ["with-temporal-bucket" ["field" 13] "month"]+ (forms/repair-field-like-map {"field_id" 13 "temporal-unit" "month"}))))+ (testing "binning wraps in with-binning"+ (is (= ["with-binning" ["field" 13] {"strategy" "num-bins" "num-bins" 10}]+ (forms/repair-field-like-map {"field_id" 13+ "binning" {"strategy" "num-bins" "num-bins" 10}}))))+ (testing "direction wraps in asc/desc"+ (is (= ["asc" ["field" 13]]+ (forms/repair-field-like-map {"field_id" 13 "direction" "asc"})))+ (is (= ["desc" ["field" 13]]+ (forms/repair-field-like-map {"field_id" 13 "direction" "DESC"}))))+ (testing "combined options nest in canonical order: direction wraps the bucketed/binned field"+ (is (= ["asc" ["with-temporal-bucket" ["field" 13] "month"]]+ (forms/repair-field-like-map {"field_id" 13+ "temporal_bucket" "month"+ "direction" "asc"}))))+ (testing "keyword keys are also accepted"+ (is (= ["with-temporal-bucket" ["field" 13] "month"]+ (forms/repair-field-like-map {:field_id 13 :temporal_bucket "month"}))))+ (testing "string id is coerced to integer"+ (is (= ["field" 13]+ (forms/repair-field-like-map {"field_id" "13"})))))++(deftest ^:parallel repair-operator-form-field-options-map-test+ (testing "field with temporal-unit option rewrites to with-temporal-bucket wrapper"+ (is (= ["with-temporal-bucket" ["field" 13] "month"]+ (forms/repair-operator-form identity ["field" 13 {"temporal-unit" "month"}]))))+ (testing "field with binning option rewrites to with-binning wrapper"+ (is (= ["with-binning" ["field" 13] {"strategy" "num-bins" "num-bins" 10}]+ (forms/repair-operator-form identity+ ["field" 13 {"binning" {"strategy" "num-bins" "num-bins" 10}}]))))+ (testing "field with both options nests with-binning outside with-temporal-bucket"+ (is (= ["with-binning"+ ["with-temporal-bucket" ["field" 13] "month"]+ {"strategy" "default"}]+ (forms/repair-operator-form identity+ ["field" 13 {"temporal-unit" "month"+ "binning" {"strategy" "default"}}]))))+ (testing "empty options map leaves field untouched"+ (is (= ["field" 13]+ (forms/repair-operator-form identity ["field" 13 {}]))))+ (testing "keyword option keys are accepted"+ (is (= ["with-temporal-bucket" ["field" 13] "month"]+ (forms/repair-operator-form identity ["field" 13 {:temporal-unit "month"}]))))+ (testing "string field id is still coerced when options are present"+ (is (= ["with-temporal-bucket" ["field" 13] "month"]+ (forms/repair-operator-form identity ["field" "13" {"temporal-unit" "month"}])))))+(deftest ^:parallel repair-operator-form-is-null-test(testing "is with null becomes is-null"(is (= ["is-null" ["field" 1]]diff --git a/test/metabase/agent_lib/repair_test.clj b/test/metabase/agent_lib/repair_test.cljindex 508a74ef1c5..b34153d044a 100644--- a/test/metabase/agent_lib/repair_test.clj+++ b/test/metabase/agent_lib/repair_test.clj@@ -197,3 +197,28 @@["relative-datetime" 0 "quarter"]]]]}](is (= expected(repair/repair-program-for-context (repair/repair-program program) context)))))++(deftest ^:parallel repair-program-normalizes-field-like-map-in-breakout-test+ (let [program {:source {:type "table" :id 1}+ :operations [["breakout" {"field_id" 13 "temporal_bucket" "month"}]]}+ expected {:source {:type "table" :id 1}+ :operations [["breakout" ["with-temporal-bucket" ["field" 13] "month"]]]}]+ (is (= expected (repair/repair-program program)))))++(deftest ^:parallel repair-program-unwraps-order-by-vector-of-direction-tuples-test+ (let [program {:source {:type "table" :id 1}+ :operations [["order-by" [["asc" {"field_id" 13 "temporal_bucket" "month"}]+ ["desc" {"field_id" 14}]]]]}+ expected {:source {:type "table" :id 1}+ :operations [["order-by" ["asc" ["with-temporal-bucket" ["field" 13] "month"]]]+ ["order-by" ["desc" ["field" 14]]]]}]+ (is (= expected (repair/repair-program program)))))++(deftest ^:parallel repair-program-normalizes-order-by-map-with-direction-key-test+ (let [program {:source {:type "table" :id 1}+ :operations [["order-by" {"field_id" 13+ "temporal_bucket" "month"+ "direction" "asc"}]]}+ expected {:source {:type "table" :id 1}+ :operations [["order-by" ["asc" ["with-temporal-bucket" ["field" 13] "month"]]]]}]+ (is (= expected (repair/repair-program program)))))diff --git a/test/metabase/agent_lib/runtime/fields_test.clj b/test/metabase/agent_lib/runtime/fields_test.cljindex 25daa5b58de..7f2e82905a0 100644--- a/test/metabase/agent_lib/runtime/fields_test.clj+++ b/test/metabase/agent_lib/runtime/fields_test.clj@@ -143,3 +143,68 @@(with-redefs [mbql/current-query-field-candidates(constantly [previous-stage])](runtime.fields/resolve-field-in-query {} ::query raw-field))))))++(deftest unavailable-field-error-enumerates-available-fields-test+ (let [raw-field {:id 999 :table-id 88 :name "not_there" :base-type :type/Text}+ candidate1 {:id 100 :table-id 10 :name "first_name" :base-type :type/Text}+ candidate2 {:id 101 :table-id 10 :name "last_name" :base-type :type/Text}]+ (try+ (with-redefs [mbql/current-query-field-candidates+ (constantly [candidate1 candidate2])]+ (runtime.fields/resolve-field-in-query {} ::query raw-field))+ (is false "expected ex-info to be thrown")+ (catch clojure.lang.ExceptionInfo e+ (let [msg (ex-message e)+ data (ex-data e)]+ (is (re-find #"first_name" msg))+ (is (re-find #"id=100" msg))+ (is (re-find #"last_name" msg))+ (is (= [{:id 100 :name "first_name" :table-id 10}+ {:id 101 :name "last_name" :table-id 10}]+ (:available-fields data))))))))++(deftest unavailable-field-error-includes-join-alias-in-summary-test+ (let [raw-field {:id 999 :table-id 88 :name "not_there" :base-type :type/Text}+ candidate {:id 200 :table-id 20 :name "customer_id" :base-type :type/Integer+ :lib/join-alias "Customers"}]+ (try+ (with-redefs [mbql/current-query-field-candidates (constantly [candidate])]+ (runtime.fields/resolve-field-in-query {} ::query raw-field))+ (is false "expected ex-info to be thrown")+ (catch clojure.lang.ExceptionInfo e+ (let [msg (ex-message e)+ data (ex-data e)+ summary (first (:available-fields data))]+ (is (= "Customers" (:join-alias summary)))+ (is (re-find #"join-alias=\"Customers\"" msg)))))))++(deftest unavailable-field-error-suppresses-listing-when-no-candidates-test+ (let [raw-field {:id 999 :table-id 88 :name "not_there" :base-type :type/Text}]+ (try+ (with-redefs [mbql/current-query-field-candidates (constantly [])]+ (runtime.fields/resolve-field-in-query {} ::query raw-field))+ (is false "expected ex-info to be thrown")+ (catch clojure.lang.ExceptionInfo e+ (let [msg (ex-message e)+ data (ex-data e)]+ (is (re-find #"No fields are visible in this stage" msg))+ (is (not (re-find #"Fields available in this stage" msg)))+ (is (= [] (:available-fields data))))))))++(deftest unavailable-field-error-caps-listed-candidates-test+ (let [raw-field {:id 999 :table-id 88 :name "not_there" :base-type :type/Text}+ candidates (mapv (fn [i]+ {:id (+ 1000 i) :table-id 10+ :name (str "field_" i) :base-type :type/Text})+ (range 25))]+ (try+ (with-redefs [mbql/current-query-field-candidates (constantly candidates)]+ (runtime.fields/resolve-field-in-query {} ::query raw-field))+ (is false "expected ex-info to be thrown")+ (catch clojure.lang.ExceptionInfo e+ (let [msg (ex-message e)+ data (ex-data e)]+ ;; all candidates captured in ex-data+ (is (= 25 (count (:available-fields data))))+ ;; message truncates with an "and N more" line+ (is (re-find #"and 5 more" msg)))))))diff --git a/test/metabase/metabot/agent/links_test.clj b/test/metabase/metabot/agent/links_test.cljindex 569429b8189..d79bc691bc6 100644--- a/test/metabase/metabot/agent/links_test.clj+++ b/test/metabase/metabot/agent/links_test.clj@@ -6,7 +6,17 @@[metabase.lib.test-metadata :as meta][metabase.lib.test-util :as lib.tu][metabase.metabot.agent.links :as links]- [metabase.test :as mt]))+ [metabase.test :as mt]+ [metabase.util :as u]+ [metabase.util.json :as json]))++(defn- decode-question-url+ "Decode a `/question#<base64>` URL into its JSON-decoded pseudo-card map."+ [url]+ (-> url+ (subs (count "/question#"))+ u/decode-base64+ (json/decode+kw)));;; resolve-metabase-uri tests@@ -20,6 +30,19 @@(is (string? result))(is (str/starts-with? result "/question#")))))+(deftest ^:parallel resolve-metabase-uri-query-link-produces-renderable-pseudo-card-test+ (testing "decoded /question# hash from a query link is a pseudo card the frontend can render"+ (let [query-id "abc-123"+ query (lib.tu/venues-query)+ result (links/resolve-metabase-uri "metabase://query/abc-123" {query-id query} {})+ decoded (decode-question-url result)]+ (testing "dataset_query is populated so the query can be executed"+ (is (map? (:dataset_query decoded)))+ (is (some? (get-in decoded [:dataset_query :database]))))+ (testing "type and visualization_settings are present so renderers like `getAlertType` don't crash"+ (is (= "question" (:type decoded)))+ (is (= {} (:visualization_settings decoded)))))))+(deftest ^:parallel resolve-metabase-uri-missing-query-test(testing "returns nil for missing query"(let [result (links/resolve-metabase-uri "metabase://query/missing" {} {})]diff --git a/test/metabase/metabot/tools/resources_test.clj b/test/metabase/metabot/tools/resources_test.cljindex 924d7d7caa5..e313fbe451b 100644--- a/test/metabase/metabot/tools/resources_test.clj+++ b/test/metabase/metabot/tools/resources_test.clj@@ -106,26 +106,6 @@(read-resource/read-resource{:uris ["metabase://table/99999"]}))))))))-(deftest read-table-resource-excludes-related-tables-test- (testing "table resources should not include related_tables (to avoid bloated responses)"- (mt/test-drivers #{:h2}- (mt/with-current-user (mt/user->id :crowberto)- ;; Use orders table which has FK relationships to other tables- (let [orders-id (mt/id :orders)]- (testing "metabase://table/:id excludes related_tables"- (let [result (read-resource/read-resource- {:uris [(str "metabase://table/" orders-id)]})- output (get-in result [:resources 0 :content :structured-output])]- (is (nil? (:related_tables output))- "table resource should not include related_tables")))-- (testing "metabase://table/:id/fields excludes related_tables"- (let [result (read-resource/read-resource- {:uris [(str "metabase://table/" orders-id "/fields")]})- output (get-in result [:resources 0 :content :structured-output])]- (is (nil? (:related_tables output))- "table/fields resource should not include related_tables"))))))))-(deftest read-dashboard-resource-test(mt/with-current-user (mt/user->id :crowberto)(mt/with-temp [:model/Dashboard {dashboard-id :id dashboard-name :name}diff --git a/test/metabase/metabot/tools/search_test.clj b/test/metabase/metabot/tools/search_test.cljindex b0c68a5075e..62a0d603fbf 100644--- a/test/metabase/metabot/tools/search_test.clj+++ b/test/metabase/metabot/tools/search_test.clj@@ -267,6 +267,69 @@:entity-types ["card"]:search-native-query nil}))))))+(deftest tool-default-entity-types-test+ (testing "tool variants restrict default entity types to their allowed set"+ (mt/with-test-user :rasta+ (with-redefs [perms/impersonated-user? (fn [] false)+ perms/sandboxed-user? (fn [] false)+ api/*current-user-id* 1]+ (testing "nlq-search-tool with no entity_types searches only table/model/metric/question"+ (let [captured (atom nil)]+ (mt/with-dynamic-fn-redefs [search-core/search (fn [context]+ (reset! captured (:models context))+ {:data []})]+ (search/nlq-search-tool {:keyword_queries ["x"]}))+ (is (= #{"table" "dataset" "metric" "card"} @captured))+ (is (not (contains? @captured "dashboard")))+ (is (not (contains? @captured "transform")))+ (is (not (contains? @captured "database")))))++ (testing "sql-search-tool with no entity_types searches only table/model"+ (let [captured (atom nil)]+ (mt/with-dynamic-fn-redefs [search-core/search (fn [context]+ (reset! captured (:models context))+ {:data []})]+ (search/sql-search-tool {:keyword_queries ["x"] :database_id 1}))+ (is (= #{"table" "dataset"} @captured))))++ (testing "agent-supplied entity_types narrow the default allowed set"+ (let [captured (atom nil)]+ (mt/with-dynamic-fn-redefs [search-core/search (fn [context]+ (reset! captured (:models context))+ {:data []})]+ (search/nlq-search-tool {:keyword_queries ["x"] :entity_types ["metric"]}))+ (is (= #{"metric"} @captured))))))))++(deftest tool-limit-test+ (testing "tool variants apply the :limit arg with default 10 and cap 50"+ (mt/with-test-user :rasta+ (with-redefs [perms/impersonated-user? (fn [] false)+ perms/sandboxed-user? (fn [] false)+ api/*current-user-id* 1]+ (testing "default limit is 10 when not provided"+ (let [captured (atom nil)]+ (mt/with-dynamic-fn-redefs [search-core/search (fn [context]+ (reset! captured (:limit-int context))+ {:data []})]+ (search/search-tool {:keyword_queries ["x"]}))+ (is (= 10 @captured))))++ (testing "explicit limit is honored"+ (let [captured (atom nil)]+ (mt/with-dynamic-fn-redefs [search-core/search (fn [context]+ (reset! captured (:limit-int context))+ {:data []})]+ (search/search-tool {:keyword_queries ["x"] :limit 25}))+ (is (= 25 @captured))))++ (testing "limit above 50 is rejected by schema validation"+ (is (thrown? Exception+ (search/search-tool {:keyword_queries ["x"] :limit 75}))))++ (testing "limit below 1 is rejected by schema validation"+ (is (thrown? Exception+ (search/search-tool {:keyword_queries ["x"] :limit 0}))))))))+(deftest other-user-collection-test(testing "excludes entities from other users' collections"(mt/with-test-user :crowberto