Skip to content

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

9.8 KB
Raw Blame
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(":");