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 { assoc, assocIn, chain, dissoc, getIn } from "icepick";
import slugg from "slugg";
import _ from "underscore";
import * as Lib from "metabase-lib";
import type Database from "metabase-lib/v1/metadata/Database";
import Metadata from "metabase-lib/v1/metadata/Metadata";
import { getQuestionVirtualTableId } from "metabase-lib/v1/metadata/utils/saved-questions";
import { getCardUiParameters } from "metabase-lib/v1/parameters/utils/cards";
import { getTemplateTagParametersFromCard } from "metabase-lib/v1/parameters/utils/template-tags";
import { InternalQuery } from "metabase-lib/v1/queries/InternalQuery";
import NativeQuery, {
NATIVE_QUERY_TEMPLATE,
} from "metabase-lib/v1/queries/NativeQuery";
import { STRUCTURED_QUERY_TEMPLATE } from "metabase-lib/v1/queries/StructuredQuery";
import type {
Card,
CardCreationType,
CardDashboardInfo,
CardDisplayType,
CardType,
Collection,
CollectionId,
DashCardId,
DashboardId,
DatabaseId,
DatasetData,
DatasetQuery,
Field,
LastEditInfo,
ParameterId,
Parameter as ParameterObject,
ParameterValuesMap,
ResultsMetadata,
TableId,
UserInfo,
VisualizationDisplay,
VisualizationSettings,
} from "metabase-types/api";
import type { Query } from "../query/types";
export type QuestionCreatorOpts = {
cardType?: CardType;
collectionId?: CollectionId;
dashboardId?: DashboardId;
metadata?: Metadata;
parameterValues?: ParameterValuesMap;
name?: string;
display?: CardDisplayType;
visualization_settings?: VisualizationSettings;
dataset_query?: DatasetQuery;
DEPRECATED_RAW_MBQL_type?: "query" | "native";
DEPRECATED_RAW_MBQL_databaseId?: DatabaseId;
DEPRECATED_RAW_MBQL_tableId?: TableId;
};
export type QuestionDashboardProps = {
dashboardId?: DashboardId;
dashcardId?: DashCardId;
};
/**
* This is a wrapper around a question/card object, which may contain one or more Query objects
*/
class Question {
/**
* The plain object presentation of this question, equal to the format that Metabase REST API understands.
* It is called `card` for both historical reasons and to make a clear distinction to this class.
*/
_card: Card;
/**
* The Question wrapper requires a metadata object because the queries it contains (like {@link StructuredQuery})
* need metadata for accessing databases, tables and metrics.
*/
_metadata: Metadata;
/**
* Parameter values mean either the current values of dashboard filters or SQL editor template parameters.
* They are in the grey area between UI state and question state, but having them in Question wrapper is convenient.
*/
_parameterValues: ParameterValuesMap;
private __libQuery: Lib.Query | undefined;
private __libMetadataProvider: Lib.MetadataProvider | undefined;
/**
* Question constructor
*/
constructor(
// This deprecated wrapper is constructed from ~200 call sites with a mix of
// saved cards, unsaved/draft cards, and (in tests) partial card mocks, so the
// card boundary stays loosely typed. Internally it is treated as a `Card`,
// guarding the saved-only fields (id, name, type, ...) where they are read.
card: any,
metadata?: Metadata,
parameterValues?: ParameterValuesMap,
) {
this._card = card;
this._metadata = metadata || new Metadata();
this._parameterValues = parameterValues || {};
}
clone() {
return new Question(this._card, this._metadata, this._parameterValues);
}
metadata(): Metadata {
return this._metadata;
}
card() {
return this._doNotCallSerializableCard();
}
/**
* returns the card but normalizes the dataset_query field.
*/
cardWithNormalizedQuery() {
return {
...this.card(),
dataset_query: Lib.toJsQuery(this.query()),
};
}
_doNotCallSerializableCard() {
return this._card;
}
setCard(card: Card): Question {
const q = this.clone();
q._card = card;
return q;
}
withoutNameAndId() {
return this.setCard(
chain(this.card())
.dissoc("id")
.dissoc("name")
.dissoc("description")
.value(),
);
}
/**
* A question contains either a:
* - StructuredQuery for queries written in MBQL
* - NativeQuery for queries written in data source's native query language
*
* This is just a wrapper object, the data is stored in `this._card.dataset_query` in a format specific to the query type.
*/
_legacyNativeQuery = _.once((): NativeQuery | undefined => {
const datasetQuery = this._card.dataset_query;
if (this.isNative()) {
return new NativeQuery(this, datasetQuery);
}
const isVirtualDashcard = !this._card.id;
// The `dataset_query` is null for questions on a dashboard the user doesn't have access to
if (!isVirtualDashcard) {
const queryType =
datasetQuery != null && "type" in datasetQuery
? datasetQuery.type
: undefined;
console.warn("Unknown query type: " + queryType);
}
});
legacyNativeQuery(): NativeQuery | undefined {
return this._legacyNativeQuery();
}
/**
* Returns a new Question object with an updated query.
* The query is saved to the `dataset_query` field of the Card object.
*/
setLegacyQuery(newQuery: NativeQuery): Question {
if (this._card.dataset_query !== newQuery.datasetQuery()) {
return this.setCard(
assoc(this.card(), "dataset_query", newQuery.datasetQuery()),
);
}
return this;
}
datasetQuery(): DatasetQuery {
return this.card().dataset_query;
}
setDatasetQuery(newDatasetQuery: DatasetQuery): Question {
return this.setCard(assoc(this.card(), "dataset_query", newDatasetQuery));
}
isNative() {
if (
this.datasetQuery() == null ||
InternalQuery.isDatasetQueryType(this.datasetQuery())
) {
return false;
}
const queryInfo = Lib.queryDisplayInfo(this.query());
return queryInfo.isNative;
}
/**
* The visualization type of the question
*/
display(): CardDisplayType {
// `_card.display` is typed `VisualizationDisplay` because `Card` reuses
// `UnsavedCard`, but a Question is never a virtual dashcard, so its display
// is always a renderable `CardDisplayType`.
return (this._card && this._card.display) as CardDisplayType;
}
setDisplay(display: VisualizationDisplay) {
return this.setCard(assoc(this.card(), "display", display));
}
type(): CardType {
return this._card?.type ?? "question";
}
setType(type: CardType) {
return this.setCard(assoc(this.card(), "type", type));
}
isPersisted() {
return this._card && this._card.persisted;
}
setPersisted(isPersisted: boolean) {
return this.setCard(assoc(this.card(), "persisted", isPersisted));
}
setPinned(pinned: boolean) {
return this.setCard(
assoc(this.card(), "collection_position", pinned ? 1 : null),
);
}
setArchived(archived: boolean) {
return this.setCard(assoc(this.card(), "archived", archived));
}
// locking the display prevents auto-selection
lockDisplay(): Question {
return this.setDisplayIsLocked(true);
}
setDisplayIsLocked(locked: boolean): Question {
return this.setCard(assoc(this.card(), "displayIsLocked", locked));
}
displayIsLocked(): boolean {
return this._card?.displayIsLocked ?? false;
}
maybeResetDisplay(
data: DatasetData,
sensibleDisplays: string[],
previousSensibleDisplays: string[] | undefined,
): Question {
const wasSensible =
previousSensibleDisplays == null ||
previousSensibleDisplays.includes(this.display());
const isSensible = sensibleDisplays.includes(this.display());
const shouldUnlock = wasSensible && !isSensible;
const defaultDisplay = this.setDefaultDisplay().display();
let question;
if (isSensible && defaultDisplay === "table") {
// any sensible display is better than the default table display
question = this;
} else if (shouldUnlock && this.displayIsLocked()) {
question = this.setDisplayIsLocked(false).setDefaultDisplay();
} else {
question = this.setDefaultDisplay();
}
return question._maybeSwitchToScalar(data);
}
// Switches display to scalar if the data is 1 row x 1 column
private _maybeSwitchToScalar({ rows, cols }: DatasetData): Question {
const isScalar = ["scalar", "progress", "gauge"].includes(this.display());
const isOneByOne = rows.length === 1 && cols.length === 1;
if (!isScalar && isOneByOne && !this.displayIsLocked()) {
return this.setDisplay("scalar");
}
return this;
}
setDefaultDisplay(): Question {
if (this.displayIsLocked()) {
return this;
}
const query = this.query();
const { display, settings = {} } = Lib.defaultDisplay(query);
return this.setDisplay(display).updateSettings(settings);
}
settings(): VisualizationSettings {
return (this._card && this._card.visualization_settings) || {};
}
setting(settingName: keyof VisualizationSettings, defaultValue = undefined) {
const value = this.settings()[settingName];
return value === undefined ? defaultValue : value;
}
setSettings(settings: VisualizationSettings) {
return this.setCard(assoc(this.card(), "visualization_settings", settings));
}
updateSettings(settings: Partial<VisualizationSettings>) {
return this.setSettings({ ...this.settings(), ...settings });
}
creationType(): CardCreationType | undefined {
return this.card().creationType;
}
/**
* How many filters or other widgets are this question's values used for?
*/
getParameterUsageCount(): number {
return this.card().parameter_usage_count || 0;
}
/**
* Question is valid (as far as we know) and can be executed
*/
canRun(): boolean {
const { isNative } = Lib.queryDisplayInfo(this.query());
return isNative
? (this.legacyNativeQuery()?.canRun() ?? false)
: Lib.canRun(this.query(), this.type());
}
canWrite(): boolean {
return this._card && this._card.can_write;
}
canWriteActions(): boolean {
const database = this.database();
return (
this.canWrite() &&
database != null &&
database.canWrite() &&
database.hasActionsEnabled()
);
}
supportsImplicitActions(): boolean {
const query = this.query();
// we want to check the metadata for the underlying table, not the model
const sourceTableId = Lib.sourceTableOrCardId(query);
const table = this.metadata().table(sourceTableId);
const hasSinglePk =
table?.fields?.filter((field) => field.isPK())?.length === 1;
const { isNative } = Lib.queryDisplayInfo(this.query());
return !isNative && !Lib.hasClauses(query, -1) && hasSinglePk;
}
canAutoRun(): boolean {
const db = this.database();
return (db && db.auto_run_queries) || false;
}
/**
* Visualization drill-through and action widget actions
*
* Although most of these are essentially a way to modify the current query, having them as a part
* of Question interface instead of Query interface makes it more convenient to also change the current visualization
*/
composeQuestion(): Question {
if (!this.isSaved()) {
return this;
}
const metadata = this.metadataProvider();
const tableId = getQuestionVirtualTableId(this.id());
const table = Lib.tableOrCardMetadata(metadata, tableId);
if (!table) {
return this;
}
const query = Lib.queryFromTableOrCardMetadata(metadata, table);
return this.setQuery(query);
}
composeQuestionAdhoc(options: QuestionCreatorOpts = {}): Question {
if (!this.isSaved()) {
return this;
}
const query = this.composeQuestion().query();
return Question.create({
metadata: this.metadata(),
dataset_query: Lib.toJsQuery(query),
...options,
});
}
/**
* A user-defined name for the question
*/
displayName(): string | null | undefined {
return this._card && this._card.name;
}
slug(): string | null | undefined {
return this._card?.name && `${this._card.id}-${slugg(this._card.name)}`;
}
setDisplayName(name: string | null | undefined) {
return this.setCard(assoc(this.card(), "name", name));
}
collection(): Collection | null | undefined {
return this._card?.collection;
}
collectionId(): CollectionId | null | undefined {
return this._card && this._card.collection_id;
}
setCollectionId(collectionId: CollectionId | null | undefined) {
return this.setCard(assoc(this.card(), "collection_id", collectionId));
}
dashboard(): CardDashboardInfo | null {
return this._card.dashboard;
}
dashboardId(): DashboardId | null {
return this._card.dashboard_id;
}
dashboardName(): string | undefined {
return this._card?.dashboard?.name ?? undefined;
}
dashboardCount(): number | null {
return this._card.dashboard_count;
}
setDashboardId(dashboardId: DashboardId | null | undefined) {
return this.setCard(assoc(this.card(), "dashboard_id", dashboardId));
}
id(): number {
return this._card && this._card.id;
}
setId(id: number | undefined): Question {
return this.setCard(assoc(this.card(), "id", id));
}
markDirty(): Question {
return this.setCard(
dissoc(assoc(this.card(), "original_card_id", this.id()), "id"),
);
}
getDashboardProps(): QuestionDashboardProps {
const { dashboardId, dashcardId } = this.card();
return { dashboardId, dashcardId };
}
setDashboardProps({
dashboardId,
dashcardId,
}: QuestionDashboardProps): Question {
const card = chain(this.card())
.assoc("dashboardId", dashboardId)
.assoc("dashcardId", dashcardId)
.value();
return this.setCard(card);
}
description(): string | null {
return this._card && this._card.description;
}
setDescription(description: string | null) {
return this.setCard(assoc(this.card(), "description", description));
}
lastEditInfo(): LastEditInfo | undefined {
return this._card && this._card["last-edit-info"];
}
lastQueryStart() {
return this._card?.last_query_start;
}
isSaved(): boolean {
return !!this.id();
}
publicUUID(): string | null {
return this._card && this._card.public_uuid;
}
database(): Database | null {
const metadata = this.metadata();
const databaseId = this.databaseId();
const database = metadata.database(databaseId);
return database;
}
databaseId(): DatabaseId | null {
const query = this.query();
return Lib.databaseID(query);
}
isArchived(): boolean {
return this._card && this._card.archived;
}
getResultMetadata() {
return this.card().result_metadata ?? [];
}
setResultsMetadata(resultsMetadata: ResultsMetadata | null) {
const metadataColumns = resultsMetadata && resultsMetadata.columns;
return this.setCard({
...this.card(),
result_metadata: metadataColumns,
});
}
setResultMetadataDiff(metadataDiff: Record<string, Partial<Field>>) {
const metadata = this.getResultMetadata();
const newMetadata = metadata.map((column) => {
const columnDiff = metadataDiff[column.name];
return columnDiff ? { ...column, ...columnDiff } : column;
});
return this.setResultsMetadata({ columns: newMetadata });
}
/**
* Returns true if the questions are equivalent (including id, card, and parameters)
*/
isEqual(
other: Question | null | undefined,
{ compareResultsMetadata = true } = {},
) {
if (!other) {
return false;
}
if (this.id() !== other.id()) {
return false;
}
const card = this.card();
const otherCard = other.card();
const areCardsEqual = compareResultsMetadata
? _.isEqual(card, otherCard)
: _.isEqual(
_.omit(card, "result_metadata"),
_.omit(otherCard, "result_metadata"),
);
if (!areCardsEqual) {
return false;
}
if (!_.isEqual(this.parameters(), other.parameters())) {
return false;
}
return true;
}
setParameter(id: ParameterId, parameter: ParameterObject) {
const newParameters = this.parameters().map((oldParameter) =>
oldParameter.id === id ? parameter : oldParameter,
);
return this.setParameters(newParameters);
}
setParameters(parameters: ParameterObject[] | undefined) {
return this.setCard(assoc(this.card(), "parameters", parameters));
}
setParameterValues(parameterValues: ParameterValuesMap = {}) {
const question = this.clone();
question._parameterValues = parameterValues;
return question;
}
private _parameters?: ParameterObject[];
parameters(): ParameterObject[] {
if (this._parameters == null) {
this._parameters = getCardUiParameters(this, this._parameterValues);
}
return this._parameters;
}
// predicate function that determines if the question is "dirty" compared to the given question
isDirtyComparedTo(originalQuestion: Question) {
if (!this.isSaved() && this.canRun() && originalQuestion == null) {
// If it's new, then it's dirty if it is runnable
return true;
} else {
// If it's saved, then it's dirty when the current card doesn't match the last saved version.
// Omit `entity_id` and `dataset_query` as they have randomized idents
const originalCard = originalQuestion?._getValueForComparison();
const currentCard = this._getValueForComparison();
if (!_.isEqual(originalCard, currentCard)) {
return true;
}
return !Lib.areLegacyQueriesEqual(
this.datasetQuery(),
originalQuestion.datasetQuery(),
);
}
}
isDirtyComparedToWithoutParameters(originalQuestion: Question) {
const [a, b] = [this, originalQuestion].map((q) => {
return (
q &&
new Question(q.card(), this.metadata())
.setParameters(
getTemplateTagParametersFromCard(q.card(), q.metadata()),
)
.setDashboardProps({
dashboardId: undefined,
dashcardId: undefined,
})
);
});
return a.isDirtyComparedTo(b);
}
isQueryDirtyComparedTo(originalQuestion: Question) {
return !Lib.areLegacyQueriesEqual(
this.datasetQuery(),
originalQuestion.datasetQuery(),
);
}
// Internal methods
_getValueForComparison(): Record<string, unknown> {
const value: Record<string, unknown> = {
...this._card,
...this._parameterValues,
};
const keys = [
"collection_id",
"dashboard_id",
"dashboardId",
"dashcardId",
"description",
"display",
"name",
"parameters",
"parameterValues",
"type",
"visualization_settings",
];
return Object.fromEntries(
keys.map((key) => [key, value[key] ?? undefined]),
);
}
query(): Query {
if (InternalQuery.isDatasetQueryType(this.datasetQuery())) {
throw new Error("Internal query is not supported by Lib");
}
this.__libQuery ??= Lib.fromJsQuery(
this.metadataProvider(),
this.datasetQuery(),
);
// Helpers for working with the current query from CLJS REPLs.
if (process.env.NODE_ENV === "development") {
window.__lib_metadata = this.__libMetadataProvider;
window.__lib_query = this.__libQuery;
window.Lib = Lib;
}
return this.__libQuery;
}
private metadataProvider(): Lib.MetadataProvider {
this.__libMetadataProvider ??= Lib.metadataProvider(
this.datasetQuery()?.database,
this.metadata(),
);
return this.__libMetadataProvider;
}
setQuery(query: Query): Question {
return this.setDatasetQuery(Lib.toJsQuery(query));
}
generateQueryDescription() {
const query = this.query();
return Lib.suggestedName(query);
}
getModerationReviews() {
return getIn(this, ["_card", "moderation_reviews"]) || [];
}
getCreator(): UserInfo {
return getIn(this, ["_card", "creator"]) || "";
}
getCreatedAt(): string {
return getIn(this, ["_card", "created_at"]) || "";
}
canManageDB(): boolean {
return this.card().can_manage_db || false;
}
/** Applies the template tag parameters from the card to the question. */
applyTemplateTagParameters(): Question {
const { isNative } = Lib.queryDisplayInfo(this.query());
if (!isNative) {
return this;
}
return this.setParameters(
getTemplateTagParametersFromCard(this.card(), this.metadata()),
);
}
/**
* TODO Atte Keinänen 6/13/17: Discussed with Tom that we could use the default Question constructor instead,
* but it would require changing the constructor signature so that `card` is an optional parameter and has a default value
*/
static create({
DEPRECATED_RAW_MBQL_type: type = "query",
DEPRECATED_RAW_MBQL_databaseId: databaseId,
DEPRECATED_RAW_MBQL_tableId: tableId,
collectionId,
dashboardId,
metadata,
parameterValues,
name,
display = "table",
visualization_settings = {},
cardType,
dataset_query = type === "native"
? NATIVE_QUERY_TEMPLATE
: STRUCTURED_QUERY_TEMPLATE,
}: QuestionCreatorOpts = {}) {
// `create` builds an unsaved draft that lacks the fields a saved Card has
// (id, entity_id, name, type, ...). The Question class nevertheless treats
// `_card` as a full Card, so we assert the draft shape here.
let card = {
name,
collection_id: collectionId,
dashboard_id: dashboardId,
display,
visualization_settings,
dataset_query,
type: cardType,
} as Card;
if (type === "native") {
card = assocIn(card, ["parameters"], []);
}
if (tableId != null) {
card = assocIn(card, ["dataset_query", "query", "source-table"], tableId);
}
if (databaseId != null) {
card = assocIn(card, ["dataset_query", "database"], databaseId);
}
return new Question(card, metadata, parameterValues);
}
}
// eslint-disable-next-line import/no-default-export -- deprecated usage
export default Question;