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
Clean up usages of 'pMBQL' in our documentation (#80390)
Cam Saula8161553664b
diff --git a/enterprise/backend/src/metabase_enterprise/audit_app/audit.clj b/enterprise/backend/src/metabase_enterprise/audit_app/audit.cljindex dd9289bc47d..80dfb2f5a79 100644--- a/enterprise/backend/src/metabase_enterprise/audit_app/audit.clj+++ b/enterprise/backend/src/metabase_enterprise/audit_app/audit.clj@@ -392,7 +392,7 @@(defn- remap-result-metadata-ref"Remap the Field ID of a single result-metadata `:field_ref` via `field-id-remap`. Handles legacy refs- (`[:field id opts]`, `[:field-id id]`, id second) and pMBQL refs (`[:field opts id]`, id last). Non-field refs and+ (`[:field id opts]`, `[:field-id id]`, id second) and MBQL 5 refs (`[:field opts id]`, id last). Non-field refs andids with no remapping are returned unchanged."[field-id-remap ref](if (and (vector? ref) (#{:field :field-id} (first ref)))diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/cli-analytics/components/CliAnalyticsSectionLayout.unit.spec.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/cli-analytics/components/CliAnalyticsSectionLayout.unit.spec.tsxindex 1873af81fd5..6407828fe45 100644--- a/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/cli-analytics/components/CliAnalyticsSectionLayout.unit.spec.tsx+++ b/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/cli-analytics/components/CliAnalyticsSectionLayout.unit.spec.tsx@@ -228,7 +228,7 @@ function setup({);}-// pMBQL order-by clause: [direction, opts, ["field", opts, fieldId]]+// MBQL 5 order-by clause: [direction, opts, ["field", opts, fieldId]]type OrderByClause = [string, unknown, [string, unknown, number]];type EventsMbqlStage = {diff --git a/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/mcp-analytics/components/McpAnalyticsSectionLayout.unit.spec.tsx b/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/mcp-analytics/components/McpAnalyticsSectionLayout.unit.spec.tsxindex 574998bb928..651ec4d6900 100644--- a/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/mcp-analytics/components/McpAnalyticsSectionLayout.unit.spec.tsx+++ b/enterprise/frontend/src/metabase-enterprise/monitor/ai-auditing/mcp-analytics/components/McpAnalyticsSectionLayout.unit.spec.tsx@@ -237,7 +237,7 @@ function setup({);}-// pMBQL order-by clause: [direction, opts, ["field", opts, fieldId]]+// MBQL 5 order-by clause: [direction, opts, ["field", opts, fieldId]]type OrderByClause = [string, unknown, [string, unknown, number]];type EventsMbqlStage = {diff --git a/src/metabase/agent_lib/representations/repair.clj b/src/metabase/agent_lib/representations/repair.cljindex 3a3f3845027..729640fb0bd 100644--- a/src/metabase/agent_lib/representations/repair.clj+++ b/src/metabase/agent_lib/representations/repair.clj@@ -1472,7 +1472,7 @@;;; canonical form with `base-type`/`effective-type` inferred from the aggregation head.;;;;;; Same-stage refs only. Cross-stage aggregation references (a stage-N+1 `:aggregation`-;;; ref pointing at a stage-N aggregation) are **out of scope** for this pass - pMBQL+;;; ref pointing at a stage-N aggregation) are **out of scope** for this pass - MBQL 5;;; actually forbids that shape; the correct downstream form is a cross-stage field ref by;;; the aggregation's column name, which Pass 4 handles once the column name is known.;;; An out-of-range or no-aggregations stage raises an `:agent-error?` ex-info with a@@ -1630,7 +1630,7 @@;;;;;; lib's canonical shape forbids `[aggregation, {}, <uuid>]` to appear inside a stage's;;; `filters:` (or `breakout:`, `expressions:`) - that's a HAVING-clause situation in SQL-;;; terms, and in pMBQL it must be expressed as a *second stage* whose `filters:` reference+;;; terms, and in MBQL 5 it must be expressed as a *second stage* whose `filters:` reference;;; the aggregation's output column by name. lib's schema is shape-only and does not catch;;; this; the broken query goes through validate, resolve, and only fails at SQL-generation;;; time (or, worse, silently produces wrong results). LLMs habitually write the single-@@ -1820,7 +1820,7 @@(some? (get stage "limit"))(seq (get stage "fields")))(throw (ex-info- (tru "Detected a post-aggregation filter alongside `order-by:`, `limit:`, or `fields:` in the same stage. pMBQL requires the filter in a separate stage, but those trailing clauses cannot be safely relocated — they may reference pre-aggregation columns that don''t survive the split. Please author this as two stages explicitly: stage 0 with `source-table`, `aggregation`, `breakout`, and any pre-aggregation `filters`; stage 1 with the post-aggregation `filters`, plus `order-by` / `limit` / `fields` that reference the aggregation''s output via cross-stage `[\"field\", (empty opts), \"<column-name>\"]` refs.")+ (tru "Detected a post-aggregation filter alongside `order-by:`, `limit:`, or `fields:` in the same stage. MBQL 5 requires the filter in a separate stage, but those trailing clauses cannot be safely relocated — they may reference pre-aggregation columns that don''t survive the split. Please author this as two stages explicitly: stage 0 with `source-table`, `aggregation`, `breakout`, and any pre-aggregation `filters`; stage 1 with the post-aggregation `filters`, plus `order-by` / `limit` / `fields` that reference the aggregation''s output via cross-stage `[\"field\", (empty opts), \"<column-name>\"]` refs."){:agent-error? true:error :post-agg-filter-with-trailing-clauses:stage stage}))@@ -1837,7 +1837,7 @@"filters" moved-filters}][s0 s1])(throw (ex-info- (tru "Detected a post-aggregation filter (a filter referencing an aggregation from the same stage). pMBQL requires this in a separate stage. Auto-fix is unsafe here — either an aggregation''s output column name cannot be derived (e.g. a `metric` reference or unknown head), or two aggregations in this stage would produce the same column name (e.g. two `sum` aggregations on different fields, which lib disambiguates as `sum` / `sum_2` based on field order). Please refactor to multi-stage manually: put the aggregations in stage 0, and the filter in stage 1 referencing the column via a cross-stage `[\"field\", (empty opts), \"<column-name>\"]` clause. Use an explicit aggregation with a `name` opts override (e.g. `[\"sum\", (opts with key \"name\" → \"sum_total\"), …]`) if you need stable cross-stage names.")+ (tru "Detected a post-aggregation filter (a filter referencing an aggregation from the same stage). MBQL 5 requires this in a separate stage. Auto-fix is unsafe here — either an aggregation''s output column name cannot be derived (e.g. a `metric` reference or unknown head), or two aggregations in this stage would produce the same column name (e.g. two `sum` aggregations on different fields, which lib disambiguates as `sum` / `sum_2` based on field order). Please refactor to multi-stage manually: put the aggregations in stage 0, and the filter in stage 1 referencing the column via a cross-stage `[\"field\", (empty opts), \"<column-name>\"]` clause. Use an explicit aggregation with a `name` opts override (e.g. `[\"sum\", (opts with key \"name\" → \"sum_total\"), …]`) if you need stable cross-stage names."){:agent-error? true:error :post-agg-filter-needs-multi-stage:stage stage}))))))))diff --git a/src/metabase/agent_lib/representations/resolve.clj b/src/metabase/agent_lib/representations/resolve.cljindex 27cfb4a272d..6b71ee2ae9d 100644--- a/src/metabase/agent_lib/representations/resolve.clj+++ b/src/metabase/agent_lib/representations/resolve.clj@@ -1,6 +1,6 @@(ns metabase.agent-lib.representations.resolve"Resolve a parsed (string-keyed, portable) representations query into canonical numeric-ID- pMBQL.+ MBQL 5.Pipeline:@@ -19,12 +19,12 @@* adds `:lib/uuid` to every clause;* keywordizes known enum values (temporal units, base-types, join strategies);* kebab-cases keys where applicable;- * attaches the metadata-provider at `:lib/metadata` so the result is a \"real\" pMBQL that+ * attaches the metadata-provider at `:lib/metadata` so the result is a \"real\" MBQL 5 thatcan be handed to `lib.query` / the QP directly.The output is a valid MBQL 5 query ready for the query processor.- The inverse direction — final pMBQL back to portable form — is handled by [[export-query]];+ The inverse direction — final MBQL 5 back to portable form — is handled by [[export-query]];the result is a Clojure map matching the external (keyword-keyed) shape, ready for JSONencoding or for handing back to the LLM as the canonical MBQL 5 representation."(:require@@ -78,7 +78,7 @@;;; ============================================================(defn- annotate-field-types- "Walk a normalized pMBQL query and stamp `:base-type` / `:effective-type` on every+ "Walk a normalized MBQL 5 query and stamp `:base-type` / `:effective-type` on every`[:field opts field-id]` clause whose integer `field-id` is known to `metadata-provider`but whose `opts` map is missing `:base-type`.@@ -191,7 +191,7 @@validate-absolute-datetime-literals))));;; ============================================================-;;; Export final pMBQL back to portable representations+;;; Export final MBQL 5 back to portable representations;;; ============================================================(defn- keyword->repr-string@@ -224,7 +224,7 @@:else x))(defn export-query- "Convert a final normalized numeric-ID pMBQL query back to portable representations data.+ "Convert a final normalized numeric-ID MBQL 5 query back to portable representations data.This is the inverse of [[resolve-query]] for the agent/tool output path: table/field/card IDsare exported to portable FK paths / entity_ids, lib's normalized keyworded form is converted@@ -259,5 +259,5 @@(try(export-query metadata-provider pmbql-query content-store)(catch Exception e- (log/warnf "Failed to export pMBQL query to portable representations; omitting from LLM payload: %s" (ex-message e))+ (log/warnf "Failed to export MBQL 5 query to portable representations; omitting from LLM payload: %s" (ex-message e))nil)))))diff --git a/src/metabase/explorations/runner.clj b/src/metabase/explorations/runner.cljindex 242ee50d11b..17f6d7b297a 100644--- a/src/metabase/explorations/runner.clj+++ b/src/metabase/explorations/runner.clj@@ -82,7 +82,7 @@`lib/prepare-for-serialization` so the metadata provider — a recordholding caching atoms that Nippy can't freeze — is stripped beforeserialization. Without this prep, Nippy chokes on the `Atom` inside the- mp the moment we hand it a qp-result whose input query is a pMBQL value+ mp the moment we hand it a qp-result whose input query is a MBQL 5 valuewith `:lib/metadata` still attached."^bytes [qp-result](qp/do-with-serializationdiff --git a/src/metabase/metabot/agent/links.clj b/src/metabase/metabot/agent/links.cljindex 5b164aaed2c..ec2ea0a1ac9 100644--- a/src/metabase/metabot/agent/links.clj+++ b/src/metabase/metabot/agent/links.clj@@ -30,8 +30,8 @@;;; Query/Chart URL Generation(defn ->legacy-mbql- "Normalize a pMBQL query (has `:lib/type`) to legacy MBQL. Frontend /question#- URLs require legacy MBQL format; non-pMBQL values pass through unchanged.+ "Normalize a MBQL 5 query (has `:lib/type`) to legacy MBQL. Frontend /question#+ URLs require legacy MBQL format; non-MBQL 5 values pass through unchanged.Agent state is JSON-persisted between turns, which preserves namespaced keys butturns enum values such as `:mbql/query`, `:field`, and `:day` into strings.@@ -56,7 +56,7 @@(defn pseudo-card->link"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.- A pMBQL `:dataset_query` is normalized to legacy MBQL (/question# URLs are legacy-only)."+ A MBQL 5 `:dataset_query` is normalized to legacy MBQL (/question# URLs are legacy-only)."[pc](let [pc (cond-> (merge {:visualization_settings {}} pc)(:dataset_query pc) (update :dataset_query ->legacy-mbql))]diff --git a/src/metabase/metabot/tools/construct.clj b/src/metabase/metabot/tools/construct.cljindex 9086fcf254c..9ac2d6fd20f 100644--- a/src/metabase/metabot/tools/construct.clj+++ b/src/metabase/metabot/tools/construct.clj@@ -368,7 +368,7 @@diagnostics over every custom column / aggregation / filter([[repr.repair/assert-editor-accepts-expressions!]]). Either failure is a retryable`:agent-error?` - success on a query the editor rejects is BOT-1442.- 7. Export that final numeric pMBQL back to the portable form for the LLM-facing+ 7. Export that final numeric MBQL 5 back to the portable form for the LLM-facing`:query-json` / `query-content` output.Returns a map with `:structured-output` and `:instructions` keys. Throws with an@@ -457,7 +457,7 @@(defn- structured->query-data"Convert tool structured output to a map suitable for [[llm-shape/query->xml]].- `:query-content` is the **canonical portable representations JSON** for the final pMBQL+ `:query-content` is the **canonical portable representations JSON** for the final MBQL 5query we actually constructed: repaired and resolved to numeric IDs, normalized by lib,then exported back to portable FK paths/entity_ids. By feeding the LLM this final portableform (rather than legacy-MBQL JSON or a pre-resolve approximation) on the next turn it candiff --git a/src/metabase/metabot/tools/shared/llm_shape.clj b/src/metabase/metabot/tools/shared/llm_shape.cljindex 29b215834d6..5658a2d0d63 100644--- a/src/metabase/metabot/tools/shared/llm_shape.clj+++ b/src/metabase/metabot/tools/shared/llm_shape.clj@@ -83,7 +83,7 @@(u/pprint-to-str (cond-> query (map? query) (dissoc :lib/metadata))))(defn export-query-for-llm- "Render a `query` (legacy or pMBQL map, or a pre-resolved string) for the LLM. A query+ "Render a `query` (legacy or MBQL 5 map, or a pre-resolved string) for the LLM. A querymap with a `:database` is normalized and exported to the portable representations formthe `construct_notebook_query` tool consumes (a JSON code block); pre-resolved stringsources pass through; a `pprint`'d map is the last-resort fallback. A permission-refuseddiff --git a/test/metabase/agent_lib/representations/resolve_test.clj b/test/metabase/agent_lib/representations/resolve_test.cljindex 99db664398f..6abe5556bd5 100644--- a/test/metabase/agent_lib/representations/resolve_test.clj+++ b/test/metabase/agent_lib/representations/resolve_test.clj@@ -88,7 +88,7 @@(is (schema-valid? q)))))(deftest export-query-round-trip-shape-test- (testing "resolved numeric pMBQL exports back to the portable string-keyed representations form"+ (testing "resolved numeric MBQL 5 exports back to the portable string-keyed representations form"(let [parsed {"lib/type" "mbql/query""database" "Sample""stages" [{"lib/type" "mbql.stage/mbql"@@ -556,7 +556,7 @@;;; ============================================================(deftest try-export-query-structured-test- (testing "structured pMBQL exports to a portable repr-form map with portable FKs and string keys"+ (testing "structured MBQL 5 exports to a portable repr-form map with portable FKs and string keys"(let [parsed {"lib/type" "mbql/query""database" "Sample""stages" [{"lib/type" "mbql.stage/mbql"diff --git a/test/metabase/lib/convert_test.cljc b/test/metabase/lib/convert_test.cljcindex b6aef19c6cf..bec593a9123 100644--- a/test/metabase/lib/convert_test.cljc+++ b/test/metabase/lib/convert_test.cljc@@ -1701,7 +1701,7 @@:dimension [:field 2 nil]}}}))))(deftest ^:parallel round-trip-offset-inside-case-inside-aggregation-test- (testing "#42377 sum(case([Total] > 0, offset([Total], -1))) survives the legacy <-> pMBQL round-trip"+ (testing "#42377 sum(case([Total] > 0, offset([Total], -1))) survives the legacy <-> MBQL 5 round-trip";; OFFSET retains a random :lib/uuid in its (mbql5-style) options, so exact round-trip equality is not;; possible; instead assert the conversion happens without an "Error normalizing" exception and that the;; clause shape is preserved in both directions.diff --git a/test/metabase/metabot/agent/user_context_test.clj b/test/metabase/metabot/agent/user_context_test.cljindex 6b9cf0ed89f..83c040a5300 100644--- a/test/metabase/metabot/agent/user_context_test.clj+++ b/test/metabase/metabot/agent/user_context_test.clj@@ -443,7 +443,7 @@"Formatting result should contain database id")))(deftest ^:parallel format-transform-source-mbql-renders-repr-json-test- (testing "transform sources with a structured MBQL `:query` are rendered as a portable repr JSON code block, not pprint'd pMBQL"+ (testing "transform sources with a structured MBQL `:query` are rendered as a portable repr JSON code block, not pprint'd MBQL 5"(mt/test-driver :h2(mt/with-current-user (mt/user->id :crowberto)(let [mp (mt/metadata-provider)@@ -454,7 +454,7 @@(assoc source :transform-source-type :query))](is (string? text))(is (re-find #"```json" text)- "output is a JSON code block (the portable representations form), not pprint'd pMBQL")+ "output is a JSON code block (the portable representations form), not pprint'd MBQL 5")(is (re-find #"\"lib/type\"\s*:\s*\"mbql/query\"" text))(is (re-find #"\"source-table\"" text))(is (not (re-find #"lib/metadata" text))diff --git a/test/metabase/metabot/tools/charts_test.clj b/test/metabase/metabot/tools/charts_test.cljindex 745330a9a35..8a18b70a9b5 100644--- a/test/metabase/metabot/tools/charts_test.clj+++ b/test/metabase/metabot/tools/charts_test.clj@@ -8,7 +8,7 @@[metabase.metabot.tools.shared :as shared]));; create-chart only needs the query present in queries-state; the link builder-;; json-encodes it and `->legacy-mbql` passes a non-pMBQL value through unchanged,+;; json-encodes it and `->legacy-mbql` passes a non-MBQL 5 value through unchanged,;; so a stub query is enough to exercise the emission branch without a database.(def ^:private stub-query{:database 1 :type "query" :query {:source-table 1}})diff --git a/test/metabase/metabot/tools/construct_representations_test.clj b/test/metabase/metabot/tools/construct_representations_test.cljindex 2a2814cc9b9..d8a64b5e1e4 100644--- a/test/metabase/metabot/tools/construct_representations_test.clj+++ b/test/metabase/metabot/tools/construct_representations_test.clj@@ -2,7 +2,7 @@"Tests for `execute-representations-query` - the representations-format entry point for`construct_notebook_query`.- Covers the happy path (external-query JSON -> resolved pMBQL wrapped in structured output),+ Covers the happy path (external-query JSON -> resolved MBQL 5 wrapped in structured output),unknown table, the `:agent-error?` error-translation contract, and the database-idresolution from the query's first-stage `source-table:` (per `repr-plan.md` step 13:unknown name, ambiguous name, missing name, mismatched DB component in source-table)."@@ -722,7 +722,7 @@(deftest expression-map-shape-end-to-end-test(testing (str "The LLM-friendly `expressions: {Name: clause, …}` map shape is normalised\n""to the canonical sequential MBQL 5 form with `lib/expression-name` stamped,\n"- "and the resolved query carries the expression in its pMBQL.")+ "and the resolved query carries the expression in its MBQL 5.")(with-mp-and-stubs!(fn [](let [result (construct/execute-representations-querydiff --git a/test/metabase/metabot/util_test.clj b/test/metabase/metabot/util_test.cljindex 031be696b9e..d90facc4a40 100644--- a/test/metabase/metabot/util_test.clj+++ b/test/metabase/metabot/util_test.clj@@ -4,7 +4,7 @@[metabase.metabot.util :as metabot.u]))(deftest ^:parallel extract-sql-content-native-test- (testing "extracts SQL from normalized pMBQL and legacy query shapes"+ (testing "extracts SQL from normalized MBQL 5 and legacy query shapes"(are [expected query] (= expected (metabot.u/extract-sql-content query))"SELECT 1" {:stages [{:lib/type :mbql.stage/native:native "SELECT 1"}]}diff --git a/test/metabase/models/serialization/resolve/mp_test.clj b/test/metabase/models/serialization/resolve/mp_test.cljindex 6677ecc7239..69daf2c8e2a 100644--- a/test/metabase/models/serialization/resolve/mp_test.clj+++ b/test/metabase/models/serialization/resolve/mp_test.clj@@ -436,7 +436,7 @@(is (nil? (resolve/export-fk-keyed r nil :model/Database :name))))))(deftest ^:parallel export-mbql-with-mp-resolver-round-trip-shape-test- (testing "final numeric pMBQL exports back to portable DB/table/field/card references"+ (testing "final numeric MBQL 5 exports back to portable DB/table/field/card references"(let [r (resolve.mp/export-resolver mp-with-cards cards-content-store)exported (resolve/export-mbqlrdiff --git a/test/metabase/models/serialization_test.clj b/test/metabase/models/serialization_test.cljindex 1c84595cb69..a28ea8521b7 100644--- a/test/metabase/models/serialization_test.clj+++ b/test/metabase/models/serialization_test.clj@@ -277,7 +277,7 @@eid (fn [c] (apply str (repeat 21 c)))](testing "MBQL ref clauses"(doseq [[label serialized raw ser-models raw-models]- [["field (pMBQL)" [:field {} ["DB" "S" "T" "F"]] [:field {} 53] #{"Database"} #{"Field"}]+ [["field (MBQL 5)" [:field {} ["DB" "S" "T" "F"]] [:field {} 53] #{"Database"} #{"Field"}]["field (legacy)" [:field ["DB" "S" "T" "F"] {}] [:field 53 {}] #{"Database"} #{"Field"}]["metric" [:metric {} (eid \a)] [:metric {} 99] #{"Card"} #{"Card"}]["segment" [:segment {} (eid \b)] [:segment {} 5] #{"Segment"} #{"Segment"}]diff --git a/test/metabase/query_processor/middleware/wrap_value_literals_test.clj b/test/metabase/query_processor/middleware/wrap_value_literals_test.cljindex 100caeebbef..ab5214df870 100644--- a/test/metabase/query_processor/middleware/wrap_value_literals_test.clj+++ b/test/metabase/query_processor/middleware/wrap_value_literals_test.clj@@ -245,10 +245,10 @@"pre-wrapped string coerced to the report timezone for a DateTimeWithZoneID field"))))(defn- year-literal-filter-query- "Build a pMBQL query whose `:=` filter compares an *unbucketed* `checkins.date` against a string-valued+ "Build a MBQL 5 query whose `:=` filter compares an *unbucketed* `checkins.date` against a string-valued`[:absolute-datetime {} `s` `unit`]`. Year / year-month string literals can't be expressed through thelegacy `mbql-query` macro, so we build a valid query and swap the literal into the already-wrapped- pMBQL clause."+ MBQL 5 clause."[s unit](-> (lib/querymeta/metadata-provider