: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
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()
}
}),
])