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.

14.9 KB
Raw Blame
import { match } from 'ts-pattern'

import { EXPERIMENT_DEFAULT_DURATION, FEATURE_FLAGS, FunnelLayout } from 'lib/constants'
import { dayjs } from 'lib/dayjs'
import type { FeatureFlagsSet } from 'lib/logic/featureFlagLogic'
import { isNotNil } from 'lib/utils/guards'
import { objectCleanWithEmpty } from 'lib/utils/objects'
import { MathAvailability } from 'scenes/insights/filters/ActionFilter/ActionFilterRow/types'
import { cleanSeriesNodes } from 'scenes/insights/filters/ActionFilter/cleanSeriesNodes'
import {
    SeriesNode,
    isActionsSeriesNode,
    isEventsSeriesNode,
    isWarehouseSeriesNode,
} from 'scenes/insights/filters/ActionFilter/seriesNode'

import { setLatestVersionsOnQuery } from '~/queries/schema/query-versions'
import type {
    ActionsNode,
    BreakdownFilter,
    DataWarehouseNode,
    DateRange,
    EntityNode,
    EventsNode,
    ExperimentFunnelMetric,
    ExperimentMetric,
    ExperimentMetricSource,
    ExperimentMetricTypeProps,
    ExperimentWarehouseNativeNode,
    FunnelsDataWarehouseNode,
    FunnelsFilter,
    FunnelsQuery,
    InsightVizNode,
    RefreshType,
    TrendsFilter,
    TrendsQuery,
} from '~/queries/schema/schema-general'
import { ExperimentMetricType, ExperimentWarehouseNativeMathType, NodeKind } from '~/queries/schema/schema-general'
import type { IntervalType } from '~/types'
import { ChartDisplayType, ExperimentMetricMathType } from '~/types'

/**
 * We extract all the math properties from the EntityNode type so we can use them as
 * options when creating a query. Tools like the running time calculator have to set
 * math properties for specific elements in the query.
 */
type MathProperties = {
    [K in keyof EntityNode as K extends `math${string}` ? K : never]: EntityNode[K]
}

/**
 * we need a left to right compose function. We won't use right to left
 * because it's counter intuitive for people not familiar with functional programming...
 *
 * this should be extracted into a library...
 */
export function compose<A, B, C>(f1: (a: A) => B, f2: (b: B) => C): (a: A) => C
export function compose<A, B, C, D>(f1: (a: A) => B, f2: (b: B) => C, f3: (c: C) => D): (a: A) => D
export function compose(...fns: Array<(arg: any) => any>): (arg: any) => any {
    return (arg: any) => fns.reduce((acc, fn) => fn(acc), arg)
}

const isEventMetricSource = (source: ExperimentMetricSource): source is EventsNode =>
    source.kind === NodeKind.EventsNode

/**
 * Converts ExperimentMetricSource to the appropriate query node type
 */
const convertSourceToQueryNode = (source: ExperimentMetricSource): EventsNode | ActionsNode | DataWarehouseNode => {
    return match(source)
        .with(
            { kind: NodeKind.EventsNode },
            (event): EventsNode => ({
                kind: NodeKind.EventsNode,
                event: event.event,
                name: event.name,
                properties: event.properties,
            })
        )
        .with(
            { kind: NodeKind.ActionsNode },
            (action): ActionsNode => ({
                kind: NodeKind.ActionsNode,
                id: action.id,
                name: action.name,
                properties: action.properties,
            })
        )
        .with(
            { kind: NodeKind.ExperimentDataWarehouseNode },
            (dataWarehouse): DataWarehouseNode => ({
                kind: NodeKind.DataWarehouseNode,
                id: dataWarehouse.table_name,
                name: dataWarehouse.name,
                table_name: dataWarehouse.table_name,
                timestamp_field: dataWarehouse.timestamp_field,
                distinct_id_field: dataWarehouse.events_join_key,
                id_field: dataWarehouse.data_warehouse_join_key,
            })
        )
        .with({ kind: NodeKind.ExperimentWarehouseNativeNode }, () => {
            throw new Error('Warehouse-native sources cannot be shown as an insight yet')
        })
        .exhaustive()
}

const defaultTrendsFilter: TrendsFilter = {
    display: ChartDisplayType.ActionsLineGraph,
}

const defaultFunnelsFilter: FunnelsFilter = {
    layout: FunnelLayout.horizontal,
}

/**
 * returns the default date range
 */
const getDefaultDateRange = (): DateRange => ({
    date_from: dayjs().subtract(EXPERIMENT_DEFAULT_DURATION, 'day').format('YYYY-MM-DDTHH:mm'),
    date_to: dayjs().endOf('d').format('YYYY-MM-DDTHH:mm'),
    explicitDate: true,
})

/**
 * returns the math properties for the source
 */
