Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

21.7 KB
Raw Blame
import { MakeLogicType, actions, afterMount, connect, kea, key, listeners, path, props, selectors } from 'kea'

import { DataColorTheme } from 'lib/colors'
import { dataThemeLogic, getColorFromToken } from 'scenes/dataThemeLogic'

import { NodeKind } from '~/queries/schema/schema-general'
import { ChartDisplayType } from '~/types'

import { getBIResultDimensions } from 'products/business_intelligence/frontend/biEditorTypes'
import { createBIMemberDisplayLookup } from 'products/business_intelligence/frontend/biMemberAliases'
import { getBISeriesSettings } from 'products/business_intelligence/frontend/biQueryResults'

import type { AnyResponseType, ChartSettings, VisualizationNode } from '../../../schema/schema-general'
import { AxisSeries, AxisSeriesSettings, SelectedYAxis, dataVisualizationLogic } from '../dataVisualizationLogic'
import type { Column } from '../dataVisualizationLogic'
import { humanizeEventColumnValue } from '../eventColumnLabels'
import type { SqlChartProps } from './Charts/SqlChart'
import { sqlChartData } from './Charts/sqlLineGraphAdapter'

/**
 * Sentinel used to key result customizations for null / undefined breakdown values.
 * Mirrors `BREAKDOWN_NULL_STRING_LABEL` from `scenes/insights/utils` to keep the
 * collision-resistance contract consistent with trends/funnels breakdowns.
 */
export const BREAKDOWN_NULL_KEY = '$$_posthog_breakdown_null_$$'

export const getBreakdownValueKey = (value: unknown): string =>
    value === null || value === undefined ? BREAKDOWN_NULL_KEY : String(value)

export interface AxisBreakdownSeries<T> {
    name: string
    /** Stable key derived from the raw breakdown column value, used for result customization lookups. */
    breakdownValue: string
    data: T[]
    settings?: AxisSeriesSettings
}

export interface BreakdownSeriesData<T> {
    xData: AxisSeries<string>
    seriesData: AxisBreakdownSeries<T>[]
    isUnaggregated?: boolean
    warning?: string
}

/** Most series we'll render for a single breakdown before the chart becomes unreadable. */
export const MAX_BREAKDOWN_SERIES = 50

/** Short label shown when a breakdown is capped — pairs with the detailed warning below. */
export const BREAKDOWN_LIMIT_LABEL = `Breakdowns are limited to ${MAX_BREAKDOWN_SERIES}`

/** Detailed, count-aware copy shown in the cap's info tooltip. */
export const getBreakdownLimitWarning = (totalValues: number): string =>
    `Showing the top ${MAX_BREAKDOWN_SERIES} breakdown values by total out of ${totalValues}. Refine your query to narrow the breakdown.`

export const EmptyBreakdownSeries: BreakdownSeriesData<number | null> = {
    xData: {
        column: {
            name: 'None',
            type: {
                name: 'INTEGER',
                isNumerical: false,
            },
            label: 'None',
            dataIndex: -1,
        },
        data: [],
    },
    seriesData: [],
}

const parseBreakdownSeriesValue = (value: unknown, selectedYAxis: SelectedYAxis): number | null => {
    if (value === undefined || value === null || Number.isNaN(value)) {
        return null
    }

    try {
        const multiplier = selectedYAxis.settings.formatting?.style === 'percent' ? 100 : 1
        const parsed = Number.isInteger(value)
            ? parseInt(String(value), 10) * multiplier
            : parseFloat(String(value)) * multiplier
        return Number.isNaN(parsed) ? null : parsed
    } catch {
        return null
    }
}

