The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
import { translateEntityId } from "embedding-sdk-bundle/lib/translate-entity-id";
import type { SdkStore } from "embedding-sdk-bundle/store/types";
import {
type DynamicQueryInput,
type QueryInput,
type TableQueryInput,
isQueryInput,
isQuestionInput,
isTableInput,
} from "embedding-sdk-shared/lib/create-metabase-query/input-guards";
import type { QuestionSchema } from "embedding-sdk-shared/lib/create-metabase-query/schema";
import { cardApi, selectCard, selectTableQueryMetadata } from "metabase/api";
import { runRtkEndpoint } from "metabase/api/utils/run-rtk-endpoint";
import { isDataApp, isDataAppDev } from "metabase/embedding-sdk/config";
import { selectMetadataProviderUnfiltered } from "metabase/metadata-store";
import { fetchTableMetadataAndForeignKeys } from "metabase/redux/tables";
import * as Lib from "metabase-lib";
import type {
Card,
DatasetQuery,
TestBreakoutSpec,
TestColumnSpec,
TestExpressionSpec,
TestOperatorArgSpec,
TestQuerySpec,
TestStageSpec,
TestStageWithSourceSpec,
} from "metabase-types/api";
import { isObject } from "metabase-types/guards";
import { loadReferencedMetricMetadata } from "./metric-metadata";
import {
validateDynamicQuery,
validateQueryInput,
validateUniqueColumnNames,
} from "./validation";
export type ResolveDatasetQuery = (
store: SdkStore,
) => (
input: QueryInput,
dynamicQuery?: DynamicQueryInput,
) => Promise<DatasetQuery>;
export const resolveDatasetQuery: ResolveDatasetQuery =
(store) => async (input: QueryInput, dynamicQuery?: DynamicQueryInput) => {
if (!isQueryInput(input)) {
throw new Error(
'Query object creation requires a source reference like `{ type: "table", id }` or `{ type: "card", id }`.',
);
}
const { input: sourceInput, card: sourceCard } = await resolveSourceCard(
store,
input,
);
validateQueryInput(sourceInput);
validateDynamicQuery(dynamicQuery);
await loadSourceMetadata(store, sourceInput, sourceCard);
return resolveQueryFromLoadedMetadata(
sourceInput,
dynamicQuery,
store.getState(),
sourceCard,
);
};
type SdkState = ReturnType<SdkStore["getState"]>;
type ResolvedSource = {
input: QueryInput;
card?: Card;
};
/**
* A card source given by its entity ID, with the card's numeric id: query
* metadata and the query itself address cards by numeric id. Outside the dev
* preview, a data app's table query runs the question its `entityId` names,
* which holds its static clauses.
*/
async function resolveSourceCard(
store: SdkStore,
input: QueryInput,
): Promise<ResolvedSource> {
if (isTableInput(input) && isDataApp() && !isDataAppDev()) {
return resolveDataAppQuestion(store, input);
}
if (!isQuestionInput(input) || input.source.id !== undefined) {
return { input };
}
const card = await fetchCardByEntityId(store, input.source.entityId);
return {
input: { ...input, source: { ...input.source, id: card.id } },
card,
};
}
async function resolveDataAppQuestion(
store: SdkStore,
{ entityId }: TableQueryInput,
): Promise<ResolvedSource> {
if (entityId === undefined) {
throw new Error(
"A data app's query needs an `entityId` in `defineQuery(...)`: the question it names is what the app runs.",
);
}
const cardId = await translateEntityId(store, "card", entityId);
const card: Card = await runRtkEndpoint(
{ id: cardId },
store.dispatch,
cardApi.endpoints.getCard,
{ forceRefetch: false },
);
return { input: { source: { type: "card", id: card.id } }, card };
}
async function fetchCardByEntityId(
store: SdkStore,
entityId: string,
): Promise<Card> {
try {
return await runRtkEndpoint(
{ id: entityId },
store.dispatch,
cardApi.endpoints.getCard,
{ forceRefetch: false },
);
} catch (error) {
if (isObject(error) && error.status === 404) {
throw new Error(
`Saved question ${entityId} does not exist. Generate the app's questions and import the repository again.`,
);
}
throw error;
}
}
function getQuestionId(source: QuestionSchema): number {
if (source.id === undefined) {
throw new Error(`Saved question ${source.entityId} was not resolved.`);
}
return source.id;
}
function resolveQueryFromLoadedMetadata(
input: QueryInput,
dynamicQuery: DynamicQueryInput | undefined,
state: SdkState,
sourceCard: Card | undefined,
) {
if (!isQueryInput(input)) {
throw new Error(
'Query object creation requires a source reference like `{ type: "table", id }` or `{ type: "card", id }`.',
);
}
const databaseId = getSourceDatabaseId(input, state, sourceCard);
const provider = selectMetadataProviderUnfiltered(state, databaseId);
const sourceStage = toStageSpec(input);
// Merged into the source stage, the dynamic clauses would run before its
// aggregation; as their own stage they act on its result columns.
const dynamicStage = dynamicQuery && toResultColumnStageSpec(dynamicQuery);
validateUniqueColumnNames(
Lib.createTestQuery(provider, {
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.
// The source itself carries the id, so set it explicitly.
return { ...datasetQuery, database: databaseId };
}
function withoutOrderBys<TStage extends TestStageSpec>({
orderBys: _orderBys,
...stage
}: TStage) {
return stage;
}
function toStageSpec(input: QueryInput): TestStageWithSourceSpec {
if (!isQuestionInput(input)) {
const { entityId: _entityId, ...stage } = input;
return stage;
}
return {
source: { type: "card", id: getQuestionId(input.source) },
...toResultColumnStageSpec(input),
};
}
/**
* A stage whose dimensions are the previous stage's result columns — a card
* stage or a dynamic stage. Both resolve their columns by name.
*/
function toResultColumnStageSpec({
filters,
aggregations,
breakouts,
orderBys,
limit,
}: DynamicQueryInput): TestStageSpec {
return {
...(filters && { filters: filters.map(toResultColumnExpressionSpec) }),
...(aggregations && {
aggregations: aggregations.map(toResultColumnExpressionSpec),
}),
...(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 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,
...resultColumn
} = spec;
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 {
if (spec.type === "column") {
return toResultColumnSpec(spec);
}
if (spec.type === "operator") {
return { ...spec, args: spec.args?.map(toResultColumnArgSpec) };
}
return spec;
}
function toResultColumnArgSpec(spec: TestOperatorArgSpec): TestOperatorArgSpec {
if (
spec.type === "segment" ||
spec.type === "measure" ||
spec.type === "metric"
) {
return spec;
}
return toResultColumnExpressionSpec(spec);
}
async function loadSourceMetadata(
store: SdkStore,
input: QueryInput,
sourceCard: Card | undefined,
) {
if (isQuestionInput(input)) {
const cardId = getQuestionId(input.source);
await (sourceCard
? loadCardQueryMetadata(store, cardId)
: loadCardMetadata(store, cardId));
return;
}
if (isTableInput(input)) {
await store.dispatch(
fetchTableMetadataAndForeignKeys({ id: input.source.id }),
);
await loadReferencedMetricMetadata(store, input);
}
}
async function loadCardMetadata(store: SdkStore, id: number) {
await Promise.all([
runRtkEndpoint({ id }, store.dispatch, cardApi.endpoints.getCard, {
forceRefetch: false,
}),
loadCardQueryMetadata(store, id),
]);
}
function loadCardQueryMetadata(store: SdkStore, id: number) {
return runRtkEndpoint(
id,
store.dispatch,
cardApi.endpoints.getCardQueryMetadata,
{ forceRefetch: false },
);
}
function getSourceDatabaseId(
input: QueryInput,
state: SdkState,
sourceCard: Card | undefined,
) {
if (isTableInput(input)) {
return getTableDatabaseId(input.source.id, state);
}
if (isQuestionInput(input)) {
const cardId = getQuestionId(input.source);
return getCardDatabaseId(
cardId,
sourceCard ?? selectCard({ id: cardId })(state).data,
);
}
throw new Error("Unable to find database for query source.");
}
// Both sources were awaited by `loadSourceMetadata`, so they are in the RTK
// cache by now.
function getTableDatabaseId(tableId: number, state: SdkState) {
const { data: table } = selectTableQueryMetadata({ id: tableId })(state);
if (typeof table?.db_id === "number") {
return table.db_id;
}
throw new Error(`Unable to find database for table ${tableId}.`);
}
function getCardDatabaseId(cardId: number, card: Card | undefined) {
const databaseId = card?.dataset_query?.database;
if (typeof databaseId === "number") {
return databaseId;
}
throw new Error(`Unable to find database for saved question ${cardId}.`);
}