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.

23.7 KB
Raw Blame
import { RETENTION_FIRST_OCCURRENCE_MATCHING_FILTERS, RETENTION_RECURRING } from 'lib/constants'
import { SummaryContext, summarizeInsight } from 'scenes/insights/summarizeInsight'

import { Noun } from '~/models/groupsModel'
import {
    DataTableNode,
    FunnelsQuery,
    InsightVizNode,
    LifecycleQuery,
    NodeKind,
    PathsQuery,
    PathsV2AnchorType,
    PathsV2Query,
    RetentionQuery,
    StickinessQuery,
    TrendsQuery,
} from '~/queries/schema/schema-general'
import {
    BaseMathType,
    CohortType,
    CountPerActorMathType,
    FilterLogicalOperator,
    GroupMathType,
    PathType,
    PropertyMathType,
} from '~/types'

import {
    BASE_MATH_DEFINITIONS,
    COUNT_PER_ACTOR_MATH_DEFINITIONS,
    HOGQL_MATH_DEFINITIONS,
    MathCategory,
    MathDefinition,
    PROPERTY_MATH_DEFINITIONS,
} from 'products/product_analytics/frontend/insights/trends/mathsLogic'

const aggregationLabel = (groupTypeIndex: number | null | undefined): Noun =>
    groupTypeIndex != undefined
        ? {
              singular: 'organization',
              plural: 'organizations',
          }
        : { singular: 'user', plural: 'users' }
const cohortIdsMapped: Partial<Record<CohortType['id'], CohortType>> = {
    1: {
        id: 1,
        name: 'Poles',
        filters: { properties: { id: '1', type: FilterLogicalOperator.Or, values: [] } },
        groups: [],
    },
}
const mathDefinitions: Record<string, MathDefinition> = {
    ...BASE_MATH_DEFINITIONS,
    'unique_group::0': {
        name: 'Unique organizations',
        shortName: 'unique organizations',
        description: 'Foo.',
        category: MathCategory.ActorCount,
    },
    ...PROPERTY_MATH_DEFINITIONS,
    ...COUNT_PER_ACTOR_MATH_DEFINITIONS,
    ...HOGQL_MATH_DEFINITIONS,
}

const summaryContext: SummaryContext = {
    aggregationLabel,
    cohortsById: cohortIdsMapped,
    mathDefinitions,
}

