: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 { z } from 'zod'
// Common enums and types
const NodeKind = z.enum(['TrendsQuery', 'FunnelsQuery', 'PathsQuery', 'HogQLQuery', 'EventsNode'])
const IntervalType = z.enum(['hour', 'day', 'week', 'month'])
const ChartDisplayType = z.enum([
'ActionsLineGraph',
'ActionsTable',
'ActionsPie',
'ActionsBar',
'ActionsStackedBar',
'ActionsAreaGraph',
'ActionsBarValue',
'WorldMap',
'BoldNumber',
'TwoDimensionalHeatmap',
])
// NOTE: Breakdowns are restricted to either person or event for simplicity
const BreakdownType = z.enum(['person', 'event'])
const FunnelVizType = z.enum(['steps', 'time_to_convert', 'trends'])
const FunnelOrderType = z.enum(['ordered', 'unordered', 'strict'])
const FunnelStepReference = z.enum(['total', 'previous'])
const BreakdownAttributionType = z.enum(['first_touch', 'last_touch', 'all_events'])
const FunnelLayout = z.enum(['horizontal', 'vertical'])
const FunnelConversionWindowTimeUnit = z.enum(['minute', 'hour', 'day', 'week', 'month'])
// Base schemas
const DateRange = z.object({
date_from: z.string().nullable().optional(),
date_to: z.string().nullable().optional(),
explicitDate: z.boolean().optional(),
})
const PropertyFilter = z.object({
key: z.string(),
value: z
.union([z.string(), z.number(), z.array(z.string()), z.array(z.number())])
.nullable()
.optional(),
operator: z.string().optional(),
type: z.string().optional(),
})
// NOTE: Only a single level of nesting is supported here, since we can't specify recursive schema for tool inputs.
const PropertyGroupFilter = z.object({
type: z.enum(['AND', 'OR']),
values: z.array(PropertyFilter),
})
const AnyPropertyFilter = z.union([PropertyFilter, PropertyGroupFilter])
const HogQLVariable = z.object({
variableId: z.string(),
code_name: z.string(),
value: z.any().optional(),
isNull: z.boolean().optional(),
})
const HogQLFilters = z.object({
properties: z.array(AnyPropertyFilter).optional(),
dateRange: DateRange.optional(),
filterTestAccounts: z.boolean().optional(),
})
const ChartAxis = z.object({
column: z.string().describe('Name of a column returned by the SQL query.'),
settings: z
.object({
formatting: z
.object({
style: z.enum(['none', 'number', 'short', 'percent']).optional(),
decimalPlaces: z.number().optional(),
prefix: z.string().optional(),
suffix: z.string().optional(),
})
.optional()
.describe('Display formatting for this axis, such as percent, decimals, prefix, or suffix.'),
display: z
.object({
label: z.string().optional(),
displayType: z.enum(['auto', 'line', 'bar', 'area']).optional(),
yAxisPosition: z.enum(['left', 'right']).optional(),
})
.optional(),
})
.optional(),
})
const ChartSettings = z.object({
xAxis: ChartAxis.optional().describe('Column used as the X axis, usually a time bucket or category.'),
yAxis: z
.array(ChartAxis)
.optional()
.describe(
'Numeric columns plotted as Y series. Include only final metrics the user cares about, not helper columns such as numerators or denominators.'
),
seriesBreakdownColumn: z
.string()
.nullable()
.optional()
.describe('Column that splits a single Y metric into multiple colored series.'),
showLegend: z.boolean().optional(),
showNullsAsZero: z.boolean().optional(),
stackBars100: z.boolean().optional(),
})
const TableSettings = z.object({
columns: z.array(ChartAxis).optional().describe('Columns to display and their order.'),
pinnedColumns: z.array(z.string()).optional(),
transpose: z.boolean().optional(),
})
// Math types that don't require a property
const BaseMathType = z.enum([
'total',
'dau',
'weekly_active',
'monthly_active',
'unique_session',
'first_time_for_user',
'first_matching_event_for_user',
])
// Math types that require a math_property
const PropertyMathType = z.enum(['avg', 'sum', 'min', 'max', 'median', 'p75', 'p90', 'p95', 'p99'])
// Combined math types
const MathType = z.union([BaseMathType, PropertyMathType])
const PROPERTY_MATH_TYPES = ['avg', 'sum', 'min', 'max', 'median', 'p75', 'p90', 'p95', 'p99']
// Base entity object without refinement for extension
const BaseEntityObject = z.object({
custom_name: z.string().describe('A display name'),
math: MathType.optional(),
math_property: z.string().optional(),
properties: z.union([z.array(AnyPropertyFilter), PropertyGroupFilter]).optional(),
})
const EventsNode = BaseEntityObject.extend({
kind: z.literal('EventsNode'),
event: z.string().optional(),
limit: z.number().optional(),
}).refine(
(data) => {
if (PROPERTY_MATH_TYPES.includes(data.math || '')) {
return !!data.math_property
}
return true
},
{
message: `math_property is required for ${PROPERTY_MATH_TYPES.join(', ')} math types`,
}
)
const AnyEntityNode = EventsNode
// Base query interface
const InsightsQueryBase = z.object({
dateRange: DateRange.optional(),
// No hard default: omission lets the project's "Filter out internal and test
// users" default setting apply, matching UI behavior for new insights.
filterTestAccounts: z.boolean().optional(),
properties: z
.union([z.array(AnyPropertyFilter), PropertyGroupFilter])
.optional()
.default([]),
})
// Breakdown filter
const BreakdownFilter = z.object({
breakdown_type: BreakdownType.nullable().optional().default('event'),
breakdown_limit: z.number().optional(),
breakdown: z
.union([z.string(), z.number(), z.array(z.union([z.string(), z.number()]))])
.nullable()
.optional(),
})
// Compare filter
const CompareFilter = z.object({
compare: z.boolean().optional().default(false),
compare_to: z.string().optional(),
})
// Trends filter
const TrendsFilter = z.object({
display: ChartDisplayType.optional().default('ActionsLineGraph'),
showLegend: z.boolean().optional().default(false),
})
// Trends query
const TrendsQuerySchema = InsightsQueryBase.extend({
kind: z.literal('TrendsQuery'),
interval: IntervalType.optional().default('day'),
series: z.array(AnyEntityNode),
trendsFilter: TrendsFilter.optional(),
breakdownFilter: BreakdownFilter.optional(),
compareFilter: CompareFilter.optional(),
conversionGoal: z.any().nullable().optional(),
})
// HogQL query
const HogQLQuerySchema = z.object({
kind: z.literal('HogQLQuery'),
query: z.string(),
filters: HogQLFilters.optional(),
connectionId: z
.string()
.optional()
.describe(
'Optional id of an external data source (e.g. a Postgres or DuckDB direct-query connection). When set, the query runs against that source instead of ClickHouse. Use external-data-sources-connections-list to discover available connection ids.'
),
})
// Funnels filter
const FunnelsFilter = z.object({
layout: FunnelLayout.optional(),
breakdownAttributionType: BreakdownAttributionType.optional(),
breakdownAttributionValue: z.number().optional(),
funnelToStep: z.number().optional(),
funnelFromStep: z.number().optional(),
funnelOrderType: FunnelOrderType.optional(),
funnelVizType: FunnelVizType.optional(),
funnelWindowInterval: z.number().optional().default(14),
funnelWindowIntervalUnit: FunnelConversionWindowTimeUnit.optional().default('day'),
funnelStepReference: FunnelStepReference.optional(),
})
// Funnels query
const FunnelsQuerySchema = InsightsQueryBase.extend({
kind: z.literal('FunnelsQuery'),
interval: IntervalType.optional(),
series: z.array(AnyEntityNode).min(2, 'At least two steps are required for a funnel'),
funnelsFilter: FunnelsFilter.optional(),
breakdownFilter: BreakdownFilter.optional(),
})
// Paths types
const PathType = z.enum(['$pageview', '$screen', 'custom_event', 'hogql'])
const PathCleaningFilter = z.object({
alias: z.string().optional(),
regex: z.string().optional(),
})
// Paths filter
const PathsFilter = z.object({
includeEventTypes: z.array(PathType).optional(),
pathsHogQLExpression: z
.string()
.optional()
.describe('A HogQL expression to use as the path step name. Requires includeEventTypes to contain "hogql".'),
startPoint: z.string().optional().describe('Only show paths starting at this step'),
endPoint: z.string().optional().describe('Only show paths ending at this step'),
stepLimit: z.number().optional().default(5).describe('Maximum number of path steps (default 5)'),
edgeLimit: z.number().optional().default(50).describe('Maximum number of edges to return (default 50)'),
excludeEvents: z.array(z.string()).optional().describe('Events to exclude from the path'),
pathGroupings: z.array(z.string()).optional().describe('Wildcard groups to merge similar path steps'),
localPathCleaningFilters: z
.array(PathCleaningFilter)
.optional()
.describe('Regex rules to clean/simplify path step names'),
minEdgeWeight: z.number().optional(),
maxEdgeWeight: z.number().optional(),
})
// Paths query
const PathsQuerySchema = InsightsQueryBase.extend({
kind: z.literal('PathsQuery'),
pathsFilter: PathsFilter.default({ stepLimit: 5, edgeLimit: 50 }),
})
// Insight Schema
const InsightVizNodeSchema = z.object({
kind: z.literal('InsightVizNode'),
source: z.discriminatedUnion('kind', [TrendsQuerySchema, FunnelsQuerySchema, PathsQuerySchema]),
})
const DataVisualizationNodeSchema = z.object({
kind: z.literal('DataVisualizationNode'),
source: HogQLQuerySchema,
display: ChartDisplayType.optional().describe(
'Visualization type. Time series should usually use ActionsLineGraph or ActionsAreaGraph; use ActionsTable only when table rows are the intended output.'
),
chartSettings: ChartSettings.optional(),
tableSettings: TableSettings.optional(),
})
// Any insight query
const InsightQuerySchema = z.discriminatedUnion('kind', [InsightVizNodeSchema, DataVisualizationNodeSchema])
// Export all schemas
export {
// Enums
NodeKind,
IntervalType,
ChartDisplayType,
BreakdownType,
FunnelVizType,
FunnelOrderType,
FunnelStepReference,
BreakdownAttributionType,
FunnelLayout,
FunnelConversionWindowTimeUnit,
// Math types
BaseMathType,
PropertyMathType,
MathType,
// Base types
DateRange,
PropertyFilter,
PropertyGroupFilter,
AnyPropertyFilter,
ChartAxis,
ChartSettings,
TableSettings,
// Entity nodes
EventsNode,
AnyEntityNode,
// Filters
BreakdownFilter,
CompareFilter,
TrendsFilter,
FunnelsFilter,
PathsFilter,
// HogQL types
HogQLVariable,
HogQLFilters,
// Queries
TrendsQuerySchema,
FunnelsQuerySchema,
PathsQuerySchema,
HogQLQuerySchema,
InsightVizNodeSchema,
DataVisualizationNodeSchema,
InsightQuerySchema,
}
export type TrendsQuery = z.infer<typeof TrendsQuerySchema>
export type FunnelsQuery = z.infer<typeof FunnelsQuerySchema>
export type PathsQuery = z.infer<typeof PathsQuerySchema>
export type HogQLQuery = z.infer<typeof HogQLQuerySchema>
export type InsightQuery = z.infer<typeof InsightQuerySchema>