Skip to content

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

Name and check result columns of data app queries (#84038)

Alexander Polyankin4ba8f731a1d5
diff --git a/e2e/test-component/scenarios/embedding-sdk/sdk-query-runtime-clauses.cy.spec.tsx b/e2e/test-component/scenarios/embedding-sdk/sdk-query-runtime-clauses.cy.spec.tsx
index 0c35c3c556d..44ca698d6f2 100644
--- a/e2e/test-component/scenarios/embedding-sdk/sdk-query-runtime-clauses.cy.spec.tsx
+++ b/e2e/test-component/scenarios/embedding-sdk/sdk-query-runtime-clauses.cy.spec.tsx
@@ -9,8 +9,9 @@ import {
useMetabaseQuery,
} from "@metabase/embedding-sdk-react/data-app";
+import { SAMPLE_DB_ID } from "e2e/support/cypress_data";
import { SAMPLE_DATABASE } from "e2e/support/cypress_sample_database";
-import { createQuestion } from "e2e/support/helpers";
+import { createCard, createTestQuery } from "e2e/support/helpers";
import {
DEFAULT_SDK_AUTH_PROVIDER_CONFIG,
mountSdk,
@@ -19,7 +20,7 @@ import {
mockAuthProviderAndJwtSignIn,
signInAsAdminAndEnableEmbeddingSdk,
} from "e2e/support/helpers/embedding-sdk-testing";
-import type { StructuredQuery } from "metabase-types/api";
+import type { TestStageWithSourceSpec } from "metabase-types/api";
const { ORDERS, ORDERS_ID, PEOPLE, PRODUCTS } = SAMPLE_DATABASE;
@@ -128,17 +129,25 @@ describe("scenarios > embedding-sdk > query runtime clauses", () => {
signInAsAdminAndEnableEmbeddingSdk();
});
+ const createTestCard = (
+ stage: TestStageWithSourceSpec,
+ details: { name: string; type?: "metric" },
+ ) =>
+ createTestQuery({ database: SAMPLE_DB_ID, stages: [stage] }).then(
+ (datasetQuery) => createCard({ ...details, dataset_query: datasetQuery }),
+ );
+
const expectRuntimeClauses = ({
- cardQuery,
+ staticQuery,
useQueryStates,
check,
}: {
- cardQuery: StructuredQuery;
+ staticQuery: TestStageWithSourceSpec;
useQueryStates: UseQueryStates;
check: RowCheck;
}) => {
- createQuestion({ name: "Runtime clauses source", query: cardQuery }).then(
- ({ body: card }) => {
+ createTestCard(staticQuery, { name: "Runtime clauses source" }).then(
+ (card) => {
cy.signOut();
mockAuthProviderAndJwtSignIn();
@@ -178,14 +187,7 @@ describe("scenarios > embedding-sdk > query runtime clauses", () => {
};
expectRuntimeClauses({
- cardQuery: {
- "source-table": ORDERS_ID,
- aggregation: [["count"]],
- breakout: [
- ["field", ORDERS.CREATED_AT, { "temporal-unit": "month" }],
- ["field", ORDERS.USER_ID, null],
- ],
- },
+ staticQuery,
useQueryStates: (cardId) => ({
fromTable: useMetabaseQuery(staticQuery, dynamicQuery),
fromCard: useMetabaseQuery(
@@ -206,11 +208,13 @@ describe("scenarios > embedding-sdk > query runtime clauses", () => {
// Generated joined fields are metric dimensions, and the skill requires
// their metric in the same query. The metric is what loads the metadata of
// the tables its foreign keys point to.
- createQuestion({
- name: "Orders count",
- type: "metric",
- query: { "source-table": ORDERS_ID, aggregation: [["count"]] },
- }).then(({ body: metric }) => {
+ createTestCard(
+ {
+ source: tableSource,
+ aggregations: [{ type: "operator", operator: "count", args: [] }],
+ },
+ { name: "Orders count", type: "metric" },
+ ).then((metric) => {
const ordersCount = {
type: "metric" as const,
id: metric.id,
@@ -221,19 +225,17 @@ describe("scenarios > embedding-sdk > query runtime clauses", () => {
const staticQuery = defineQuery({
source: tableSource,
aggregations: [ordersCount],
- breakouts: [breakout(productsIdField), breakout(peopleIdField)],
+ breakouts: [
+ breakout(productsIdField, { name: "product_id" }),
+ breakout(peopleIdField, { name: "people_id" }),
+ ],
});
- const dynamicQuery = { filters: [filter(peopleIdField, "<", 10)] };
+ const dynamicQuery = {
+ filters: [filter({ ...peopleIdField, name: "people_id" }, "<", 10)],
+ };
expectRuntimeClauses({
- cardQuery: {
- "source-table": ORDERS_ID,
- aggregation: [["metric", metric.id]],
- breakout: [
- ["field", PRODUCTS.ID, { "source-field": ORDERS.PRODUCT_ID }],
- ["field", PEOPLE.ID, { "source-field": ORDERS.USER_ID }],
- ],
- },
+ staticQuery,
useQueryStates: (cardId) => ({
fromTable: useMetabaseQuery(staticQuery, dynamicQuery),
fromCard: useMetabaseQuery(
@@ -263,22 +265,6 @@ describe("scenarios > embedding-sdk > query runtime clauses", () => {
aggregations: [totalSum, subtotalSum],
breakouts: [breakout(productIdField)],
});
- const cardQuery: StructuredQuery = {
- "source-table": ORDERS_ID,
- aggregation: [
- [
- "aggregation-options",
- ["sum", ["field", ORDERS.TOTAL, null]],
- { name: "total", "display-name": "Sum of Total" },
- ],
- [
- "aggregation-options",
- ["sum", ["field", ORDERS.SUBTOTAL, null]],
- { name: "subtotal", "display-name": "Sum of Subtotal" },
- ],
- ],
- breakout: [["field", ORDERS.PRODUCT_ID, null]],
- };
[
{ aggregation: totalSum, name: "total", index: 1 },
@@ -288,7 +274,7 @@ describe("scenarios > embedding-sdk > query runtime clauses", () => {
const dynamicQuery = { orderBys: [orderBy(aggregation, "desc")] };
expectRuntimeClauses({
- cardQuery,
+ staticQuery,
useQueryStates: (cardId) => ({
fromTable: useMetabaseQuery(staticQuery, dynamicQuery),
fromCard: useMetabaseQuery(
diff --git a/enterprise/backend/src/metabase_enterprise/data_apps/generate/resources.clj b/enterprise/backend/src/metabase_enterprise/data_apps/generate/resources.clj
index a41b7ed1da9..519cb93e365 100644
--- a/enterprise/backend/src/metabase_enterprise/data_apps/generate/resources.clj
+++ b/enterprise/backend/src/metabase_enterprise/data_apps/generate/resources.clj
@@ -101,13 +101,34 @@
(tru "Could not serialize {0}: {1}" label cause)
(tru "Could not serialize {0}." label)))))
+(defn- check-unique-column-names
+ "Throws naming the breakouts and aggregations of `query` whose result columns share a name."
+ [query]
+ (let [columns (concat (for [breakout (lib/breakouts query)
+ :let [column (lib/breakout-column query breakout)]]
+ {:name (:name column)
+ :clause column})
+ (for [aggregation (lib/aggregations query)]
+ {:name (:name (lib/aggregation-column query aggregation))
+ :clause aggregation}))
+ conflicts (for [[column-name same-name] (group-by :name columns)
+ :when (> (count same-name) 1)]
+ (tru "{0} share the column name \"{1}\""
+ (str/join ", " (map #(lib/display-name query (:clause %)) same-name))
+ column-name))]
+ (when (seq conflicts)
+ (fail (tru "Breakouts and aggregations need unique column names: {0}. Name them apart with the `name` option of `breakout` or of an aggregation helper, or with `aggregations.measure` or `aggregations.metric` for a measure or metric."
+ (str/join "; " conflicts))))))
+
(mu/defn- build-query :- ::lib.schema/query
"The query Lib builds from `query-definition`, once its source table and every table it reads at any depth exist."
[{[{{table-id :id} :source}] :stages, :as query-definition} :- ::query-definition/query-definition]
(let [table (data-apps.db/table table-id)]
(when-not table
(fail (tru "Table {0} does not exist." (str table-id))))
- (let [query (lib/test-query (lib-be/application-database-metadata-provider (:db_id table)) query-definition)]
+ (let [mp (lib-be/application-database-metadata-provider (:db_id table))
+ _ (check-unique-column-names (lib/test-query mp (update-in query-definition [:stages 0] dissoc :order-bys)))
+ query (lib/test-query mp query-definition)]
(when-not (mr/validate ::lib.schema/query query)
(fail (tru "The definition does not build a valid query.")))
(doseq [read-id (sort (into (:table (lib/all-referenced-entity-ids-recursive query))
diff --git a/enterprise/backend/src/metabase_enterprise/data_apps/query_definition.clj b/enterprise/backend/src/metabase_enterprise/data_apps/query_definition.clj
index e0b19062aa6..a08d819d7e7 100644
--- a/enterprise/backend/src/metabase_enterprise/data_apps/query_definition.clj
+++ b/enterprise/backend/src/metabase_enterprise/data_apps/query_definition.clj
@@ -58,8 +58,18 @@
[:map {:closed true :decode/normalize {:compile query-map-decoder}}
[:binning {:optional true} [:maybe ::binning]]]])
+(mr/def ::named-breakout
+ "A breakout whose result column is named, as `breakout(field, { name })` names it."
+ [:map {:closed true :decode/normalize {:compile query-map-decoder}}
+ [:type [:= {:decode/normalize lib.schema.common/normalize-keyword} :breakout]]
+ [:name string?]
+ [:column [:ref ::column-with-binning]]])
+
(mr/def ::breakout
- [:ref ::column-with-binning])
+ [:multi {:decode/normalize lib.schema.common/normalize-map-no-kebab-case
+ :dispatch (comp keyword :type)}
+ [:column [:ref ::column-with-binning]]
+ [:breakout [:ref ::named-breakout]]])
(mr/def ::order-by
[:merge
@@ -121,9 +131,17 @@
[:literal [:ref ::literal-expression]]
[:operator [:ref ::aggregation-operator-expression]]])
+(mr/def ::named-aggregation
+ "A measure or a metric whose result column is named, as `aggregations.measure` and `aggregations.metric` name it."
+ [:map {:closed true :decode/normalize {:compile query-map-decoder}
+ ::sdk-metadata [:columns]}
+ [:name string?]
+ [:value [:or [:ref ::measure] [:ref ::metric]]]])
+
(mr/def ::aggregation
[:or
[:ref ::aggregation-expression]
+ [:ref ::named-aggregation]
[:ref ::measure]
[:ref ::metric]])
diff --git a/enterprise/backend/test/metabase_enterprise/data_apps/generate/resources_test.clj b/enterprise/backend/test/metabase_enterprise/data_apps/generate/resources_test.clj
index 198bee029f8..15486971245 100644
--- a/enterprise/backend/test/metabase_enterprise/data_apps/generate/resources_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/data_apps/generate/resources_test.clj
@@ -9,6 +9,7 @@
[metabase.actions.core :as actions]
[metabase.lib.core :as lib]
[metabase.lib.metadata :as lib.metadata]
+ [metabase.lib.test-util :as lib.tu]
[metabase.models.serialization :as serdes]
[metabase.test :as mt]
[metabase.util :as u]
@@ -527,3 +528,101 @@
:queries first)]
(is (= [:database :stages :lib/type] (keys (:dataset_query (file-entity file)))))
(is (< (str/index-of yaml "name:") (str/index-of yaml "\ndataset_query:"))))))
+
+(defn- venues-sum
+ [column-name]
+ {:type "operator" :operator "sum" :args [{:type "column" :name column-name}]})
+
+(deftest refuses-aggregations-sharing-column-name-test
+ (testing "aggregations named alike would be read as one by a later stage or a result row, so the author names them"
+ (is (=? {:queries [{:error "Breakouts and aggregations need unique column names: Sum of Price, Sum of Latitude share the column name \"sum\". Name them apart with the `name` option of `breakout` or of an aggregation helper, or with `aggregations.measure` or `aggregations.metric` for a measure or metric."}]}
+ (generate! :crowberto 200
+ {:queries [(query-item "Sums" {:stages [{:source {:type "table" :id (mt/id :venues)}
+ :aggregations [(venues-sum "PRICE") (venues-sum "LATITUDE")]}]})]})))))
+
+(deftest accepts-named-aggregations-test
+ (let [{[file] :queries} (generate! :crowberto 200
+ {:queries [(query-item "Sums" {:stages [{:source {:type "table" :id (mt/id :venues)}
+ :aggregations [(assoc (venues-sum "PRICE") :name "price")
+ (venues-sum "LATITUDE")]}]})]})]
+ (is (=? [["sum" {:name "price"} some?] ["sum" {} some?]]
+ (get-in (file-entity file) [:dataset_query :stages 0 :aggregation])))))
+
+(deftest names-measure-test
+ (testing "measure wrapped as `{name, value}` gets that column name, and its own `name` is left out"
+ (let [mp (mt/metadata-provider)]
+ (mt/with-temp [:model/Measure {measure-id :id} {:table_id (mt/id :venues)
+ :name "Revenue"
+ :definition (-> (lib/query mp (lib.metadata/table mp (mt/id :venues)))
+ (lib/aggregate (lib/sum (lib.metadata/field mp (mt/id :venues :price)))))}]
+ (let [measure {:type "measure" :id measure-id :name "Revenue" :tableId (mt/id :venues)}
+ body (fn [measure]
+ {:queries [(query-item "Revenue" {:stages [{:source {:type "table" :id (mt/id :venues)}
+ :aggregations [measure (venues-sum "LATITUDE")]}]})]})]
+ (testing "unnamed, it shares the column name of the sum beside it"
+ (is (=? {:queries [{:error #".*share the column name \"sum\".*"}]}
+ (generate! :crowberto 200 (body measure)))))
+ (let [{[file] :queries} (generate! :crowberto 200 (body {:name "revenue" :value measure :columns [{:name "revenue"}]}))]
+ (is (=? [["measure" {:name "revenue"} some?] ["sum" {} some?]]
+ (get-in (file-entity file) [:dataset_query :stages 0 :aggregation])))))))))
+
+(deftest refuses-order-by-on-shared-column-name-test
+ (testing "order-by naming a column two aggregations share gets the same refusal, not Lib's ambiguity error"
+ (is (=? {:queries [{:error #"Breakouts and aggregations need unique column names: Sum of Price, Sum of Latitude share the column name \"sum\"\..*"}]}
+ (generate! :crowberto 200
+ {:queries [(query-item "Sums" {:stages [{:source {:type "table" :id (mt/id :venues)}
+ :aggregations [(venues-sum "PRICE") (venues-sum "LATITUDE")]
+ :order-bys [{:type "column" :name "sum"}]}]})]})))))
+
+(defn- check-unique-names
+ "Calls the uniqueness check on `query`, returning the refusal's message or nil."
+ [query]
+ (try
+ (#'generate.resources/check-unique-column-names query)
+ nil
+ (catch clojure.lang.ExceptionInfo e
+ (ex-message e))))
+
+(deftest refuses-aggregation-sharing-breakout-field-name-test
+ (testing "a `sum` aggregation next to a breakout on a field named `sum` collide"
+ (let [mp (mt/metadata-provider)
+ mp (lib.tu/mock-metadata-provider
+ mp
+ {:fields [(assoc (lib.metadata/field mp (mt/id :venues :name)) :name "sum")]})
+ query (-> (lib/query mp (lib.metadata/table mp (mt/id :venues)))
+ (lib/breakout (lib.metadata/field mp (mt/id :venues :name)))
+ (lib/aggregate (lib/sum (lib.metadata/field mp (mt/id :venues :price)))))]
+ (is (=? #"Breakouts and aggregations need unique column names: .* share the column name \"sum\".*"
+ (check-unique-names query))))))
+
+(deftest refuses-named-breakouts-sharing-name-test
+ (let [mp (mt/metadata-provider)
+ created-at (lib.metadata/field mp (mt/id :checkins :date))
+ named (fn [column column-name] (lib/update-options (lib/ref column) assoc :name column-name))
+ query (fn [first-name second-name]
+ (-> (lib/query mp (lib.metadata/table mp (mt/id :checkins)))
+ (lib/breakout (named (lib/with-temporal-bucket created-at :month) first-name))
+ (lib/breakout (named (lib/with-temporal-bucket created-at :year) second-name))
+ (lib/aggregate (lib/count))))]
+ (testing "named breakouts sharing a name collide"
+ (is (=? #".* share the column name \"period\".*" (check-unique-names (query "period" "period")))))
+ (testing "named apart they don't"
+ (is (nil? (check-unique-names (query "month" "year")))))
+ (testing "the same field broken out twice without names collides too"
+ (is (=? #".* share the column name \"DATE\".*"
+ (check-unique-names (-> (lib/query mp (lib.metadata/table mp (mt/id :checkins)))
+ (lib/breakout (lib/with-temporal-bucket created-at :month))
+ (lib/breakout (lib/with-temporal-bucket created-at :year))
+ (lib/aggregate (lib/count)))))))))
+
+(deftest names-breakout-test
+ (testing "breakout sent as `{type: breakout, name, column}` keeps its name in the saved question"
+ (let [{[file] :queries} (generate! :crowberto 200
+ {:queries [(query-item "Venues by category"
+ {:stages [{:source {:type "table" :id (mt/id :venues)}
+ :aggregations [{:type "operator" :operator "count"}]
+ :breakouts [{:type "breakout"
+ :name "category"
+ :column {:type "column" :name "CATEGORY_ID"}}]}]})]})]
+ (is (=? [["field" {:name "category"} some?]]
+ (get-in (file-entity file) [:dataset_query :stages 0 :breakout]))))))
diff --git a/enterprise/backend/test/metabase_enterprise/data_apps/query_definition_test.clj b/enterprise/backend/test/metabase_enterprise/data_apps/query_definition_test.clj
index af02b2a041b..a2a0238af01 100644
--- a/enterprise/backend/test/metabase_enterprise/data_apps/query_definition_test.clj
+++ b/enterprise/backend/test/metabase_enterprise/data_apps/query_definition_test.clj
@@ -69,3 +69,17 @@
(assoc-in query-definition [:stages 0 :aggregations]
[{:name "count" :value {:type :operator :operator :count :args []}}])]]
(is (not (mr/validate ::query-definition/query-definition query)))))
+
+(deftest ^:parallel named-saved-aggregation-test
+ (testing "measure or metric named with `aggregations.measure` / `aggregations.metric`"
+ (doseq [saved [{:type :measure :id 1} {:type :metric :id 1}]]
+ (is (nil? (mr/explain ::query-definition/query-definition
+ (assoc-in query-definition [:stages 0 :aggregations]
+ [{:name "revenue" :value saved}])))))))
+
+(deftest ^:parallel named-breakout-test
+ (testing "breakout named with `breakout(field, { name })`"
+ (is (nil? (mr/explain ::query-definition/query-definition
+ (assoc-in query-definition [:stages 0 :breakouts]
+ [{:type :breakout :name "created_month"
+ :column {:type :column :name "DATE" :unit :month}}]))))))
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app.ts b/enterprise/frontend/src/embedding-sdk-package/data-app.ts
index 9e27fec16a2..cc4ed2c4c2d 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app.ts
@@ -54,14 +54,14 @@ export {
} from "./hooks/public/use-metabase-query";
export type {
DefinedQuery,
- LocalFieldReference,
+ MetabaseLocalFieldReference,
MetabaseBreakout,
MetabaseDynamicColumn,
MetabaseDynamicQuery,
MetabaseOrderBy,
MetabaseQueryOptions,
MetabaseQueryObject,
- OrderByDirection,
+ MetabaseOrderByDirection,
UseMetabaseQueryObjectResult,
UseMetabaseQueryResult,
} from "./hooks/public/use-metabase-query";
diff --git a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/aggregation-helpers.ts b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/aggregation-helpers.ts
index f71a591bfd3..95e43d91c89 100644
--- a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/aggregation-helpers.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/aggregation-helpers.ts
@@ -1,9 +1,10 @@
-import type { SchemaJavaScriptType } from "../data-schema";
+import type { SchemaColumn, SchemaJavaScriptType } from "../data-schema";
import type {
CountAggregationSchema,
FieldAggregationOperator,
FieldAggregationSchema,
+ NamedSavedAggregation,
NumericAggregationDimension,
OrderableAggregationDimension,
} from "./types";
@@ -34,7 +35,7 @@ export function count(
};
}
-export const sum = <TDimension, const TName extends string = "sum">(
+export const sum = <const TDimension, const TName extends string = "sum">(
dimension: NumericAggregationDimension<TDimension>,
options?: AggregationOptions<TName>,
): FieldAggregationSchema<
@@ -44,7 +45,7 @@ export const sum = <TDimension, const TName extends string = "sum">(
NoInfer<TName>
> => fieldAggregation("sum", "Sum", dimension, options);
-export const avg = <TDimension, const TName extends string = "avg">(
+export const avg = <const TDimension, const TName extends string = "avg">(
dimension: NumericAggregationDimension<TDimension>,
options?: AggregationOptions<TName>,
): FieldAggregationSchema<
@@ -54,7 +55,7 @@ export const avg = <TDimension, const TName extends string = "avg">(
NoInfer<TName>
> => fieldAggregation("avg", "Average", dimension, options);
-export const median = <TDimension, const TName extends string = "median">(
+export const median = <const TDimension, const TName extends string = "median">(
dimension: NumericAggregationDimension<TDimension>,
options?: AggregationOptions<TName>,
): FieldAggregationSchema<
@@ -64,13 +65,16 @@ export const median = <TDimension, const TName extends string = "median">(
NoInfer<TName>
> => fieldAggregation("median", "Median", dimension, options);
-export const distinct = <TDimension, const TName extends string = "count">(
+export const distinct = <
+ const TDimension,
+ const TName extends string = "count",
+>(
dimension: TDimension,
options?: AggregationOptions<TName>,
): FieldAggregationSchema<"distinct", TDimension, "number", NoInfer<TName>> =>
fieldAggregation("distinct", "Distinct values", dimension, options);
-export const min = <TDimension, const TName extends string = "min">(
+export const min = <const TDimension, const TName extends string = "min">(
dimension: OrderableAggregationDimension<TDimension>,
options?: AggregationOptions<TName>,
): FieldAggregationSchema<
@@ -80,7 +84,7 @@ export const min = <TDimension, const TName extends string = "min">(
NoInfer<TName>
> => fieldAggregation("min", "Minimum", dimension, options);
-export const max = <TDimension, const TName extends string = "max">(
+export const max = <const TDimension, const TName extends string = "max">(
dimension: OrderableAggregationDimension<TDimension>,
options?: AggregationOptions<TName>,
): FieldAggregationSchema<
@@ -159,12 +163,65 @@ const isOrderableJavaScriptType = (
value === "boolean" ||
value === "Date";
+type SavedAggregation<TType extends "measure" | "metric"> = {
+ type: TType;
+ columns?: readonly SchemaColumn[];
+};
+
+const namedSavedAggregation = <TAggregation, TName extends string>(
+ aggregation: TAggregation & { columns?: readonly SchemaColumn[] },
+ name: TName,
+): NamedSavedAggregation<TAggregation, TName> =>
+ // The column type is the wrapped aggregation's first column with the new
+ // name, a conditional type TS can't check the spread against.
+ ({
+ name,
+ value: aggregation,
+ columns: [{ ...aggregation.columns?.[0], name }],
+ }) as unknown as NamedSavedAggregation<TAggregation, TName>;
+
+export function measure<const TMeasure extends SavedAggregation<"measure">>(
+ measure: TMeasure,
+): TMeasure;
+export function measure<
+ const TMeasure extends SavedAggregation<"measure">,
+ const TName extends string,
+>(
+ measure: TMeasure,
+ options: AggregationOptions<TName>,
+): NamedSavedAggregation<TMeasure, TName>;
+export function measure(
+ measure: SavedAggregation<"measure">,
+ options?: AggregationOptions<string>,
+) {
+ return options ? namedSavedAggregation(measure, options.name) : measure;
+}
+
+export function metric<const TMetric extends SavedAggregation<"metric">>(
+ metric: TMetric,
+): TMetric;
+export function metric<
+ const TMetric extends SavedAggregation<"metric">,
+ const TName extends string,
+>(
+ metric: TMetric,
+ options: AggregationOptions<TName>,
+): NamedSavedAggregation<TMetric, TName>;
+export function metric(
+ metric: SavedAggregation<"metric">,
+ options?: AggregationOptions<string>,
+) {
+ return options ? namedSavedAggregation(metric, options.name) : metric;
+}
+
export const aggregations = {
avg,
count,
distinct,
max,
median,
+ measure,
+ metric,
min,
sum,
} as const;
diff --git a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/define-query.ts b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/define-query.ts
index 7dfa55cc2d3..8adad5e70dd 100644
--- a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/define-query.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/define-query.ts
@@ -4,6 +4,7 @@ import type {
DefinedQuery,
MetabaseQueryOptions,
RequireAggregationsForBreakouts,
+ RequireGroupedOrderByNames,
} from "./types";
type SavedQuestionBinding = {
@@ -24,7 +25,8 @@ export function defineQuery<
(TQuery extends SavedQuestionBinding ? unknown : SavedQuestionBinding) &
(TQuery extends MetabaseQueryOptions<TEntity, TSchema>
? TQuery extends { source: unknown }
- ? RequireAggregationsForBreakouts<TQuery>
+ ? RequireAggregationsForBreakouts<TQuery> &
+ RequireGroupedOrderByNames<TQuery>
: unknown
: MetabaseQueryOptions<TEntity, TSchema>),
): TQuery & DefinedQuery {
diff --git a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/index.ts b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/index.ts
index 2f0862d9f41..4dd356a1c5d 100644
--- a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/index.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/index.ts
@@ -4,7 +4,9 @@ export {
count,
distinct,
max,
+ measure,
median,
+ metric,
min,
sum,
} from "./aggregation-helpers";
@@ -13,13 +15,13 @@ export { useMetabaseQuery } from "./use-metabase-query";
export { useMetabaseQueryObject } from "./use-metabase-query-object";
export type {
DefinedQuery,
- LocalFieldReference,
+ MetabaseLocalFieldReference,
MetabaseBreakout,
MetabaseDynamicColumn,
MetabaseDynamicQuery,
MetabaseOrderBy,
MetabaseQueryOptions,
- OrderByDirection,
+ MetabaseOrderByDirection,
UseMetabaseQueryResult,
} from "./types";
export type { UseMetabaseQueryObjectResult } from "./use-metabase-query-object";
diff --git a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/query-helpers.ts b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/query-helpers.ts
index 9410e22f7c5..4b6237fa0b1 100644
--- a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/query-helpers.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/query-helpers.ts
@@ -1,14 +1,19 @@
-import { isUnaryOperator } from "embedding-sdk-shared/lib/create-metabase-query/input-guards";
+import {
+ isNamedBreakout,
+ isUnaryOperator,
+} from "embedding-sdk-shared/lib/create-metabase-query/input-guards";
import type { SchemaColumn } from "../data-schema";
import type {
+ AggregationResultColumnName,
BetweenFilterOperatorForDimension,
BreakoutOptionsArgument,
+ FilterForOperator,
FilterLiteralValue,
FilterOperator,
- MetabaseDimensionFilterForOperator,
- OrderByDirection,
+ MetabaseOrderByDirection,
+ NamedBreakout,
UnaryFilterOperatorForDimension,
ValueFilterOperatorForDimension,
} from "./types";
@@ -26,7 +31,7 @@ export function filter<
dimension: TDimension,
operator: TOperator,
value: unknown,
-): MetabaseDimensionFilterForOperator<TDimension, TOperator>;
+): FilterForOperator<TDimension, TOperator>;
export function filter<
const TDimension,
@@ -35,7 +40,7 @@ export function filter<
dimension: TDimension,
operator: TOperator,
values: readonly [unknown, unknown],
-): MetabaseDimensionFilterForOperator<TDimension, TOperator>;
+): FilterForOperator<TDimension, TOperator>;
export function filter<
const TDimension,
@@ -43,13 +48,13 @@ export function filter<
>(
dimension: TDimension,
operator: TOperator,
-): MetabaseDimensionFilterForOperator<TDimension, TOperator>;
+): FilterForOperator<TDimension, TOperator>;
export function filter(
dimension: unknown,
operator: FilterOperator,
value?: unknown,
-): MetabaseDimensionFilterForOperator<unknown, FilterOperator> {
+): FilterForOperator<unknown, FilterOperator> {
if (operator === "between") {
// The `between` overload takes a `[min, max]` tuple, but the implementation
// signature shared by all overloads widens `value` to `unknown`.
@@ -77,6 +82,14 @@ export function breakout<const TDimension extends object>(
dimension: TDimension,
): TDimension;
+export function breakout<
+ const TDimension extends object,
+ const TName extends string,
+>(
+ dimension: TDimension,
+ options: BreakoutOptionsArgument<TDimension> & { name: TName },
+): NamedBreakout<TDimension & BreakoutOptionsArgument<TDimension>, TName>;
+
export function breakout<const TDimension extends object>(
dimension: TDimension,
options: BreakoutOptionsArgument<TDimension>,
@@ -84,42 +97,54 @@ export function breakout<const TDimension extends object>(
export function breakout<TDimension extends object>(
dimension: TDimension,
- options?: BreakoutOptionsArgument<TDimension>,
+ options?: BreakoutOptionsArgument<TDimension> & { name?: string },
) {
- return {
+ const column = {
...dimension,
...(options?.unit !== undefined ? { unit: options.unit } : undefined),
...(options?.binning !== undefined
? { binning: options.binning }
: undefined),
};
+
+ return options?.name !== undefined
+ ? { type: "breakout", name: options.name, column }
+ : column;
}
+export function orderBy<const TName extends string>(
+ breakout: NamedBreakout<unknown, TName>,
+ direction?: MetabaseOrderByDirection,
+): { type: "column"; name: TName; direction?: MetabaseOrderByDirection };
+
export function orderBy<
TAggregation extends { columns?: readonly SchemaColumn[] },
>(
aggregation: TAggregation,
- direction?: OrderByDirection,
-): SchemaColumn & { type: "column"; direction?: OrderByDirection };
+ direction?: MetabaseOrderByDirection,
+): {
+ type: "column";
+ name: AggregationResultColumnName<TAggregation>;
+ direction?: MetabaseOrderByDirection;
+};
export function orderBy<const TDimension>(
dimension: TDimension,
- direction?: OrderByDirection,
-): TDimension & { direction?: OrderByDirection };
-
-export function orderBy<const TDimension>(
- dimension: TDimension,
- direction: OrderByDirection | undefined,
- options: BreakoutOptionsArgument<TDimension>,
-): TDimension & {
- direction?: OrderByDirection;
-} & BreakoutOptionsArgument<TDimension>;
+ direction?: MetabaseOrderByDirection,
+): TDimension & { direction?: MetabaseOrderByDirection };
export function orderBy<TDimension>(
dimension: TDimension,
- direction?: OrderByDirection,
- options?: BreakoutOptionsArgument<TDimension>,
+ direction?: MetabaseOrderByDirection,
) {
+ if (isNamedBreakout(dimension)) {
+ return {
+ type: "column",
+ name: dimension.name,
+ ...(direction ? { direction } : undefined),
+ };
+ }
+
const aggregationColumn = getAggregationResultColumn(dimension);
if (aggregationColumn) {
@@ -139,10 +164,6 @@ export function orderBy<TDimension>(
return {
...orderableDimension,
...(direction ? { direction } : undefined),
- ...(options?.unit !== undefined ? { unit: options.unit } : undefined),
- ...(options?.binning !== undefined
- ? { binning: options.binning }
- : undefined),
};
}
diff --git a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/tests/fixtures.ts b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/tests/fixtures.ts
index acf68590329..087649100f6 100644
--- a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/tests/fixtures.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/tests/fixtures.ts
@@ -106,7 +106,7 @@ export const TEST_SCHEMA = {
id: 21,
tableId: 1,
name: "Revenue",
- columns: [{ name: "sum", displayName: "Sum", jsType: "number" }],
+ columns: [{ name: "count", displayName: "Count", jsType: "number" }],
},
},
},
@@ -241,12 +241,17 @@ export const TEST_METADATA = {
name: "Revenue",
table_id: 1,
definition: {
- type: "query",
+ "lib/type": "mbql/query",
database: 1,
- query: {
- "source-table": 1,
- aggregation: [["count"]],
- },
+ stages: [
+ {
+ "lib/type": "mbql.stage/mbql",
+ "source-table": 1,
+ aggregation: [
+ ["count", { "lib/uuid": "00000000-0000-4000-8000-000000000021" }],
+ ],
+ },
+ ],
},
},
},
diff --git a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/tests/resolve-dataset-query-validation.unit.spec.tsx b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/tests/resolve-dataset-query-validation.unit.spec.tsx
index 1bba8c15954..b7df04fccf1 100644
--- a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/tests/resolve-dataset-query-validation.unit.spec.tsx
+++ b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/tests/resolve-dataset-query-validation.unit.spec.tsx
@@ -15,9 +15,9 @@ describe("resolveDatasetQuery validation", () => {
const field = TEST_SCHEMA.tables.orders.fields.createdAt;
expect(breakout(field, { unit: undefined })).not.toHaveProperty("unit");
- expect(orderBy(field, "asc", { unit: undefined })).not.toHaveProperty(
- "unit",
- );
+ expect(
+ orderBy(breakout(field, { unit: undefined }), "asc"),
+ ).not.toHaveProperty("unit");
});
it("rejects unknown dynamic query properties", async () => {
@@ -105,9 +105,12 @@ describe("resolveDatasetQuery validation", () => {
}),
],
orderBys: [
- orderBy(TEST_SCHEMA.tables.orders.fields.createdAt, "desc", {
- unit: "year",
- }),
+ orderBy(
+ breakout(TEST_SCHEMA.tables.orders.fields.createdAt, {
+ unit: "year",
+ }),
+ "desc",
+ ),
],
}),
).rejects.toThrow(
diff --git a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/tests/resolve-dataset-query.unit.spec.tsx b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/tests/resolve-dataset-query.unit.spec.tsx
index c6596d45966..56d7c312f0c 100644
--- a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/tests/resolve-dataset-query.unit.spec.tsx
+++ b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/tests/resolve-dataset-query.unit.spec.tsx
@@ -13,7 +13,16 @@ import { resolveDatasetQuery as resolveDatasetQueryInBundle } from "embedding-sd
import { cardApi } from "metabase/api";
import * as Lib from "metabase-lib";
-import { avg, breakout, count, filter, orderBy, sum } from "..";
+import {
+ aggregations,
+ avg,
+ breakout,
+ count,
+ distinct,
+ filter,
+ orderBy,
+ sum,
+} from "..";
import { TEST_METADATA, TEST_SCHEMA } from "./fixtures";
@@ -22,6 +31,12 @@ beforeEach(resetTestState);
describe("resolveDatasetQuery", () => {
it("loads table metadata and passes the public source DSL through Lib.createTestQuery", async () => {
const store = createMockStore();
+ const createdAtMonth = breakout(
+ TEST_SCHEMA.tables.orders.fields.createdAt,
+ {
+ unit: "month",
+ },
+ );
const datasetQuery = await resolveDatasetQueryInBundle(store)({
source: TEST_SCHEMA.tables.orders,
@@ -34,14 +49,8 @@ describe("resolveDatasetQuery", () => {
filter(TEST_SCHEMA.tables.orders.fields.status, "=", "paid"),
],
aggregations: [count(), sum(TEST_SCHEMA.tables.orders.fields.amount)],
- breakouts: [
- breakout(TEST_SCHEMA.tables.orders.fields.createdAt, { unit: "month" }),
- ],
- orderBys: [
- orderBy(TEST_SCHEMA.tables.orders.fields.createdAt, "desc", {
- unit: "month",
- }),
- ],
+ breakouts: [createdAtMonth],
+ orderBys: [orderBy(createdAtMonth, "desc")],
limit: 100,
});
@@ -99,13 +108,15 @@ describe("resolveDatasetQuery", () => {
it("passes breakout and orderBy binning through Lib.createTestQuery", async () => {
const { amount } = TEST_SCHEMA.tables.orders.fields;
- const binning = { strategy: "num-bins", numBins: 10 } as const;
+ const binnedAmountBreakout = breakout(amount, {
+ binning: { strategy: "num-bins", numBins: 10 },
+ });
const datasetQuery = await resolveDatasetQueryInBundle(createMockStore())({
source: TEST_SCHEMA.tables.orders,
aggregations: [count()],
- breakouts: [breakout(amount, { binning })],
- orderBys: [orderBy(amount, "asc", { binning })],
+ breakouts: [binnedAmountBreakout],
+ orderBys: [orderBy(binnedAmountBreakout, "asc")],
});
const binnedAmount = [
@@ -185,10 +196,12 @@ describe("resolveDatasetQuery", () => {
),
],
aggregations: [
- TEST_SCHEMA.metrics.revenue,
+ aggregations.metric(TEST_SCHEMA.metrics.revenue, { name: "revenue" }),
count(),
sum(TEST_SCHEMA.metrics.revenue.dimensions.orders.amount),
- TEST_SCHEMA.tables.orders.measures.revenue,
+ aggregations.measure(TEST_SCHEMA.tables.orders.measures.revenue, {
+ name: "orders",
+ }),
],
breakouts: [
breakout(TEST_SCHEMA.metrics.revenue.dimensions.orders.createdAt, {
@@ -228,10 +241,10 @@ describe("resolveDatasetQuery", () => {
["=", expect.anything(), ["field", expect.anything(), 101], "paid"],
],
aggregation: [
- ["metric", expect.anything(), 31],
+ ["metric", expect.objectContaining({ name: "revenue" }), 31],
["count", expect.anything()],
["sum", expect.anything(), ["field", expect.anything(), 102]],
- ["measure", expect.anything(), 21],
+ ["measure", expect.objectContaining({ name: "orders" }), 21],
],
breakout: [
[
@@ -302,9 +315,10 @@ describe("resolveDatasetQuery", () => {
],
orderBys: [
orderBy(
- TEST_SCHEMA.metrics.revenue.dimensions.orders.createdAt,
+ breakout(TEST_SCHEMA.metrics.revenue.dimensions.orders.createdAt, {
+ unit: "month",
+ }),
"desc",
- { unit: "month" },
),
],
limit: 12,
@@ -651,3 +665,242 @@ describe("resolveDatasetQuery", () => {
});
});
});
+
+describe("resolveDatasetQuery aggregation column names", () => {
+ const orders = TEST_SCHEMA.tables.orders;
+
+ it("refuses aggregations that share a column name", async () => {
+ await expect(
+ resolveDatasetQueryInBundle(createMockStore())({
+ source: orders,
+ aggregations: [count(), distinct(orders.fields.status)],
+ }),
+ ).rejects.toThrow(
+ 'Breakouts and aggregations need unique column names: Count, Distinct values of Status share the column name "count". Name them apart with the `name` option of `breakout` or of an aggregation helper, or with `aggregations.measure` or `aggregations.metric` for a measure or metric.',
+ );
+ });
+
+ it("accepts aggregations named apart", async () => {
+ const datasetQuery = await resolveDatasetQueryInBundle(createMockStore())({
+ source: orders,
+ aggregations: [
+ count(),
+ distinct(orders.fields.status, { name: "statuses" }),
+ ],
+ });
+
+ expect(stagesOf(datasetQuery)[0].aggregation).toEqual([
+ ["count", expect.anything()],
+ [
+ "distinct",
+ expect.objectContaining({ name: "statuses" }),
+ ["field", expect.anything(), 101],
+ ],
+ ]);
+ });
+
+ it("leaves a measure's own name out of its column name", async () => {
+ const datasetQuery = await resolveDatasetQueryInBundle(createMockStore())({
+ source: orders,
+ aggregations: [orders.measures.revenue],
+ });
+
+ expect(stagesOf(datasetQuery)[0].aggregation).toEqual([
+ ["measure", expect.not.objectContaining({ name: "Revenue" }), 21],
+ ]);
+ });
+
+ it("refuses a measure that shares a column name with another aggregation", async () => {
+ await expect(
+ resolveDatasetQueryInBundle(createMockStore())({
+ source: orders,
+ aggregations: [orders.measures.revenue, count()],
+ }),
+ ).rejects.toThrow('share the column name "count"');
+ });
+
+ it("passes a measure through aggregations.measure unchanged without a name", () => {
+ expect(aggregations.measure(orders.measures.revenue)).toBe(
+ orders.measures.revenue,
+ );
+ });
+
+ it("names a measure's column with aggregations.measure", async () => {
+ const datasetQuery = await resolveDatasetQueryInBundle(createMockStore())({
+ source: orders,
+ aggregations: [
+ aggregations.measure(orders.measures.revenue, { name: "revenue" }),
+ count(),
+ ],
+ });
+
+ expect(stagesOf(datasetQuery)[0].aggregation).toEqual([
+ ["measure", expect.objectContaining({ name: "revenue" }), 21],
+ ["count", expect.anything()],
+ ]);
+ });
+
+ it("refuses an orderBy on a column two aggregations share with the same message", async () => {
+ await expect(
+ resolveDatasetQueryInBundle(createMockStore())({
+ source: orders,
+ aggregations: [count(), distinct(orders.fields.status)],
+ breakouts: [breakout(orders.fields.createdAt, { unit: "month" })],
+ orderBys: [{ type: "column", name: "count" }],
+ }),
+ ).rejects.toThrow('share the column name "count"');
+ });
+
+ it("refuses named breakouts that share a column name", async () => {
+ await expect(
+ resolveDatasetQueryInBundle(createMockStore())({
+ source: orders,
+ aggregations: [count()],
+ breakouts: [
+ {
+ type: "breakout",
+ name: "period",
+ column: { ...orders.fields.createdAt, unit: "month" },
+ },
+ {
+ type: "breakout",
+ name: "period",
+ column: { ...orders.fields.createdAt, unit: "year" },
+ },
+ ],
+ }),
+ ).rejects.toThrow('share the column name "period"');
+ });
+
+ it("refuses a named breakout that shares an aggregation's column name", async () => {
+ await expect(
+ resolveDatasetQueryInBundle(createMockStore())({
+ source: orders,
+ aggregations: [count()],
+ breakouts: [
+ { type: "breakout", name: "count", column: orders.fields.status },
+ ],
+ }),
+ ).rejects.toThrow('share the column name "count"');
+ });
+
+ it("refuses a field broken out twice without names", async () => {
+ await expect(
+ resolveDatasetQueryInBundle(createMockStore())({
+ source: orders,
+ aggregations: [count()],
+ breakouts: [
+ breakout(orders.fields.createdAt, { unit: "month" }),
+ breakout(orders.fields.createdAt, { unit: "year" }),
+ ],
+ }),
+ ).rejects.toThrow('share the column name "CREATED_AT"');
+ });
+
+ it("accepts a field broken out twice with names", async () => {
+ const datasetQuery = await resolveDatasetQueryInBundle(createMockStore())({
+ source: orders,
+ aggregations: [count()],
+ breakouts: [
+ breakout(orders.fields.createdAt, { unit: "month", name: "month" }),
+ breakout(orders.fields.createdAt, { unit: "year", name: "year" }),
+ ],
+ });
+
+ expect(stagesOf(datasetQuery)[0].breakout).toHaveLength(2);
+ });
+
+ it("refuses dynamic aggregations that share a column name", async () => {
+ await expect(
+ resolveDatasetQueryInBundle(createMockStore())(
+ {
+ source: orders,
+ aggregations: [count()],
+ breakouts: [breakout(orders.fields.status)],
+ },
+ {
+ aggregations: [count(), distinct({ type: "column", name: "STATUS" })],
+ },
+ ),
+ ).rejects.toThrow('share the column name "count"');
+ });
+});
+
+describe("resolveDatasetQuery named breakouts", () => {
+ const orders = TEST_SCHEMA.tables.orders;
+ const createdMonth = breakout(orders.fields.createdAt, {
+ unit: "month",
+ name: "created_month",
+ });
+
+ it("names a breakout's result column with breakout's name option", async () => {
+ const datasetQuery = await resolveDatasetQueryInBundle(createMockStore())({
+ source: orders,
+ aggregations: [count()],
+ breakouts: [createdMonth],
+ orderBys: [orderBy(createdMonth, "desc")],
+ });
+
+ expect(stagesOf(datasetQuery)[0]).toMatchObject({
+ breakout: [
+ [
+ "field",
+ expect.objectContaining({
+ name: "created_month",
+ "temporal-unit": "month",
+ }),
+ 103,
+ ],
+ ],
+ "order-by": [
+ [
+ "desc",
+ expect.anything(),
+ ["field", expect.objectContaining({ name: "created_month" }), 103],
+ ],
+ ],
+ });
+ });
+
+ it("resolves a dynamic column by name, ignoring a field ID from another instance", async () => {
+ const datasetQuery = await resolveDatasetQueryInBundle(createMockStore())(
+ {
+ source: orders,
+ aggregations: [count()],
+ breakouts: [breakout(orders.fields.status)],
+ },
+ {
+ filters: [
+ filter({ ...orders.fields.status, fieldId: 999999 }, "=", "paid"),
+ ],
+ },
+ );
+
+ expect(stagesOf(datasetQuery)[1].filters).toEqual([
+ ["=", expect.anything(), ["field", expect.anything(), "STATUS"], "paid"],
+ ]);
+ });
+
+ it("lets a dynamic stage refer to a named breakout by its name", async () => {
+ const datasetQuery = await resolveDatasetQueryInBundle(createMockStore())(
+ {
+ source: orders,
+ aggregations: [count()],
+ breakouts: [createdMonth],
+ },
+ {
+ filters: [
+ filter({ type: "column", name: "created_month" }, "not-null"),
+ ],
+ },
+ );
+
+ expect(stagesOf(datasetQuery)[1].filters).toEqual([
+ [
+ "not-null",
+ expect.anything(),
+ ["field", expect.anything(), "created_month"],
+ ],
+ ]);
+ });
+});
diff --git a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/tests/type-contract-invalid.ts b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/tests/type-contract-invalid.ts
index 3ae0013a8a2..277b630e493 100644
--- a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/tests/type-contract-invalid.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/tests/type-contract-invalid.ts
@@ -2,8 +2,11 @@ import type { MetabaseCard } from "metabase/embedding-sdk/types/question";
import type { MetabaseQueryOptions, UseMetabaseQueryObjectResult } from "..";
import {
+ aggregations,
breakout,
count,
+ filter,
+ orderBy,
sum,
useMetabaseQuery,
useMetabaseQueryObject,
@@ -118,6 +121,63 @@ const _invalidMetricSourceQuery = {
// @ts-expect-error `unit` buckets a date, so only a date dimension offers it
breakout(TEST_SCHEMA.tables.orders.fields.status, { unit: "month" });
+// @ts-expect-error A bucketed orderBy takes the bucketed breakout instead of options
+orderBy(TEST_SCHEMA.tables.orders.fields.createdAt, "desc", { unit: "month" });
+
+const groupedOrders = TEST_SCHEMA.tables.orders;
+const groupedCreatedMonth = breakout(groupedOrders.fields.createdAt, {
+ unit: "month",
+ name: "created_month",
+});
+const groupedTotal = aggregations.sum(groupedOrders.fields.amount, {
+ name: "total",
+});
+const groupedQuery = {
+ source: groupedOrders,
+ aggregations: [
+ count(),
+ groupedTotal,
+ aggregations.max(groupedOrders.fields.amount),
+ ],
+ breakouts: [groupedCreatedMonth, groupedOrders.fields.status],
+} as const;
+
+defineQuery({
+ ...groupedQuery,
+ orderBys: [
+ // @ts-expect-error a grouped stage orders only by its breakout and aggregation names
+ { type: "column", name: "AMOUNT" },
+ // @ts-expect-error a named breakout's column takes its name, not its field's
+ { type: "column", name: "CREATED_AT" },
+ // @ts-expect-error a named aggregation's column takes its name, not its operator's
+ { type: "column", name: "sum" },
+ ],
+});
+
+defineQuery({
+ source: groupedOrders,
+ aggregations: [
+ {
+ type: "operator",
+ operator: "sum",
+ args: [groupedOrders.fields.amount],
+ name: "total",
+ },
+ ],
+ // @ts-expect-error a named aggregation's column takes its name, not its operator's
+ orderBys: [{ type: "column", name: "sum" }],
+});
+
+const plainOrdersQuery = defineQuery({ source: groupedOrders });
+const pickedOrdersQuery = defineQuery({
+ source: groupedOrders,
+ fields: [groupedOrders.fields.id, groupedOrders.fields.createdAt],
+});
+const aggregatedOrdersQuery = defineQuery({
+ source: groupedOrders,
+ aggregations: [count(), groupedTotal],
+});
+
function InvalidTypeFixtures() {
const staticQuery = defineQuery({
source: TEST_SCHEMA.tables.orders,
@@ -249,6 +309,68 @@ function InvalidTypeFixtures() {
// @ts-expect-error grouping in the dynamic stage drops the source columns
void groupedDynamicResult.data?.rows[0]?.AMOUNT;
+ const groupedStaticQuery = defineQuery(groupedQuery);
+
+ useMetabaseQuery(groupedStaticQuery, {
+ // @ts-expect-error a dynamic stage orders by the static query's result columns
+ orderBys: [{ type: "column", name: "AMOUNT" }],
+ });
+
+ useMetabaseQuery(groupedStaticQuery, {
+ aggregations: [count()],
+ breakouts: [{ ...groupedOrders.fields.status }],
+ // @ts-expect-error a grouping dynamic stage orders by its own breakouts and aggregations
+ orderBys: [{ type: "column", name: "total" }],
+ });
+
+ useMetabaseQuery(plainOrdersQuery, {
+ // @ts-expect-error a string column takes no numeric comparison
+ filters: [filter({ type: "column", name: "STATUS" }, ">", 1)],
+ });
+
+ useMetabaseQuery(pickedOrdersQuery, {
+ // @ts-expect-error the static query's fields leave out STATUS
+ filters: [filter({ type: "column", name: "STATUS" }, "not-null")],
+ });
+
+ useMetabaseQuery(aggregatedOrdersQuery, {
+ // @ts-expect-error a number column takes no string operator
+ filters: [filter({ type: "column", name: "total" }, "contains", "x")],
+ });
+
+ useMetabaseQuery(groupedStaticQuery, {
+ // @ts-expect-error a named breakout's column takes its name, not its field's
+ filters: [filter({ type: "column", name: "CREATED_AT" }, "not-null")],
+ });
+
+ useMetabaseQuery(groupedStaticQuery, {
+ // @ts-expect-error a date column takes no string operator
+ filters: [
+ filter({ type: "column", name: "created_month" }, "contains", "x"),
+ ],
+ });
+
+ // @ts-expect-error `unit` buckets a date, so a string column doesn't take it
+ useMetabaseQuery(groupedStaticQuery, {
+ aggregations: [count()],
+ breakouts: [breakout({ type: "column", name: "STATUS" }, { unit: "year" })],
+ });
+
+ useMetabaseQuery(groupedStaticQuery, {
+ aggregations: [
+ // @ts-expect-error a sum takes a number column
+ aggregations.sum({ type: "column", name: "STATUS" }),
+ ],
+ });
+
+ const regroupedResult = useMetabaseQuery(groupedStaticQuery, {
+ aggregations: [count()],
+ breakouts: [{ type: "column", name: "created_month" }],
+ });
+
+ // @ts-expect-error grouping in the dynamic stage drops the other static columns
+ void regroupedResult.data?.rows[0]?.STATUS;
+
return null;
}
diff --git a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/tests/type-contract-valid.ts b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/tests/type-contract-valid.ts
index 82dff006135..d56270c08d7 100644
--- a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/tests/type-contract-valid.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/tests/type-contract-valid.ts
@@ -2,6 +2,7 @@ import type { MetabaseCard } from "metabase/embedding-sdk/types/question";
import type { UseMetabaseQueryObjectResult } from "..";
import {
+ aggregations,
breakout,
count,
filter,
@@ -66,6 +67,84 @@ const _validHookResultCard = {
query: hookResult.query,
} satisfies MetabaseCard;
+const groupedOrders = TEST_SCHEMA.tables.orders;
+const groupedCreatedMonth = breakout(groupedOrders.fields.createdAt, {
+ unit: "month",
+ name: "created_month",
+});
+const groupedTotal = aggregations.sum(groupedOrders.fields.amount, {
+ name: "total",
+});
+const groupedQuery = {
+ source: groupedOrders,
+ aggregations: [
+ count(),
+ groupedTotal,
+ aggregations.max(groupedOrders.fields.amount),
+ ],
+ breakouts: [groupedCreatedMonth, groupedOrders.fields.status],
+} as const;
+
+defineQuery({
+ ...groupedQuery,
+ orderBys: [
+ orderBy(groupedCreatedMonth, "desc"),
+ orderBy(groupedTotal, "desc"),
+ orderBy(count()),
+ orderBy(groupedOrders.fields.status),
+ { type: "column", name: "created_month" },
+ { type: "column", name: "STATUS" },
+ { type: "column", name: "total" },
+ { type: "column", name: "count" },
+ { type: "column", name: "max" },
+ ],
+});
+
+defineQuery({
+ source: groupedOrders,
+ aggregations: [aggregations.distinct(groupedOrders.fields.status)],
+ orderBys: [{ type: "column", name: "count" }],
+});
+
+defineQuery({
+ source: groupedOrders,
+ aggregations: [
+ { type: "operator", operator: "sum", args: [groupedOrders.fields.amount] },
+ {
+ type: "operator",
+ operator: "avg",
+ args: [groupedOrders.fields.amount],
+ name: "average",
+ },
+ ],
+ orderBys: [
+ { type: "column", name: "sum" },
+ { type: "column", name: "average" },
+ ],
+});
+
+defineQuery({
+ source: groupedOrders,
+ aggregations: [
+ groupedOrders.measures.revenue,
+ aggregations.measure(groupedOrders.measures.revenue, { name: "revenue" }),
+ ],
+ orderBys: [
+ { type: "column", name: "count" },
+ { type: "column", name: "revenue" },
+ ],
+});
+
+const plainOrdersQuery = defineQuery({ source: groupedOrders });
+const pickedOrdersQuery = defineQuery({
+ source: groupedOrders,
+ fields: [groupedOrders.fields.id, groupedOrders.fields.createdAt],
+});
+const aggregatedOrdersQuery = defineQuery({
+ source: groupedOrders,
+ aggregations: [count(), groupedTotal],
+});
+
function ValidTypeFixtures() {
// A definition types `execute` and `result` on its own, no generics written.
const createOrder = useDataAppAction(CreateOrder);
@@ -156,6 +235,43 @@ function ValidTypeFixtures() {
void namedCountValue;
void namedSumValue;
+ const namedMeasureResult = useMetabaseQuery(
+ defineQuery({
+ source: TEST_SCHEMA.tables.orders,
+ aggregations: [
+ aggregations.measure(TEST_SCHEMA.tables.orders.measures.revenue, {
+ name: "revenue",
+ }),
+ count(),
+ ],
+ }),
+ );
+
+ const namedMeasureValue: number | null | undefined =
+ namedMeasureResult.data?.rows[0]?.revenue;
+
+ void namedMeasureValue;
+
+ const createdMonth = breakout(TEST_SCHEMA.tables.orders.fields.createdAt, {
+ unit: "month",
+ name: "created_month",
+ });
+
+ const namedBreakoutResult = useMetabaseQuery(
+ defineQuery({
+ source: TEST_SCHEMA.tables.orders,
+ aggregations: [count()],
+ breakouts: [createdMonth],
+ orderBys: [orderBy(createdMonth, "desc")],
+ }),
+ { orderBys: [orderBy(createdMonth, "asc")] },
+ );
+
+ const namedBreakoutValue: string | Date | null | undefined =
+ namedBreakoutResult.data?.rows[0]?.created_month;
+
+ void namedBreakoutValue;
+
const groupedMetricResult = useMetabaseQuery(
defineQuery<OrdersTable>({
source: TEST_SCHEMA.tables.orders,
@@ -220,6 +336,81 @@ function ValidTypeFixtures() {
useMetabaseQueryObject(staticQuery, { limit: 10 });
+ const groupedStaticQuery = defineQuery(groupedQuery);
+
+ useMetabaseQuery(groupedStaticQuery, {
+ orderBys: [
+ orderBy(groupedCreatedMonth, "asc"),
+ { type: "column", name: "total" },
+ ],
+ });
+
+ useMetabaseQuery(groupedStaticQuery, {
+ aggregations: [count()],
+ breakouts: [{ ...groupedOrders.fields.status }],
+ orderBys: [{ type: "column", name: "count" }],
+ });
+
+ useMetabaseQuery(plainOrdersQuery, {
+ filters: [filter({ type: "column", name: "STATUS" }, "contains", "p")],
+ });
+
+ useMetabaseQuery(pickedOrdersQuery, {
+ filters: [
+ filter({ type: "column", name: "CREATED_AT" }, "time-interval", "x"),
+ ],
+ });
+
+ useMetabaseQuery(aggregatedOrdersQuery, {
+ filters: [filter({ type: "column", name: "total" }, ">", 1)],
+ });
+
+ useMetabaseQuery(groupedStaticQuery, {
+ filters: [
+ filter({ type: "column", name: "created_month" }, "not-null"),
+ filter({ type: "column", name: "STATUS" }, "=", "paid"),
+ ],
+ });
+
+ const regroupedPlainResult = useMetabaseQuery(plainOrdersQuery, {
+ aggregations: [count()],
+ breakouts: [{ type: "column", name: "STATUS" }],
+ });
+
+ const regroupedStatus: string | null | undefined =
+ regroupedPlainResult.data?.rows[0]?.STATUS;
+ const regroupedCount: number | null | undefined =
+ regroupedPlainResult.data?.rows[0]?.count;
+
+ void [regroupedStatus, regroupedCount];
+
+ const regroupedResult = useMetabaseQuery(groupedStaticQuery, {
+ aggregations: [
+ aggregations.sum({ type: "column", name: "total" }),
+ aggregations.max({ type: "column", name: "total" }),
+ aggregations.distinct(
+ { type: "column", name: "STATUS" },
+ { name: "statuses" },
+ ),
+ ],
+ breakouts: [
+ { type: "column", name: "created_month" },
+ breakout(
+ { type: "column", name: "created_month" },
+ { unit: "year", name: "created_year" },
+ ),
+ ],
+ });
+
+ const regroupedMonth: string | Date | null | undefined =
+ regroupedResult.data?.rows[0]?.created_month;
+ const regroupedYear: string | Date | null | undefined =
+ regroupedResult.data?.rows[0]?.created_year;
+ const regroupedSum: number | null | undefined =
+ regroupedResult.data?.rows[0]?.sum;
+
+ void [regroupedMonth, regroupedYear, regroupedSum];
+
return null;
}
diff --git a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/types.ts b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/types.ts
index b7bf7360d48..e6506a10673 100644
--- a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/types.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-metabase-query/types.ts
@@ -107,7 +107,7 @@ export type MetricReference<TTable = unknown> = Omit<
* `FieldReference` is deliberately not the type to reach for: it also admits
* FK-joined dimensions, which a local source table can't accept.
*/
-export type LocalFieldReference<TTable = unknown> = Omit<
+export type MetabaseLocalFieldReference<TTable = unknown> = Omit<
FieldSchema,
"sourceFieldId" | "tableId"
> & {
@@ -130,7 +130,7 @@ type JoinedFieldReference = Omit<FieldSchema, "sourceFieldId" | "tableId"> & {
};
export type FieldReference<TTable = unknown> =
- | LocalFieldReference<TTable>
+ | MetabaseLocalFieldReference<TTable>
| JoinedFieldReference;
// `name` names the result column, which is how a later stage refers to it. A
@@ -188,16 +188,38 @@ export type FieldAggregationSchema<
];
};
-type DimensionAggregation<TDimension> =
+type AggregationForDimension<TDimension> =
| CountAggregation
| CountAggregationSchema
- | FieldAggregation<FieldAggregationOperator, TDimension>
- | FieldAggregationSchema<FieldAggregationOperator, TDimension>;
+ | FieldAggregation<
+ "sum" | "avg" | "median",
+ NumericAggregationDimension<TDimension>
+ >
+ | FieldAggregation<"min" | "max", OrderableAggregationDimension<TDimension>>
+ | FieldAggregation<"distinct", TDimension>;
+
+type FirstSchemaColumn<TAggregation> = TAggregation extends {
+ columns?: readonly [infer TColumn, ...unknown[]];
+}
+ ? TColumn
+ : SchemaColumn;
+
+export type NamedSavedAggregation<
+ TAggregation = unknown,
+ TName extends string = string,
+> = {
+ name: TName;
+ value: TAggregation;
+ columns: readonly [
+ Omit<FirstSchemaColumn<TAggregation>, "name"> & { name: TName },
+ ];
+};
type AnyAggregation<TTable = unknown> =
- | DimensionAggregation<FieldReference<TTable>>
+ | AggregationForDimension<FieldReference<TTable>>
| MeasureReference<TTable>
- | MetricReference<TTable>;
+ | MetricReference<TTable>
+ | NamedSavedAggregation<MeasureReference<TTable> | MetricReference<TTable>>;
type AggregationDimensionWithJavaScriptType<
TDimension,
@@ -266,7 +288,7 @@ export type ValueFilterOperatorForDimension<TDimension> = Exclude<
UnaryFilterOperator | BetweenFilterOperator
>;
-export type MetabaseDimensionFilterForOperator<
+export type FilterForOperator<
TDimension,
TOperator extends FilterOperatorForDimension<TDimension>,
> = {
@@ -281,23 +303,19 @@ export type MetabaseDimensionFilterForOperator<
];
};
-type MetabaseDimensionFilterForDimension<TDimension> =
- TDimension extends unknown
- ? {
- type: "operator";
- operator: FilterOperatorForDimension<TDimension>;
- args: readonly [
- TDimension,
- ...{
- type: "literal";
- value: FilterLiteralValue;
- }[],
- ];
- }
- : never;
-
-export type MetabaseDimensionFilter<TEntity = unknown> =
- MetabaseDimensionFilterForDimension<FieldReference<TEntity>>;
+type FilterForDimension<TDimension> = TDimension extends unknown
+ ? {
+ type: "operator";
+ operator: FilterOperatorForDimension<TDimension>;
+ args: readonly [
+ TDimension,
+ ...{
+ type: "literal";
+ value: FilterLiteralValue;
+ }[],
+ ];
+ }
+ : never;
export type FilterLiteralValue = string | number | bigint | boolean;
@@ -323,7 +341,7 @@ export type BreakoutOptionsArgument<TDimension> = [
? { unit?: never; binning?: BinningOptions }
: { unit?: TemporalUnit; binning?: BinningOptions };
-export type MetabaseBreakoutObjectForDimension<TDimension> =
+export type BreakoutObjectForDimension<TDimension> =
| ([DateBucketDimension<TDimension>] extends [never]
? never
: DateBucketDimension<TDimension> & {
@@ -333,27 +351,35 @@ export type MetabaseBreakoutObjectForDimension<TDimension> =
| ([NonDateBucketDimension<TDimension>] extends [never]
? never
: NonDateBucketDimension<TDimension> & {
+ unit?: never;
binning?: BinningOptions;
});
+export type NamedBreakout<TColumn = unknown, TName extends string = string> = {
+ type: "breakout";
+ name: TName;
+ column: TColumn;
+};
+
type BreakoutForDimension<TDimension> =
- | TDimension
- | MetabaseBreakoutObjectForDimension<TDimension>;
+ | (TDimension & { unit?: never; binning?: never })
+ | BreakoutObjectForDimension<TDimension>
+ | NamedBreakout<TDimension | BreakoutObjectForDimension<TDimension>>;
export type MetabaseBreakout<TTable = unknown> = BreakoutForDimension<
FieldReference<TTable>
>;
-export type OrderByDirection = "asc" | "desc";
+export type MetabaseOrderByDirection = "asc" | "desc";
-type MetabaseOrderByObjectForDimension<TDimension> =
- MetabaseBreakoutObjectForDimension<TDimension> & {
- direction?: OrderByDirection;
+type OrderByObjectForDimension<TDimension> =
+ BreakoutObjectForDimension<TDimension> & {
+ direction?: MetabaseOrderByDirection;
};
type OrderByForDimension<TDimension> =
- | (TDimension & { direction?: OrderByDirection })
- | MetabaseOrderByObjectForDimension<TDimension>
+ | (TDimension & { direction?: MetabaseOrderByDirection })
+ | OrderByObjectForDimension<TDimension>
| AggregationResultOrderBy;
export type MetabaseOrderBy<TTable = unknown> = OrderByForDimension<
@@ -363,7 +389,7 @@ export type MetabaseOrderBy<TTable = unknown> = OrderByForDimension<
type AggregationResultOrderBy = {
type: "column";
name: string;
- direction?: OrderByDirection;
+ direction?: MetabaseOrderByDirection;
};
export type DefaultBinningOptions = {
@@ -391,10 +417,7 @@ export type BinningOptions =
* question's result columns.
*/
type StageClauses<TDimension, TAggregation, TFilter> = {
- filters?: readonly (
- | TFilter
- | MetabaseDimensionFilterForDimension<TDimension>
- )[];
+ filters?: readonly (TFilter | FilterForDimension<TDimension>)[];
orderBys?: readonly OrderByForDimension<TDimension>[];
limit?: number;
enabled?: boolean;
@@ -434,9 +457,76 @@ export type RequireAggregationsForBreakouts<TQuery> = TQuery extends {
: { aggregations: readonly [unknown, ...unknown[]] }
: unknown;
-export type TableQuery<TTable, TQuery = unknown> = TableQueryBase<TTable> &
+type TableQuery<TTable, TQuery = unknown> = TableQueryBase<TTable> &
RequireAggregationsForBreakouts<TQuery>;
+export type AggregationResultColumnName<TAggregation> = TAggregation extends {
+ columns: readonly [{ name: infer TName }, ...unknown[]];
+}
+ ? TName
+ : TAggregation extends { type: "operator"; operator: infer TOperator }
+ ? TAggregation extends { name: infer TName extends string }
+ ? TName
+ : TOperator extends "distinct"
+ ? "count"
+ : TOperator
+ : string;
+
+type ColumnName<TColumn> = TColumn extends { name: infer TName }
+ ? TName
+ : never;
+
+type QueryGroupedColumnNames<TQuery> =
+ | ColumnName<QueryBreakoutColumns<TQuery>>
+ | (TQuery extends { aggregations?: infer TAggregations }
+ ? AggregationResultColumnName<TupleElement<NonNullable<TAggregations>>>
+ : never);
+
+type AggregatesResultColumns<TQuery> = TQuery extends {
+ aggregations: readonly [unknown, ...unknown[]];
+}
+ ? true
+ : false;
+
+type OrderByWithName<TOrderBy, TNames> = TOrderBy extends
+ | { tableId: unknown }
+ | { sourceFieldId: unknown }
+ ? TOrderBy
+ : TOrderBy extends { type: "column"; name: infer TName }
+ ? [TName] extends [TNames]
+ ? TOrderBy
+ : { orderByColumnNames: `${TNames & string}` }
+ : TOrderBy;
+
+/** Narrows the name-only order-bys of `TQuery` to `TNames`. */
+type RequireOrderByNames<TQuery, TNames> = [TNames] extends [never]
+ ? unknown
+ : TQuery extends { orderBys: infer TOrderBys extends readonly unknown[] }
+ ? {
+ orderBys: {
+ [TIndex in keyof TOrderBys]: OrderByWithName<
+ TOrderBys[TIndex],
+ TNames
+ >;
+ };
+ }
+ : unknown;
+
+/** Requires a grouped stage's name-only order-bys to name one of its breakout or aggregation columns. */
+export type RequireGroupedOrderByNames<TQuery> =
+ AggregatesResultColumns<TQuery> extends true
+ ? RequireOrderByNames<TQuery, QueryGroupedColumnNames<TQuery>>
+ : unknown;
+
+/** Requires a dynamic stage's name-only order-bys to name its own grouped columns, or else the static query's result columns. */
+type RequireDynamicOrderByNames<TEntity, TQuery, TDynamic> =
+ AggregatesResultColumns<TDynamic> extends true
+ ? RequireGroupedOrderByNames<TDynamic>
+ : RequireOrderByNames<
+ TDynamic,
+ ColumnName<QueryResultColumns<TEntity, TQuery>>
+ >;
+
export type MetabaseQueryOptions<
TEntity = unknown,
_TSchema = unknown,
@@ -462,10 +552,15 @@ type QueryFieldColumns<TQuery> = TQuery extends { fields?: infer TFields }
? TupleElement<NonNullable<TFields>>
: never;
+type BreakoutColumn<TBreakout> =
+ TBreakout extends NamedBreakout<infer TColumn, infer TName>
+ ? Omit<TColumn, "name"> & { name: TName }
+ : TBreakout;
+
type QueryBreakoutColumns<TQuery> = TQuery extends {
breakouts?: infer TBreakouts;
}
- ? TupleElement<NonNullable<TBreakouts>>
+ ? BreakoutColumn<TupleElement<NonNullable<TBreakouts>>>
: never;
type QueryAggregationColumns<TQuery> = TQuery extends {
@@ -520,7 +615,7 @@ type DefaultQuestionColumns<TEntity, TQuery> =
? TupleElement<NonNullable<TColumns>>
: never;
-type QueryResultColumn<TEntity, TQuery> =
+type QueryResultColumns<TEntity, TQuery> =
| DefaultTableColumns<TEntity, TQuery>
| DefaultQuestionColumns<TEntity, TQuery>
| QueryFieldColumns<TQuery>
@@ -532,10 +627,38 @@ type QueryResultColumn<TEntity, TQuery> =
* without a generated schema name a result column by hand.
*/
export type MetabaseDynamicColumn<TEntity = unknown, TQuery = unknown> = [
- QueryResultColumn<TEntity, TQuery>,
+ QueryResultColumns<TEntity, TQuery>,
] extends [never]
? SchemaColumn & { type: "column" }
- : QueryResultColumn<TEntity, TQuery>;
+ :
+ | QueryResultColumns<TEntity, TQuery>
+ | ColumnNameReference<QueryResultColumns<TEntity, TQuery>>;
+
+/** A result column referenced by its name alone, typed by the column's `jsType`. */
+type ColumnNameReference<TColumn> = TColumn extends SchemaColumn
+ ? { type: "column"; name: TColumn["name"] } & (TColumn extends {
+ jsType: infer TJavaScriptType;
+ }
+ ? { jsType?: TJavaScriptType }
+ : unknown)
+ : never;
+
+type ColumnByName<TColumns, TColumn> = TColumn extends { name: infer TName }
+ ? [Extract<TColumns, { name: TName }>] extends [never]
+ ? TColumn
+ : Extract<TColumns, { name: TName }>
+ : TColumn;
+
+type DynamicBreakoutColumn<TColumns, TBreakout> =
+ TBreakout extends NamedBreakout<infer TColumn, infer TName>
+ ? Omit<ColumnByName<TColumns, TColumn>, "name"> & { name: TName }
+ : ColumnByName<TColumns, TBreakout>;
+
+type DynamicBreakoutColumns<TColumns, TDynamic> = TDynamic extends {
+ breakouts?: infer TBreakouts;
+}
+ ? DynamicBreakoutColumn<TColumns, TupleElement<NonNullable<TBreakouts>>>
+ : never;
/**
* Clauses layered on top of a static query — the part a UI changes at runtime.
@@ -547,7 +670,7 @@ export type MetabaseDynamicQuery<
TQuery = unknown,
> = StageClauses<
MetabaseDynamicColumn<TEntity, TQuery>,
- DimensionAggregation<MetabaseDynamicColumn<TEntity, TQuery>>,
+ AggregationForDimension<MetabaseDynamicColumn<TEntity, TQuery>>,
never
>;
@@ -562,7 +685,8 @@ type QueryEntity<TEntity, TQuery> = [TEntity] extends [undefined]
type InferResultSchema<TEntity, TQuery, TDynamic> =
ReshapesResultColumns<TDynamic> extends true
? RowsFromColumns<
- QueryBreakoutColumns<TDynamic> | QueryAggregationColumns<TDynamic>
+ | DynamicBreakoutColumns<QueryResultColumns<TEntity, TQuery>, TDynamic>
+ | QueryAggregationColumns<TDynamic>
>
: InferQuerySchema<TEntity, TQuery>;
@@ -597,11 +721,17 @@ export type UseMetabaseQuery = <
DefinedQuery &
(TQuery extends MetabaseQueryOptions<TEntity, TSchema>
? TQuery extends { source: unknown }
- ? RequireAggregationsForBreakouts<TQuery>
+ ? RequireAggregationsForBreakouts<TQuery> &
+ RequireGroupedOrderByNames<TQuery>
: unknown
: MetabaseQueryOptions<TEntity, TSchema>),
dynamicQuery?: TDynamic &
- (TDynamic extends MetabaseDynamicQuery<TEntity, TQuery>
- ? RequireAggregationsForBreakouts<TDynamic>
- : MetabaseDynamicQuery<TEntity, TQuery>),
+ (TDynamic extends MetabaseDynamicQuery<QueryEntity<TEntity, TQuery>, TQuery>
+ ? RequireAggregationsForBreakouts<TDynamic> &
+ RequireDynamicOrderByNames<
+ QueryEntity<TEntity, TQuery>,
+ TQuery,
+ TDynamic
+ >
+ : MetabaseDynamicQuery<QueryEntity<TEntity, TQuery>, TQuery>),
) => UseMetabaseQueryResult<QueryEntity<TEntity, TQuery>, TQuery, TDynamic>;
diff --git a/frontend/src/embedding-sdk-bundle/lib/create-metabase-query/index.ts b/frontend/src/embedding-sdk-bundle/lib/create-metabase-query/index.ts
index 3db80d15f0a..9a3a6fb2d4c 100644
--- a/frontend/src/embedding-sdk-bundle/lib/create-metabase-query/index.ts
+++ b/frontend/src/embedding-sdk-bundle/lib/create-metabase-query/index.ts
@@ -15,6 +15,7 @@ import * as Lib from "metabase-lib";
import type {
Card,
DatasetQuery,
+ TestBreakoutSpec,
TestColumnSpec,
TestExpressionSpec,
TestQuerySpec,
@@ -24,7 +25,11 @@ import type {
import { isObject } from "metabase-types/guards";
import { loadReferencedMetricMetadata } from "./metric-metadata";
-import { validateDynamicQuery, validateQueryInput } from "./validation";
+import {
+ validateDynamicQuery,
+ validateQueryInput,
+ validateUniqueColumnNames,
+} from "./validation";
export type ResolveDatasetQuery = (
store: SdkStore,
@@ -135,18 +140,26 @@ function resolveQueryFromLoadedMetadata(
const provider = selectMetadataProviderUnfiltered(state, databaseId);
const sourceStage = toStageSpec(input);
- const datasetQuery = Lib.toJsQuery(
+ // The dynamic clauses run as their own stage rather than merging into the
+ // source stage. Merged, they would apply before the static aggregation on
+ // a table source but after it on the published card — the same app would
+ // return different numbers in the dev preview and in production.
+ const dynamicStage = dynamicQuery && toResultColumnStageSpec(dynamicQuery);
+
+ validateUniqueColumnNames(
Lib.createTestQuery(provider, {
- // The dynamic clauses run as their own stage rather than merging into the
- // source stage. Merged, they would apply before the static aggregation on
- // a table source but after it on the published card — the same app would
- // return different numbers in the dev preview and in production.
- stages: dynamicQuery
- ? [sourceStage, toResultColumnStageSpec(dynamicQuery)]
- : [sourceStage],
+ stages: dynamicStage
+ ? [withoutOrderBys(sourceStage), withoutOrderBys(dynamicStage)]
+ : [withoutOrderBys(sourceStage)],
} satisfies TestQuerySpec),
);
+ const query = Lib.createTestQuery(provider, {
+ stages: dynamicStage ? [sourceStage, dynamicStage] : [sourceStage],
+ } satisfies TestQuerySpec);
+
+ const datasetQuery = Lib.toJsQuery(query);
+
// Lib reads the database off the metadata provider, and a user who may read a
// card but not create queries gets none from `/api/card/:id/query_metadata` —
// so the query comes back without `:database`, which `/api/dataset` rejects.
@@ -154,6 +167,13 @@ function resolveQueryFromLoadedMetadata(
return { ...datasetQuery, database: databaseId };
}
+function withoutOrderBys<TStage extends TestStageSpec>({
+ orderBys: _orderBys,
+ ...stage
+}: TStage) {
+ return stage;
+}
+
function toStageSpec(input: QueryInput): TestStageWithSourceSpec {
if (!isQuestionInput(input)) {
return input;
@@ -181,17 +201,19 @@ function toResultColumnStageSpec({
...(aggregations && {
aggregations: aggregations.map(toResultColumnExpressionSpec),
}),
- ...(breakouts && { breakouts: breakouts.map(toResultColumnSpec) }),
+ ...(breakouts && { breakouts: breakouts.map(toResultBreakoutSpec) }),
...(orderBys && { orderBys: orderBys.map(toResultColumnSpec) }),
...(limit != null && { limit }),
};
}
// A card stage exposes the saved question's result columns, which are no
-// longer joined, so the join and foreign key keys are dropped; the field ID or
-// the name still finds the column.
+// longer joined, so the join and foreign key keys are dropped. The field ID is
+// dropped too, as it differs between the instance an app is built against and
+// the one it runs on; the name finds the column.
function toResultColumnSpec<TSpec extends TestColumnSpec>(spec: TSpec) {
const {
+ fieldId: _fieldId,
joinAlias: _joinAlias,
sourceFieldId: _sourceFieldId,
sourceFieldJoinAlias: _sourceFieldJoinAlias,
@@ -201,6 +223,14 @@ function toResultColumnSpec<TSpec extends TestColumnSpec>(spec: TSpec) {
return resultColumn;
}
+function toResultBreakoutSpec(spec: TestBreakoutSpec): TestBreakoutSpec {
+ if (spec.type === "breakout") {
+ return { ...spec, column: toResultColumnSpec(spec.column) };
+ }
+
+ return toResultColumnSpec(spec);
+}
+
function toResultColumnExpressionSpec(
spec: TestExpressionSpec,
): TestExpressionSpec {
diff --git a/frontend/src/embedding-sdk-bundle/lib/create-metabase-query/metric-metadata.ts b/frontend/src/embedding-sdk-bundle/lib/create-metabase-query/metric-metadata.ts
index c35c3de26fc..da92e538fa1 100644
--- a/frontend/src/embedding-sdk-bundle/lib/create-metabase-query/metric-metadata.ts
+++ b/frontend/src/embedding-sdk-bundle/lib/create-metabase-query/metric-metadata.ts
@@ -1,6 +1,9 @@
import type { SdkStore } from "embedding-sdk-bundle/store/types";
import type { TableQueryInput } from "embedding-sdk-shared/lib/create-metabase-query/input-guards";
-import { isMetricReference } from "embedding-sdk-shared/lib/create-metabase-query/input-guards";
+import {
+ isMetricReference,
+ unwrapNamedAggregation,
+} from "embedding-sdk-shared/lib/create-metabase-query/input-guards";
import { cardApi } from "metabase/api";
import { runRtkEndpoint } from "metabase/api/utils/run-rtk-endpoint";
@@ -16,7 +19,10 @@ export const loadReferencedMetricMetadata = (
const collectMetricIdsToLoadMetadata = (query: TableQueryInput): number[] => [
...new Set(
- query.aggregations?.filter(isMetricReference).map((metric) => metric.id),
+ query.aggregations
+ ?.map(unwrapNamedAggregation)
+ .filter(isMetricReference)
+ .map((metric) => metric.id),
),
];
diff --git a/frontend/src/embedding-sdk-bundle/lib/create-metabase-query/validation.ts b/frontend/src/embedding-sdk-bundle/lib/create-metabase-query/validation.ts
index ff84ab820c1..d30e666ba9c 100644
--- a/frontend/src/embedding-sdk-bundle/lib/create-metabase-query/validation.ts
+++ b/frontend/src/embedding-sdk-bundle/lib/create-metabase-query/validation.ts
@@ -5,12 +5,15 @@ import {
type TableQueryInput,
isMeasureReference,
isMetricReference,
+ isNamedBreakout,
isSegmentReference,
+ unwrapNamedAggregation,
} from "embedding-sdk-shared/lib/create-metabase-query/input-guards";
import type {
MetricSchema,
QuestionSchema,
} from "embedding-sdk-shared/lib/create-metabase-query/schema";
+import * as Lib from "metabase-lib";
import { isObject } from "metabase-types/guards";
// `satisfies` ties the list to the input type, so a renamed or mistyped clause
@@ -130,7 +133,8 @@ function validateResultColumnClauses(
});
input.aggregations?.forEach((aggregation) => {
- if (isMeasureReference(aggregation) || isMetricReference(aggregation)) {
+ const unwrapped = unwrapNamedAggregation(aggregation);
+ if (isMeasureReference(unwrapped) || isMetricReference(unwrapped)) {
throw new Error(
`${label} aggregations cannot use Measures or Metrics, which belong to a table source.`,
);
@@ -147,7 +151,10 @@ function validateResultColumnClauses(
});
input.breakouts?.forEach((breakout) => {
- validateDimension(breakout, `${label} breakouts`);
+ validateDimension(
+ isNamedBreakout(breakout) ? breakout.column : breakout,
+ `${label} breakouts`,
+ );
});
validateOrderBys(
@@ -210,7 +217,7 @@ function validateTableScopedInputs(input: TableQueryInput) {
);
});
- input.aggregations?.forEach((aggregation) => {
+ input.aggregations?.map(unwrapNamedAggregation).forEach((aggregation) => {
if (isMetricReference(aggregation)) {
validateMetricAggregation(aggregation, tableId);
return;
@@ -233,7 +240,11 @@ function validateTableScopedInputs(input: TableQueryInput) {
});
input.breakouts?.forEach((breakout) => {
- validateGeneratedTableReference(breakout, tableId, "Table query breakouts");
+ validateGeneratedTableReference(
+ isNamedBreakout(breakout) ? breakout.column : breakout,
+ tableId,
+ "Table query breakouts",
+ );
});
validateOrderBys(input, "Table query orderBys", (orderBy) =>
@@ -387,12 +398,18 @@ function isBreakoutReference(
return false;
}
- return (breakouts ?? []).some(
- (breakout) =>
- (matchByName
- ? namesMatch(breakout, value)
- : fieldsMatch(breakout, value)) && bucketOptionsMatch(breakout, value),
- );
+ return (breakouts ?? []).some((breakout) => {
+ if (isNamedBreakout(breakout) && breakout.name === value.name) {
+ return true;
+ }
+
+ const column = isNamedBreakout(breakout) ? breakout.column : breakout;
+
+ return (
+ (matchByName ? namesMatch(column, value) : fieldsMatch(column, value)) &&
+ bucketOptionsMatch(column, value)
+ );
+ });
}
function getTableId(value: unknown): number | undefined {
@@ -500,3 +517,69 @@ function binningOptionsMatch(left: unknown, right: unknown) {
left.binWidth === right.binWidth
);
}
+
+type StageColumnName = {
+ name: string;
+ displayName: string;
+};
+
+function stageColumnNames(
+ query: Lib.Query,
+ stageIndex: number,
+): StageColumnName[] {
+ const breakouts = Lib.breakouts(query, stageIndex).reduce<StageColumnName[]>(
+ (columns, breakout) => {
+ const column = Lib.breakoutColumn(query, stageIndex, breakout);
+
+ if (column) {
+ const { name, displayName } = Lib.displayInfo(
+ query,
+ stageIndex,
+ column,
+ );
+ columns.push({ name, displayName });
+ }
+
+ return columns;
+ },
+ [],
+ );
+ const aggregations = Lib.aggregations(query, stageIndex).map(
+ (aggregation) => ({
+ name: Lib.displayInfo(
+ query,
+ stageIndex,
+ Lib.aggregationColumn(query, stageIndex, aggregation),
+ ).name,
+ displayName: Lib.displayInfo(query, stageIndex, aggregation).displayName,
+ }),
+ );
+
+ return [...breakouts, ...aggregations];
+}
+
+function stageConflicts(query: Lib.Query, stageIndex: number): string[] {
+ const byName = new Map<string, StageColumnName[]>();
+ stageColumnNames(query, stageIndex).forEach((column) => {
+ byName.set(column.name, [...(byName.get(column.name) ?? []), column]);
+ });
+
+ return [...byName]
+ .filter(([, columns]) => columns.length > 1)
+ .map(
+ ([name, columns]) =>
+ `${columns.map((column) => column.displayName).join(", ")} share the column name "${name}"`,
+ );
+}
+
+export function validateUniqueColumnNames(query: Lib.Query) {
+ const conflicts = Lib.stageIndexes(query).flatMap((stageIndex) =>
+ stageConflicts(query, stageIndex),
+ );
+
+ if (conflicts.length > 0) {
+ throw new Error(
+ `Breakouts and aggregations need unique column names: ${conflicts.join("; ")}. Name them apart with the \`name\` option of \`breakout\` or of an aggregation helper, or with \`aggregations.measure\` or \`aggregations.metric\` for a measure or metric.`,
+ );
+ }
+}
diff --git a/frontend/src/embedding-sdk-shared/lib/create-metabase-query/input-guards.ts b/frontend/src/embedding-sdk-shared/lib/create-metabase-query/input-guards.ts
index 579da54ffcf..f7603d0018f 100644
--- a/frontend/src/embedding-sdk-shared/lib/create-metabase-query/input-guards.ts
+++ b/frontend/src/embedding-sdk-shared/lib/create-metabase-query/input-guards.ts
@@ -1,5 +1,8 @@
import type {
+ TestAggregationSpec,
+ TestBreakoutWithNameSpec,
TestExpressionSpec,
+ TestNamedAggregationSpec,
TestStageSpec,
TestStageWithSourceSpec,
} from "metabase-types/api";
@@ -55,6 +58,25 @@ export const isSegmentReference = (value: unknown): value is SegmentSchema =>
export const isMeasureReference = (value: unknown): value is MeasureSchema =>
isObject(value) && typeof value.id === "number" && value.type === "measure";
+export const isNamedBreakout = (
+ value: unknown,
+): value is TestBreakoutWithNameSpec =>
+ isObject(value) &&
+ value.type === "breakout" &&
+ typeof value.name === "string" &&
+ isObject(value.column);
+
+export const isNamedAggregation = (
+ value: unknown,
+): value is TestNamedAggregationSpec =>
+ isObject(value) &&
+ typeof value.name === "string" &&
+ "value" in value &&
+ !("type" in value);
+
+export const unwrapNamedAggregation = (aggregation: TestAggregationSpec) =>
+ isNamedAggregation(aggregation) ? aggregation.value : aggregation;
+
export const isQuestionInput = (input: unknown): input is QuestionQueryInput =>
isObject(input) && "source" in input && isQuestionReference(input.source);
diff --git a/frontend/src/metabase-lib/query/aggregation.ts b/frontend/src/metabase-lib/query/aggregation.ts
index 6375b2bdd99..a1febd8ca08 100644
--- a/frontend/src/metabase-lib/query/aggregation.ts
+++ b/frontend/src/metabase-lib/query/aggregation.ts
@@ -59,6 +59,14 @@ export function aggregations(
return ML.aggregations(query, stageIndex);
}
+export function aggregationColumn(
+ query: Query,
+ stageIndex: number,
+ aggregation: AggregationClause,
+): ColumnMetadata {
+ return ML.aggregation_column(query, stageIndex, aggregation);
+}
+
export function aggregationClause(
operator: AggregationOperator,
column?: ColumnMetadata,
diff --git a/frontend/src/metabase-lib/query/breakout.unit.spec.ts b/frontend/src/metabase-lib/query/breakout.unit.spec.ts
index 68df260a56d..18beea30959 100644
--- a/frontend/src/metabase-lib/query/breakout.unit.spec.ts
+++ b/frontend/src/metabase-lib/query/breakout.unit.spec.ts
@@ -1,5 +1,6 @@
import { checkNotNull } from "metabase/utils/types";
import * as Lib from "metabase-lib";
+import { ORDERS_ID } from "metabase-types/api/mocks/presets";
import {
DEFAULT_TEST_QUERY,
@@ -169,3 +170,34 @@ describe("breakout", () => {
});
});
});
+
+describe("named breakouts", () => {
+ it("names a breakout's result column with a test spec of type breakout", () => {
+ const query = Lib.createTestQuery(SAMPLE_PROVIDER, {
+ stages: [
+ {
+ source: { type: "table", id: ORDERS_ID },
+ breakouts: [
+ {
+ type: "breakout",
+ name: "created_month",
+ column: { type: "column", name: "CREATED_AT", unit: "month" },
+ },
+ {
+ type: "breakout",
+ name: "created_year",
+ column: { type: "column", name: "CREATED_AT", unit: "year" },
+ },
+ ],
+ aggregations: [{ type: "operator", operator: "count", args: [] }],
+ },
+ ],
+ });
+
+ expect(
+ Lib.returnedColumns(query, 0).map(
+ (column) => Lib.displayInfo(query, 0, column).name,
+ ),
+ ).toEqual(["created_month", "created_year", "count"]);
+ });
+});
diff --git a/frontend/src/metabase-lib/v1/parameters/utils/targets.unit.spec.ts b/frontend/src/metabase-lib/v1/parameters/utils/targets.unit.spec.ts
index 5fd71d85f5f..e0e24ee7f91 100644
--- a/frontend/src/metabase-lib/v1/parameters/utils/targets.unit.spec.ts
+++ b/frontend/src/metabase-lib/v1/parameters/utils/targets.unit.spec.ts
@@ -775,7 +775,7 @@ function createComplex2StageQuery() {
operator: "=",
left: {
type: "column",
- name: "CREATED_AT",
+ name: "User's 18th birthday",
},
right: {
type: "column",
diff --git a/frontend/src/metabase-types/api/query.ts b/frontend/src/metabase-types/api/query.ts
index 831ce8ce61d..ac36b445479 100644
--- a/frontend/src/metabase-types/api/query.ts
+++ b/frontend/src/metabase-types/api/query.ts
@@ -496,9 +496,14 @@ export type TestMetricSpec = {
export type TestFilterSpec = TestExpressionSpec | TestSegmentSpec;
+export type TestNamedAggregationSpec = {
+ name: string;
+ value: TestExpressionSpec | TestMeasureSpec | TestMetricSpec;
+};
+
export type TestAggregationSpec =
| TestExpressionSpec
- | TestNamedExpressionSpec
+ | TestNamedAggregationSpec
| TestMeasureSpec
| TestMetricSpec;
@@ -551,7 +556,15 @@ type TestBucketSpec = TestTemporalBucketSpec & {
export type TestColumnWithBinningSpec = TestColumnSpec & TestBucketSpec;
-export type TestBreakoutSpec = TestColumnWithBinningSpec;
+export type TestBreakoutWithNameSpec = {
+ type: "breakout";
+ name: string;
+ column: TestColumnWithBinningSpec;
+};
+
+export type TestBreakoutSpec =
+ | TestColumnWithBinningSpec
+ | TestBreakoutWithNameSpec;
export type TestJoinSpec = {
source: TestSourceSpec;
diff --git a/src/metabase/lib/aggregation.cljc b/src/metabase/lib/aggregation.cljc
index f7e1c768ad8..6447e5b2ae3 100644
--- a/src/metabase/lib/aggregation.cljc
+++ b/src/metabase/lib/aggregation.cljc
@@ -365,6 +365,18 @@
stage-number :- :int]
(not-empty (:aggregation (lib.util/query-stage query stage-number)))))
+(mu/defn aggregation-column :- ::lib.metadata.calculation/column-metadata-with-source
+ "Given an `aggregation-clause` from [[aggregations]], returns the column it produces, with the name its result column
+ gets before the stage deduplicates its column names."
+ [query :- ::lib.schema/query
+ stage-number :- :int
+ aggregation-clause :- ::lib.schema.aggregation/aggregation]
+ (let [metadata (lib.metadata.calculation/metadata query stage-number aggregation-clause)]
+ (-> metadata
+ (u/assoc-default :effective-type (or (:base-type metadata) :type/*))
+ (assoc :lib/source :source/aggregations
+ :lib/source-uuid (lib.options/uuid aggregation-clause)))))
+
(mu/defn aggregations-metadata :- [:maybe [:sequential ::lib.metadata.calculation/column-metadata-with-source]]
"Get metadata about the aggregations in a given stage of a query."
([query :- ::lib.schema/query]
@@ -373,12 +385,7 @@
([query :- ::lib.schema/query
stage-number :- :int]
(some->> (not-empty (:aggregation (lib.util/query-stage query stage-number)))
- (into [] (map (fn [aggregation]
- (let [metadata (lib.metadata.calculation/metadata query stage-number aggregation)]
- (-> metadata
- (u/assoc-default :effective-type (or (:base-type metadata) :type/*))
- (assoc :lib/source :source/aggregations
- :lib/source-uuid (lib.options/uuid aggregation))))))))))
+ (into [] (map #(aggregation-column query stage-number %))))))
(mr/def ::operator-with-columns
[:merge
diff --git a/src/metabase/lib/breakout.cljc b/src/metabase/lib/breakout.cljc
index c22a9109708..40d5f402e8f 100644
--- a/src/metabase/lib/breakout.cljc
+++ b/src/metabase/lib/breakout.cljc
@@ -5,6 +5,7 @@
[metabase.lib.binning :as lib.binning]
[metabase.lib.equality :as lib.equality]
[metabase.lib.metadata.calculation :as lib.metadata.calculation]
+ [metabase.lib.options :as lib.options]
[metabase.lib.ref :as lib.ref]
[metabase.lib.remove-replace :as lib.remove-replace]
[metabase.lib.schema :as lib.schema]
@@ -147,7 +148,7 @@
(existing-breakouts query stage-number column))))
(mu/defn breakout-column :- ::lib.schema.metadata/column
- "Returns the input column used for this breakout."
+ "Returns the input column used for this breakout, with its binning, temporal bucket, and name."
([query :- ::lib.schema/query
breakout-ref :- ::lib.schema.ref/ref]
(breakout-column query -1 breakout-ref))
@@ -157,11 +158,14 @@
(when-let [column (lib.equality/find-matching-column breakout-ref
(breakoutable-columns query stage-number)
{:generous? true})]
- (let [binning (lib.binning/binning breakout-ref)
- bucket (lib.temporal-bucket/temporal-bucket breakout-ref)]
+ (let [binning (lib.binning/binning breakout-ref)
+ bucket (lib.temporal-bucket/temporal-bucket breakout-ref)
+ ref-name (:name (lib.options/options breakout-ref))]
(cond-> column
- binning (lib.binning/with-binning binning)
- bucket (lib.temporal-bucket/with-temporal-bucket bucket))))))
+ binning (lib.binning/with-binning binning)
+ bucket (lib.temporal-bucket/with-temporal-bucket bucket)
+ ref-name (-> (assoc :name ref-name :lib/original-name ref-name)
+ (dissoc :lib/deduplicated-name)))))))
(mu/defn remove-all-breakouts :- ::lib.schema/query
"Remove all breakouts from a query stage."
diff --git a/src/metabase/lib/core.cljc b/src/metabase/lib/core.cljc
index fde57c39777..dde7789d5ed 100644
--- a/src/metabase/lib/core.cljc
+++ b/src/metabase/lib/core.cljc
@@ -546,6 +546,19 @@
agg-index :- nat-int?]
(lib.aggregation/aggregation-ref a-query stage-number agg-index)))
+(mu/defn aggregation-column :- ::lib.metadata.calculation/column-metadata-with-source
+ "Given an `aggregation-clause` from [[aggregations]], returns the column it produces, named before the stage
+ deduplicates its column names.
+
+ **Code Health:** Healthy."
+ ([a-query :- ::lib.schema/query
+ aggregation-clause :- ::lib.schema.aggregation/aggregation]
+ (aggregation-column a-query -1 aggregation-clause))
+ ([a-query :- ::lib.schema/query
+ stage-number :- :int
+ aggregation-clause :- ::lib.schema.aggregation/aggregation]
+ (lib.aggregation/aggregation-column a-query stage-number aggregation-clause)))
+
;;; These functions all directly construct an aggregation clause suitable for passing to [[aggregate]], taking
;;; input column and/or filter clauses as arguments, depending on the operator.
;;;
diff --git a/src/metabase/lib/field/resolution.cljc b/src/metabase/lib/field/resolution.cljc
index 58f4e3f8d61..2d7fbbf3a06 100644
--- a/src/metabase/lib/field/resolution.cljc
+++ b/src/metabase/lib/field/resolution.cljc
@@ -718,6 +718,10 @@
{:lib/original-ref-style-for-result-metadata-purposes (if (pos-int? id-or-name)
:original-ref-style/id
:original-ref-style/name)}])
+ (as-> $col (cond-> $col
+ (:lib/ref-name $col) (-> (assoc :name (:lib/ref-name $col)
+ :lib/original-name (:lib/ref-name $col))
+ (dissoc :lib/deduplicated-name))))
(as-> $col (assoc $col :display-name (lib.metadata.calculation/display-name query stage-number $col))
(cond-> $col
(and (contains? #{nil :type/*} (:effective-type $col))
diff --git a/src/metabase/lib/js.cljs b/src/metabase/lib/js.cljs
index a68e3f1d6b9..5d6849d78dc 100644
--- a/src/metabase/lib/js.cljs
+++ b/src/metabase/lib/js.cljs
@@ -958,6 +958,14 @@
[a-query stage-number]
(to-array (lib.core/aggregations a-query stage-number)))
+(defn ^:export aggregation-column
+ "Given an `aggregation-clause` from [[aggregations]], returns the column it produces, named as its result column is
+ before the stage deduplicates its column names.
+
+ > **Code health:** Healthy"
+ [a-query stage-number aggregation-clause]
+ (lib.core/aggregation-column a-query stage-number aggregation-clause))
+
(defn ^:export aggregation-clause
"Returns a standalone aggregation clause for an `aggregation-operator` and a `column`.
diff --git a/src/metabase/lib/query/test_spec.cljc b/src/metabase/lib/query/test_spec.cljc
index 55f6486fa24..b59966dd5b1 100644
--- a/src/metabase/lib/query/test_spec.cljc
+++ b/src/metabase/lib/query/test_spec.cljc
@@ -44,42 +44,56 @@
:table (lib.metadata/table metadata-providerable spec-id)
:card (lib.metadata/card metadata-providerable spec-id)))
-(mu/defn- matches-column? :- :boolean
- [{:keys [name field-id join-alias source-field-id source-field-join-alias]}
- :- ::lib.schema.test-spec/test-order-by-spec
- column :- ::lib.schema.metadata/column]
- (and (if field-id
- (= field-id (:id column))
- (= name ((some-fn :lib/deduplicated-name :name) column)))
- (= join-alias (lib.join.util/current-join-alias column))
+(defn- deduplicated-name [column]
+ ((some-fn :lib/deduplicated-name :name) column))
+
+(defn- original-name [column]
+ ((some-fn :lib/original-name :name) column))
+
+(mu/defn- matches-join-and-fk? :- :boolean
+ [{:keys [join-alias source-field-id source-field-join-alias]} :- ::lib.schema.test-spec/test-order-by-spec
+ column :- ::lib.schema.metadata/column]
+ (and (= join-alias (lib.join.util/current-join-alias column))
(= source-field-id (:fk-field-id column))
(= source-field-join-alias (:fk-join-alias column))))
-(mu/defn- matches-bucketing? :- :boolean
- [{:keys [unit binning]} :- ::lib.schema.test-spec/test-order-by-spec
- column :- ::lib.schema.metadata/column]
- (let [{:keys [strategy] :as column-binning} (lib.binning/binning column)]
- (and (= unit (lib.temporal-bucket/raw-temporal-bucket column))
- (= (:strategy binning) strategy)
- (or (nil? binning)
- (= strategy :default)
- (== (strategy binning) (strategy column-binning))))))
+(mu/defn- matches-column? :- :boolean
+ [{:keys [name field-id] :as column-spec} :- ::lib.schema.test-spec/test-order-by-spec
+ column :- ::lib.schema.metadata/column]
+ (and (if field-id
+ (= field-id (:id column))
+ (= name (deduplicated-name column)))
+ (matches-join-and-fk? column-spec column)))
+
+(mu/defn- check-unambiguous-name :- :nil
+ "Throws when `column` shares its original name with another of `available-columns` that only a deduplication
+ suffix tells apart from it."
+ [available-columns :- [:sequential ::lib.schema.metadata/column]
+ column-spec :- ::lib.schema.test-spec/test-order-by-spec
+ column :- ::lib.schema.metadata/column]
+ (when-let [others (seq (filter #(and (= (original-name column) (original-name %))
+ (not= (deduplicated-name column) (deduplicated-name %))
+ (matches-join-and-fk? column-spec %))
+ available-columns))]
+ (throw (ex-info (str "Ambiguous column: " (count others) " other column(s) are also named "
+ (pr-str (original-name column)))
+ {:column-spec column-spec, :columns (cons column others)}))))
(mu/defn- find-column :- ::lib.schema.metadata/column
- "Finds the column a spec names. A column already bucketed more than one way, like a breakout by month and by year,
- is told apart by the spec's `:unit` or `:binning`."
+ "Finds the one column a spec names, by field ID or else by deduplicated name. A name is refused when its column
+ shares its original name with another column that only a deduplication suffix tells apart, like a previous stage's
+ `ID` and `ID_2`; a field broken out twice is named apart instead."
[_query :- ::lib.schema/query
_stage-number :- :int
available-columns :- [:sequential ::lib.schema.metadata/column]
column-spec :- ::lib.schema.test-spec/test-order-by-spec]
- (let [matching (filterv (partial matches-column? column-spec) available-columns)
- columns (if (and (> (count matching) 1)
- ((some-fn :unit :binning) column-spec))
- (filterv (partial matches-bucketing? column-spec) matching)
- matching)]
+ (let [columns (filterv (partial matches-column? column-spec) available-columns)]
(case (count columns)
0 (throw (ex-info "No column found" {:columns available-columns, :column-spec column-spec}))
- 1 (first columns)
+ 1 (let [column (first columns)]
+ (when-not (:field-id column-spec)
+ (check-unambiguous-name available-columns column-spec column))
+ column)
(throw (ex-info "Multiple columns found" {:columns columns, :column-spec column-spec})))))
(mu/defn- append-fields :- ::lib.schema/query
@@ -157,9 +171,14 @@
stage-number :- :int
columns :- [:sequential ::lib.schema.metadata/column]
breakout-spec :- ::lib.schema.test-spec/test-breakout-spec]
- (->> (find-column query stage-number columns breakout-spec)
- (apply-binning query stage-number breakout-spec)
- (lib.breakout/breakout query stage-number)))
+ (let [named? (= :breakout (keyword (:type breakout-spec)))
+ column-spec (if named? (:column breakout-spec) breakout-spec)
+ column (->> (find-column query stage-number columns column-spec)
+ (apply-binning query stage-number column-spec))]
+ (lib.breakout/breakout query stage-number
+ (cond-> column
+ named? (-> lib.ref/ref
+ (lib.options/update-options assoc :name (:name breakout-spec)))))))
(mu/defn- append-breakouts :- ::lib.schema/query
[query :- ::lib.schema/query
@@ -310,16 +329,19 @@
[query :- ::lib.schema/query
stage-number :- :int
aggregation-spec :- ::lib.schema.test-spec/test-aggregation-spec]
- (if (saved-aggregation-spec? aggregation-spec)
- (if-let [aggregation (saved-aggregation query aggregation-spec)]
- (lib.aggregation/aggregate query stage-number aggregation)
- (throw (ex-info "No saved aggregation found" {:aggregation-spec aggregation-spec})))
- (let [clause (->> (lib.aggregation/aggregable-columns query stage-number)
- (expression-spec->expression-clause query stage-number aggregation-spec))]
- (lib.aggregation/aggregate query stage-number
- (cond-> clause
- ;; Only the name a later stage refers to; the display name stays derived.
- (:name aggregation-spec) (lib.options/update-options assoc :name (:name aggregation-spec)))))))
+ (let [saved-spec (cond
+ (saved-aggregation-spec? aggregation-spec) aggregation-spec
+ (some-> (:value aggregation-spec) saved-aggregation-spec?) (:value aggregation-spec))
+ clause (if saved-spec
+ (if-let [aggregation (saved-aggregation query saved-spec)]
+ (lib.ref/ref aggregation)
+ (throw (ex-info "No saved aggregation found" {:aggregation-spec saved-spec})))
+ (->> (lib.aggregation/aggregable-columns query stage-number nil)
+ (expression-spec->expression-clause query stage-number aggregation-spec)))]
+ (lib.aggregation/aggregate query stage-number
+ (cond-> clause
+ ;; Only the name a later stage refers to; the display name stays derived.
+ (:name aggregation-spec) (lib.options/update-options assoc :name (:name aggregation-spec))))))
(mu/defn- append-aggregations :- ::lib.schema/query
[query :- ::lib.schema/query
diff --git a/src/metabase/lib/schema/test_spec.cljc b/src/metabase/lib/schema/test_spec.cljc
index fb2dbb5ec2c..b2464729392 100644
--- a/src/metabase/lib/schema/test_spec.cljc
+++ b/src/metabase/lib/schema/test_spec.cljc
@@ -66,8 +66,17 @@
::test-temporal-bucket-spec
::test-binning-bucket-spec])
+(mr/def ::test-breakout-with-name-spec
+ [:map {:closed true}
+ [:type [:= {:decode/normalize lib.schema.common/normalize-keyword} :breakout]]
+ [:name string?]
+ [:column [:ref ::test-column-with-binning-spec]]])
+
(mr/def ::test-breakout-spec
- [:ref ::test-column-with-binning-spec])
+ [:multi {:decode/normalize lib.schema.common/normalize-map-no-kebab-case
+ :dispatch (comp keyword :type)}
+ [:column [:ref ::test-column-with-binning-spec]]
+ [:breakout [:ref ::test-breakout-with-name-spec]]])
(mr/def ::test-order-by-spec
[:merge
@@ -139,10 +148,18 @@
[:left [:ref ::test-join-source-spec]]
[:right [:ref ::test-join-source-spec]]])
+(mr/def ::test-named-aggregation-spec
+ [:map {:closed true}
+ [:name string?]
+ [:value [:or
+ [:ref ::test-expression-spec]
+ [:ref ::test-measure-spec]
+ [:ref ::test-metric-spec]]]])
+
(mr/def ::test-aggregation-spec
[:or
[:ref ::test-expression-spec]
- [:ref ::test-named-expression-spec]
+ [:ref ::test-named-aggregation-spec]
[:ref ::test-measure-spec]
[:ref ::test-metric-spec]])
diff --git a/test/metabase/lib/aggregation_test.cljc b/test/metabase/lib/aggregation_test.cljc
index 22faef5bc59..983b3c05ca1 100644
--- a/test/metabase/lib/aggregation_test.cljc
+++ b/test/metabase/lib/aggregation_test.cljc
@@ -1113,3 +1113,29 @@
(testing "the joined card's aggregation column is offered as an aggregation input"
(is (some? maxcol)))
(is (= 1 (count (lib/aggregations (lib/aggregate joined (lib/sum maxcol)))))))))
+
+(deftest ^:parallel aggregation-column-test
+ (testing "column each aggregation produces, named before the stage deduplicates its column names"
+ (let [measure-mp (lib.tu/mock-metadata-provider
+ meta/metadata-provider
+ {:measures [{:id 1
+ :name "Revenue"
+ :table-id (meta/id :venues)
+ :definition (-> (lib/query meta/metadata-provider (meta/table-metadata :venues))
+ (lib/aggregate (lib/sum (meta/field-metadata :venues :price))))}]})
+ query (lib/test-query measure-mp
+ {:stages [{:source {:type :table :id (meta/id :venues)}
+ :breakouts [{:type :column :name "NAME"}]
+ :aggregations [{:type :operator :operator :sum :args [{:type :column :name "PRICE"}]}
+ {:type :operator :operator :sum :args [{:type :column :name "LATITUDE"}]}
+ {:type :operator :operator :count}
+ {:type :operator :operator :distinct :args [{:type :column :name "CATEGORY_ID"}]}
+ {:type :operator :operator :count :name "NAME"}
+ {:type :measure :id 1}
+ {:name "revenue" :value {:type :measure :id 1}}]}]})]
+ (is (= ["sum" "sum" "count" "count" "NAME" "sum" "revenue"]
+ (map #(:name (lib/aggregation-column query -1 %)) (lib/aggregations query))))
+ (is (=? [{:display-name "Sum of Price" :lib/source :source/aggregations}]
+ [(lib/aggregation-column query -1 (first (lib/aggregations query)))]))
+ (is (= ["NAME" "sum" "sum_2" "count" "count_2" "NAME_2" "sum_3" "revenue"]
+ (map :name (lib/returned-columns query)))))))
diff --git a/test/metabase/lib/breakout_test.cljc b/test/metabase/lib/breakout_test.cljc
index 3f871d9d6dc..2b7a41ab115 100644
--- a/test/metabase/lib/breakout_test.cljc
+++ b/test/metabase/lib/breakout_test.cljc
@@ -5,6 +5,7 @@
[medley.core :as m]
[metabase.lib.breakout :as lib.breakout]
[metabase.lib.core :as lib]
+ [metabase.lib.options :as lib.options]
[metabase.lib.test-metadata :as meta]
[metabase.lib.test-util :as lib.tu]
[metabase.lib.test-util.mocks-31368 :as lib.tu.mocks-31368]
@@ -837,3 +838,36 @@
(= :source/table-defaults (:lib/source %)))
(lib/breakoutable-columns query))]
(is (= 1 (count cols))))))
+
+(deftest ^:parallel named-breakout-column-name-test
+ (testing "breakout ref with `:name` gives its result column that name, as an aggregation's `:name` does"
+ (let [created-at (meta/field-metadata :orders :created-at)
+ named (fn [column column-name]
+ (lib.options/update-options (lib/ref column) assoc :name column-name))
+ query (-> (lib/query meta/metadata-provider (meta/table-metadata :orders))
+ (lib/breakout (named (lib/with-temporal-bucket created-at :month) "created_month"))
+ (lib/breakout (named (lib/with-temporal-bucket created-at :year) "created_year"))
+ (lib/aggregate (lib/count)))]
+ (is (= [["created_month" "created_month"] ["created_year" "created_year"] ["count" "count"]]
+ (map (juxt :name :lib/original-name) (lib/returned-columns query))))
+ (testing "next stage sees the columns by those names, as their original names"
+ (is (= [["created_month" "created_month"] ["created_year" "created_year"] ["count" "count"]]
+ (map (juxt :name :lib/original-name) (lib/visible-columns (lib/append-stage query))))))
+ (testing "breakout-column gives the breakout's column its name, with its temporal bucket"
+ (is (=? [{:name "created_month" :lib/original-name "created_month" :lib/temporal-unit :month}
+ {:name "created_year" :lib/original-name "created_year" :lib/temporal-unit :year}]
+ (map #(lib/breakout-column query %) (lib/breakouts query)))))
+ (testing "the SQL alias of the source column stays the field's own name"
+ (is (= ["CREATED_AT" "CREATED_AT"]
+ (map :lib/source-column-alias (take 2 (lib/returned-columns query)))))))))
+
+(deftest ^:parallel unnamed-breakout-column-name-test
+ (testing "breakout ref without `:name` keeps the field's name, deduplicated"
+ (let [created-at (meta/field-metadata :orders :created-at)
+ query (-> (lib/query meta/metadata-provider (meta/table-metadata :orders))
+ (lib/breakout (lib/with-temporal-bucket created-at :month))
+ (lib/breakout (lib/with-temporal-bucket created-at :year)))]
+ (is (= ["CREATED_AT" "CREATED_AT_2"]
+ (map :name (lib/returned-columns query))))
+ (is (= ["CREATED_AT" "CREATED_AT"]
+ (map #(:name (lib/breakout-column query %)) (lib/breakouts query)))))))
diff --git a/test/metabase/lib/query/test_spec_test.cljc b/test/metabase/lib/query/test_spec_test.cljc
index ec16a1a9a31..48dd9e0a78f 100644
--- a/test/metabase/lib/query/test_spec_test.cljc
+++ b/test/metabase/lib/query/test_spec_test.cljc
@@ -473,42 +473,23 @@
(lib/order-bys query))))))
(deftest ^:parallel test-query-order-by-with-temporal-bucket-test-with-duplicate-column
- (testing "test-query adds order-by with temporal bucketing when selecting the first column"
- (let [query (lib.query.test-spec/test-query
+ (let [date {:type :column :name "DATE"}
+ query (fn [breakouts order-by]
+ (lib.query.test-spec/test-query
meta/metadata-provider
- {:stages [{:source {:type :table
- :id (meta/id :checkins)}
- :breakouts [{:type :column
- :name "DATE"
- :unit :month}
- {:type :column
- :name "DATE"
- :unit :year}]
- :order-bys [{:type :column
- :name "DATE"
- :unit :month
- :direction :desc}]}]})]
- (is (=? [[:desc {}
- [:field {:temporal-unit :month} (meta/id :checkins :date)]]]
- (lib/order-bys query)))))
- (testing "test-query adds order-by with temporal bucketing when selecting the second column"
- (let [query (lib.query.test-spec/test-query
- meta/metadata-provider
- {:stages [{:source {:type :table
- :id (meta/id :checkins)}
- :breakouts [{:type :column
- :name "DATE"
- :unit :month}
- {:type :column
- :name "DATE"
- :unit :year}]
- :order-bys [{:type :column
- :name "DATE"
- :unit :year
- :direction :desc}]}]})]
- (is (=? [[:desc {}
- [:field {:temporal-unit :year} (meta/id :checkins :date)]]]
- (lib/order-bys query))))))
+ {:stages [{:source {:type :table :id (meta/id :checkins)}
+ :breakouts breakouts
+ :order-bys [(assoc order-by :direction :desc)]}]}))]
+ (testing "a field broken out twice can't be ordered by, whatever unit the order-by asks for"
+ (is (thrown-with-msg? #?(:clj Exception :cljs js/Error) #"Multiple columns found"
+ (query [(assoc date :unit :month) (assoc date :unit :year)]
+ (assoc date :unit :year)))))
+ (testing "named apart, each breakout is ordered by by its name"
+ (doseq [[column-name unit] [["month" :month] ["year" :year]]]
+ (is (=? [[:desc {} [:field {:temporal-unit unit :name column-name} (meta/id :checkins :date)]]]
+ (lib/order-bys (query [{:type :breakout :name "month" :column (assoc date :unit :month)}
+ {:type :breakout :name "year" :column (assoc date :unit :year)}]
+ {:type :column :name column-name}))))))))
(deftest ^:parallel test-query-order-by-with-binning-test
(testing "test-query adds order-by with binning"
@@ -1333,7 +1314,7 @@
1)))))
(deftest ^:parallel test-query-joined-result-column-through-card-test
- (testing "a saved card stores the second joined ID as ID_2, and that name picks it"
+ (testing "a saved card stores the second joined ID as ID_2, and that name is refused as ambiguous"
(let [card-query (lib.query.test-spec/test-query
meta/metadata-provider
{:stages [{:source {:type :table :id (meta/id :orders)}
@@ -1345,15 +1326,15 @@
meta/metadata-provider 1 card-query
{:result-metadata (mapv #(assoc % :name (:lib/deduplicated-name %))
(lib/returned-columns card-query))})
- query (lib.query.test-spec/test-query
- mp
- {:stages [{:source {:type :card :id 1}}
- {:filters [{:type :operator
- :operator :<
- :args [{:type :column :name "ID_2"}
- {:type :literal :value 10}]}]}]})]
- (is (=? [[:< {} [:field {} "PEOPLE__via__USER_ID__ID"] 10]]
- (lib/filters query 1))))))
+ query #(lib.query.test-spec/test-query
+ mp
+ {:stages [{:source {:type :card :id 1}}
+ {:filters [{:type :operator
+ :operator :<
+ :args [{:type :column :name "ID_2"}
+ {:type :literal :value 10}]}]}]})]
+ (is (thrown-with-msg? #?(:clj Exception :cljs js/Error) #"Ambiguous column"
+ (query))))))
(def ^:private two-fks-to-products-provider
"ORDERS with USER_ID as a second FK into PRODUCTS."
@@ -1447,3 +1428,132 @@
:args [{:type :column :name "TOTAL"} {:type :literal :value 1}]}}]
:aggregations [{:type :operator :operator :count}]
:breakouts [{:type :column :name "TOTAL"}]}]})))))
+
+(def ^:private metadata-provider-with-measure
+ (lib.tu/mock-metadata-provider
+ meta/metadata-provider
+ {:measures [{:id 1
+ :name "Revenue"
+ :table-id (meta/id :venues)
+ :definition (-> (lib/query meta/metadata-provider (meta/table-metadata :venues))
+ (lib/aggregate (lib/sum (meta/field-metadata :venues :price))))}]}))
+
+(deftest ^:parallel test-query-names-saved-aggregation-test
+ (testing "measure or metric is named by wrapping it as `{:name .. :value ..}`, as an operator aggregation can be"
+ (let [measure-query (lib.query.test-spec/test-query
+ metadata-provider-with-measure
+ {:stages [{:source {:type :table :id (meta/id :venues)}
+ :aggregations [{:name "revenue" :value {:type :measure :id 1}}
+ {:type :operator :operator :sum
+ :args [{:type :column :name "PRICE"}]}]}]})
+ metric-query (lib.query.test-spec/test-query
+ lib.tu/metadata-provider-with-metric
+ {:stages [{:source {:type :table :id (meta/id :checkins)}
+ :aggregations [{:name "visits" :value {:type :metric :id 1}}]}]})]
+ (is (=? [[:measure {:name "revenue"} 1] [:sum {} some?]]
+ (lib/aggregations measure-query)))
+ (is (= ["revenue" "sum"] (map :name (lib/returned-columns measure-query))))
+ (is (=? [[:metric {:name "visits"} 1]] (lib/aggregations metric-query)))
+ (is (= ["visits"] (map :name (lib/returned-columns metric-query)))))))
+
+(deftest ^:parallel test-query-ignores-saved-aggregation-own-name-test
+ (testing "measure's own `:name`, as a generated schema carries it, is not its result column's name"
+ (let [query (lib.query.test-spec/test-query
+ metadata-provider-with-measure
+ {:stages [{:source {:type :table :id (meta/id :venues)}
+ :aggregations [{:type :measure :id 1 :name "Revenue"}]}]})]
+ (is (= ["sum"] (map :name (lib/returned-columns query)))))))
+
+(deftest ^:parallel test-query-aggregation-of-earlier-aggregation-test
+ (testing "aggregation can refer to an earlier aggregation of its stage"
+ (let [query (lib.query.test-spec/test-query
+ meta/metadata-provider
+ {:stages [{:source {:type :table :id (meta/id :venues)}
+ :aggregations [{:type :operator :operator :count}
+ {:type :operator
+ :operator :/
+ :args [{:type :column :name "count"}
+ {:type :literal :value 2}]}]}]})]
+ (is (=? [[:count {}] [:/ {} [:aggregation {} string?] 2]]
+ (lib/aggregations query))))))
+
+(deftest ^:parallel test-query-names-breakouts-test
+ (testing "breakout of type `:breakout` gives its result column its `:name`, and a later stage finds it by that name"
+ (let [created-at {:type :column :name "CREATED_AT"}
+ query (lib.query.test-spec/test-query
+ meta/metadata-provider
+ {:stages [{:source {:type :table :id (meta/id :orders)}
+ :breakouts [{:type :breakout :name "created_month" :column (assoc created-at :unit :month)}
+ {:type :breakout :name "created_year" :column (assoc created-at :unit :year)}]
+ :aggregations [{:type :operator :operator :count}]}
+ {:filters [{:type :operator
+ :operator :>
+ :args [{:type :column :name "count"} {:type :literal :value 1}]}]
+ :breakouts [{:type :column :name "created_year"}]}]})]
+ (is (=? [[:field {:name "created_month" :temporal-unit :month} (meta/id :orders :created-at)]
+ [:field {:name "created_year" :temporal-unit :year} (meta/id :orders :created-at)]]
+ (lib/breakouts query 0)))
+ (is (= ["created_month" "created_year" "count"]
+ (map :name (lib/returned-columns query 0))))
+ (is (=? [[:field {} "created_year"]]
+ (lib/breakouts query 1))))))
+
+(def ^:private two-ids-stage
+ {:source {:type :table :id (meta/id :orders)}
+ :fields [{:type :column :name "ID" :field-id (meta/id :orders :id)}
+ {:type :column
+ :name "ID"
+ :field-id (meta/id :products :id)
+ :source-field-id (meta/id :orders :product-id)}]})
+
+(deftest ^:parallel test-query-refuses-ambiguous-column-in-later-stage-test
+ (testing "name of a column only a deduplication suffix tells apart from another one of the previous stage is ambiguous"
+ (doseq [[label mp first-stage]
+ [["after a table query" meta/metadata-provider two-ids-stage]
+ ["on a saved question"
+ (lib.tu/metadata-provider-with-card-from-query
+ meta/metadata-provider 1 (lib.query.test-spec/test-query meta/metadata-provider {:stages [two-ids-stage]}))
+ {:source {:type :card :id 1}}]]
+ column [{:type :column :name "ID"}
+ {:type :column :name "ID_2"}]]
+ (testing (str label " " (pr-str column))
+ (is (thrown-with-msg? #?(:clj Exception :cljs js/Error) #"Ambiguous column"
+ (lib.query.test-spec/test-query
+ mp
+ {:stages [first-stage
+ {:filters [{:type :operator
+ :operator :>
+ :args [column {:type :literal :value 1}]}]}]})))))))
+
+(deftest ^:parallel test-query-finds-later-stage-column-by-field-id-test
+ (testing "field ID finds its column of the previous stage although another one shares its name"
+ (is (=? [[:> {} [:field {} "PRODUCTS__via__PRODUCT_ID__ID"] 1]]
+ (lib/filters (lib.query.test-spec/test-query
+ meta/metadata-provider
+ {:stages [two-ids-stage
+ {:filters [{:type :operator
+ :operator :>
+ :args [{:type :column :field-id (meta/id :products :id)}
+ {:type :literal :value 1}]}]}]})
+ -1)))))
+
+(deftest ^:parallel test-query-refuses-bucketed-column-of-previous-stage-test
+ (testing "previous stage's column bucketed two ways is ambiguous, whatever unit the spec asks for"
+ (let [created-at {:type :column :name "CREATED_AT"}]
+ (is (thrown-with-msg? #?(:clj Exception :cljs js/Error) #"Ambiguous column"
+ (lib.query.test-spec/test-query
+ meta/metadata-provider
+ {:stages [{:source {:type :table :id (meta/id :orders)}
+ :breakouts [(assoc created-at :unit :month) (assoc created-at :unit :year)]
+ :aggregations [{:type :operator :operator :count}]}
+ {:order-bys [(assoc created-at :unit :year)]}]}))))))
+
+(deftest ^:parallel test-query-finds-table-column-among-joinable-ones-test
+ (testing "in a table stage, the table's own column is found, not an implicitly joinable one of the same name"
+ (doseq [column [{:type :column :name "ID"}
+ {:type :column :name "ID" :field-id (meta/id :orders :id)}]]
+ (is (=? [[:field {} (meta/id :orders :id)]]
+ (lib/fields (lib.query.test-spec/test-query
+ meta/metadata-provider
+ {:stages [{:source {:type :table :id (meta/id :orders)}
+ :fields [column]}]})))))))
diff --git a/test/metabase/query_processor/aggregation_test.clj b/test/metabase/query_processor/aggregation_test.clj
index ed1db9c047e..b4b0fef23e5 100644
--- a/test/metabase/query_processor/aggregation_test.clj
+++ b/test/metabase/query_processor/aggregation_test.clj
@@ -9,6 +9,7 @@
[metabase.driver :as driver]
[metabase.lib.core :as lib]
[metabase.lib.metadata :as lib.metadata]
+ [metabase.lib.options :as lib.options]
[metabase.lib.test-util :as lib.tu]
[metabase.query-processor.preprocess :as qp.preprocess]
;; binds mock metadata providers via the ambient store, which the code under test reads
@@ -638,3 +639,48 @@
;; round the numeric column: Presto's distributed SUM is ULP-nondeterministic across the two runs
(is (= (mt/formatted-rows [str 2.0] (qp/process-query direct-query))
(mt/formatted-rows [str 2.0] (qp/process-query measure-query))))))))
+
+(deftest ^:parallel aggregation-column-names-match-result-columns-test
+ (mt/test-drivers (mt/normal-drivers-with-feature :left-join)
+ (testing "the names Lib gives breakout and aggregation columns, deduplicated in stage order, are the names of the
+ result columns, even when aggregations share names with each other and with a breakout"
+ (let [mp (mt/metadata-provider)
+ orders (lib.metadata/table mp (mt/id :orders))
+ field #(lib.metadata/field mp (mt/id :orders %))
+ mp (lib.tu/mock-metadata-provider
+ mp
+ {:measures [{:id 1
+ :name "Total Subtotal"
+ :table-id (mt/id :orders)
+ :definition (-> (lib/query mp orders)
+ (lib/aggregate (lib/sum (field :subtotal))))}]
+ :cards [{:id 1
+ :type :metric
+ :name "Order Count"
+ :database-id (mt/id)
+ :dataset-query (-> (lib/query mp orders)
+ (lib/aggregate (lib/count)))}]})
+ base (lib/query mp (lib.metadata/table mp (mt/id :orders)))
+ category (m/find-first #(= (mt/id :products :category) (:id %)) (lib/breakoutable-columns base))
+ named (fn [clause column-name] (lib.options/update-options clause assoc :name column-name))
+ query (-> base
+ (lib/breakout (lib/with-temporal-bucket (field :created_at) :month))
+ (lib/breakout (lib/with-temporal-bucket (field :created_at) :year))
+ (lib/breakout category)
+ (lib/aggregate (lib/count))
+ (lib/aggregate (lib/sum (field :total)))
+ (lib/aggregate (lib/sum (field :tax)))
+ (lib/aggregate (lib/distinct (field :user_id)))
+ (lib/aggregate (lib/avg (field :total)))
+ (lib/aggregate (named (lib/count) (:name category)))
+ (lib/aggregate (lib.metadata/measure mp 1))
+ (lib/aggregate (lib.metadata/metric mp 1))
+ (lib/aggregate (named (lib/ref (lib.metadata/measure mp 1)) "revenue")))
+ column-names (concat (for [breakout (lib/breakouts query)]
+ (:name (lib/breakout-column query breakout)))
+ (for [aggregation (lib/aggregations query)]
+ (:name (lib/aggregation-column query aggregation))))]
+ (testing "the case is one where names collide"
+ (is (not= column-names (distinct column-names))))
+ (is (= (map (lib/non-truncating-unique-name-generator) column-names)
+ (map :name (mt/cols (qp/process-query query)))))))))
diff --git a/test/metabase/query_processor/breakout_test.clj b/test/metabase/query_processor/breakout_test.clj
index a53cd3b1dbd..ffab3a8c6dc 100644
--- a/test/metabase/query_processor/breakout_test.clj
+++ b/test/metabase/query_processor/breakout_test.clj
@@ -9,6 +9,7 @@
[metabase.lib.convert :as lib.convert]
[metabase.lib.core :as lib]
[metabase.lib.metadata :as lib.metadata]
+ [metabase.lib.options :as lib.options]
[metabase.lib.test-util :as lib.tu]
[metabase.query-processor.middleware.add-remaps :as qp.add-remaps]
;; binds mock metadata providers via the ambient store, which the code under test reads
@@ -472,3 +473,44 @@
[2.0 0 36791.99]
[3.0 0 454525.88]]
(mt/formatted-rows [1.0 int 2.0] (qp/process-query query))))))
+
+(deftest ^:parallel named-breakouts-test
+ (mt/test-drivers (mt/normal-drivers-with-feature :basic-aggregations)
+ (testing "breakouts named with `:name` come back under those names, and a later stage reads them by name"
+ (let [mp (mt/metadata-provider)
+ created-at (lib.metadata/field mp (mt/id :orders :created_at))
+ named (fn [column column-name]
+ (lib.options/update-options (lib/ref column) assoc :name column-name))
+ query (-> (lib/query mp (lib.metadata/table mp (mt/id :orders)))
+ (lib/breakout (named (lib/with-temporal-bucket created-at :month) "created_month"))
+ (lib/breakout (named (lib/with-temporal-bucket created-at :year) "created_year"))
+ (lib/aggregate (lib/count))
+ lib/append-stage)
+ by-name (fn [column-name]
+ (first (filter #(= column-name (:name %)) (lib/visible-columns query))))
+ query (-> query
+ (lib/breakout (by-name "created_year"))
+ (lib/aggregate (lib/sum (by-name "count"))))
+ unnamed (-> (lib/query mp (lib.metadata/table mp (mt/id :orders)))
+ (lib/breakout (lib/with-temporal-bucket created-at :year))
+ (lib/aggregate (lib/count)))]
+ (is (= ["created_year" "sum"]
+ (map :name (mt/cols (qp/process-query query)))))
+ (testing "the yearly totals equal those of the same query without names"
+ (is (= (mt/formatted-rows [str int] (qp/process-query unnamed))
+ (mt/formatted-rows [str int] (qp/process-query query)))))))))
+
+(deftest ^:parallel named-implicitly-joined-breakouts-test
+ (mt/test-drivers (mt/normal-drivers-with-feature :basic-aggregations :left-join)
+ (testing "breakouts on implicitly joined fields of the same name come back under their names"
+ (let [mp (mt/metadata-provider)
+ joined-id (fn [table fk]
+ (assoc (lib.metadata/field mp (mt/id table :id)) :fk-field-id (mt/id :checkins fk)))
+ named (fn [column column-name]
+ (lib.options/update-options (lib/ref column) assoc :name column-name))
+ query (-> (lib/query mp (lib.metadata/table mp (mt/id :checkins)))
+ (lib/breakout (named (joined-id :users :user_id) "user_id"))
+ (lib/breakout (named (joined-id :venues :venue_id) "venue_id"))
+ (lib/aggregate (lib/count)))]
+ (is (= ["user_id" "venue_id" "count"]
+ (map :name (mt/cols (qp/process-query query)))))))))