export interface SeriesBreakdownLogicProps {
    key: string
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface seriesBreakdownLogicValues {
    getTheme: (themeId: number | string | null | undefined) => DataColorTheme | null // dataThemeLogic
    chartSettings: ChartSettings // dataVisualizationLogic
    columns: Column[] // dataVisualizationLogic
    effectiveVisualizationType: ChartDisplayType // dataVisualizationLogic
    query: VisualizationNode // dataVisualizationLogic
    response: AnyResponseType | null // dataVisualizationLogic
    selectedXAxis: string | null // dataVisualizationLogic
    selectedYAxis: (SelectedYAxis | null)[] | null // dataVisualizationLogic
    xData: AxisSeries<string> | null // dataVisualizationLogic
    yData: AxisSeries<number | null>[] // dataVisualizationLogic
    breakdownColumnValues: string[]
    chartData: Pick<SqlChartProps, 'xData' | 'yData'>
    selectedSeriesBreakdownColumn: string | null | undefined
    seriesBreakdownData: BreakdownSeriesData<number | null>
    showSeriesBreakdown: boolean
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface seriesBreakdownLogicActions {
    clearAxis: () => {
        value: true
    } // dataVisualizationLogic
    setQuery: (setter: (node: VisualizationNode) => VisualizationNode) => {
        setter: (node: VisualizationNode) => VisualizationNode
    } // dataVisualizationLogic
    addSeriesBreakdown: (columnName: string | null) => {
        columnName: string | null
        response: AnyResponseType | null
    }
    deleteSeriesBreakdown: () => {}
}

// Generated by kea-typegen. Update if you're an agent, ignore if you're human.
export interface seriesBreakdownLogicMeta {
    key: string
    __keaTypeGenInternalSelectorTypes: {
        selectedSeriesBreakdownColumn: (query: VisualizationNode) => string | null | undefined
        showSeriesBreakdown: (selectedSeriesBreakdownColumn: string | null | undefined) => boolean
        breakdownColumnValues: (
            selectedSeriesBreakdownColumn: string | null | undefined,
            response: AnyResponseType | null,
            columns: Column[]
        ) => string[]
        seriesBreakdownData: (
            selectedSeriesBreakdownColumn: string | null | undefined,
            breakdownColumnValues: string[],
            selectedYAxis: (SelectedYAxis | null)[] | null,
            selectedXAxis: string | null,
            response: AnyResponseType | null,
            columns: Column[],
            chartSettings: ChartSettings,
            getTheme: (themeId: number | string | null | undefined) => DataColorTheme | null, // dataThemeLogic
            query: VisualizationNode
        ) => BreakdownSeriesData<number | null>
        chartData: (
            seriesBreakdownData: BreakdownSeriesData<number | null>,
            xData: AxisSeries<string> | null, // dataVisualizationLogic
            yData: AxisSeries<number | null>[], // dataVisualizationLogic
            effectiveVisualizationType: ChartDisplayType // dataVisualizationLogic
        ) => Pick<SqlChartProps, 'xData' | 'yData'>
    }
}

export type seriesBreakdownLogicType = MakeLogicType<
    seriesBreakdownLogicValues,
    seriesBreakdownLogicActions,
    SeriesBreakdownLogicProps,
    seriesBreakdownLogicMeta
>

export const seriesBreakdownLogic = kea<seriesBreakdownLogicType>([
    path(['queries', 'nodes', 'DataVisualization', 'Components', 'seriesBreakdownLogic']),
    key((props) => props.key),
    props({ key: '' } as SeriesBreakdownLogicProps),
    connect(() => ({
        actions: [dataVisualizationLogic, ['clearAxis', 'setQuery']],
        values: [
            dataVisualizationLogic,
            [
                'query',
                'response',
                'columns',
                'selectedXAxis',
                'selectedYAxis',
                'chartSettings',
                'xData',
                'yData',
                'effectiveVisualizationType',
            ],
            dataThemeLogic,
            ['getTheme'],
        ],
    })),
    actions(({ values }) => ({
        addSeriesBreakdown: (columnName: string | null) => ({ columnName, response: values.response }),
        deleteSeriesBreakdown: () => ({}),
    })),
    selectors({
        selectedSeriesBreakdownColumn: [
            (s) => [s.query],
            (query: import('../../../schema').DataVisualizationNode): string | null | undefined => {
                return query?.chartSettings?.seriesBreakdownColumn
            },
        ],
        showSeriesBreakdown: [
            (s) => [s.selectedSeriesBreakdownColumn],
            (selectedSeriesBreakdownColumn: string | null | undefined): boolean =>
                selectedSeriesBreakdownColumn !== undefined,
        ],
        breakdownColumnValues: [
            (s) => [s.selectedSeriesBreakdownColumn, s.response, s.columns],
            (
                breakdownColumn: string | null | undefined,
                response:
                    | Record<string, any>
                    | null
                    | import('../../../schema').ErrorTrackingQueryResponse
                    | import('../../../schema').HogQLAutocompleteResponse
                    | import('../../../schema').HogQLMetadataResponse
                    | import('../../../schema').HogQLQueryResponse<any[]>
                    | import('../../../schema').HogQueryResponse
                    | import('../../../schema').LogAttributesQueryResponse
                    | import('../../../schema').LogValuesQueryResponse
                    | import('../../../schema').MetricsQueryResponse
                    | import('../../../schema').SessionsQueryResponse
                    | import('../../../schema').TraceSpansAggregationQueryResponse
                    | import('../../../schema').TraceSpansAttributeBreakdownQueryResponse
                    | import('../../../schema').TraceSpansQueryResponse,
                columns: import('../dataVisualizationLogic').Column[]
            ): string[] => {
                if (!response || breakdownColumn === null) {
                    return []
                }

                const data = 'results' in response ? response.results : 'result' in response ? response.result : []

                const column = columns.find((n) => n.name === breakdownColumn)
                if (!column) {
                    return []
                }

                // return list of unique column values
                return Array.from(new Set(data.map((n: any) => n[column.dataIndex])))
            },
        ],
        seriesBreakdownData: [
            (s) => [
                s.selectedSeriesBreakdownColumn,
                s.breakdownColumnValues,
                s.selectedYAxis,
                s.selectedXAxis,
                s.response,
                s.columns,
                s.chartSettings,
                s.getTheme,
                s.query,
            ],
            (
                selectedBreakdownColumn: string | null | undefined,
                breakdownColumnValues: string[],
                ySeries: (SelectedYAxis | null)[] | null,
                xSeries: string | null,
                response:
                    | Record<string, any>
                    | null
                    | import('../../../schema').ErrorTrackingQueryResponse
                    | import('../../../schema').HogQLAutocompleteResponse
                    | import('../../../schema').HogQLMetadataResponse
                    | import('../../../schema').HogQLQueryResponse<any[]>
                    | import('../../../schema').HogQueryResponse
                    | import('../../../schema').LogAttributesQueryResponse
                    | import('../../../schema').LogValuesQueryResponse
                    | import('../../../schema').MetricsQueryResponse
                    | import('../../../schema').SessionsQueryResponse
                    | import('../../../schema').TraceSpansAggregationQueryResponse
                    | import('../../../schema').TraceSpansAttributeBreakdownQueryResponse
                    | import('../../../schema').TraceSpansQueryResponse,
                columns: import('../dataVisualizationLogic').Column[],
                chartSettings: import('../../../schema').ChartSettings,
                getTheme: (themeId: string | number | null | undefined) => DataColorTheme | null,
                query: VisualizationNode
            ): BreakdownSeriesData<number | null> => {
                if (
                    !response ||
                    !selectedBreakdownColumn ||
                    ySeries === null ||
                    ySeries.length === 0 ||
                    xSeries === null ||
                    columns === null ||
                    columns.length === 0
                ) {
                    return EmptyBreakdownSeries
                }

                const yAxis = ySeries.filter((n): n is SelectedYAxis => Boolean(n))
                if (!yAxis || !yAxis.length) {
                    return EmptyBreakdownSeries
                }

                const xColumn = columns.find((n) => n.name === xSeries)
                if (!xColumn) {
                    return EmptyBreakdownSeries
                }

                const breakdownColumn = columns.find((n) => n.name === selectedBreakdownColumn)
                if (!breakdownColumn) {
                    return EmptyBreakdownSeries
                }

                const data: any[] =
                    'results' in response && Array.isArray(response.results)
                        ? response.results
                        : 'result' in response && Array.isArray(response.result)
                          ? response.result
                          : []

                const yColumns = yAxis
                    .map((selectedYAxis) => columns.find((n) => n.name === selectedYAxis.name))
                    .filter((column): column is NonNullable<typeof column> => Boolean(column))

                // When there are more breakdown values than we can legibly chart, keep the
                // most significant ones (highest total across the y-series) rather than an
                // arbitrary first-N, and tell the user we capped it.
                let visibleBreakdownValues = breakdownColumnValues
                let warning: string | undefined
                if (breakdownColumnValues.length > MAX_BREAKDOWN_SERIES) {
                    const totalByValue = new Map<unknown, number>()
                    for (const row of data) {
                        const rowTotal = yColumns.reduce((sum, yColumn) => {
                            const numeric = Number(row[yColumn.dataIndex])
                            return Number.isNaN(numeric) ? sum : sum + numeric
                        }, 0)
                        const breakdownValue = row[breakdownColumn.dataIndex]
                        totalByValue.set(breakdownValue, (totalByValue.get(breakdownValue) ?? 0) + rowTotal)
                    }

                    visibleBreakdownValues = [...breakdownColumnValues]
                        .sort((a, b) => (totalByValue.get(b) ?? 0) - (totalByValue.get(a) ?? 0))
                        .slice(0, MAX_BREAKDOWN_SERIES)
                    warning = getBreakdownLimitWarning(breakdownColumnValues.length)
                }

                // xData is unique x values
                const xData = Array.from(new Set(data.map((n) => n[xColumn.dataIndex])))

                const rowsByBreakdown = new Map<unknown, any[]>()
                for (const row of data) {
                    const value = row[breakdownColumn.dataIndex]
                    const rows = rowsByBreakdown.get(value)
                    if (rows) {
                        rows.push(row)
                    } else {
                        rowsByBreakdown.set(value, [row])
                    }
                }

                let isUnaggregated = false

                const multipleYSeries = yAxis.length > 1
                const showNullsAsZero = chartSettings.showNullsAsZero ?? false
                const resultCustomizations = chartSettings.resultCustomizations ?? {}
                const theme = getTheme(undefined)
                const dimension =
                    query.kind === NodeKind.BIVisualizationNode
                        ? getBIResultDimensions(query.config).find(({ column }) => column === breakdownColumn.name)
                        : undefined
                const memberLabel =
                    query.kind === NodeKind.BIVisualizationNode ? createBIMemberDisplayLookup(query.config) : undefined

                const seriesData: AxisBreakdownSeries<number | null>[] = yAxis.flatMap((selectedYAxis) => {
                    const yColumn = columns.find((n) => n.name === selectedYAxis.name)
                    if (!yColumn) {
                        return []
                    }

                    return visibleBreakdownValues.map<AxisBreakdownSeries<number | null>>((value) => {
                        const valueLabel = humanizeEventColumnValue(breakdownColumn.name, value) || '[No value]'
                        const measureLabel = selectedYAxis.settings.display?.label || selectedYAxis.name
                        const alias = dimension ? memberLabel?.(dimension.field, value) : undefined
                        const aliasLabel =
                            alias === undefined ? undefined : multipleYSeries ? `${measureLabel} - ${alias}` : alias
                        const seriesName = multipleYSeries ? `${measureLabel} - ${valueLabel}` : valueLabel
                        const breakdownValue = getBreakdownValueKey(value)
                        const customColorToken = resultCustomizations[breakdownValue]?.color
                        const customColor =
                            resultCustomizations[breakdownValue]?.customColor ??
                            (customColorToken && theme ? getColorFromToken(theme, customColorToken) : undefined)

                        const filteredData = rowsByBreakdown.get(value) ?? []
                        if (filteredData.length === 0) {
                            return {
                                name: seriesName,
                                breakdownValue,
                                data: [],
                                settings: getBISeriesSettings(
                                    query,
                                    customColor ? { display: { color: customColor } } : undefined
                                ),
                            }
                        }

                        const totalsByX = new Map<unknown, number | null>()
                        for (const row of filteredData) {
                            const xValue = row[xColumn.dataIndex]
                            if (totalsByX.has(xValue)) {
                                isUnaggregated = true
                            }
                            const numeric = parseBreakdownSeriesValue(row[yColumn.dataIndex], selectedYAxis)
                            const previous = totalsByX.get(xValue)
                            totalsByX.set(xValue, numeric === null ? (previous ?? null) : (previous ?? 0) + numeric)
                        }

                        // Missing buckets should remain null unless the chart explicitly
                        // requests zero-filling, matching the non-breakdown series path.
                        const dataset = xData.map((xValue) => totalsByX.get(xValue) ?? (showNullsAsZero ? 0 : null))

                        return {
                            name: seriesName,
                            breakdownValue,
                            data: dataset,
                            // we copy supported settings over from the selected
                            // y-axis since we don't support setting these on the
                            // breakdown series at the moment. The y-axis color is not
                            // copied, so each breakdown value gets its own palette color.
                            settings: getBISeriesSettings(query, {
                                formatting: selectedYAxis.settings.formatting,
                                display: {
                                    yAxisPosition: selectedYAxis.settings?.display?.yAxisPosition,
                                    displayType: selectedYAxis.settings?.display?.displayType,
                                    color: customColor,
                                    ...(aliasLabel === undefined ? {} : { label: aliasLabel }),
                                },
                            }),
                        }
                    })
                })

                return {
                    xData: {
                        column: xColumn,
                        data: xData.map((value) =>
                            query.kind === NodeKind.BIVisualizationNode
                                ? value
                                : humanizeEventColumnValue(xColumn.name, value)
                        ),
                    },
                    seriesData,
                    isUnaggregated,
                    warning,
                }
            },
        ],
        chartData: [
            (s) => [s.seriesBreakdownData, s.xData, s.yData, s.effectiveVisualizationType],
            (
                seriesBreakdownData: BreakdownSeriesData<number | null>,
                xData: AxisSeries<string> | null,
                yData: AxisSeries<number | null>[],
                effectiveVisualizationType: ChartDisplayType
            ): Pick<SqlChartProps, 'xData' | 'yData'> =>
                sqlChartData(seriesBreakdownData, xData, yData, effectiveVisualizationType),
        ],
    }),
    listeners(({ actions }) => ({
        addSeriesBreakdown: ({ columnName }) => {
            actions.setQuery((query) => ({
                ...query,
                chartSettings: {
                    ...query.chartSettings,
                    seriesBreakdownColumn: columnName,
                },
            }))
        },
        deleteSeriesBreakdown: () => {
            actions.setQuery((query) => {
                return {
                    ...query,
                    chartSettings: {
                        ...query.chartSettings,
                        seriesBreakdownColumn: undefined,
                    },
                }
            })
        },
    })),
    afterMount(({ actions, values }) => {
        if (values.query.chartSettings?.seriesBreakdownColumn === undefined) {
            actions.deleteSeriesBreakdown()
        }
    }),
])