export const getMathProperties = (source: ExperimentMetricSource): MathProperties => {
    if (source.kind === NodeKind.ExperimentWarehouseNativeNode) {
        return source.math === ExperimentWarehouseNativeMathType.Sum
            ? { math: ExperimentMetricMathType.Sum, math_property: source.math_property }
            : { math: ExperimentMetricMathType.TotalCount, math_property: undefined }
    }
    if (!source.math || source.math === ExperimentMetricMathType.TotalCount) {
        return { math: ExperimentMetricMathType.TotalCount, math_property: undefined }
    }

    if (source.math === ExperimentMetricMathType.UniqueSessions) {
        return { math: source.math }
    }

    // For Sum, Avg, Min, Max - all require math_property
    return { math: source.math, math_property: source.math_property }
}

type GetQueryOptions = {
    breakdownFilter: BreakdownFilter
    filterTestAccounts: boolean
    trendsFilter: TrendsFilter
    trendsInterval: IntervalType
    funnelsFilter: FunnelsFilter
    funnelsInterval: IntervalType
    dateRange: DateRange
}

/**
 * Returns a complete FunnelQuery | TrendsQuery with strong defaults for the
 * provided ExperimentMetric.
 *
 * This query can be used on Insights like:
 * - Metric Preview
 * - Results Breakdowns
 */
export const getQuery =
    (options?: Partial<GetQueryOptions>) =>
    (metric: ExperimentMetric): FunnelsQuery | TrendsQuery | undefined => {
        /**
         * we get all the options or their defaults. There's no overrides that could
         * cause unexpected effects.
         */
        const {
            breakdownFilter = {},
            filterTestAccounts = true,
            trendsFilter = defaultTrendsFilter,
            trendsInterval = 'day',
            funnelsFilter = defaultFunnelsFilter,
            funnelsInterval = 'day',
            dateRange = getDefaultDateRange(),
        } = options || {}

        return match(metric)
            .with({ metric_type: ExperimentMetricType.MEAN }, (meanMetric) => {
                const source = meanMetric.source

                // Return undefined if this is not an EventsNode and has no math specified
                if (!isEventMetricSource(source) && !source.math) {
                    return undefined
                }
                // An insight cannot read a warehouse-native query
                if (source.kind === NodeKind.ExperimentWarehouseNativeNode) {
                    return undefined
                }

                /**
                 * return a TrendsQuery
                 */
                return setLatestVersionsOnQuery({
                    kind: NodeKind.TrendsQuery,
                    filterTestAccounts,
                    dateRange,
                    interval: trendsInterval,
                    trendsFilter,
                    series: [
                        {
                            ...convertSourceToQueryNode(source),
                            ...getMathProperties(source),
                        },
                    ],
                }) as TrendsQuery
            })
            .with({ metric_type: ExperimentMetricType.FUNNEL }, (funnelMetric) => {
                /**
                 * return a FunnelsQuery
                 */
                return setLatestVersionsOnQuery({
                    kind: NodeKind.FunnelsQuery,
                    filterTestAccounts,
                    // only add breakdownFilter if it's not empty. It has no default value.
                    ...(Object.keys(breakdownFilter).length > 0 ? { breakdownFilter } : {}),
                    dateRange,
                    funnelsFilter,
                    interval: funnelsInterval,
                    series: getFunnelSeries(funnelMetric),
                }) as FunnelsQuery
            })
            .otherwise(() => undefined)
    }

/** Funnel steps carry no math, so only identity, name and properties cross over. */
const getFunnelSeries = (
    funnelMetric: ExperimentFunnelMetric
): (EventsNode | ActionsNode | FunnelsDataWarehouseNode)[] =>
    funnelMetric.series.map((step) =>
        match(step)
            .with({ kind: NodeKind.EventsNode }, (eventStep) =>
                objectCleanWithEmpty({
                    kind: NodeKind.EventsNode as const,
                    event: eventStep.event,
                    name: eventStep.name || eventStep.event || undefined,
                    custom_name: eventStep.custom_name,
                    properties: eventStep.properties,
                })
            )
            .with({ kind: NodeKind.ActionsNode }, (actionStep) =>
                objectCleanWithEmpty({
                    kind: NodeKind.ActionsNode as const,
                    id: actionStep.id,
                    name: actionStep.name || undefined,
                    custom_name: actionStep.custom_name,
                    properties: actionStep.properties,
                })
            )
            .with({ kind: NodeKind.ExperimentDataWarehouseNode }, (dwStep) =>
                objectCleanWithEmpty({
                    kind: NodeKind.FunnelsDataWarehouseNode as const,
                    id: dwStep.table_name,
                    name: dwStep.name || dwStep.table_name,
                    custom_name: dwStep.custom_name,
                    table_name: dwStep.table_name,
                    timestamp_field: dwStep.timestamp_field,
                    id_field: dwStep.data_warehouse_join_key,
                    aggregation_target_field: dwStep.events_join_key,
                    properties: dwStep.properties,
                })
            )
            .exhaustive()
    )

