Skip to content

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

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.clj
index 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 and
ids 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.tsx
index 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.tsx
index 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.clj
index 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.clj
index 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 that
can 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 JSON
encoding 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 IDs
are 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.clj
index 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 record
holding caching atoms that Nippy can't freeze — is stripped before
serialization. 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 value
with `:lib/metadata` still attached."
^bytes [qp-result]
(qp/do-with-serialization
diff --git a/src/metabase/metabot/agent/links.clj b/src/metabase/metabot/agent/links.clj
index 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 but
turns 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.clj
index 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 5
query 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 portable
form (rather than legacy-MBQL JSON or a pre-resolve approximation) on the next turn it can
diff --git a/src/metabase/metabot/tools/shared/llm_shape.clj b/src/metabase/metabot/tools/shared/llm_shape.clj
index 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 query
map with a `:database` is normalized and exported to the portable representations form
the `construct_notebook_query` tool consumes (a JSON code block); pre-resolved string
sources pass through; a `pprint`'d map is the last-resort fallback. A permission-refused
diff --git a/test/metabase/agent_lib/representations/resolve_test.clj b/test/metabase/agent_lib/representations/resolve_test.clj
index 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.cljc
index 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.clj
index 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.clj
index 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.clj
index 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-id
resolution 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-query
diff --git a/test/metabase/metabot/util_test.clj b/test/metabase/metabot/util_test.clj
index 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.clj
index 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-mbql
r
diff --git a/test/metabase/models/serialization_test.clj b/test/metabase/models/serialization_test.clj
index 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.clj
index 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 the
legacy `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/query
meta/metadata-provider