Skip to content

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

Add mockDataAppQuery and mockDataAppAction to the SDK testing entry (#85732)

Alexander Polyankind190a51539b7
diff --git a/enterprise/frontend/src/embedding-sdk-package/data-app.ts b/enterprise/frontend/src/embedding-sdk-package/data-app.ts
index 03fc89278ab..fc35e64bb8f 100644
--- a/enterprise/frontend/src/embedding-sdk-package/data-app.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/data-app.ts
@@ -64,6 +64,7 @@ export type {
MetabaseQueryObject,
MetabaseOrderByDirection,
UseMetabaseQueryObjectResult,
+ MetabaseQueryRow,
UseMetabaseQueryResult,
} from "./hooks/public/use-metabase-query";
export type {
diff --git a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-action/types.ts b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-action/types.ts
index 67660ca1418..2815fc99fb0 100644
--- a/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-action/types.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/hooks/public/use-action/types.ts
@@ -39,21 +39,21 @@ export type ActionResultForCreate = {
};
/**
- * Response from a single-row update — the affected primary keys.
+ * Response from a single-row update — the number of rows updated.
*
* @category useAction
*/
export type ActionResultForUpdate = {
- "rows-updated": readonly RowValue[];
+ "rows-updated": number;
};
/**
- * Response from a single-row delete — the affected primary keys.
+ * Response from a single-row delete — the number of rows deleted.
*
* @category useAction
*/
export type ActionResultForDelete = {
- "rows-deleted": readonly RowValue[];
+ "rows-deleted": number;
};
/**
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 95e43d91c89..69c125c3e89 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,7 +1,15 @@
+import {
+ getAggregationResultColumnDefaultName,
+ getAggregationResultColumnJavaScriptType,
+} from "embedding-sdk-shared/lib/create-metabase-query/result-columns";
+
import type { SchemaColumn, SchemaJavaScriptType } from "../data-schema";
import type {
+ AggregationColumn,
+ CountAggregation,
CountAggregationSchema,
+ FieldAggregation,
FieldAggregationOperator,
FieldAggregationSchema,
NamedSavedAggregation,
@@ -13,13 +21,17 @@ type AggregationOptions<TName extends string> = {
name: TName;
};
+type AggregationDimension = {
+ jsType?: SchemaJavaScriptType;
+};
+
export function count(): CountAggregationSchema;
export function count<const TName extends string>(
options: AggregationOptions<TName>,
): CountAggregationSchema<TName>;
export function count(
options?: AggregationOptions<string>,
-): CountAggregationSchema<string> {
+): CountAggregation & { columns: readonly [AggregationColumn] } {
return {
type: "operator",
operator: "count",
@@ -27,7 +39,7 @@ export function count(
...(options && { name: options.name }),
columns: [
{
- name: options?.name ?? "count",
+ name: options?.name ?? getAggregationResultColumnDefaultName("count"),
displayName: "Count",
jsType: "number",
},
@@ -35,150 +47,149 @@ export function count(
};
}
-export const sum = <const TDimension, const TName extends string = "sum">(
+export function sum<const TDimension>(
dimension: NumericAggregationDimension<TDimension>,
- options?: AggregationOptions<TName>,
+): FieldAggregationSchema<"sum", NumericAggregationDimension<TDimension>>;
+export function sum<const TDimension, const TName extends string>(
+ dimension: NumericAggregationDimension<TDimension>,
+ options: AggregationOptions<TName>,
): FieldAggregationSchema<
"sum",
NumericAggregationDimension<TDimension>,
- "number",
- NoInfer<TName>
-> => fieldAggregation("sum", "Sum", dimension, options);
+ TName
+>;
+export function sum(
+ dimension: AggregationDimension,
+ options?: AggregationOptions<string>,
+) {
+ return fieldAggregation("sum", "Sum", dimension, options);
+}
-export const avg = <const TDimension, const TName extends string = "avg">(
+export function avg<const TDimension>(
+ dimension: NumericAggregationDimension<TDimension>,
+): FieldAggregationSchema<"avg", NumericAggregationDimension<TDimension>>;
+export function avg<const TDimension, const TName extends string>(
dimension: NumericAggregationDimension<TDimension>,
- options?: AggregationOptions<TName>,
+ options: AggregationOptions<TName>,
): FieldAggregationSchema<
"avg",
NumericAggregationDimension<TDimension>,
- "number",
- NoInfer<TName>
-> => fieldAggregation("avg", "Average", dimension, options);
+ TName
+>;
+export function avg(
+ dimension: AggregationDimension,
+ options?: AggregationOptions<string>,
+) {
+ return fieldAggregation("avg", "Average", dimension, options);
+}
-export const median = <const TDimension, const TName extends string = "median">(
+export function median<const TDimension>(
+ dimension: NumericAggregationDimension<TDimension>,
+): FieldAggregationSchema<"median", NumericAggregationDimension<TDimension>>;
+export function median<const TDimension, const TName extends string>(
dimension: NumericAggregationDimension<TDimension>,
- options?: AggregationOptions<TName>,
+ options: AggregationOptions<TName>,
): FieldAggregationSchema<
"median",
NumericAggregationDimension<TDimension>,
- "number",
- NoInfer<TName>
-> => fieldAggregation("median", "Median", dimension, options);
+ TName
+>;
+export function median(
+ dimension: AggregationDimension,
+ options?: AggregationOptions<string>,
+) {
+ return fieldAggregation("median", "Median", dimension, options);
+}
-export const distinct = <
- const TDimension,
- const TName extends string = "count",
->(
+export function distinct<const TDimension>(
+ dimension: TDimension,
+): FieldAggregationSchema<"distinct", TDimension>;
+export function distinct<const TDimension, const TName extends string>(
dimension: TDimension,
- options?: AggregationOptions<TName>,
-): FieldAggregationSchema<"distinct", TDimension, "number", NoInfer<TName>> =>
- fieldAggregation("distinct", "Distinct values", dimension, options);
+ options: AggregationOptions<TName>,
+): FieldAggregationSchema<"distinct", TDimension, TName>;
+export function distinct(
+ dimension: AggregationDimension,
+ options?: AggregationOptions<string>,
+) {
+ return fieldAggregation("distinct", "Distinct values", dimension, options);
+}
-export const min = <const TDimension, const TName extends string = "min">(
+export function min<const TDimension>(
+ dimension: OrderableAggregationDimension<TDimension>,
+): FieldAggregationSchema<"min", OrderableAggregationDimension<TDimension>>;
+export function min<const TDimension, const TName extends string>(
dimension: OrderableAggregationDimension<TDimension>,
- options?: AggregationOptions<TName>,
+ options: AggregationOptions<TName>,
): FieldAggregationSchema<
"min",
OrderableAggregationDimension<TDimension>,
- "number",
- NoInfer<TName>
-> => fieldAggregation("min", "Minimum", dimension, options);
+ TName
+>;
+export function min(
+ dimension: AggregationDimension,
+ options?: AggregationOptions<string>,
+) {
+ return fieldAggregation("min", "Minimum", dimension, options);
+}
-export const max = <const TDimension, const TName extends string = "max">(
+export function max<const TDimension>(
+ dimension: OrderableAggregationDimension<TDimension>,
+): FieldAggregationSchema<"max", OrderableAggregationDimension<TDimension>>;
+export function max<const TDimension, const TName extends string>(
dimension: OrderableAggregationDimension<TDimension>,
- options?: AggregationOptions<TName>,
+ options: AggregationOptions<TName>,
): FieldAggregationSchema<
"max",
OrderableAggregationDimension<TDimension>,
- "number",
- NoInfer<TName>
-> => fieldAggregation("max", "Maximum", dimension, options);
-
-const fieldAggregation = <
- TOperator extends FieldAggregationOperator,
- TDimension,
- TName extends string,
->(
- type: TOperator,
+ TName
+>;
+export function max(
+ dimension: AggregationDimension,
+ options?: AggregationOptions<string>,
+) {
+ return fieldAggregation("max", "Maximum", dimension, options);
+}
+
+function fieldAggregation(
+ operator: FieldAggregationOperator,
displayName: string,
- dimension: TDimension,
- options: AggregationOptions<TName> | undefined,
-): FieldAggregationSchema<TOperator, TDimension, "number", TName> =>
- // The column's `name`/`jsType` are computed at runtime (`string` /
- // `SchemaJavaScriptType`), while the schema type states them as the literals
- // derived from `TName` and `TOperator` — TS can't connect the two.
- ({
+ dimension: AggregationDimension,
+ options: AggregationOptions<string> | undefined,
+): FieldAggregation & { columns: readonly [AggregationColumn] } {
+ return {
type: "operator",
- operator: type,
+ operator,
args: [dimension],
...(options && { name: options.name }),
columns: [
{
- name: options?.name ?? getFieldAggregationColumnName(type),
+ name: options?.name ?? getAggregationResultColumnDefaultName(operator),
displayName,
- jsType: getFieldAggregationColumnJavaScriptType(type, dimension),
+ jsType: getAggregationResultColumnJavaScriptType(
+ operator,
+ dimension.jsType,
+ ),
},
],
- }) as unknown as FieldAggregationSchema<
- TOperator,
- TDimension,
- "number",
- TName
- >;
-
-const getFieldAggregationColumnName = (
- type: FieldAggregationOperator,
-): string => (type === "distinct" ? "count" : type);
-
-function getFieldAggregationColumnJavaScriptType(
- type: FieldAggregationOperator,
- dimension: unknown,
-): SchemaJavaScriptType {
- if (type !== "min" && type !== "max") {
- return "number";
- }
-
- if (
- dimension == null ||
- typeof dimension !== "object" ||
- !("jsType" in dimension)
- ) {
- return "number";
- }
-
- const { jsType } = dimension;
-
- if (isOrderableJavaScriptType(jsType)) {
- return jsType;
- }
-
- return "number";
+ };
}
-const isOrderableJavaScriptType = (
- value: unknown,
-): value is Exclude<SchemaJavaScriptType, "unknown"> =>
- value === "string" ||
- value === "number" ||
- 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.
- ({
+function namedSavedAggregation<TType extends "measure" | "metric">(
+ aggregation: SavedAggregation<TType>,
+ name: string,
+): NamedSavedAggregation<SavedAggregation<TType>> {
+ return {
name,
value: aggregation,
columns: [{ ...aggregation.columns?.[0], name }],
- }) as unknown as NamedSavedAggregation<TAggregation, TName>;
+ };
+}
export function measure<const TMeasure extends SavedAggregation<"measure">>(
measure: TMeasure,
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 a29b6286d6c..5bd14ab7a32 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
@@ -23,6 +23,7 @@ export type {
MetabaseOrderBy,
MetabaseQueryOptions,
MetabaseOrderByDirection,
+ MetabaseQueryRow,
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 0245e3ae32b..bc42b7260f8 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,20 +1,25 @@
import {
+ isAggregationSpec,
isNamedBreakout,
isUnaryOperator,
} from "embedding-sdk-shared/lib/create-metabase-query/input-guards";
+import { getAggregationResultColumnNames } from "embedding-sdk-shared/lib/create-metabase-query/result-columns";
import type { TemporalUnit } from "metabase-types/api";
-import type { SchemaColumn } from "../data-schema";
-
import type {
AggregationResultColumnName,
BetweenFilterOperatorForDimension,
BreakoutOptionsArgument,
+ CountAggregation,
+ FieldAggregation,
FilterForOperator,
FilterLiteralValue,
FilterOperator,
+ MeasureReference,
MetabaseOrderByDirection,
+ MetricReference,
NamedBreakout,
+ NamedSavedAggregation,
TimeIntervalFilterOperatorForDimension,
UnaryFilterOperatorForDimension,
ValueFilterOperatorForDimension,
@@ -146,7 +151,12 @@ export function orderBy<const TName extends string>(
};
export function orderBy<
- TAggregation extends { columns?: readonly SchemaColumn[] },
+ TAggregation extends
+ | CountAggregation
+ | FieldAggregation
+ | NamedSavedAggregation
+ | MeasureReference
+ | MetricReference,
>(
aggregation: TAggregation,
direction?: MetabaseOrderByDirection,
@@ -176,12 +186,14 @@ export function orderBy<TDimension>(
};
}
- const aggregationColumn = getAggregationResultColumn(dimension);
+ const [aggregationName] = isAggregationSpec(dimension)
+ ? getAggregationResultColumnNames([dimension])
+ : [];
- if (aggregationColumn) {
+ if (aggregationName) {
return {
type: "column",
- name: aggregationColumn.name,
+ name: aggregationName,
...(direction ? { direction } : undefined),
};
}
@@ -198,31 +210,6 @@ export function orderBy<TDimension>(
};
}
-function getAggregationResultColumn(value: unknown): SchemaColumn | undefined {
- if (value == null || typeof value !== "object" || !("columns" in value)) {
- return undefined;
- }
-
- const { columns } = value;
-
- if (!Array.isArray(columns)) {
- return undefined;
- }
-
- const [column] = columns;
-
- return isSchemaColumn(column) ? column : undefined;
-}
-
-function isSchemaColumn(value: unknown): value is SchemaColumn {
- return (
- value != null &&
- typeof value === "object" &&
- "name" in value &&
- typeof value.name === "string"
- );
-}
-
function toFilterLiteral(value: unknown): {
type: "literal";
value: FilterLiteralValue;
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 15445ec0799..b8771e10970 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
@@ -215,9 +215,9 @@ function ValidTypeFixtures() {
void sdkCreateOrder.execute({ status: "shipped" });
void useAction(CreateOrder).execute({ status: "shipped" });
- const updatedRows = updateOrder.result?.["rows-updated"];
+ const updatedCount: number | undefined = updateOrder.result?.["rows-updated"];
- void updatedRows;
+ void updatedCount;
// A raw id types nothing, so the generics still stand in for a definition.
const rawAction = useAction<{ status: string }, "create">(51);
@@ -263,6 +263,20 @@ function ValidTypeFixtures() {
void scalarAggregationValue;
+ const latestOrderResult = useMetabaseQuery(
+ defineQuery({
+ source: TEST_SCHEMA.tables.orders,
+ aggregations: [
+ aggregations.max(TEST_SCHEMA.tables.orders.fields.createdAt),
+ ],
+ }),
+ );
+
+ const latestOrderCreatedAt: string | null | undefined =
+ latestOrderResult.data?.rows[0]?.max;
+
+ void latestOrderCreatedAt;
+
const namedAggregationResult = useMetabaseQuery(
defineQuery({
source: TEST_SCHEMA.tables.orders,
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 edcd0e9a814..b8a96164f95 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
@@ -135,26 +135,13 @@ export type FieldReference<TTable = unknown> =
// `name` names the result column, which is how a later stage refers to it. A
// query with two aggregations of the same kind needs it to tell them apart.
-export type CountAggregation = {
+export type CountAggregation<TName extends string = string> = {
type: "operator";
operator: "count";
args: [];
- name?: string;
+ name?: TName;
};
-export type CountAggregationSchema<TName extends string = "count"> =
- CountAggregation & {
- columns: readonly [
- {
- name: TName;
- displayName: "Count";
- jsType: "number";
- },
- ];
- };
-
-type CountAggregationColumn = CountAggregationSchema["columns"][number];
-
export type FieldAggregationOperator =
| "sum"
| "avg"
@@ -166,31 +153,57 @@ export type FieldAggregationOperator =
export type FieldAggregation<
TOperator extends FieldAggregationOperator = FieldAggregationOperator,
TDimension = unknown,
+ TName extends string = string,
> = {
type: "operator";
operator: TOperator;
args: readonly [TDimension];
- name?: string;
+ name?: TName;
+};
+
+export type AggregationResultColumnDefaultName<TOperator> =
+ TOperator extends "distinct" ? "count" : TOperator;
+
+export type AggregationResultColumnJavaScriptType<TOperator, TDimension> =
+ TOperator extends "min" | "max"
+ ? TDimension extends {
+ jsType?: infer TJavaScriptType extends SchemaJavaScriptType;
+ }
+ ? [Exclude<NonNullable<TJavaScriptType>, "unknown">] extends [never]
+ ? "number"
+ : Exclude<NonNullable<TJavaScriptType>, "unknown">
+ : "number"
+ : "number";
+
+export type AggregationColumn<
+ TName extends string = string,
+ TJavaScriptType extends SchemaJavaScriptType = SchemaJavaScriptType,
+> = {
+ name: TName;
+ displayName: string;
+ jsType: TJavaScriptType;
};
+export type CountAggregationSchema<TName extends string = "count"> =
+ CountAggregation<TName> & {
+ columns: readonly [AggregationColumn<TName, "number">];
+ };
+
export type FieldAggregationSchema<
TOperator extends FieldAggregationOperator = FieldAggregationOperator,
TDimension = unknown,
- TJavaScriptType extends SchemaJavaScriptType = "number",
- TName extends string = TOperator extends "distinct" ? "count" : TOperator,
-> = FieldAggregation<TOperator, TDimension> & {
+ TName extends string = AggregationResultColumnDefaultName<TOperator>,
+> = FieldAggregation<TOperator, TDimension, TName> & {
columns: readonly [
- {
- name: TName;
- displayName: string;
- jsType: TJavaScriptType;
- },
+ AggregationColumn<
+ TName,
+ AggregationResultColumnJavaScriptType<TOperator, TDimension>
+ >,
];
};
type AggregationForDimension<TDimension> =
| CountAggregation
- | CountAggregationSchema
| FieldAggregation<
"sum" | "avg" | "median",
NumericAggregationDimension<TDimension>
@@ -469,17 +482,36 @@ export type RequireAggregationsForBreakouts<TQuery> = TQuery extends {
type TableQuery<TTable, TQuery = unknown> = TableQueryBase<TTable> &
RequireAggregationsForBreakouts<TQuery>;
-export type AggregationResultColumnName<TAggregation> = TAggregation extends {
- columns: readonly [{ name: infer TName }, ...unknown[]];
+type AggregationClauseDimension<TAggregation> = TAggregation extends {
+ args: readonly [infer TDimension, ...unknown[]];
}
- ? TName
+ ? TDimension
+ : unknown;
+
+type AggregationClauseColumnName<TAggregation, TOperator> =
+ TAggregation extends { name: infer TName extends string }
+ ? TName
+ : Extract<AggregationResultColumnDefaultName<TOperator>, string>;
+
+type AggregationResultColumn<TAggregation> = TAggregation extends {
+ columns: infer TColumns;
+}
+ ? TupleElement<NonNullable<TColumns>>
: TAggregation extends { type: "operator"; operator: infer TOperator }
- ? TAggregation extends { name: infer TName extends string }
- ? TName
- : TOperator extends "distinct"
- ? "count"
- : TOperator
- : string;
+ ? AggregationColumn<
+ AggregationClauseColumnName<TAggregation, TOperator>,
+ AggregationResultColumnJavaScriptType<
+ TOperator,
+ AggregationClauseDimension<TAggregation>
+ >
+ >
+ : never;
+
+export type AggregationResultColumnName<TAggregation> = [
+ AggregationResultColumn<TAggregation>,
+] extends [never]
+ ? string
+ : ColumnName<AggregationResultColumn<TAggregation>>;
type ColumnName<TColumn> = TColumn extends { name: infer TName }
? TName
@@ -599,13 +631,7 @@ type QueryBreakoutColumns<TQuery> = TQuery extends {
type QueryAggregationColumns<TQuery> = TQuery extends {
aggregations?: infer TAggregations;
}
- ? TupleElement<NonNullable<TAggregations>> extends infer TAggregation
- ? TAggregation extends { columns: infer TColumns }
- ? TupleElement<NonNullable<TColumns>>
- : TAggregation extends CountAggregation
- ? CountAggregationColumn
- : never
- : never
+ ? AggregationResultColumn<TupleElement<NonNullable<TAggregations>>>
: never;
/**
@@ -734,6 +760,14 @@ export type UseMetabaseQueryResult<
refetch: () => Promise<void>;
};
+export type MetabaseQueryRow<TQuery, TDynamic = undefined> = NonNullable<
+ UseMetabaseQueryResult<
+ QueryEntity<undefined, TQuery>,
+ TQuery,
+ TDynamic
+ >["data"]
+>["rows"][number];
+
/**
* Marks a query as declared through `defineQuery`. The query hooks accept only
* marked queries, so an inline query object is a compile-time error.
@@ -744,6 +778,16 @@ export declare class DefinedQuery {
private readonly definedWithDefineQuery: true;
}
+export type DynamicQueryArgument<TEntity, TQuery, TDynamic> = TDynamic &
+ (TDynamic extends MetabaseDynamicQuery<QueryEntity<TEntity, TQuery>, TQuery>
+ ? RequireAggregationsForBreakouts<TDynamic> &
+ RequireDynamicOrderByNames<
+ QueryEntity<TEntity, TQuery>,
+ TQuery,
+ TDynamic
+ >
+ : MetabaseDynamicQuery<QueryEntity<TEntity, TQuery>, TQuery>);
+
export type UseMetabaseQuery = <
TEntity extends TableSchema | undefined = undefined,
TSchema = unknown,
@@ -758,15 +802,7 @@ export type UseMetabaseQuery = <
RequireGroupedOrderByNames<TQuery>
: unknown
: MetabaseQueryOptions<TEntity, TSchema>),
- dynamicQuery?: TDynamic &
- (TDynamic extends MetabaseDynamicQuery<QueryEntity<TEntity, TQuery>, TQuery>
- ? RequireAggregationsForBreakouts<TDynamic> &
- RequireDynamicOrderByNames<
- QueryEntity<TEntity, TQuery>,
- TQuery,
- TDynamic
- >
- : MetabaseDynamicQuery<QueryEntity<TEntity, TQuery>, TQuery>),
+ dynamicQuery?: DynamicQueryArgument<TEntity, TQuery, TDynamic>,
) => UseMetabaseQueryResult<QueryEntity<TEntity, TQuery>, TQuery, TDynamic>;
export type UseMetabaseQueryObject = <
@@ -783,15 +819,7 @@ export type UseMetabaseQueryObject = <
RequireGroupedOrderByNames<TQuery>
: unknown
: MetabaseQueryOptions<TEntity, TSchema>),
- dynamicQuery?: TDynamic &
- (TDynamic extends MetabaseDynamicQuery<QueryEntity<TEntity, TQuery>, TQuery>
- ? RequireAggregationsForBreakouts<TDynamic> &
- RequireDynamicOrderByNames<
- QueryEntity<TEntity, TQuery>,
- TQuery,
- TDynamic
- >
- : MetabaseDynamicQuery<QueryEntity<TEntity, TQuery>, TQuery>),
+ dynamicQuery?: DynamicQueryArgument<TEntity, TQuery, TDynamic>,
) => UseMetabaseQueryObjectResult;
export type UseMetabaseQueryObjectResult = {
diff --git a/enterprise/frontend/src/embedding-sdk-package/testing.ts b/enterprise/frontend/src/embedding-sdk-package/testing.ts
index 004d62ebd9a..c48d895d223 100644
--- a/enterprise/frontend/src/embedding-sdk-package/testing.ts
+++ b/enterprise/frontend/src/embedding-sdk-package/testing.ts
@@ -10,3 +10,17 @@ export {
createMockQuestion,
createMockUser,
} from "./testing/lib/public/mocks";
+export {
+ mockDataAppAction,
+ mockDataAppActionError,
+ type DataAppActionMock,
+ type DataAppActionMockCall,
+ type DataAppActionMockError,
+} from "./testing/lib/public/data-app-actions";
+export {
+ mockDataAppQuery,
+ mockDataAppQueryError,
+ type DataAppQueryMock,
+ type DataAppQueryMockCall,
+ type DataAppMockError,
+} from "./testing/lib/public/data-app-queries";
diff --git a/enterprise/frontend/src/embedding-sdk-package/testing/components/MetabaseTestProvider/MetabaseTestProvider.tsx b/enterprise/frontend/src/embedding-sdk-package/testing/components/MetabaseTestProvider/MetabaseTestProvider.tsx
index e22baf4eece..7056a823e4a 100644
--- a/enterprise/frontend/src/embedding-sdk-package/testing/components/MetabaseTestProvider/MetabaseTestProvider.tsx
+++ b/enterprise/frontend/src/embedding-sdk-package/testing/components/MetabaseTestProvider/MetabaseTestProvider.tsx
@@ -22,8 +22,10 @@ import type {
LoginStatus,
MetabaseUser,
} from "embedding-sdk-bundle/types/user";
+import type { MetabaseActionMock } from "embedding-sdk-package/testing/lib/private/actions";
import { createMockSdkBundle } from "embedding-sdk-package/testing/lib/private/bundle";
import { installMockSdk } from "embedding-sdk-package/testing/lib/private/install";
+import type { MetabaseQueryMock } from "embedding-sdk-package/testing/lib/private/queries";
export type MetabaseTestOptions = {
CollectionBrowser?: ComponentType<CollectionBrowserProps>;
@@ -41,6 +43,8 @@ export type MetabaseTestOptions = {
loginStatus?: LoginStatus;
applicationName?: string;
availableFonts?: string[];
+ dataAppQueries?: readonly MetabaseQueryMock[];
+ dataAppActions?: readonly MetabaseActionMock[];
};
export type MetabaseTestProviderProps = MetabaseTestOptions & {
diff --git a/enterprise/frontend/src/embedding-sdk-package/testing/components/MetabaseTestProvider/MetabaseTestProvider.unit.spec.tsx b/enterprise/frontend/src/embedding-sdk-package/testing/components/MetabaseTestProvider/MetabaseTestProvider.unit.spec.tsx
index e1b8f77b5ef..8a011cd8d00 100644
--- a/enterprise/frontend/src/embedding-sdk-package/testing/components/MetabaseTestProvider/MetabaseTestProvider.unit.spec.tsx
+++ b/enterprise/frontend/src/embedding-sdk-package/testing/components/MetabaseTestProvider/MetabaseTestProvider.unit.spec.tsx
@@ -13,8 +13,6 @@ import { useApplicationName } from "embedding-sdk-package/hooks/public/use-appli
import { useCurrentUser } from "embedding-sdk-package/hooks/public/use-current-user";
import { useDateFormatter } from "embedding-sdk-package/hooks/public/use-date-formatter";
import { useMetabaseAuthStatus } from "embedding-sdk-package/hooks/public/use-metabase-auth-status";
-import { useMetabaseQuery } from "embedding-sdk-package/hooks/public/use-metabase-query";
-import { defineQuery } from "embedding-sdk-package/hooks/public/use-metabase-query/define-query";
import {
createMockDashboard,
createMockUser,
@@ -25,10 +23,6 @@ import {
type MetabaseTestProviderProps,
} from "./MetabaseTestProvider";
-const ORDERS_QUERY = defineQuery({
- source: { type: "card", entityId: "ordersQuestionEntity" },
-});
-
const CREATED_DASHBOARD = createMockDashboard({ name: "Q3 revenue" });
function SessionInfo() {
@@ -43,12 +37,6 @@ function SessionInfo() {
);
}
-function OrdersQueryError() {
- const { error } = useMetabaseQuery(ORDERS_QUERY);
-
- return <p>{error instanceof Error ? error.message : "no error"}</p>;
-}
-
function DateRangeLabel() {
const { formatDateRange } = useDateFormatter();
@@ -149,14 +137,6 @@ describe("MetabaseTestProvider", () => {
).toBeInTheDocument();
});
- it("rejects unmocked data requests", async () => {
- setup({ children: <OrdersQueryError /> });
-
- expect(
- await screen.findByText(/No mock for resolveDatasetQuery/),
- ).toBeInTheDocument();
- });
-
it("keeps serving SDK through strict mode effect replay", async () => {
render(
<StrictMode>
diff --git a/enterprise/frontend/src/embedding-sdk-package/testing/lib/private/action-parameters.ts b/enterprise/frontend/src/embedding-sdk-package/testing/lib/private/action-parameters.ts
new file mode 100644
index 00000000000..3929a3249d7
--- /dev/null
+++ b/enterprise/frontend/src/embedding-sdk-package/testing/lib/private/action-parameters.ts
@@ -0,0 +1,64 @@
+import type { ExecuteActionParams } from "embedding-sdk-bundle/lib/execute-action";
+import type {
+ ActionDefinition,
+ ActionParametersFromDefinition,
+} from "embedding-sdk-package/hooks/public/use-action/types";
+import type {
+ SchemaJavaScriptType,
+ TableFieldSchema,
+} from "embedding-sdk-shared/lib/create-metabase-query/schema";
+
+export type ActionParameters = NonNullable<ExecuteActionParams["parameters"]>;
+
+function isValueOfType(
+ value: unknown,
+ jsType: SchemaJavaScriptType | undefined,
+): boolean {
+ if (jsType === undefined || jsType === "unknown") {
+ return true;
+ }
+
+ if (jsType === "Date") {
+ return typeof value === "string" || value instanceof Date;
+ }
+
+ return typeof value === jsType;
+}
+
+export function getActionParametersError(
+ action: ActionDefinition,
+ parameters: ActionParameters,
+): string | null {
+ const fieldsBySlug = new Map<string, TableFieldSchema>(
+ Object.values(action.table.fields ?? {}).map((field) => [
+ field.slug,
+ field,
+ ]),
+ );
+
+ const unknownSlug = Object.keys(parameters).find(
+ (slug) => !fieldsBySlug.has(slug),
+ );
+
+ if (unknownSlug !== undefined) {
+ return `"${unknownSlug}" is not a column of the action's table`;
+ }
+
+ const mistypedField = [...fieldsBySlug.values()].find((field) => {
+ const value = parameters[field.slug];
+ const isEmptyValue = value === undefined || value === null;
+
+ return !isEmptyValue && !isValueOfType(value, field.jsType);
+ });
+
+ return mistypedField
+ ? `"${mistypedField.slug}" must be a ${mistypedField.jsType} value`
+ : null;
+}
+
+export function isActionParameters<TAction extends ActionDefinition>(
+ action: TAction,
+ parameters: ActionParameters,
+): parameters is ActionParametersFromDefinition<TAction> {
+ return getActionParametersError(action, parameters) === null;
+}
diff --git a/enterprise/frontend/src/embedding-sdk-package/testing/lib/private/actions.ts b/enterprise/frontend/src/embedding-sdk-package/testing/lib/private/actions.ts
new file mode 100644
index 00000000000..65d7d621030
--- /dev/null
+++ b/enterprise/frontend/src/embedding-sdk-package/testing/lib/private/actions.ts
@@ -0,0 +1,51 @@
+import _ from "underscore";
+
+import type { ExecuteActionResult } from "embedding-sdk-bundle/lib/execute-action";
+import type { SdkActionInput } from "embedding-sdk-bundle/types/action";
+import type { MetabaseEmbeddingSdkBundleExports } from "embedding-sdk-bundle/types/sdk-bundle";
+
+import type { ActionParameters } from "./action-parameters";
+import { TEST_PROVIDER_NAME } from "./constants";
+
+export type MetabaseActionMock = {
+ definition: SdkActionInput;
+ respond: (parameters: ActionParameters) => Promise<ExecuteActionResult>;
+};
+
+type ActionHandlers = {
+ executeAction: MetabaseEmbeddingSdkBundleExports["executeAction"];
+};
+
+function getActionLabel(input: SdkActionInput) {
+ if (typeof input !== "object") {
+ return String(input);
+ }
+
+ return String("entityId" in input ? input.entityId : input.action.id);
+}
+
+function createNoActionMockError(input: SdkActionInput) {
+ return new Error(
+ `No mock for action "${getActionLabel(input)}". Pass mockDataAppAction for it in ${TEST_PROVIDER_NAME} dataAppActions.`,
+ );
+}
+
+export function createActionHandlers(
+ actions: readonly MetabaseActionMock[],
+): ActionHandlers {
+ return {
+ executeAction:
+ () =>
+ async ({ actionId, parameters = {} }) => {
+ const mock = actions.find(({ definition }) =>
+ _.isEqual(definition, actionId),
+ );
+
+ if (!mock) {
+ throw createNoActionMockError(actionId);
+ }
+
+ return mock.respond(parameters);
+ },
+ };
+}
diff --git a/enterprise/frontend/src/embedding-sdk-package/testing/lib/private/bundle.tsx b/enterprise/frontend/src/embedding-sdk-package/testing/lib/private/bundle.tsx
index f0c84d31dec..3d03823f86f 100644
--- a/enterprise/frontend/src/embedding-sdk-package/testing/lib/private/bundle.tsx
+++ b/enterprise/frontend/src/embedding-sdk-package/testing/lib/private/bundle.tsx
@@ -14,11 +14,16 @@ import type { MetabaseEmbeddingSdkBundleExports } from "embedding-sdk-bundle/typ
import type { LoginStatus } from "embedding-sdk-bundle/types/user";
import type { MetabaseTestOptions } from "embedding-sdk-package/testing/components/MetabaseTestProvider";
+import { type MetabaseActionMock, createActionHandlers } from "./actions";
+import { type MetabaseQueryMock, createQueryHandlers } from "./queries";
+
type ChildrenProps = { children?: ReactNode };
// eslint-disable-next-line metabase/no-literal-metabase-strings -- the default name a real instance reports
const DEFAULT_APPLICATION_NAME = "Metabase";
const NO_FONTS: string[] = [];
+const NO_DATA_APP_QUERIES: MetabaseQueryMock[] = [];
+const NO_DATA_APP_ACTIONS: MetabaseActionMock[] = [];
const SIGNED_IN_STATUS: LoginStatus = { status: "success" };
const STATIC_QUESTION_SUBCOMPONENTS = {
@@ -83,6 +88,8 @@ export function createMockSdkBundle({
loginStatus = SIGNED_IN_STATUS,
applicationName = DEFAULT_APPLICATION_NAME,
availableFonts = NO_FONTS,
+ dataAppQueries = NO_DATA_APP_QUERIES,
+ dataAppActions = NO_DATA_APP_ACTIONS,
}: MetabaseTestOptions): MetabaseEmbeddingSdkBundleExports {
return {
CollectionBrowser,
@@ -111,11 +118,10 @@ export function createMockSdkBundle({
MetabotSubscriber: () => throwNoMock("MetabotSubscriber"),
SdkThemeProviderWithStore: () => throwNoMock("SdkThemeProviderWithStore"),
getSdkStore: () => throwNoMock("getSdkStore"),
- resolveDatasetQuery: () => () => throwNoMock("resolveDatasetQuery"),
- queryDataset: () => () => throwNoMock("queryDataset"),
+ ...createQueryHandlers(dataAppQueries),
queryQuestion: () => () => throwNoMock("queryQuestion"),
createDashboard: () => () => throwNoMock("createDashboard"),
- executeAction: () => () => throwNoMock("executeAction"),
+ ...createActionHandlers(dataAppActions),
getApplicationName: () => applicationName,
getAvailableFonts: () => availableFonts,
getLoginStatus: () => loginStatus,
diff --git a/enterprise/frontend/src/embedding-sdk-package/testing/lib/private/mock-calls.ts b/enterprise/frontend/src/embedding-sdk-package/testing/lib/private/mock-calls.ts
new file mode 100644
index 00000000000..addf0c1255a
--- /dev/null
+++ b/enterprise/frontend/src/embedding-sdk-package/testing/lib/private/mock-calls.ts
@@ -0,0 +1,16 @@
+export type MockCalls<TCall> = {
+ calls: () => readonly TCall[];
+ lastCall: () => TCall | undefined;
+};
+
+export function createMockCalls<TCall>() {
+ const calls: TCall[] = [];
+
+ return {
+ record: (call: TCall) => {
+ calls.push(call);
+ },
+ calls: () => calls,
+ lastCall: () => calls.at(-1),
+ };
+}
diff --git a/enterprise/frontend/src/embedding-sdk-package/testing/lib/private/queries.ts b/enterprise/frontend/src/embedding-sdk-package/testing/lib/private/queries.ts
new file mode 100644
index 00000000000..ada250b9dee
--- /dev/null
+++ b/enterprise/frontend/src/embedding-sdk-package/testing/lib/private/queries.ts
@@ -0,0 +1,105 @@
+import _ from "underscore";
+
+import type { QueryDatasetResult } from "embedding-sdk-bundle/lib/query-dataset";
+import type { MetabaseEmbeddingSdkBundleExports } from "embedding-sdk-bundle/types/sdk-bundle";
+import {
+ type DynamicQueryInput,
+ type QueryInput,
+ isTableInput,
+} from "embedding-sdk-shared/lib/create-metabase-query/input-guards";
+import type { NativeDatasetQuery } from "metabase-types/api";
+
+import { TEST_PROVIDER_NAME } from "./constants";
+
+export type MetabaseQueryMock = {
+ query: QueryInput;
+ dynamicQuery: DynamicQueryInput | undefined;
+ respond: () => Promise<QueryDatasetResult>;
+};
+
+type QueryHandlers = {
+ resolveDatasetQuery: MetabaseEmbeddingSdkBundleExports["resolveDatasetQuery"];
+ queryDataset: MetabaseEmbeddingSdkBundleExports["queryDataset"];
+};
+
+function getQueryClauses(dynamicQuery: DynamicQueryInput | undefined) {
+ return _.omit(dynamicQuery ?? {}, "enabled");
+}
+
+function isSameRequest(
+ mock: MetabaseQueryMock,
+ query: QueryInput,
+ dynamicQuery: DynamicQueryInput | undefined,
+) {
+ return (
+ _.isEqual(mock.query, query) &&
+ _.isEqual(getQueryClauses(mock.dynamicQuery), getQueryClauses(dynamicQuery))
+ );
+}
+
+function getQueryLabel(query: QueryInput): string {
+ if (isTableInput(query) && query.entityId !== undefined) {
+ return query.entityId;
+ }
+
+ const { source } = query;
+
+ return source.type === "card"
+ ? (source.name ?? source.entityId ?? String(source.id))
+ : String(source.id);
+}
+
+function createNoQueryMockError(
+ query: QueryInput,
+ dynamicQuery: DynamicQueryInput | undefined,
+) {
+ const clauses = getQueryClauses(dynamicQuery);
+ const dynamicPart = _.isEmpty(clauses)
+ ? ""
+ : ` with dynamic part ${JSON.stringify(clauses)}`;
+
+ return new Error(
+ `No mock for query "${getQueryLabel(query)}"${dynamicPart}. Pass mockDataAppQuery for it in ${TEST_PROVIDER_NAME} dataAppQueries.`,
+ );
+}
+
+export function createQueryHandlers(
+ queries: readonly MetabaseQueryMock[],
+): QueryHandlers {
+ const entries = queries.map((mock) => {
+ const datasetQuery: NativeDatasetQuery = {
+ type: "native",
+ native: { query: "" },
+ database: null,
+ };
+
+ return { mock, datasetQuery };
+ });
+
+ return {
+ resolveDatasetQuery: () => async (query, dynamicQuery) => {
+ const entry = entries.find(({ mock }) =>
+ isSameRequest(mock, query, dynamicQuery),
+ );
+
+ if (!entry) {
+ throw createNoQueryMockError(query, dynamicQuery);
+ }
+
+ return entry.datasetQuery;
+ },
+ queryDataset:
+ () =>
+ async ({ datasetQuery }) => {
+ const entry = entries.find(
+ (candidate) => candidate.datasetQuery === datasetQuery,
+ );
+
+ if (!entry) {
+ throw new Error("Dataset query was not built by a query mock.");
+ }
+
+ return entry.mock.respond();
+ },
+ };
+}
diff --git a/enterprise/frontend/src/embedding-sdk-package/testing/lib/public/data-app-actions.ts b/enterprise/frontend/src/embedding-sdk-package/testing/lib/public/data-app-actions.ts
new file mode 100644
index 00000000000..782da65ef25
--- /dev/null
+++ b/enterprise/frontend/src/embedding-sdk-package/testing/lib/public/data-app-actions.ts
@@ -0,0 +1,81 @@
+import type { ExecuteActionResult } from "embedding-sdk-bundle/lib/execute-action";
+import type {
+ ActionDefinition,
+ ActionKindFromDefinition,
+ ActionParametersFromDefinition,
+ ActionResultForKind,
+} from "embedding-sdk-package/hooks/public/use-action/types";
+import type { MetabaseActionMock } from "embedding-sdk-package/testing/lib/private/actions";
+import {
+ type MockCalls,
+ createMockCalls,
+} from "embedding-sdk-package/testing/lib/private/mock-calls";
+
+import {
+ getActionParametersError,
+ isActionParameters,
+} from "../private/action-parameters";
+
+import type { DataAppMockError } from "./data-app-queries";
+
+export type DataAppActionMockCall<TParameters> = {
+ parameters: TParameters;
+};
+
+export type DataAppActionMock<TParameters> = MetabaseActionMock &
+ MockCalls<DataAppActionMockCall<TParameters>>;
+
+export type DataAppActionMockError<TAction extends ActionDefinition> =
+ DataAppMockError & {
+ errors?: Partial<
+ Record<keyof ActionParametersFromDefinition<TAction>, string>
+ >;
+ };
+
+function createActionMock<TAction extends ActionDefinition>(
+ definition: TAction,
+ respond: () => Promise<ExecuteActionResult>,
+): DataAppActionMock<ActionParametersFromDefinition<TAction>> {
+ const calls =
+ createMockCalls<
+ DataAppActionMockCall<ActionParametersFromDefinition<TAction>>
+ >();
+
+ return {
+ definition,
+ respond: (parameters) => {
+ if (!isActionParameters(definition, parameters)) {
+ return Promise.reject(
+ new Error(
+ `Invalid parameters for action "${definition.entityId}": ${getActionParametersError(definition, parameters)}.`,
+ ),
+ );
+ }
+
+ calls.record({ parameters });
+
+ return respond();
+ },
+ calls: calls.calls,
+ lastCall: calls.lastCall,
+ };
+}
+
+export function mockDataAppAction<TAction extends ActionDefinition>(
+ action: TAction,
+ result: ActionResultForKind<ActionKindFromDefinition<TAction>>,
+): DataAppActionMock<ActionParametersFromDefinition<TAction>> {
+ return createActionMock(action, () => Promise.resolve(result));
+}
+
+export function mockDataAppActionError<TAction extends ActionDefinition>(
+ action: TAction,
+ error: DataAppActionMockError<TAction> = {},
+): DataAppActionMock<ActionParametersFromDefinition<TAction>> {
+ return createActionMock(action, () =>
+ Promise.reject({
+ status: error.status ?? 500,
+ data: { message: error.message, errors: error.errors ?? {} },
+ }),
+ );
+}
diff --git a/enterprise/frontend/src/embedding-sdk-package/testing/lib/public/data-app-actions.unit.spec.tsx b/enterprise/frontend/src/embedding-sdk-package/testing/lib/public/data-app-actions.unit.spec.tsx
new file mode 100644
index 00000000000..dca1b04f0ec
--- /dev/null
+++ b/enterprise/frontend/src/embedding-sdk-package/testing/lib/public/data-app-actions.unit.spec.tsx
@@ -0,0 +1,154 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { useState } from "react";
+
+import { useDataAppAction } from "embedding-sdk-package/hooks/public/use-action";
+import { defineAction } from "embedding-sdk-package/hooks/public/use-action/define-action";
+import {
+ type MetabaseTestOptions,
+ MetabaseTestProvider,
+} from "embedding-sdk-package/testing/components/MetabaseTestProvider";
+
+import { mockDataAppAction, mockDataAppActionError } from "./data-app-actions";
+
+type RefundButtonProps = {
+ parameters: { id: number; status?: string };
+};
+
+type SetupOpts = {
+ parameters?: RefundButtonProps["parameters"];
+ dataAppActions?: MetabaseTestOptions["dataAppActions"];
+};
+
+const ORDERS_TABLE = {
+ type: "table",
+ id: 1,
+ fields: {
+ id: {
+ type: "column",
+ fieldId: 100,
+ tableId: 1,
+ name: "ID",
+ slug: "id",
+ jsType: "number",
+ },
+ status: {
+ type: "column",
+ fieldId: 101,
+ tableId: 1,
+ name: "STATUS",
+ slug: "status",
+ jsType: "string",
+ },
+ },
+} as const;
+
+const REFUND_ORDER = defineAction({
+ entityId: "refundOrderEntity",
+ kind: "row/update",
+ table: ORDERS_TABLE,
+});
+
+function RefundButton({ parameters }: RefundButtonProps) {
+ const { execute, result, error } = useDataAppAction(REFUND_ORDER);
+ const [thrownMessage, setThrownMessage] = useState("");
+
+ function handleClick() {
+ return execute(parameters).catch((thrown: unknown) =>
+ setThrownMessage(thrown instanceof Error ? thrown.message : ""),
+ );
+ }
+
+ return (
+ <div>
+ <button onClick={handleClick}>Refund</button>
+ {result && <p>Refunded {result["rows-updated"]} order</p>}
+ {error && <p>{error.data.message}</p>}
+ {error?.data.errors?.status && <p>{error.data.errors.status}</p>}
+ {thrownMessage && <p>{thrownMessage}</p>}
+ </div>
+ );
+}
+
+async function setup({
+ parameters = { id: 1 },
+ dataAppActions,
+}: SetupOpts = {}) {
+ render(
+ <MetabaseTestProvider dataAppActions={dataAppActions}>
+ <RefundButton parameters={parameters} />
+ </MetabaseTestProvider>,
+ );
+
+ await userEvent.click(await screen.findByRole("button", { name: "Refund" }));
+}
+
+describe("mockDataAppAction", () => {
+ it("resolves action with mocked result and records parameters", async () => {
+ const refund = mockDataAppAction(REFUND_ORDER, { "rows-updated": 1 });
+
+ await setup({
+ parameters: { id: 7, status: "refunded" },
+ dataAppActions: [refund],
+ });
+
+ expect(await screen.findByText("Refunded 1 order")).toBeInTheDocument();
+ expect(refund.calls()).toEqual([
+ { parameters: { id: 7, status: "refunded" } },
+ ]);
+ expect(refund.lastCall()).toEqual({
+ parameters: { id: 7, status: "refunded" },
+ });
+ });
+
+ it("rejects action that has no mock", async () => {
+ await setup();
+
+ expect(
+ await screen.findByText(/No mock for action "refundOrderEntity"/),
+ ).toBeInTheDocument();
+ });
+
+ it("rejects parameters that do not match action", async () => {
+ const refund = mockDataAppAction(REFUND_ORDER, { "rows-updated": 1 });
+
+ // @ts-expect-error `id` is a number; the mock checks it at runtime too
+ await setup({ parameters: { id: "7" }, dataAppActions: [refund] });
+
+ expect(
+ await screen.findByText(/"id" must be a number value/),
+ ).toBeInTheDocument();
+ expect(refund.calls()).toHaveLength(0);
+ });
+
+ it("rejects parameters that are not columns of action table", async () => {
+ const refund = mockDataAppAction(REFUND_ORDER, { "rows-updated": 1 });
+
+ await setup({
+ // @ts-expect-error `note` is not a column of the table
+ parameters: { id: 7, note: "Damaged" },
+ dataAppActions: [refund],
+ });
+
+ expect(
+ await screen.findByText(/"note" is not a column of the action's table/),
+ ).toBeInTheDocument();
+ expect(refund.calls()).toHaveLength(0);
+ });
+});
+
+describe("mockDataAppActionError", () => {
+ it("rejects action with mocked error and field errors", async () => {
+ const refund = mockDataAppActionError(REFUND_ORDER, {
+ status: 400,
+ message: "Refund failed",
+ errors: { status: "Status is required" },
+ });
+
+ await setup({ dataAppActions: [refund] });
+
+ expect(await screen.findByText("Refund failed")).toBeInTheDocument();
+ expect(screen.getByText("Status is required")).toBeInTheDocument();
+ expect(refund.lastCall()).toEqual({ parameters: { id: 1 } });
+ });
+});
diff --git a/enterprise/frontend/src/embedding-sdk-package/testing/lib/public/data-app-queries.ts b/enterprise/frontend/src/embedding-sdk-package/testing/lib/public/data-app-queries.ts
new file mode 100644
index 00000000000..9b1d102214c
--- /dev/null
+++ b/enterprise/frontend/src/embedding-sdk-package/testing/lib/public/data-app-queries.ts
@@ -0,0 +1,122 @@
+import _ from "underscore";
+
+import type { RowValue } from "embedding-sdk-package/hooks/public/data-schema";
+import type {
+ DynamicQueryArgument,
+ MetabaseQueryOptions,
+ MetabaseQueryRow,
+} from "embedding-sdk-package/hooks/public/use-metabase-query/types";
+import {
+ type MockCalls,
+ createMockCalls,
+} from "embedding-sdk-package/testing/lib/private/mock-calls";
+import type { MetabaseQueryMock } from "embedding-sdk-package/testing/lib/private/queries";
+import type {
+ DynamicQueryInput,
+ QueryInput,
+} from "embedding-sdk-shared/lib/create-metabase-query/input-guards";
+import { getQueryResultColumnNames } from "embedding-sdk-shared/lib/create-metabase-query/result-columns";
+import type { DatasetColumn, RowValues } from "metabase-types/api";
+
+export type DataAppQueryMockCall<TDynamic> = {
+ dynamicQuery: TDynamic;
+};
+
+export type DataAppQueryMock<TDynamic> = MetabaseQueryMock &
+ MockCalls<DataAppQueryMockCall<TDynamic>>;
+
+export type DataAppMockError = {
+ status?: number;
+ message?: string;
+};
+
+type MockRow = Partial<Record<string, RowValue>>;
+
+function getResultColumns(
+ query: QueryInput,
+ dynamicQuery: DynamicQueryInput | undefined,
+ rows: readonly MockRow[],
+): DatasetColumn[] {
+ const queryNames = getQueryResultColumnNames(query, dynamicQuery);
+ const names =
+ queryNames.length > 0 ? queryNames : _.uniq(rows.flatMap(Object.keys));
+
+ return names.map((name) => ({ name, display_name: name, source: "fields" }));
+}
+
+function createQueryMock<TDynamic>(
+ query: QueryInput,
+ dynamicQuery: TDynamic & (DynamicQueryInput | undefined),
+ respond: () => Promise<{ columns: DatasetColumn[]; rows: RowValues[] }>,
+): DataAppQueryMock<TDynamic> {
+ const calls = createMockCalls<DataAppQueryMockCall<TDynamic>>();
+
+ return {
+ query,
+ dynamicQuery,
+ respond: async () => {
+ calls.record({ dynamicQuery });
+ const { columns, rows } = await respond();
+
+ return { columns, rows, rowCount: rows.length, runningTime: 0 };
+ },
+ calls: calls.calls,
+ lastCall: calls.lastCall,
+ };
+}
+
+export function mockDataAppQuery<TQuery extends MetabaseQueryOptions>(
+ query: TQuery,
+ rows: readonly Partial<MetabaseQueryRow<TQuery>>[],
+): DataAppQueryMock<undefined>;
+export function mockDataAppQuery<
+ TQuery extends MetabaseQueryOptions,
+ const TDynamic = undefined,
+>(
+ query: TQuery,
+ dynamicQuery: DynamicQueryArgument<undefined, TQuery, TDynamic> | undefined,
+ rows: readonly Partial<MetabaseQueryRow<TQuery, TDynamic>>[],
+): DataAppQueryMock<TDynamic>;
+export function mockDataAppQuery(
+ query: MetabaseQueryOptions,
+ ...args:
+ | [readonly MockRow[]]
+ | [DynamicQueryInput | undefined, readonly MockRow[]]
+): DataAppQueryMock<DynamicQueryInput | undefined> {
+ const [dynamicQuery, rows] = args.length === 1 ? [undefined, args[0]] : args;
+ const columns = getResultColumns(query, dynamicQuery, rows);
+
+ return createQueryMock(query, dynamicQuery, async () => ({
+ columns,
+ rows: rows.map((row) => columns.map(({ name }) => row[name] ?? null)),
+ }));
+}
+
+export function mockDataAppQueryError<TQuery extends MetabaseQueryOptions>(
+ query: TQuery,
+ error?: DataAppMockError,
+): DataAppQueryMock<undefined>;
+export function mockDataAppQueryError<
+ TQuery extends MetabaseQueryOptions,
+ const TDynamic = undefined,
+>(
+ query: TQuery,
+ dynamicQuery: DynamicQueryArgument<undefined, TQuery, TDynamic> | undefined,
+ error: DataAppMockError,
+): DataAppQueryMock<TDynamic>;
+export function mockDataAppQueryError(
+ query: MetabaseQueryOptions,
+ ...args:
+ | [DataAppMockError?]
+ | [DynamicQueryInput | undefined, DataAppMockError]
+): DataAppQueryMock<DynamicQueryInput | undefined> {
+ const [dynamicQuery, error = {}] =
+ args.length === 2 ? args : [undefined, args[0]];
+
+ return createQueryMock(query, dynamicQuery, () =>
+ Promise.reject({
+ status: error.status ?? 500,
+ data: { message: error.message ?? "Query failed" },
+ }),
+ );
+}
diff --git a/enterprise/frontend/src/embedding-sdk-package/testing/lib/public/data-app-queries.unit.spec.tsx b/enterprise/frontend/src/embedding-sdk-package/testing/lib/public/data-app-queries.unit.spec.tsx
new file mode 100644
index 00000000000..09958cfbcc8
--- /dev/null
+++ b/enterprise/frontend/src/embedding-sdk-package/testing/lib/public/data-app-queries.unit.spec.tsx
@@ -0,0 +1,254 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import {
+ aggregations,
+ filter,
+ useMetabaseQuery,
+} from "embedding-sdk-package/hooks/public/use-metabase-query";
+import { defineQuery } from "embedding-sdk-package/hooks/public/use-metabase-query/define-query";
+import {
+ type MetabaseTestOptions,
+ MetabaseTestProvider,
+} from "embedding-sdk-package/testing/components/MetabaseTestProvider";
+
+import { mockDataAppQuery, mockDataAppQueryError } from "./data-app-queries";
+
+type OrdersListProps = {
+ status?: string;
+};
+
+type SetupOpts = {
+ status?: string;
+ dataAppQueries?: MetabaseTestOptions["dataAppQueries"];
+};
+
+const ORDERS_TABLE = {
+ type: "table",
+ id: 1,
+ fields: {
+ id: {
+ type: "column",
+ fieldId: 100,
+ tableId: 1,
+ name: "id",
+ slug: "id",
+ displayName: "ID",
+ jsType: "number",
+ },
+ status: {
+ type: "column",
+ fieldId: 101,
+ tableId: 1,
+ name: "status",
+ slug: "status",
+ displayName: "Status",
+ jsType: "string",
+ },
+ total: {
+ type: "column",
+ fieldId: 102,
+ tableId: 1,
+ name: "total",
+ slug: "total",
+ displayName: "Total",
+ jsType: "number",
+ },
+ },
+} as const;
+
+const ORDERS_QUERY = defineQuery({
+ entityId: "ordersListEntity",
+ source: ORDERS_TABLE,
+});
+
+const REFUNDED_ORDERS = {
+ filters: [filter({ type: "column", name: "status" }, "=", "refunded")],
+} as const;
+
+const ORDERS_BY_STATUS = {
+ breakouts: [{ type: "column", name: "status" }],
+ aggregations: [aggregations.count()],
+} as const;
+
+function getErrorMessage(error: unknown) {
+ if (error instanceof Error) {
+ return error.message;
+ }
+
+ const isApiError =
+ typeof error === "object" &&
+ error !== null &&
+ "status" in error &&
+ "data" in error;
+
+ return isApiError ? JSON.stringify(error) : "";
+}
+
+function OrdersList({ status }: OrdersListProps) {
+ const { data, error, refetch } = useMetabaseQuery(
+ ORDERS_QUERY,
+ status === undefined
+ ? undefined
+ : { filters: [filter({ type: "column", name: "status" }, "=", status)] },
+ );
+
+ return (
+ <div>
+ <ul>
+ {data?.rows.map((row) => (
+ <li key={String(row.id)}>
+ {row.id} {row.status} {row.total}
+ </li>
+ ))}
+ </ul>
+ <p>{getErrorMessage(error)}</p>
+ <button onClick={refetch}>Refetch</button>
+ </div>
+ );
+}
+
+function OrdersByStatus() {
+ const { data } = useMetabaseQuery(ORDERS_QUERY, {
+ breakouts: [{ type: "column", name: "status" }],
+ aggregations: [aggregations.count()],
+ });
+
+ return (
+ <div>
+ <p>{data?.columns.map((column) => column.name).join(",")}</p>
+ <ul>
+ {data?.rows.map((row) => (
+ <li key={String(row.status)}>
+ {row.status}: {row.count}
+ </li>
+ ))}
+ </ul>
+ </div>
+ );
+}
+
+function setup({ status, dataAppQueries }: SetupOpts = {}) {
+ return render(
+ <MetabaseTestProvider dataAppQueries={dataAppQueries}>
+ <OrdersList status={status} />
+ </MetabaseTestProvider>,
+ );
+}
+
+describe("mockDataAppQuery", () => {
+ it("serves mocked rows and leaves unset columns null", async () => {
+ setup({
+ dataAppQueries: [
+ mockDataAppQuery(ORDERS_QUERY, [
+ { id: 1, status: "paid", total: 42 },
+ { id: 2 },
+ ]),
+ ],
+ });
+
+ expect(await screen.findByText("1 paid 42")).toBeInTheDocument();
+ expect(screen.getByText("2")).toBeInTheDocument();
+ });
+
+ it("answers only requests with mocked dynamic part", async () => {
+ setup({
+ status: "refunded",
+ dataAppQueries: [
+ mockDataAppQuery(ORDERS_QUERY, [{ id: 1, status: "paid" }]),
+ mockDataAppQuery(ORDERS_QUERY, REFUNDED_ORDERS, [
+ { id: 2, status: "refunded" },
+ ]),
+ ],
+ });
+
+ expect(await screen.findByText("2 refunded")).toBeInTheDocument();
+ expect(screen.queryByText("1 paid")).not.toBeInTheDocument();
+ });
+
+ it("rejects query that has no mock", async () => {
+ setup();
+
+ expect(
+ await screen.findByText(
+ /No mock for query "ordersListEntity"\. Pass mockDataAppQuery/,
+ ),
+ ).toBeInTheDocument();
+ });
+
+ it("rejects requests with unmocked dynamic part", async () => {
+ setup({
+ status: "pending",
+ dataAppQueries: [
+ mockDataAppQuery(ORDERS_QUERY, [{ id: 1, status: "paid" }]),
+ ],
+ });
+
+ expect(
+ await screen.findByText(
+ /No mock for query "ordersListEntity" with dynamic part/,
+ ),
+ ).toBeInTheDocument();
+ });
+
+ it("builds result columns from query", async () => {
+ render(
+ <MetabaseTestProvider
+ dataAppQueries={[
+ mockDataAppQuery(ORDERS_QUERY, ORDERS_BY_STATUS, [
+ { status: "paid", count: 12 },
+ { status: "refunded" },
+ ]),
+ ]}
+ >
+ <OrdersByStatus />
+ </MetabaseTestProvider>,
+ );
+
+ expect(await screen.findByText("paid: 12")).toBeInTheDocument();
+ expect(screen.getByText("refunded:")).toBeInTheDocument();
+ expect(screen.getByText("status,count")).toBeInTheDocument();
+ });
+
+ it("records every request it answers", async () => {
+ const orders = mockDataAppQuery(ORDERS_QUERY, REFUNDED_ORDERS, [{ id: 2 }]);
+
+ setup({ status: "refunded", dataAppQueries: [orders] });
+ await screen.findByText("2");
+ await userEvent.click(screen.getByRole("button", { name: "Refetch" }));
+
+ await waitFor(() => expect(orders.calls()).toHaveLength(2));
+ expect(orders.lastCall()).toEqual({ dynamicQuery: REFUNDED_ORDERS });
+ });
+});
+
+describe("mockDataAppQueryError", () => {
+ it("rejects query with mocked API error", async () => {
+ setup({
+ dataAppQueries: [
+ mockDataAppQueryError(ORDERS_QUERY, {
+ status: 403,
+ message: "No access",
+ }),
+ ],
+ });
+
+ expect(
+ await screen.findByText(
+ JSON.stringify({ status: 403, data: { message: "No access" } }),
+ ),
+ ).toBeInTheDocument();
+ });
+
+ it("rejects only requests with mocked dynamic part", async () => {
+ setup({
+ status: "refunded",
+ dataAppQueries: [
+ mockDataAppQuery(ORDERS_QUERY, [{ id: 1, status: "paid" }]),
+ mockDataAppQueryError(ORDERS_QUERY, REFUNDED_ORDERS, { status: 500 }),
+ ],
+ });
+
+ expect(await screen.findByText(/"status":500/)).toBeInTheDocument();
+ });
+});
diff --git a/enterprise/frontend/src/embedding-sdk-package/testing/tests/data-app-actions-type-contract.ts b/enterprise/frontend/src/embedding-sdk-package/testing/tests/data-app-actions-type-contract.ts
new file mode 100644
index 00000000000..c94777f2211
--- /dev/null
+++ b/enterprise/frontend/src/embedding-sdk-package/testing/tests/data-app-actions-type-contract.ts
@@ -0,0 +1,60 @@
+import { defineAction } from "embedding-sdk-package/hooks/public/use-action/define-action";
+
+import {
+ mockDataAppAction,
+ mockDataAppActionError,
+} from "../lib/public/data-app-actions";
+
+const ORDERS_TABLE = {
+ type: "table",
+ id: 1,
+ fields: {
+ id: {
+ type: "column",
+ fieldId: 100,
+ tableId: 1,
+ name: "ID",
+ slug: "id",
+ jsType: "number",
+ },
+ status: {
+ type: "column",
+ fieldId: 101,
+ tableId: 1,
+ name: "STATUS",
+ slug: "status",
+ jsType: "string",
+ },
+ },
+} as const;
+
+const CREATE_ORDER = defineAction({
+ entityId: "createOrderEntity",
+ kind: "row/create",
+ table: ORDERS_TABLE,
+});
+
+const UPDATE_ORDER = defineAction({
+ entityId: "updateOrderEntity",
+ kind: "row/update",
+ table: ORDERS_TABLE,
+});
+
+const createOrder = mockDataAppAction(CREATE_ORDER, {
+ "created-row": { id: 1 },
+});
+
+// @ts-expect-error `status` is `string | null | undefined`, not a number
+export const status: number | undefined =
+ createOrder.lastCall()?.parameters.status;
+
+// @ts-expect-error a table create returns `created-row`, not `rows-updated`
+mockDataAppAction(CREATE_ORDER, { "rows-updated": 1 });
+
+// @ts-expect-error `note` is not a column of the action's table
+mockDataAppActionError(CREATE_ORDER, { errors: { note: "Too long" } });
+
+mockDataAppAction(UPDATE_ORDER, { "rows-updated": 1 });
+
+// @ts-expect-error a table update returns a count of rows
+mockDataAppAction(UPDATE_ORDER, { "rows-updated": [1] });
diff --git a/enterprise/frontend/src/embedding-sdk-package/testing/tests/data-app-queries-type-contract.ts b/enterprise/frontend/src/embedding-sdk-package/testing/tests/data-app-queries-type-contract.ts
new file mode 100644
index 00000000000..6f981431052
--- /dev/null
+++ b/enterprise/frontend/src/embedding-sdk-package/testing/tests/data-app-queries-type-contract.ts
@@ -0,0 +1,58 @@
+import {
+ aggregations,
+ filter,
+} from "embedding-sdk-package/hooks/public/use-metabase-query";
+import { defineQuery } from "embedding-sdk-package/hooks/public/use-metabase-query/define-query";
+
+import {
+ mockDataAppQuery,
+ mockDataAppQueryError,
+} from "../lib/public/data-app-queries";
+
+const ORDERS_QUERY = defineQuery({
+ source: {
+ type: "card",
+ entityId: "ordersQuestionEntity",
+ name: "Orders list",
+ columns: [
+ { type: "column", name: "id", displayName: "ID", jsType: "number" },
+ {
+ type: "column",
+ name: "status",
+ displayName: "Status",
+ jsType: "string",
+ },
+ { type: "column", name: "total", displayName: "Total", jsType: "number" },
+ ],
+ },
+});
+
+const REFUNDED_ORDERS = {
+ filters: [filter({ type: "column", name: "status" }, "=", "refunded")],
+} as const;
+
+const ORDERS_BY_STATUS = {
+ breakouts: [{ type: "column", name: "status" }],
+ aggregations: [aggregations.count()],
+} as const;
+
+// @ts-expect-error `unknown` is not a column of the query
+mockDataAppQuery(ORDERS_QUERY, [{ unknown: 1 }]);
+
+// @ts-expect-error `id` is a number
+mockDataAppQuery(ORDERS_QUERY, [{ id: "1" }]);
+
+mockDataAppQuery(ORDERS_QUERY, ORDERS_BY_STATUS, [
+ // @ts-expect-error grouped rows have only the breakout and aggregation columns
+ { status: "paid", total: 1 },
+]);
+
+mockDataAppQuery(
+ ORDERS_QUERY,
+ // @ts-expect-error breakouts need aggregations
+ { breakouts: [{ type: "column", name: "status" }] },
+ [],
+);
+
+// @ts-expect-error an error with a dynamic part needs the error argument
+mockDataAppQueryError(ORDERS_QUERY, REFUNDED_ORDERS);
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 e20aa22867d..5ae8358e4da 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
@@ -3,17 +3,20 @@ import {
type QueryInput,
type QuestionQueryInput,
type TableQueryInput,
+ isCountAggregation,
isMeasureReference,
isMetricReference,
isNamedBreakout,
isSegmentReference,
unwrapNamedAggregation,
} from "embedding-sdk-shared/lib/create-metabase-query/input-guards";
+import { getAggregationResultColumnNames } from "embedding-sdk-shared/lib/create-metabase-query/result-columns";
import type {
MetricSchema,
QuestionSchema,
} from "embedding-sdk-shared/lib/create-metabase-query/schema";
import * as Lib from "metabase-lib";
+import type { TestAggregationSpec } from "metabase-types/api";
import { isObject } from "metabase-types/guards";
// `satisfies` ties the list to the input type, so a renamed or mistyped clause
@@ -312,18 +315,8 @@ function getFirstOperatorArg(value: unknown) {
return value.args[0];
}
-function isCountAggregation(value: unknown) {
- return (
- isObject(value) &&
- value.type === "operator" &&
- value.operator === "count" &&
- Array.isArray(value.args) &&
- value.args.length === 0
- );
-}
-
type GroupingClauses = {
- aggregations?: readonly unknown[];
+ aggregations?: readonly TestAggregationSpec[];
breakouts?: readonly unknown[];
};
@@ -337,7 +330,7 @@ function isGroupedQuery(input: GroupingClauses) {
}
function isAggregationResultReference(
- aggregations: readonly unknown[] | undefined,
+ aggregations: readonly TestAggregationSpec[] | undefined,
value: unknown,
) {
if (
@@ -351,44 +344,6 @@ function isAggregationResultReference(
return getAggregationResultColumnNames(aggregations).includes(value.name);
}
-function getAggregationResultColumnNames(
- aggregations: readonly unknown[] | undefined,
-) {
- return (aggregations ?? []).flatMap((aggregation) => {
- // Metrics and Measures also carry a `name`, but it is their title, not a
- // result column name.
- if (
- isObject(aggregation) &&
- aggregation.type === "operator" &&
- typeof aggregation.name === "string"
- ) {
- return [aggregation.name];
- }
-
- if (isCountAggregation(aggregation)) {
- return ["count"];
- }
-
- const columns = getColumns(aggregation);
-
- if (!columns) {
- return [];
- }
-
- return columns.flatMap((column) =>
- isObject(column) && typeof column.name === "string" ? [column.name] : [],
- );
- });
-}
-
-function getColumns(value: unknown) {
- if (!isObject(value) || !("columns" in value)) {
- return null;
- }
-
- return Array.isArray(value.columns) ? value.columns : null;
-}
-
function isBreakoutReference(
breakouts: readonly unknown[] | undefined,
value: unknown,
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 459756d2116..30beed221f9 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
@@ -3,6 +3,7 @@ import type {
TestBreakoutWithNameSpec,
TestExpressionSpec,
TestNamedAggregationSpec,
+ TestOperatorSpec,
TestStageSpec,
TestStageWithSourceSpec,
} from "metabase-types/api";
@@ -89,6 +90,25 @@ export const isQuestionReference = (value: unknown): value is QuestionSchema =>
export const isQueryInput = (input: unknown): input is QueryInput =>
isTableInput(input) || isQuestionInput(input);
+const isOperator = (value: unknown): value is TestOperatorSpec =>
+ isObject(value) &&
+ value.type === "operator" &&
+ typeof value.operator === "string";
+
+export const isAggregationSpec = (
+ value: unknown,
+): value is TestAggregationSpec =>
+ isOperator(value) ||
+ isNamedAggregation(value) ||
+ isMetricReference(value) ||
+ isMeasureReference(value);
+
+export const isCountAggregation = (aggregation: TestAggregationSpec) =>
+ !isNamedAggregation(aggregation) &&
+ aggregation.type === "operator" &&
+ aggregation.operator === "count" &&
+ aggregation.args?.length === 0;
+
export const isUnaryOperator = (operator: string) =>
operator === "is-empty" ||
operator === "not-empty" ||
diff --git a/frontend/src/embedding-sdk-shared/lib/create-metabase-query/result-columns.ts b/frontend/src/embedding-sdk-shared/lib/create-metabase-query/result-columns.ts
new file mode 100644
index 00000000000..6dd36065f64
--- /dev/null
+++ b/frontend/src/embedding-sdk-shared/lib/create-metabase-query/result-columns.ts
@@ -0,0 +1,124 @@
+import type {
+ TestAggregationSpec,
+ TestBreakoutSpec,
+ TestColumnSpec,
+} from "metabase-types/api";
+
+import {
+ type DynamicQueryInput,
+ type QueryInput,
+ isMeasureReference,
+ isMetricReference,
+ isNamedAggregation,
+ isTableInput,
+} from "./input-guards";
+import type {
+ QuestionSchema,
+ SchemaJavaScriptType,
+ TableSchema,
+} from "./schema";
+
+const ORDERABLE_JAVASCRIPT_TYPES: readonly SchemaJavaScriptType[] = [
+ "string",
+ "number",
+ "boolean",
+ "Date",
+];
+
+export function getAggregationResultColumnDefaultName(
+ operator: string,
+): string {
+ return operator === "distinct" ? "count" : operator;
+}
+
+export function getAggregationResultColumnJavaScriptType(
+ operator: string,
+ dimensionJavaScriptType: SchemaJavaScriptType | undefined,
+): SchemaJavaScriptType {
+ const isOrderableDimension =
+ dimensionJavaScriptType !== undefined &&
+ ORDERABLE_JAVASCRIPT_TYPES.includes(dimensionJavaScriptType);
+
+ return (operator === "min" || operator === "max") && isOrderableDimension
+ ? dimensionJavaScriptType
+ : "number";
+}
+
+export function getAggregationResultColumnNames(
+ aggregations: readonly TestAggregationSpec[] = [],
+): string[] {
+ return aggregations.flatMap((aggregation) => {
+ if (isNamedAggregation(aggregation)) {
+ return [aggregation.name];
+ }
+
+ if (isMeasureReference(aggregation) || isMetricReference(aggregation)) {
+ return (aggregation.columns ?? []).map(({ name }) => name);
+ }
+
+ if (aggregation.type === "operator") {
+ return [
+ aggregation.name ??
+ getAggregationResultColumnDefaultName(aggregation.operator),
+ ];
+ }
+
+ return [];
+ });
+}
+
+function getSourceResultColumnNames(
+ source: TableSchema | QuestionSchema,
+): string[] {
+ const columns =
+ source.columns ??
+ (source.type === "table" ? Object.values(source.fields ?? {}) : []);
+
+ return columns.map(({ name }) => name);
+}
+
+function getBreakoutResultColumnNames(
+ breakouts: readonly TestBreakoutSpec[],
+): string[] {
+ return breakouts.flatMap(({ name }) => name ?? []);
+}
+
+function getFieldResultColumnNames(
+ fields: readonly TestColumnSpec[],
+): string[] {
+ return fields.flatMap(({ name }) => name ?? []);
+}
+
+function getStageResultColumnNames(
+ stage: QueryInput | DynamicQueryInput | undefined,
+ inputNames: string[],
+): string[] {
+ if (stage === undefined) {
+ return inputNames;
+ }
+
+ const { breakouts = [], aggregations = [] } = stage;
+
+ if (breakouts.length > 0 || aggregations.length > 0) {
+ return [
+ ...getBreakoutResultColumnNames(breakouts),
+ ...getAggregationResultColumnNames(aggregations),
+ ];
+ }
+
+ const fieldNames = isTableInput(stage)
+ ? getFieldResultColumnNames(stage.fields ?? [])
+ : [];
+
+ return fieldNames.length > 0 ? fieldNames : inputNames;
+}
+
+export function getQueryResultColumnNames(
+ query: QueryInput,
+ dynamicQuery?: DynamicQueryInput,
+): string[] {
+ return getStageResultColumnNames(
+ dynamicQuery,
+ getStageResultColumnNames(query, getSourceResultColumnNames(query.source)),
+ );
+}