/**
 * The series editor has rows for events, actions and synced warehouse tables only. A
 * warehouse-native source has its own fields in the metric form, so it must never reach this editor.
 */
export function metricSourcesToSeries(sources: ExperimentMetricSource[]): SeriesNode[] {
    return sources.map((source) => {
        if (source.kind === NodeKind.ExperimentWarehouseNativeNode) {
            throw new Error('Warehouse-native sources cannot be edited in the series editor')
        }
        return source
    })
}

/**
 * The picker mirrors a warehouse table's name onto `id`, which `ExperimentDataWarehouseNode` does
 * not accept, so a table keeps only `table_name`. A group has no experiment equivalent and gives null.
 */
/** The sources the series picker can produce. A warehouse-native source has no picker row. */
type PickedMetricSource = Exclude<ExperimentMetricSource, ExperimentWarehouseNativeNode>

const toExperimentSourceNode = (node: SeriesNode): PickedMetricSource | null => {
    if (isEventsSeriesNode(node) || isActionsSeriesNode(node)) {
        return node
    }
    if (isWarehouseSeriesNode(node)) {
        const { id: _id, ...warehouseNode } = node as SeriesNode & { id?: string }
        return { ...warehouseNode, kind: NodeKind.ExperimentDataWarehouseNode } as PickedMetricSource
    }
    return null
}

/**
 * Turns the series a single-source picker emits into a metric source, with total count as the
 * default math. Returns null when the picker holds no event, action or table.
 */
export function seriesToMetricSource(series: SeriesNode[]): PickedMetricSource | null {
    const [node] = cleanSeriesNodes(series.slice(0, 1), MathAvailability.All)
    const source = node ? toExperimentSourceNode(node) : null
    if (source?.kind === NodeKind.EventsNode) {
        // Fall back to `name` when taxonomic selection leaves `event` empty/null.
        return { ...source, event: source.event || source.name }
    }
    return source
}

/**
 * Turns the series the metric picker emits into the part of the metric it edits: the funnel
 * steps, which carry no math, or the mean metric's source.
 */
export function seriesToMetricConfig(
    metricType: ExperimentMetricType,
    series: SeriesNode[]
): ExperimentMetricTypeProps | undefined {
    return match(metricType)
        .with(ExperimentMetricType.FUNNEL, () => {
            const steps = cleanSeriesNodes(series, MathAvailability.None).map(toExperimentSourceNode).filter(isNotNil)
            return steps.length > 0 ? { metric_type: ExperimentMetricType.FUNNEL as const, series: steps } : undefined
        })
        .with(ExperimentMetricType.MEAN, () => {
            const source = seriesToMetricSource(series)
            return source ? { metric_type: ExperimentMetricType.MEAN as const, source } : undefined
        })
        .otherwise(() => undefined)
}

/**
 * we can only add exposure to funnel metrics, that have a series.
 * we may want to add exposure at this stage to process all items in the series
 * together, or make sense sematically
 */
export const addExposureToMetric =
    (exposureEvent: EventsNode | ActionsNode) =>
    (metric: ExperimentMetric): ExperimentMetric =>
        match(metric)
            .with({ metric_type: ExperimentMetricType.FUNNEL }, (funnelMetric) => {
                /**
                 * we add the exposure event node to the funnel metric
                 */
                return {
                    ...funnelMetric,
                    series: [exposureEvent, ...funnelMetric.series],
                }
            })
            .otherwise(() => metric)

type InsightVizNodeOptions = {
    showTable: boolean
    showLastComputation: boolean
    showLastComputationRefresh: boolean
}

/**
 * wraps a query into an InsightVizNode, by adding some default options.
 * this is the format that the Query component expects
 */
export const getInsight =
    (options?: Partial<InsightVizNodeOptions>) =>
    (query: FunnelsQuery | TrendsQuery | undefined): InsightVizNode | undefined => {
        if (!query) {
            return undefined
        }

        const { showTable = false, showLastComputation = false, showLastComputationRefresh = false } = options || {}
        return {
            kind: NodeKind.InsightVizNode,
            source: query,
            showTable,
            showLastComputation,
            showLastComputationRefresh,
        }
    }

// Gated by the experiments-sync-queries flag during rollout. Flag on → run experiment
// queries synchronously in the web request; flag off → legacy Celery/async path.
// Once the flag reaches 100%, inline the sync branch and delete these helpers.
export const getExperimentExecutionMode = (featureFlags: FeatureFlagsSet): 'sync' | 'async' =>
    featureFlags[FEATURE_FLAGS.EXPERIMENTS_SYNC_QUERIES] ? 'sync' : 'async'

export const getExperimentRefreshMode = (featureFlags: FeatureFlagsSet, forceRefresh: boolean): RefreshType => {
    if (getExperimentExecutionMode(featureFlags) === 'sync') {
        return forceRefresh ? 'force_blocking' : 'blocking'
    }
    return forceRefresh ? 'force_async' : 'async'
}