describe('summarizing insights', () => {
    describe('summariseInsightQuery()', () => {
        it('summarizes a Trends insight with four event and actor count series', () => {
            const query: TrendsQuery = {
                kind: NodeKind.TrendsQuery,
                series: [
                    {
                        kind: NodeKind.EventsNode,
                        event: '$pageview',
                        name: '$pageview',
                        math: BaseMathType.UniqueUsers,
                    },
                    {
                        kind: NodeKind.EventsNode,
                        event: '$rageclick',
                        name: '$rageclick',
                        math: BaseMathType.MonthlyActiveUsers,
                    },
                    {
                        kind: NodeKind.ActionsNode,
                        id: 1,
                        name: 'Random action',
                        math: BaseMathType.TotalCount,
                    },
                    {
                        kind: NodeKind.EventsNode,
                        event: '$pageview',
                        name: '$pageview',
                        math: GroupMathType.UniqueGroup,
                        math_group_type_index: 0,
                    },
                    {
                        kind: NodeKind.EventsNode,
                        event: '$autocapture',
                        name: '$autocapture',
                        math: GroupMathType.UniqueGroup,
                        math_group_type_index: 4, // Non-existent group
                    },
                ],
            }

            const result = summarizeInsight(
                { kind: NodeKind.InsightVizNode, source: query } as InsightVizNode,
                summaryContext
            )

            expect(result).toEqual(
                'Pageview unique users & Rageclick MAUs & Random action count & Pageview unique organizations & Autocapture unique groups'
            )
        })

        it('summarizes a Trends insight with two property value and event count per actor series', () => {
            const query: TrendsQuery = {
                kind: NodeKind.TrendsQuery,
                series: [
                    {
                        kind: NodeKind.ActionsNode,
                        id: 1,
                        name: 'Random action',
                        math: CountPerActorMathType.Average,
                    },
                    {
                        kind: NodeKind.EventsNode,
                        event: 'purchase',
                        name: 'purchase',
                        math: PropertyMathType.Sum,
                        math_property: 'price',
                    },
                ],
            }

            const result = summarizeInsight(
                { kind: NodeKind.InsightVizNode, source: query } as InsightVizNode,
                summaryContext
            )

            expect(result).toEqual("Random action count per user average & purchase's price sum")
        })

        it('summarizes a Trends insight with no series', () => {
            const query: TrendsQuery = {
                kind: NodeKind.TrendsQuery,
                series: [],
            }

            const result = summarizeInsight(
                { kind: NodeKind.InsightVizNode, source: query } as InsightVizNode,
                summaryContext
            )

            expect(result).toEqual('')
        })

        it('summarizes a Trends insight with event property breakdown', () => {
            const query: TrendsQuery = {
                kind: NodeKind.TrendsQuery,
                series: [
                    {
                        kind: NodeKind.EventsNode,
                        event: '$pageview',
                        name: '$pageview',
                        math: BaseMathType.UniqueUsers,
                    },
                ],
                breakdownFilter: {
                    breakdown_type: 'event',
                    breakdown: '$browser',
                },
            }

            const result = summarizeInsight(
                { kind: NodeKind.InsightVizNode, source: query } as InsightVizNode,
                summaryContext
            )

            expect(result).toEqual("Pageview unique users by event's Browser")
        })

        it('summarizes a Trends insight with cohort breakdown', () => {
            const query: TrendsQuery = {
                kind: NodeKind.TrendsQuery,
                series: [
                    {
                        kind: NodeKind.EventsNode,
                        event: '$pageview',
                        name: '$pageview',
                    },
                    {
                        kind: NodeKind.EventsNode,
                        event: '$pageview',
                        name: '$pageview',
                        math: BaseMathType.UniqueUsers,
                    },
                ],
                breakdownFilter: {
                    breakdown_type: 'cohort',
                    breakdown: ['all', 1],
                },
            }

            const result = summarizeInsight(
                { kind: NodeKind.InsightVizNode, source: query } as InsightVizNode,
                summaryContext
            )

            expect(result).toEqual('Pageview count & Pageview unique users, by cohorts: all users, Poles')
        })

        it('summarizes a Trends insight with a formula', () => {
            const query: TrendsQuery = {
                kind: NodeKind.TrendsQuery,
                series: [
                    {
                        kind: NodeKind.EventsNode,
                        event: '$pageview',
                        name: '$pageview',
                        math: BaseMathType.UniqueUsers,
                    },
                    {
                        kind: NodeKind.ActionsNode,
                        id: 1,
                        name: 'Random action',
                        math: BaseMathType.TotalCount,
                    },
                ],
                trendsFilter: {
                    formula: '(A + B) / 100',
                },
            }

            const result = summarizeInsight(
                { kind: NodeKind.InsightVizNode, source: query } as InsightVizNode,
                summaryContext
            )

            expect(result).toEqual('(A + B) / 100 on A. Pageview unique users & B. Random action count')
        })

        it('does not prefix with an empty formula node label', () => {
            const query: TrendsQuery = {
                kind: NodeKind.TrendsQuery,
                series: [
                    {
                        kind: NodeKind.EventsNode,
                        event: '$pageview',
                        name: '$pageview',
                        math: BaseMathType.TotalCount,
                    },
                ],
                trendsFilter: {
                    formulaNodes: [{ formula: '', custom_name: '' }],
                },
            }

            const result = summarizeInsight(
                { kind: NodeKind.InsightVizNode, source: query } as InsightVizNode,
                summaryContext
            )

            expect(result).toEqual('Pageview count')
        })

        it('summarizes a user-based Funnels insight with 3 steps', () => {
            const query: FunnelsQuery = {
                kind: NodeKind.FunnelsQuery,
                series: [
                    {
                        kind: NodeKind.EventsNode,
                        event: '$pageview',
                        name: '$pageview',
                    },
                    {
                        kind: NodeKind.EventsNode,
                        event: 'random_event',
                        name: 'random_event',
                    },
                    {
                        kind: NodeKind.ActionsNode,
                        id: 1,
                        name: 'Random action',
                    },
                ],
            }

            const result = summarizeInsight(
                { kind: NodeKind.InsightVizNode, source: query } as InsightVizNode,
                summaryContext
            )

            expect(result).toEqual('Pageview → random_event → Random action user conversion rate')
        })

        it('summarizes an organization-based Funnels insight with 2 steps and a breakdown', () => {
            const query: FunnelsQuery = {
                kind: NodeKind.FunnelsQuery,
                series: [
                    {
                        kind: NodeKind.EventsNode,
                        event: '$pageview',
                        name: '$pageview',
                    },
                    {
                        kind: NodeKind.EventsNode,
                        event: 'random_event',
                        name: 'random_event',
                    },
                ],
                aggregation_group_type_index: 0,
                breakdownFilter: {
                    breakdown_type: 'person',
                    breakdown: 'some_prop',
                },
            }

            const result = summarizeInsight(
                { kind: NodeKind.InsightVizNode, source: query } as InsightVizNode,
                summaryContext
            )

            expect(result).toEqual("Pageview → random_event organization conversion rate by person's some_prop")
        })

        it('summarizes a user first-time Retention insight with the same event for cohortizing and returning', () => {
            const query: RetentionQuery = {
                kind: NodeKind.RetentionQuery,
                retentionFilter: {
                    targetEntity: {
                        id: '$autocapture',
                        name: '$autocapture',
                        type: 'events',
                    },
                    returningEntity: {
                        id: '$autocapture',
                        name: '$autocapture',
                        type: 'events',
                    },
                    retentionType: RETENTION_FIRST_OCCURRENCE_MATCHING_FILTERS,
                },
            }

            const result = summarizeInsight(
                { kind: NodeKind.InsightVizNode, source: query } as InsightVizNode,
                summaryContext
            )

            expect(result).toEqual(
                'Retention of users based on doing Autocapture first occurrence matching filters and returning with the same event'
            )
        })

        it('summarizes an organization recurring Retention insight with the different events for cohortizing and returning', () => {
            const query: RetentionQuery = {
                kind: NodeKind.RetentionQuery,
                retentionFilter: {
                    targetEntity: {
                        id: 'purchase',
                        name: 'purchase',
                        type: 'events',
                    },
                    returningEntity: {
                        id: '$pageview',
                        name: '$pageview',
                        type: 'events',
                    },
                    retentionType: RETENTION_RECURRING,
                },
                aggregation_group_type_index: 0,
            }

            const result = summarizeInsight(
                { kind: NodeKind.InsightVizNode, source: query } as InsightVizNode,
                summaryContext
            )

            expect(result).toEqual(
                'Retention of organizations based on doing purchase recurringly and returning with Pageview'
            )
        })

        it('summarizes a Paths insight based on all events', () => {
            const query: PathsQuery = {
                kind: NodeKind.PathsQuery,
                pathsFilter: {
                    includeEventTypes: [PathType.PageView, PathType.Screen, PathType.CustomEvent],
                },
            }

            const result = summarizeInsight(
                { kind: NodeKind.InsightVizNode, source: query } as InsightVizNode,
                summaryContext
            )

            expect(result).toEqual('User paths based on all events')
        })

        it('summarizes a Paths insight based on all events (empty includeEventTypes case)', () => {
            const query: PathsQuery = {
                kind: NodeKind.PathsQuery,
                pathsFilter: {
                    includeEventTypes: [],
                },
            }

            const result = summarizeInsight(
                { kind: NodeKind.InsightVizNode, source: query } as InsightVizNode,
                summaryContext
            )

            expect(result).toEqual('User paths based on all events')
        })

        it('summarizes a Paths insight based on pageviews with start and end points', () => {
            const query: PathsQuery = {
                kind: NodeKind.PathsQuery,
                pathsFilter: {
                    includeEventTypes: [PathType.PageView],
                    startPoint: '/landing-page',
                    endPoint: '/basket',
                },
            }

            const result = summarizeInsight(
                { kind: NodeKind.InsightVizNode, source: query } as InsightVizNode,
                summaryContext
            )

            expect(result).toEqual('User paths based on page views starting at /landing-page and ending at /basket')
        })

        it.each([
            ['absent step sources (runner default)', undefined, 'Journeys based on page views'],
            [
                'a matching preset',
                { stepSources: [{ event: '$screen', namingProperty: '$screen_name' }] },
                'Journeys based on screen views',
            ],
            [
                'custom step sources',
                { stepSources: [{ event: '$pageview', namingProperty: '$pathname' }, { event: 'purchase' }] },
                'Journeys based on Pageview and purchase',
            ],
            [
                'a start anchor',
                {
                    anchor: {
                        type: PathsV2AnchorType.Start,
                        item: { event: '$pageview', label: '/landing-page' },
                    },
                },
                'Journeys based on page views starting at /landing-page',
            ],
            [
                'an end anchor with an empty label',
                {
                    anchor: { type: PathsV2AnchorType.End, item: { event: '$pageview', label: '' } },
                },
                'Journeys based on page views ending at (empty)',
            ],
        ] as [string, PathsV2Query['pathsV2Filter'], string][])(
            'summarizes a Journeys insight with %s',
            (_name, pathsV2Filter, expected) => {
                const query: PathsV2Query = { kind: NodeKind.PathsV2Query, pathsV2Filter }

                const result = summarizeInsight(
                    { kind: NodeKind.InsightVizNode, source: query } as InsightVizNode,
                    summaryContext
                )

                expect(result).toEqual(expected)
            }
        )

        it('summarizes a Stickiness insight with a user-based series and an organization-based one', () => {
            const query: StickinessQuery = {
                kind: NodeKind.StickinessQuery,
                series: [
                    {
                        kind: NodeKind.ActionsNode,
                        id: 1,
                        name: 'Random action',
                        math_group_type_index: 0,
                    },
                    {
                        kind: NodeKind.EventsNode,
                        event: '$pageview',
                        name: '$pageview',
                    },
                ],
            }

            const result = summarizeInsight(
                { kind: NodeKind.InsightVizNode, source: query } as InsightVizNode,
                summaryContext
            )

            expect(result).toEqual('Organization stickiness based on Random action & user stickiness based on Pageview')
        })

        it('summarizes a Lifecycle insight', () => {
            const query: LifecycleQuery = {
                kind: NodeKind.LifecycleQuery,
                series: [
                    {
                        kind: NodeKind.EventsNode,
                        event: '$rageclick',
                        name: '$rageclick',
                    },
                ],
            }

            const result = summarizeInsight(
                { kind: NodeKind.InsightVizNode, source: query } as InsightVizNode,
                summaryContext
            )

            expect(result).toEqual('User lifecycle based on Rageclick')
        })

        it('summarizes a Lifecycle insight with groups', () => {
            const query: LifecycleQuery = {
                kind: NodeKind.LifecycleQuery,
                series: [
                    {
                        kind: NodeKind.EventsNode,
                        event: '$rageclick',
                        name: '$rageclick',
                    },
                ],
                aggregation_group_type_index: 0,
            }

            const result = summarizeInsight(
                { kind: NodeKind.InsightVizNode, source: query } as InsightVizNode,
                summaryContext
            )

            expect(result).toEqual('Organization lifecycle based on Rageclick')
        })
    })

    describe('summarize data table query', () => {
        it('summarizes a simple query', () => {
            const query: DataTableNode = {
                kind: NodeKind.DataTableNode,
                source: {
                    kind: NodeKind.EventsQuery,
                    select: ['event'],
                },
            }

            const result = summarizeInsight(query, summaryContext)

            expect(result).toEqual('event from events')
        })

        it('summarizes a two column events query', () => {
            const query: DataTableNode = {
                kind: NodeKind.DataTableNode,
                source: {
                    kind: NodeKind.EventsQuery,
                    select: ['event', 'timestamp'],
                },
            }

            const result = summarizeInsight(query, summaryContext)

            expect(result).toEqual('event, timestamp from events')
        })

        it('summarizes using columns from top-level query', () => {
            const query: DataTableNode = {
                kind: NodeKind.DataTableNode,
                columns: ['event'],
                source: {
                    kind: NodeKind.EventsQuery,
                    select: ['event', 'timestamp'],
                },
            }

            const result = summarizeInsight(query, summaryContext)

            expect(result).toEqual('event from events')
        })

        it('summarizes using hiddencolumns from top-level query', () => {
            const query: DataTableNode = {
                kind: NodeKind.DataTableNode,
                hiddenColumns: ['event'],
                source: {
                    kind: NodeKind.EventsQuery,
                    select: ['event', 'timestamp'],
                },
            }

            const result = summarizeInsight(query, summaryContext)

            expect(result).toEqual('timestamp from events')
        })

        it('summarizes a count table', () => {
            const query: DataTableNode = {
                kind: NodeKind.DataTableNode,
                full: true,
                source: {
                    kind: NodeKind.EventsQuery,
                    select: ['count()'],
                },
            }
            const result = summarizeInsight(query, summaryContext)

            expect(result).toEqual('count() from events')
        })

        it('avoids summarizing SQL query', () => {
            const query: DataTableNode = {
                kind: NodeKind.DataTableNode,
                full: true,
                source: {
                    kind: NodeKind.HogQLQuery,
                    query: 'select event,\n          person.properties.email from events\n  where timestamp > now() - interval 1 day',
                },
            }

            const result = summarizeInsight(query, summaryContext)

            expect(result).toEqual('SQL query')
        })

        it('summarizes a person query', () => {
            const query: DataTableNode = {
                kind: NodeKind.DataTableNode,
                columns: ['person', 'id', 'created_at', 'person.$delete'],
                source: {
                    kind: NodeKind.PersonsNode,
                },
            }
            const result = summarizeInsight(query, summaryContext)

            expect(result).toEqual('person, id, created_at, person.$delete from persons')
        })

        it('summarizes a Trends insight with multiple breakdowns', () => {
            const query: TrendsQuery = {
                kind: NodeKind.TrendsQuery,
                series: [
                    {
                        kind: NodeKind.EventsNode,
                        event: '$pageview',
                        name: '$pageview',
                        math: BaseMathType.UniqueUsers,
                    },
                ],
                breakdownFilter: {
                    breakdowns: [
                        {
                            type: 'event',
                            property: '$browser',
                        },
                        {
                            type: 'person',
                            property: 'custom_prop',
                        },
                        {
                            type: 'session',
                            property: '$session_duration',
                        },
                    ],
                },
            }

            const result = summarizeInsight(
                { kind: NodeKind.InsightVizNode, source: query } as InsightVizNode,
                summaryContext
            )

            expect(result).toEqual(
                "Pageview unique users by event's Browser, person's custom_prop, session's Session duration"
            )
        })
    })
})