Key Driver Analysis

Key Driver Analysis finds the attribute values that explain a change in a measure between two periods: which regions, products, or channels moved revenue the most, and in which direction. It’s a GoodData Cloud feature in beta, described in Key Driver Analysis in the GoodData Cloud documentation. GoodData.UI doesn’t add a standalone component for it. The analysis surfaces inside two components you may already embed, and the Dashboard component announces it through events you can listen to.

Where it appears

Both run the analysis on your GoodData Cloud instance and render the result. In the AI Assistant, the analysis dialog is the public GenAiKeyDriverAnalysis component. GoodData.UI has no public hook or backend method for running Key Driver Analysis yourself: the service interface is @internal, so it can change in any release.

What a dashboard needs

The Dashboard component adds Run Key Driver Analysis to a data point’s drill menu on its own, next to the drill-downs and other interactions the dashboard author configured. The entry appears when all of the following hold:

• AI features are enabled for the organization and the workspace, and the user may use the AI Assistant in that workspace. The Dashboard component reads this from the workspace settings it loads at startup.
• The visualization is sliced by exactly one date attribute, with a granularity the analysis supports: year, quarter, month, week, day, hour, or minute.
• The measure is allowed for Key Driver Analysis. Analytics builders can switch it off per measure in the Analytics Catalog (Use for Key driver analysis) and per visualization in Analyze. Objects a builder excluded carry isHiddenFromKda: true when you read them from the catalog.
• The visualization type supports it. Headlines don’t.

The menu offers one entry per comparison the clicked point allows, such as against the previous period or against the same period a year earlier. Which attributes the analysis considers, and how the result is ranked, is configured on the GoodData Cloud side.

Listen to the analysis on a dashboard

The Dashboard component fires two @beta events around the analysis. Both carry the drill definition and the IDashboardDrillEvent of the click that started it, so you know which widget and which measure the user asked about.

Register a handler the same way as for any other dashboard event, through the eventHandlers prop or from a plugin. Handle dashboard events explains both.

import {
    type DashboardEventHandler,
    type IDashboardKeyDriverAnalysisRequested,
    isDashboardKeyDriverAnalysisRequested,
} from "@gooddata/sdk-ui-dashboard";

export const trackKeyDriverAnalysis: DashboardEventHandler<IDashboardKeyDriverAnalysisRequested> = {
    eval: isDashboardKeyDriverAnalysisRequested,
    handler: (event) => {
        const { widgetRef, drillContext } = event.payload.drillEvent;
        // widgetRef: the widget the user clicked
        // drillContext.intersection: the measure and attribute values of the clicked point
    },
};

The payloads also include the analysis parameters themselves, but those types are @internal and not part of the public API.

The drill definition in the model

In @gooddata/sdk-model, Key Driver Analysis is a drill type like drill-down or cross-filtering: IKeyDriveAnalysis with type: "keyDriveAnalysis" is one of the InsightDrillDefinition variants, and isKeyDriveAnalysis narrows to it. You’ll meet it in the drillDefinitions of a dashboard drill event. You don’t configure it on a widget yourself. The Dashboard component derives it from the conditions above.

API maturity

The events, their type guards, and the IKeyDriveAnalysis type are the public surface. Everything else that mentions Key Driver Analysis in the API reference, such as the KdaDialog component, the key-driver combination items, and the backend service, is @internal or @alpha. See API maturity for what that means for your code.