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 { useReducer, useRef, useState } from "react";
import { useAsyncFn, useUnmount } from "react-use";
import {
loadQuestionSdk,
runQuestionOnNavigateSdk,
runQuestionQuerySdk,
updateQuestionSdk,
} from "embedding-sdk-bundle/lib/sdk-question";
import { useSdkDispatch, useSdkSelector } from "embedding-sdk-bundle/store";
import { setError } from "embedding-sdk-bundle/store/reducer";
import { getIsGuestEmbed } from "embedding-sdk-bundle/store/selectors";
import type {
LoadSdkQuestionParams,
NavigateToNewCardParams,
SdkQuestionState,
SqlParameterValues,
} from "embedding-sdk-bundle/types/question";
import { isAbortError } from "metabase/api/client";
import { isStaticEmbeddingEntityLoadingError } from "metabase/utils/errors/is-static-embedding-entity-loading-error";
import type Question from "metabase-lib/v1/Question";
import type {
ParameterValuesMap,
QueryVisualizationDisplayType,
} from "metabase-types/api";
import type { EntityToken } from "metabase-types/api/entity";
type LoadQuestionResult = Promise<
SdkQuestionState & { originalQuestion?: Question }
>;
export interface LoadQuestionHookResult {
question?: Question;
originalQuestion?: Question;
parameterValues?: ParameterValuesMap;
queryResults?: any[];
isQuestionLoading: boolean;
isQueryRunning: boolean;
queryQuestion(options?: {
ignoreCache?: boolean;
}): Promise<Question | undefined>;
loadAndQueryQuestion(): LoadQuestionResult;
updateQuestion(
question: Question,
options?: { run?: boolean },
): Promise<void>;
updateParameterValues(parameterValues: ParameterValuesMap): Promise<void>;
/**
* Replaces both the question and originalQuestion object directly.
* Unlike updateQuestion, this does not turn the question into an ad-hoc question.
*/
replaceQuestion(question: Question): void;
navigateToNewCard:
| ((params: NavigateToNewCardParams) => Promise<void>)
| null;
}
type UseLoadQuestionParams = LoadSdkQuestionParams & {
isGuestEmbed: boolean;
token: EntityToken | null | undefined;
initialVisualization?: QueryVisualizationDisplayType;
};
export function useLoadQuestion({
questionId,
token,
options,
// Passed when navigating from `InteractiveDashboard` or `EditableDashboard`
deserializedCard,
initialSqlParameters,
targetDashboardId,
initialVisualization,
}: UseLoadQuestionParams): LoadQuestionHookResult {
const dispatch = useSdkDispatch();
// Keep track of the latest question and query results.
// They can be updated from the below actions.
const [questionState, mergeQuestionState] = useReducer(questionReducer, {});
const { question, originalQuestion, queryResults, parameterValues } =
questionState;
const isGuestEmbed = useSdkSelector(getIsGuestEmbed);
/**
* Token change isn't an indicator to re-run the query. When users are refreshing
* the guest embeds token, the token will change, but not questionId. So we can
* rely on questionId that will change the loadAndQueryQuestion value and trigger
* the query again.
*
* As a reference, dashboards don't use this approach. It detects if the
* dashboardId has changed before triggering the query. So, the idea is quite similar.
*/
const tokenRef = useRef(token);
tokenRef.current = token;
const controllerRef = useRef<AbortController>(undefined);
function nextSignal() {
// Cancel the previous query when a new one is started.
controllerRef.current?.abort();
controllerRef.current = new AbortController();
return controllerRef.current.signal;
}
// Cancel the running query when the component unmounts.
useUnmount(() => {
controllerRef.current?.abort();
});
// Avoid re-running the query if the parameters haven't changed.
const sqlParameterKey = getParameterDependencyKey(initialSqlParameters);
const shouldLoadQuestion = questionId != null || deserializedCard != null;
const [isLoadInFlight, setIsLoadInFlight] = useState(shouldLoadQuestion);
const isQuestionLoading = isLoadInFlight || !shouldLoadQuestion;
const [, loadAndQueryQuestion] = useAsyncFn(async () => {
if (!shouldLoadQuestion) {
return {};
}
setIsLoadInFlight(true);
try {
const questionState = await dispatch(
loadQuestionSdk({
options,
deserializedCard,
questionId,
token: tokenRef.current,
initialSqlParameters,
targetDashboardId,
}),
);
mergeQuestionState(questionState);
const results = await runQuestionQuerySdk({
question: questionState.question,
isGuestEmbed,
token: tokenRef.current,
originalQuestion: questionState.originalQuestion,
parameterValues: questionState.parameterValues,
signal: nextSignal(),
dispatch,
initialVisualization,
});
mergeQuestionState(results);
setIsLoadInFlight(false);
return { ...results, originalQuestion };
} catch (err) {
// Ignore cancelled requests (e.g. when the component unmounts, or when a
// controlled `sqlParameters` push cancels the in-flight load query via the
// shared `controllerRef`). React simulates unmounting on strict mode,
// therefore "Question not found" will be shown without this.
if (isAbortError(err)) {
setIsLoadInFlight(false);
return {};
}
if (isStaticEmbeddingEntityLoadingError(err, { isGuestEmbed })) {
dispatch(
setError({
status: err.status,
message: err.data,
}),
);
}
mergeQuestionState({
question: undefined,
originalQuestion: undefined,
queryResults: undefined,
parameterValues: undefined,
});
setIsLoadInFlight(false);
return {};
}
}, [
dispatch,
options,
deserializedCard,
isGuestEmbed,
sqlParameterKey,
questionId,
targetDashboardId,
initialVisualization,
]);
const [runQuestionState, queryQuestion] = useAsyncFn(
async (options?: { ignoreCache?: boolean }) => {
if (!question) {
return;
}
const state = await runQuestionQuerySdk({
question,
isGuestEmbed,
token,
originalQuestion,
parameterValues,
signal: nextSignal(),
dispatch,
ignoreCache: options?.ignoreCache,
});
mergeQuestionState(state);
return state.question;
},
[
dispatch,
question,
isGuestEmbed,
token,
originalQuestion,
parameterValues,
],
);
const [updateQuestionState, updateQuestion] = useAsyncFn(
async (nextQuestion: Question, options: { run?: boolean }) => {
const { run = false } = options ?? {};
if (!question) {
return;
}
const state = await dispatch(
updateQuestionSdk({
nextQuestion,
previousQuestion: question,
originalQuestion,
nextParameterValues: parameterValues ?? {},
signal: nextSignal(),
optimisticUpdateQuestion: (question) =>
mergeQuestionState({ question }),
shouldRunQueryOnQuestionChange: run,
shouldStartAdHocQuestion: true,
isGuestEmbed,
token,
}),
);
mergeQuestionState(state);
},
[
dispatch,
question,
originalQuestion,
parameterValues,
isGuestEmbed,
token,
],
);
const [updateParameterValuesState, updateParameterValues] = useAsyncFn(
async (nextParameterValues: ParameterValuesMap) => {
if (!question) {
return;
}
mergeQuestionState({
parameterValues: nextParameterValues,
});
const state = await dispatch(
updateQuestionSdk({
nextQuestion: question,
previousQuestion: question,
originalQuestion,
nextParameterValues,
signal: nextSignal(),
optimisticUpdateQuestion: (question) =>
mergeQuestionState({ question }),
shouldRunQueryOnQuestionChange: true,
shouldStartAdHocQuestion: false,
isGuestEmbed,
token,
}),
);
mergeQuestionState(state);
},
[
dispatch,
question,
originalQuestion,
parameterValues,
isGuestEmbed,
token,
],
);
const [navigateToNewCardState, navigateToNewCard] = useAsyncFn(
async (params: NavigateToNewCardParams) => {
const state = await dispatch(
runQuestionOnNavigateSdk({
...params,
isGuestEmbed,
token,
originalQuestion,
parameterValues,
signal: nextSignal(),
onQuestionChange: (question) => mergeQuestionState({ question }),
onClearQueryResults: () =>
mergeQuestionState({ queryResults: [null] }),
}),
);
if (!state) {
return;
}
mergeQuestionState(state);
},
[dispatch, originalQuestion, isGuestEmbed, token, parameterValues],
);
const isQueryRunning =
runQuestionState.loading ||
updateQuestionState.loading ||
updateParameterValuesState.loading ||
navigateToNewCardState.loading;
const replaceQuestion = (question: Question) =>
mergeQuestionState({ question, originalQuestion: question });
return {
question,
originalQuestion,
parameterValues,
queryResults,
isQuestionLoading,
isQueryRunning,
queryQuestion,
replaceQuestion,
loadAndQueryQuestion,
updateQuestion,
updateParameterValues,
navigateToNewCard,
};
}
const questionReducer = (state: SdkQuestionState, next: SdkQuestionState) => ({
...state,
...next,
});
export const getParameterDependencyKey = (
parameters?: SqlParameterValues,
): string =>
Object.entries(parameters ?? {})
.sort(([keyA], [keyB]) => keyA.localeCompare(keyB))
.map(([key, value]) => `${key}=${value}`)
.join(":");