Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

feat: add cohort

Carl-Gerhard Lindesvärdd6877dd7cfb4
diff --git a/apps/start/src/components/cohort/cohort-criteria-builder.tsx b/apps/start/src/components/cohort/cohort-criteria-builder.tsx
new file mode 100644
index 000000000..e2b7ef214
--- /dev/null
+++ b/apps/start/src/components/cohort/cohort-criteria-builder.tsx
@@ -0,0 +1,630 @@
+import { Button } from '@/components/ui/button';
+import { ComboboxAdvanced } from '@/components/ui/combobox-advanced';
+import { DropdownMenuComposed } from '@/components/ui/dropdown-menu';
+import { useAppParams } from '@/hooks/use-app-params';
+import { useEventNames } from '@/hooks/use-event-names';
+import type {
+ CohortDefinition,
+ EventBasedCohortDefinition,
+ EventCriteria,
+ IChartEventFilter,
+ IChartEventFilterOperator,
+ IChartEventFilterValue,
+ PropertyBasedCohortDefinition,
+} from '@openpanel/validation';
+import { PlusIcon, TrashIcon } from 'lucide-react';
+import { PureFilterItem } from '../report/sidebar/filters/FilterItem';
+import { PropertiesCombobox } from '../report/sidebar/PropertiesCombobox';
+
+interface CohortCriteriaBuilderProps {
+ definition: CohortDefinition;
+ onChange: (definition: CohortDefinition) => void;
+}
+
+export function CohortCriteriaBuilder({
+ definition,
+ onChange,
+}: CohortCriteriaBuilderProps) {
+ const { projectId } = useAppParams();
+ const eventNames = useEventNames({ projectId });
+
+ const handleTypeChange = (type: 'event' | 'property') => {
+ if (type === 'event') {
+ onChange({
+ type: 'event',
+ criteria: { events: [], operator: 'or' },
+ });
+ } else {
+ onChange({
+ type: 'property',
+ criteria: { properties: [], operator: 'or' },
+ });
+ }
+ };
+
+ return (
+ <div className="flex flex-col gap-4">
+ <div className="flex gap-2">
+ <Button
+ type="button"
+ variant={definition.type === 'event' ? 'default' : 'outline'}
+ onClick={() => handleTypeChange('event')}
+ className="flex-1"
+ >
+ Event-based
+ </Button>
+ <Button
+ type="button"
+ variant={definition.type === 'property' ? 'default' : 'outline'}
+ onClick={() => handleTypeChange('property')}
+ className="flex-1"
+ >
+ Property-based
+ </Button>
+ </div>
+
+ {definition.type === 'event' && (
+ <EventBasedBuilder
+ definition={definition}
+ onChange={onChange}
+ eventNames={eventNames}
+ />
+ )}
+
+ {definition.type === 'property' && (
+ <PropertyBasedBuilder definition={definition} onChange={onChange} />
+ )}
+ </div>
+ );
+}
+
+interface EventBasedBuilderProps {
+ definition: EventBasedCohortDefinition;
+ onChange: (definition: EventBasedCohortDefinition) => void;
+ eventNames: Array<{ name: string; count: number; meta: unknown }>;
+}
+
+function EventBasedBuilder({
+ definition,
+ onChange,
+ eventNames: eventNamesArray,
+}: EventBasedBuilderProps) {
+ const eventNames = eventNamesArray.map((event) => ({
+ value: event.name,
+ label: event.name,
+ count: event.count,
+ }));
+
+ const addEventCriteria = () => {
+ onChange({
+ ...definition,
+ criteria: {
+ ...definition.criteria,
+ events: [
+ ...definition.criteria.events,
+ {
+ name: '',
+ filters: [],
+ timeframe: { type: 'relative', value: '30d' },
+ frequency: { operator: 'gte', count: 1 },
+ },
+ ],
+ },
+ });
+ };
+
+ const removeEventCriteria = (index: number) => {
+ onChange({
+ ...definition,
+ criteria: {
+ ...definition.criteria,
+ events: definition.criteria.events.filter((_, i) => i !== index),
+ },
+ });
+ };
+
+ const updateEventCriteria = (index: number, criteria: EventCriteria) => {
+ onChange({
+ ...definition,
+ criteria: {
+ ...definition.criteria,
+ events: definition.criteria.events.map((e, i) =>
+ i === index ? criteria : e,
+ ),
+ },
+ });
+ };
+
+ const updateOperator = (operator: 'or' | 'and') => {
+ onChange({
+ ...definition,
+ criteria: { ...definition.criteria, operator },
+ });
+ };
+
+ return (
+ <div className="flex flex-col gap-4">
+ <div className="flex items-center gap-2">
+ <span className="text-sm text-muted-foreground">Match</span>
+ <DropdownMenuComposed
+ onChange={updateOperator}
+ items={[
+ { value: 'or', label: 'Any of these events' },
+ { value: 'and', label: 'All of these events' },
+ ]}
+ label="Operator"
+ >
+ <Button variant="outline" size="sm">
+ {definition.criteria.operator === 'or' ? 'Any' : 'All'}
+ </Button>
+ </DropdownMenuComposed>
+ </div>
+
+ {definition.criteria.events.map((eventCriteria, index) => (
+ <EventCriteriaItem
+ key={index}
+ criteria={eventCriteria}
+ onChange={(criteria) => updateEventCriteria(index, criteria)}
+ onRemove={() => removeEventCriteria(index)}
+ eventNames={eventNames}
+ />
+ ))}
+
+ <Button
+ type="button"
+ variant="outline"
+ onClick={addEventCriteria}
+ icon={PlusIcon}
+ >
+ Add event criteria
+ </Button>
+ </div>
+ );
+}
+
+interface EventCriteriaItemProps {
+ criteria: EventCriteria;
+ onChange: (criteria: EventCriteria) => void;
+ onRemove: () => void;
+ eventNames: Array<{ value: string; label: string; count: number }>;
+}
+
+function EventCriteriaItem({
+ criteria,
+ onChange,
+ onRemove,
+ eventNames,
+}: EventCriteriaItemProps) {
+ const addFilter = (propertyName: string) => {
+ onChange({
+ ...criteria,
+ filters: [
+ ...criteria.filters,
+ {
+ id: Math.random().toString(36).substring(7),
+ name: propertyName,
+ operator: 'is',
+ value: [],
+ },
+ ],
+ });
+ };
+
+ const removeFilter = (filter: IChartEventFilter) => {
+ onChange({
+ ...criteria,
+ filters: criteria.filters.filter((f) => f.id !== filter.id),
+ });
+ };
+
+ const updateFilterValue = (
+ value: IChartEventFilterValue[],
+ filter: IChartEventFilter,
+ ) => {
+ onChange({
+ ...criteria,
+ filters: criteria.filters.map((f) =>
+ f.id === filter.id ? { ...f, value } : f,
+ ),
+ });
+ };
+
+ const updateFilterOperator = (
+ operator: IChartEventFilterOperator,
+ filter: IChartEventFilter,
+ ) => {
+ onChange({
+ ...criteria,
+ filters: criteria.filters.map((f) =>
+ f.id === filter.id
+ ? { ...f, operator, value: f.value.slice(0, 1) }
+ : f,
+ ),
+ });
+ };
+
+ return (
+ <div className="rounded border p-4">
+ <div className="mb-3 flex items-start justify-between gap-2">
+ <div className="flex-1">
+ <label className="mb-1 block text-sm font-medium">Event</label>
+ <ComboboxAdvanced
+ items={eventNames}
+ value={criteria.name ? [criteria.name] : []}
+ onChange={(values) =>
+ onChange({ ...criteria, name: String(values[0] ?? '') })
+ }
+ placeholder="Select event..."
+ className="w-full"
+ />
+ </div>
+ <Button
+ type="button"
+ variant="ghost"
+ size="sm"
+ onClick={onRemove}
+ className="mt-6"
+ >
+ <TrashIcon size={16} />
+ </Button>
+ </div>
+
+ <div className="mb-3">
+ <label className="mb-1 block text-sm font-medium">Frequency</label>
+ <div className="flex gap-2">
+ <DropdownMenuComposed
+ onChange={(operator) =>
+ onChange({
+ ...criteria,
+ frequency: {
+ ...(criteria.frequency ?? { count: 1 }),
+ operator,
+ },
+ })
+ }
+ items={[
+ { value: 'gte', label: 'At least' },
+ { value: 'eq', label: 'Exactly' },
+ { value: 'lte', label: 'At most' },
+ ]}
+ label="Operator"
+ >
+ <Button variant="outline" size="sm">
+ {criteria.frequency?.operator === 'gte' && 'At least'}
+ {criteria.frequency?.operator === 'eq' && 'Exactly'}
+ {criteria.frequency?.operator === 'lte' && 'At most'}
+ </Button>
+ </DropdownMenuComposed>
+ <input
+ type="number"
+ min="1"
+ value={criteria.frequency?.count ?? 1}
+ onChange={(e) =>
+ onChange({
+ ...criteria,
+ frequency: {
+ operator: criteria.frequency?.operator ?? 'gte',
+ count: Number.parseInt(e.target.value) || 1,
+ },
+ })
+ }
+ className="w-20 rounded border px-2 py-1 text-sm"
+ />
+ <span className="flex items-center text-sm text-muted-foreground">
+ times
+ </span>
+ </div>
+ </div>
+
+ <div className="mb-3">
+ <label className="mb-1 block text-sm font-medium">Timeframe</label>
+ <div className="flex flex-col gap-2">
+ <div className="flex gap-2">
+ <DropdownMenuComposed
+ onChange={(type) => {
+ if (type === 'relative') {
+ onChange({
+ ...criteria,
+ timeframe: { type: 'relative', value: '30d' },
+ });
+ } else if (type === 'since') {
+ onChange({
+ ...criteria,
+ timeframe: {
+ type: 'absolute',
+ start:
+ new Date().toISOString().split('T')[0] ?? '',
+ },
+ });
+ } else {
+ const today = new Date().toISOString().split('T')[0] ?? '';
+ const thirtyDaysAgo =
+ new Date(Date.now() - 30 * 24 * 60 * 60 * 1000)
+ .toISOString()
+ .split('T')[0] ?? '';
+ onChange({
+ ...criteria,
+ timeframe: {
+ type: 'absolute',
+ start: thirtyDaysAgo,
+ end: today,
+ },
+ });
+ }
+ }}
+ items={[
+ { value: 'relative', label: 'Last' },
+ { value: 'since', label: 'Since' },
+ { value: 'between', label: 'Between' },
+ ]}
+ label="Type"
+ >
+ <Button variant="outline" size="sm">
+ {criteria.timeframe.type === 'relative'
+ ? 'Last'
+ : criteria.timeframe.type === 'absolute' &&
+ !criteria.timeframe.end
+ ? 'Since'
+ : 'Between'}
+ </Button>
+ </DropdownMenuComposed>
+ {criteria.timeframe.type === 'relative' ? (
+ <DropdownMenuComposed
+ onChange={(value) =>
+ onChange({
+ ...criteria,
+ timeframe: { type: 'relative', value },
+ })
+ }
+ items={[
+ { value: '7d', label: '7 days' },
+ { value: '30d', label: '30 days' },
+ { value: '90d', label: '90 days' },
+ { value: '180d', label: '180 days' },
+ { value: '365d', label: '365 days' },
+ ]}
+ label="Period"
+ >
+ <Button variant="outline" size="sm">
+ {criteria.timeframe.value === '7d' && '7 days'}
+ {criteria.timeframe.value === '30d' && '30 days'}
+ {criteria.timeframe.value === '90d' && '90 days'}
+ {criteria.timeframe.value === '180d' && '180 days'}
+ {criteria.timeframe.value === '365d' && '365 days'}
+ </Button>
+ </DropdownMenuComposed>
+ ) : !criteria.timeframe.end ? (
+ <input
+ type="date"
+ value={criteria.timeframe.start}
+ onChange={(e) =>
+ onChange({
+ ...criteria,
+ timeframe: { type: 'absolute', start: e.target.value },
+ })
+ }
+ className="rounded border px-2 py-1 text-sm"
+ />
+ ) : null}
+ </div>
+ {criteria.timeframe.type === 'absolute' &&
+ criteria.timeframe.end && (
+ <div className="flex items-center gap-2">
+ <input
+ type="date"
+ value={criteria.timeframe.start}
+ onChange={(e) =>
+ onChange({
+ ...criteria,
+ timeframe: {
+ type: 'absolute',
+ start: e.target.value,
+ end: criteria.timeframe.type === 'absolute'
+ ? criteria.timeframe.end
+ : undefined,
+ },
+ })
+ }
+ className="flex-1 rounded border px-2 py-1 text-sm"
+ />
+ <span className="text-sm text-muted-foreground">to</span>
+ <input
+ type="date"
+ value={criteria.timeframe.end}
+ onChange={(e) =>
+ onChange({
+ ...criteria,
+ timeframe: {
+ type: 'absolute',
+ start:
+ criteria.timeframe.type === 'absolute'
+ ? criteria.timeframe.start
+ : '',
+ end: e.target.value,
+ },
+ })
+ }
+ className="flex-1 rounded border px-2 py-1 text-sm"
+ />
+ </div>
+ )}
+ </div>
+ </div>
+
+ {criteria.filters.length > 0 && (
+ <div className="mb-2">
+ <label className="mb-2 block text-sm font-medium">
+ Event Filters
+ </label>
+ <div className="space-y-2">
+ {criteria.filters.map((filter) => (
+ <PureFilterItem
+ key={filter.id}
+ eventName={criteria.name}
+ filter={filter}
+ onRemove={removeFilter}
+ onChangeValue={updateFilterValue}
+ onChangeOperator={updateFilterOperator}
+ className="rounded border p-2"
+ />
+ ))}
+ </div>
+ </div>
+ )}
+
+ <PropertiesCombobox
+ event={{ name: criteria.name, id: 'cohort-event' } as never}
+ onSelect={(action) => {
+ addFilter(action.value);
+ }}
+ mode="events"
+ >
+ {(setOpen) => (
+ <Button
+ type="button"
+ variant="outline"
+ size="sm"
+ onClick={() => setOpen(true)}
+ icon={PlusIcon}
+ disabled={!criteria.name}
+ >
+ Add filter
+ </Button>
+ )}
+ </PropertiesCombobox>
+ </div>
+ );
+}
+
+interface PropertyBasedBuilderProps {
+ definition: PropertyBasedCohortDefinition;
+ onChange: (definition: PropertyBasedCohortDefinition) => void;
+}
+
+function PropertyBasedBuilder({
+ definition,
+ onChange,
+}: PropertyBasedBuilderProps) {
+ const addPropertyFilter = (propertyName: string) => {
+ onChange({
+ ...definition,
+ criteria: {
+ ...definition.criteria,
+ properties: [
+ ...definition.criteria.properties,
+ {
+ id: Math.random().toString(36).substring(7),
+ name: propertyName,
+ operator: 'is',
+ value: [],
+ },
+ ],
+ },
+ });
+ };
+
+ const removePropertyFilter = (filter: IChartEventFilter) => {
+ onChange({
+ ...definition,
+ criteria: {
+ ...definition.criteria,
+ properties: definition.criteria.properties.filter(
+ (f) => f.id !== filter.id,
+ ),
+ },
+ });
+ };
+
+ const updatePropertyFilterValue = (
+ value: IChartEventFilterValue[],
+ filter: IChartEventFilter,
+ ) => {
+ onChange({
+ ...definition,
+ criteria: {
+ ...definition.criteria,
+ properties: definition.criteria.properties.map((f) =>
+ f.id === filter.id ? { ...f, value } : f,
+ ),
+ },
+ });
+ };
+
+ const updatePropertyFilterOperator = (
+ operator: IChartEventFilterOperator,
+ filter: IChartEventFilter,
+ ) => {
+ onChange({
+ ...definition,
+ criteria: {
+ ...definition.criteria,
+ properties: definition.criteria.properties.map((f) =>
+ f.id === filter.id
+ ? { ...f, operator, value: f.value.slice(0, 1) }
+ : f,
+ ),
+ },
+ });
+ };
+
+ const updateOperator = (operator: 'or' | 'and') => {
+ onChange({
+ ...definition,
+ criteria: { ...definition.criteria, operator },
+ });
+ };
+
+ return (
+ <div className="flex flex-col gap-4">
+ <div className="flex items-center gap-2">
+ <span className="text-sm text-muted-foreground">Match</span>
+ <DropdownMenuComposed
+ onChange={updateOperator}
+ items={[
+ { value: 'or', label: 'Any of these properties' },
+ { value: 'and', label: 'All of these properties' },
+ ]}
+ label="Operator"
+ >
+ <Button variant="outline" size="sm">
+ {definition.criteria.operator === 'or' ? 'Any' : 'All'}
+ </Button>
+ </DropdownMenuComposed>
+ </div>
+
+ {definition.criteria.properties.length > 0 && (
+ <div className="space-y-2">
+ {definition.criteria.properties.map((filter) => (
+ <PureFilterItem
+ key={filter.id}
+ eventName=""
+ filter={filter}
+ onRemove={removePropertyFilter}
+ onChangeValue={updatePropertyFilterValue}
+ onChangeOperator={updatePropertyFilterOperator}
+ className="rounded border p-2"
+ />
+ ))}
+ </div>
+ )}
+
+ <PropertiesCombobox
+ onSelect={(action) => {
+ addPropertyFilter(action.value);
+ }}
+ mode="profile"
+ >
+ {(setOpen) => (
+ <Button
+ type="button"
+ variant="outline"
+ onClick={() => setOpen(true)}
+ icon={PlusIcon}
+ >
+ Add property filter
+ </Button>
+ )}
+ </PropertiesCombobox>
+ </div>
+ );
+}
diff --git a/apps/start/src/components/report/sidebar/PropertiesCombobox.tsx b/apps/start/src/components/report/sidebar/PropertiesCombobox.tsx
index e4d5c673e..e0adc4d53 100644
--- a/apps/start/src/components/report/sidebar/PropertiesCombobox.tsx
+++ b/apps/start/src/components/report/sidebar/PropertiesCombobox.tsx
@@ -5,6 +5,7 @@ import {
ArrowLeftIcon,
Building2Icon,
DatabaseIcon,
+ TargetIcon,
UserIcon,
} from 'lucide-react';
import VirtualList from 'rc-virtual-list';
@@ -20,20 +21,25 @@ import {
} from '@/components/ui/dropdown-menu';
import { Input } from '@/components/ui/input';
import { useAppParams } from '@/hooks/use-app-params';
+import { useCohorts } from '@/hooks/use-cohorts';
import { useEventProperties } from '@/hooks/use-event-properties';
import { useTRPC } from '@/integrations/trpc/react';
+export type PropertiesComboboxAction = {
+ value: string;
+ label: string;
+ description: string;
+ cohortId?: string;
+};
+
interface PropertiesComboboxProps {
event?: IChartEvent;
children: (setOpen: Dispatch<SetStateAction<boolean>>) => React.ReactNode;
- onSelect: (action: {
- value: string;
- label: string;
- description: string;
- }) => void;
+ onSelect: (action: PropertiesComboboxAction) => void;
exclude?: string[];
include?: string[];
mode?: 'events' | 'profile';
+ showCohorts?: boolean;
}
function SearchHeader({
@@ -69,6 +75,7 @@ export function PropertiesCombobox({
mode,
exclude = [],
include = [],
+ showCohorts = false,
}: PropertiesComboboxProps) {
const { projectId } = useAppParams();
const trpc = useTRPC();
@@ -80,9 +87,13 @@ export function PropertiesCombobox({
const groupPropertiesQuery = useQuery(
trpc.group.properties.queryOptions({ projectId })
);
- const [state, setState] = useState<'index' | 'event' | 'profile' | 'group'>(
- 'index'
+ const cohorts = useCohorts(
+ { projectId, includeCount: false },
+ { enabled: showCohorts },
);
+ const [state, setState] = useState<
+ 'index' | 'event' | 'profile' | 'group' | 'cohort'
+ >('index');
const [search, setSearch] = useState('');
const [direction, setDirection] = useState<'forward' | 'backward'>('forward');
@@ -138,21 +149,26 @@ export function PropertiesCombobox({
}));
const handleStateChange = (
- newState: 'index' | 'event' | 'profile' | 'group'
+ newState: 'index' | 'event' | 'profile' | 'group' | 'cohort'
) => {
setDirection(newState === 'index' ? 'backward' : 'forward');
setState(newState);
};
- const handleSelect = (action: {
- value: string;
- label: string;
- description: string;
- }) => {
+ const handleSelect = (action: PropertiesComboboxAction) => {
setOpen(false);
onSelect(action);
};
+ const cohortActions: PropertiesComboboxAction[] = cohorts.map((cohort) => ({
+ value: `cohort:${cohort.id}`,
+ label: cohort.name,
+ description: cohort.description
+ ? cohort.description
+ : `${cohort.profileCount ?? 0} members`,
+ cohortId: cohort.id,
+ }));
+
const renderIndex = () => {
return (
<DropdownMenuGroup>
@@ -188,10 +204,61 @@ export function PropertiesCombobox({
Group properties
<Building2Icon className="size-4 transition-all group-hover:rotate-12 group-hover:scale-125 group-hover:text-blue-500" />
</DropdownMenuItem>
+ {showCohorts && (
+ <DropdownMenuItem
+ className="group justify-between gap-2"
+ onClick={(e) => {
+ e.preventDefault();
+ handleStateChange('cohort');
+ }}
+ >
+ Cohorts
+ <TargetIcon className="size-4 transition-all group-hover:rotate-12 group-hover:scale-125 group-hover:text-blue-500" />
+ </DropdownMenuItem>
+ )}
</DropdownMenuGroup>
);
};
+ const renderCohort = () => {
+ const filteredActions = cohortActions.filter(
+ (action) =>
+ action.label.toLowerCase().includes(search.toLowerCase()) ||
+ action.description.toLowerCase().includes(search.toLowerCase()),
+ );
+
+ return (
+ <div className="flex flex-col">
+ <SearchHeader
+ onBack={() => handleStateChange('index')}
+ onSearch={setSearch}
+ value={search}
+ />
+ <DropdownMenuSeparator />
+ <VirtualList
+ data={filteredActions}
+ height={Math.min(300, filteredActions.length * 40 + 8)}
+ itemHeight={40}
+ itemKey="value"
+ >
+ {(action) => (
+ <motion.div
+ animate={{ opacity: 1, y: 0 }}
+ className="col cursor-pointer gap-px rounded-md p-2 hover:bg-accent"
+ initial={{ opacity: 0, y: 10 }}
+ onClick={() => handleSelect(action)}
+ >
+ <div className="font-medium">{action.label}</div>
+ <div className="text-muted-foreground text-sm">
+ {action.description}
+ </div>
+ </motion.div>
+ )}
+ </VirtualList>
+ </div>
+ );
+ };
+
const renderEvent = () => {
const filteredActions = eventActions.filter(
(action) =>
@@ -365,6 +432,17 @@ export function PropertiesCombobox({
{renderGroup()}
</motion.div>
)}
+ {state === 'cohort' && (
+ <motion.div
+ animate={{ opacity: 1, x: 0 }}
+ exit={{ opacity: 0, x: direction === 'forward' ? -20 : 20 }}
+ initial={{ opacity: 0, x: direction === 'forward' ? 20 : -20 }}
+ key="cohort"
+ transition={{ duration: 0.05 }}
+ >
+ {renderCohort()}
+ </motion.div>
+ )}
</AnimatePresence>
</DropdownMenuContent>
</DropdownMenu>
diff --git a/apps/start/src/components/report/sidebar/ReportBreakdowns.tsx b/apps/start/src/components/report/sidebar/ReportBreakdowns.tsx
index 628db5def..e5c7ec92e 100644
--- a/apps/start/src/components/report/sidebar/ReportBreakdowns.tsx
+++ b/apps/start/src/components/report/sidebar/ReportBreakdowns.tsx
@@ -71,6 +71,7 @@ export function ReportBreakdowns() {
})}
<PropertiesCombobox
+ showCohorts
onSelect={(action) => {
dispatch(
addBreakdown({
diff --git a/apps/start/src/components/report/sidebar/ReportSeriesItem.tsx b/apps/start/src/components/report/sidebar/ReportSeriesItem.tsx
index 18e038158..c30b5f5f4 100644
--- a/apps/start/src/components/report/sidebar/ReportSeriesItem.tsx
+++ b/apps/start/src/components/report/sidebar/ReportSeriesItem.tsx
@@ -71,18 +71,27 @@ export function ReportSeriesItem({
{showAddFilter && (
<PropertiesCombobox
event={chartEvent}
+ showCohorts
onSelect={(action) => {
dispatch(
changeEvent({
...chartEvent,
filters: [
...chartEvent.filters,
- {
- id: shortId(),
- name: action.value,
- operator: 'is',
- value: [],
- },
+ action.cohortId
+ ? {
+ id: shortId(),
+ name: action.value,
+ operator: 'inCohort',
+ value: [],
+ cohortId: action.cohortId,
+ }
+ : {
+ id: shortId(),
+ name: action.value,
+ operator: 'is',
+ value: [],
+ },
],
}),
);
diff --git a/apps/start/src/components/report/sidebar/filters/CohortFilterItem.tsx b/apps/start/src/components/report/sidebar/filters/CohortFilterItem.tsx
new file mode 100644
index 000000000..ca9b33e0e
--- /dev/null
+++ b/apps/start/src/components/report/sidebar/filters/CohortFilterItem.tsx
@@ -0,0 +1,151 @@
+import { ColorSquare } from '@/components/color-square';
+import { RenderDots } from '@/components/ui/RenderDots';
+import { Button } from '@/components/ui/button';
+import { ComboboxAdvanced } from '@/components/ui/combobox-advanced';
+import { DropdownMenuComposed } from '@/components/ui/dropdown-menu';
+import { useAppParams } from '@/hooks/use-app-params';
+import { useCohorts } from '@/hooks/use-cohorts';
+import { useDispatch } from '@/redux';
+import type {
+ IChartEvent,
+ IChartEventFilter,
+ IChartEventFilterOperator,
+} from '@openpanel/validation';
+import { SlidersHorizontal, Trash } from 'lucide-react';
+import { changeEvent } from '../../reportSlice';
+
+interface CohortFilterItemProps {
+ event: IChartEvent;
+ filter: IChartEventFilter;
+}
+
+interface PureCohortFilterItemProps {
+ filter: IChartEventFilter;
+ onRemove: (filter: IChartEventFilter) => void;
+ onChangeOperator: (
+ operator: IChartEventFilterOperator,
+ filter: IChartEventFilter,
+ ) => void;
+ onChangeCohort: (cohortId: string, filter: IChartEventFilter) => void;
+ className?: string;
+}
+
+export function CohortFilterItem({ filter, event }: CohortFilterItemProps) {
+ const dispatch = useDispatch();
+
+ const onRemove = ({ id }: IChartEventFilter) => {
+ dispatch(
+ changeEvent({
+ ...event,
+ filters: event.filters.filter((item) => item.id !== id),
+ type: 'event',
+ }),
+ );
+ };
+
+ const onChangeOperator = (
+ operator: IChartEventFilterOperator,
+ { id }: IChartEventFilter,
+ ) => {
+ dispatch(
+ changeEvent({
+ ...event,
+ type: 'event',
+ filters: event.filters.map((item) =>
+ item.id === id ? { ...item, operator } : item,
+ ),
+ }),
+ );
+ };
+
+ const onChangeCohort = (cohortId: string, { id }: IChartEventFilter) => {
+ dispatch(
+ changeEvent({
+ ...event,
+ type: 'event',
+ filters: event.filters.map((item) =>
+ item.id === id ? { ...item, cohortId } : item,
+ ),
+ }),
+ );
+ };
+
+ return (
+ <PureCohortFilterItem
+ filter={filter}
+ onRemove={onRemove}
+ onChangeOperator={onChangeOperator}
+ onChangeCohort={onChangeCohort}
+ className="px-4 py-2 shadow-[inset_6px_0_0] shadow-def-300 first:border-t"
+ />
+ );
+}
+
+export function PureCohortFilterItem({
+ filter,
+ onRemove,
+ onChangeOperator,
+ onChangeCohort,
+ className,
+}: PureCohortFilterItemProps) {
+ const { projectId } = useAppParams();
+
+ const cohorts = useCohorts({ projectId, includeCount: false });
+
+ const cohortsCombobox = cohorts.map((cohort) => ({
+ value: cohort.id,
+ label: cohort.name,
+ }));
+
+ const removeFilter = () => {
+ onRemove(filter);
+ };
+
+ const changeFilterOperator = (operator: IChartEventFilterOperator) => {
+ onChangeOperator(operator, filter);
+ };
+
+ const changeCohort = (cohortIds: Array<string | number>) => {
+ const cohortId = cohortIds[0];
+ if (cohortId && typeof cohortId === 'string') {
+ onChangeCohort(cohortId, filter);
+ }
+ };
+
+ return (
+ <div className={className}>
+ <div className="mb-2 flex items-center gap-2">
+ <ColorSquare className="bg-emerald-500">
+ <SlidersHorizontal size={10} />
+ </ColorSquare>
+ <div className="flex flex-1">
+ <RenderDots truncate>{filter.name}</RenderDots>
+ </div>
+ <Button variant="ghost" size="sm" onClick={removeFilter}>
+ <Trash size={16} />
+ </Button>
+ </div>
+ <div className="flex gap-1">
+ <DropdownMenuComposed
+ onChange={changeFilterOperator}
+ items={[
+ { value: 'inCohort', label: 'In cohort' },
+ { value: 'notInCohort', label: 'Not in cohort' },
+ ]}
+ label="Operator"
+ >
+ <Button variant="outline" className="whitespace-nowrap">
+ {filter.operator === 'inCohort' ? 'In cohort' : 'Not in cohort'}
+ </Button>
+ </DropdownMenuComposed>
+ <ComboboxAdvanced
+ items={cohortsCombobox}
+ value={filter.cohortId ? [filter.cohortId] : []}
+ className="flex-1"
+ onChange={changeCohort}
+ placeholder="Select cohort..."
+ />
+ </div>
+ </div>
+ );
+}
diff --git a/apps/start/src/components/report/sidebar/filters/FilterOperatorSelect.tsx b/apps/start/src/components/report/sidebar/filters/FilterOperatorSelect.tsx
index 1eb5562ea..39a17dd9b 100644
--- a/apps/start/src/components/report/sidebar/filters/FilterOperatorSelect.tsx
+++ b/apps/start/src/components/report/sidebar/filters/FilterOperatorSelect.tsx
@@ -24,10 +24,13 @@ export function FilterOperatorSelect({
return (
<DropdownMenuComposed
onChange={onChange}
- items={mapKeys(operators).map((key) => ({
- value: key,
- label: operators[key],
- }))}
+ items={mapKeys(operators)
+ // Cohort operators are surfaced via CohortFilterItem, not here.
+ .filter((key) => key !== 'inCohort' && key !== 'notInCohort')
+ .map((key) => ({
+ value: key,
+ label: operators[key],
+ }))}
label="Operator"
>
{trigger}
diff --git a/apps/start/src/components/report/sidebar/filters/FiltersList.tsx b/apps/start/src/components/report/sidebar/filters/FiltersList.tsx
index 2172c86eb..8a5424d02 100644
--- a/apps/start/src/components/report/sidebar/filters/FiltersList.tsx
+++ b/apps/start/src/components/report/sidebar/filters/FiltersList.tsx
@@ -1,5 +1,6 @@
import type { IChartEvent } from '@openpanel/validation';
+import { CohortFilterItem } from './CohortFilterItem';
import { FilterItem } from './FilterItem';
interface ReportEventFiltersProps {
@@ -11,7 +12,25 @@ export function FiltersList({ event }: ReportEventFiltersProps) {
<div>
<div className="bg-def-100 flex flex-col divide-y overflow-hidden rounded-b-md">
{event.filters.map((filter) => {
- return <FilterItem key={filter.name} filter={filter} event={event} />;
+ const isCohortFilter =
+ filter.operator === 'inCohort' ||
+ filter.operator === 'notInCohort';
+ if (isCohortFilter) {
+ return (
+ <CohortFilterItem
+ key={filter.id ?? filter.name}
+ filter={filter}
+ event={event}
+ />
+ );
+ }
+ return (
+ <FilterItem
+ key={filter.id ?? filter.name}
+ filter={filter}
+ event={event}
+ />
+ );
})}
</div>
</div>
diff --git a/apps/start/src/components/sidebar-project-menu.tsx b/apps/start/src/components/sidebar-project-menu.tsx
index 7b8d92e08..e78ae4f3e 100644
--- a/apps/start/src/components/sidebar-project-menu.tsx
+++ b/apps/start/src/components/sidebar-project-menu.tsx
@@ -17,6 +17,7 @@ import {
PlusIcon,
SearchIcon,
SparklesIcon,
+ TargetIcon,
TrendingUpDownIcon,
UndoDotIcon,
UserCircleIcon,
@@ -67,6 +68,7 @@ export default function SidebarProjectMenu({
<SidebarLink href={'/sessions'} icon={UsersIcon} label="Sessions" />
<SidebarLink href={'/profiles'} icon={UserCircleIcon} label="Profiles" />
<SidebarLink href={'/groups'} icon={Building2Icon} label="Groups" />
+ <SidebarLink href={'/cohorts'} icon={TargetIcon} label="Cohorts" />
<div className="mt-4 mb-2 font-medium text-muted-foreground text-sm">
Manage
</div>
diff --git a/apps/start/src/hooks/use-cohorts.ts b/apps/start/src/hooks/use-cohorts.ts
new file mode 100644
index 000000000..c7a53c0a7
--- /dev/null
+++ b/apps/start/src/hooks/use-cohorts.ts
@@ -0,0 +1,18 @@
+import { useTRPC } from '@/integrations/trpc/react';
+import { useQuery } from '@tanstack/react-query';
+
+export function useCohorts(
+ params: { projectId: string; includeCount?: boolean },
+ options?: { enabled?: boolean },
+) {
+ const trpc = useTRPC();
+ const query = useQuery(
+ trpc.cohort.list.queryOptions(params, {
+ enabled:
+ !!params.projectId && typeof options?.enabled !== 'undefined'
+ ? options.enabled
+ : true,
+ }),
+ );
+ return query.data ?? [];
+}
diff --git a/apps/start/src/modals/add-cohort.tsx b/apps/start/src/modals/add-cohort.tsx
new file mode 100644
index 000000000..75ac793d0
--- /dev/null
+++ b/apps/start/src/modals/add-cohort.tsx
@@ -0,0 +1,129 @@
+import { ButtonContainer } from '@/components/button-container';
+import { CohortCriteriaBuilder } from '@/components/cohort/cohort-criteria-builder';
+import { InputWithLabel, WithLabel } from '@/components/forms/input-with-label';
+import { Button } from '@/components/ui/button';
+import { Label } from '@/components/ui/label';
+import { Switch } from '@/components/ui/switch';
+import { Textarea } from '@/components/ui/textarea';
+import { useAppParams } from '@/hooks/use-app-params';
+import { handleError, useTRPC } from '@/integrations/trpc/react';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import type { CohortDefinition } from '@openpanel/validation';
+import { Controller, useForm } from 'react-hook-form';
+import { toast } from 'sonner';
+import { z } from 'zod';
+
+import { popModal } from '.';
+import { ModalContent, ModalHeader } from './Modal/Container';
+
+const validator = z.object({
+ name: z.string().min(1, 'Required'),
+ description: z.string().optional(),
+ definition: z.any(),
+ isStatic: z.boolean().default(false),
+});
+
+type IForm = z.infer<typeof validator>;
+
+export default function AddCohort() {
+ const { projectId } = useAppParams();
+ const trpc = useTRPC();
+ const queryClient = useQueryClient();
+
+ const { register, handleSubmit, formState, control } = useForm<IForm>({
+ resolver: zodResolver(validator),
+ defaultValues: {
+ name: '',
+ description: '',
+ definition: {
+ type: 'event',
+ criteria: {
+ events: [],
+ operator: 'or',
+ },
+ },
+ isStatic: false,
+ },
+ });
+
+ const mutation = useMutation(
+ trpc.cohort.create.mutationOptions({
+ onSuccess() {
+ toast('Success', { description: 'Cohort created.' });
+ queryClient.invalidateQueries(trpc.cohort.pathFilter());
+ popModal();
+ },
+ onError: handleError,
+ }),
+ );
+
+ return (
+ <ModalContent className="max-w-3xl">
+ <ModalHeader title="Create cohort" />
+ <form
+ className="flex flex-col gap-4"
+ onSubmit={handleSubmit((data) => {
+ mutation.mutate({
+ ...data,
+ projectId,
+ definition: data.definition as CohortDefinition,
+ });
+ })}
+ >
+ <InputWithLabel
+ label="Name"
+ placeholder="Name of the cohort"
+ {...register('name')}
+ />
+
+ <WithLabel label="Description">
+ <Textarea
+ placeholder="Optional description"
+ {...register('description')}
+ />
+ </WithLabel>
+
+ <div className="flex items-center gap-2">
+ <Controller
+ name="isStatic"
+ control={control}
+ render={({ field }) => (
+ <Switch
+ id="isStatic"
+ checked={field.value}
+ onCheckedChange={field.onChange}
+ />
+ )}
+ />
+ <Label htmlFor="isStatic" className="cursor-pointer text-sm">
+ Freeze snapshot (don&apos;t auto-refresh)
+ </Label>
+ </div>
+
+ <div>
+ <Label className="mb-2 block">Cohort Criteria</Label>
+ <Controller
+ name="definition"
+ control={control}
+ render={({ field }) => (
+ <CohortCriteriaBuilder
+ definition={field.value as CohortDefinition}
+ onChange={field.onChange}
+ />
+ )}
+ />
+ </div>
+
+ <ButtonContainer>
+ <Button type="button" variant="outline" onClick={() => popModal()}>
+ Cancel
+ </Button>
+ <Button type="submit" disabled={!formState.isDirty}>
+ Create
+ </Button>
+ </ButtonContainer>
+ </form>
+ </ModalContent>
+ );
+}
diff --git a/apps/start/src/modals/edit-cohort.tsx b/apps/start/src/modals/edit-cohort.tsx
new file mode 100644
index 000000000..ab6bbc573
--- /dev/null
+++ b/apps/start/src/modals/edit-cohort.tsx
@@ -0,0 +1,131 @@
+import { ButtonContainer } from '@/components/button-container';
+import { CohortCriteriaBuilder } from '@/components/cohort/cohort-criteria-builder';
+import { InputWithLabel, WithLabel } from '@/components/forms/input-with-label';
+import { Button } from '@/components/ui/button';
+import { Label } from '@/components/ui/label';
+import { Switch } from '@/components/ui/switch';
+import { Textarea } from '@/components/ui/textarea';
+import { handleError, useTRPC } from '@/integrations/trpc/react';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import type { CohortDefinition } from '@openpanel/validation';
+import { Controller, useForm } from 'react-hook-form';
+import { toast } from 'sonner';
+import { z } from 'zod';
+
+import { popModal } from '.';
+import { ModalContent, ModalHeader } from './Modal/Container';
+
+const validator = z.object({
+ name: z.string().min(1, 'Required'),
+ description: z.string().optional(),
+ definition: z.any(),
+ isStatic: z.boolean().default(false),
+});
+
+type IForm = z.infer<typeof validator>;
+
+interface EditCohortProps {
+ id: string;
+ name: string;
+ description?: string | null;
+ definition: CohortDefinition;
+ isStatic: boolean;
+}
+
+export default function EditCohort(props: EditCohortProps) {
+ const trpc = useTRPC();
+ const queryClient = useQueryClient();
+
+ const { register, handleSubmit, formState, control } = useForm<IForm>({
+ resolver: zodResolver(validator),
+ defaultValues: {
+ name: props.name,
+ description: props.description || '',
+ definition: props.definition,
+ isStatic: props.isStatic,
+ },
+ });
+
+ const mutation = useMutation(
+ trpc.cohort.update.mutationOptions({
+ onSuccess() {
+ toast('Success', { description: 'Cohort updated.' });
+ queryClient.invalidateQueries(trpc.cohort.pathFilter());
+ popModal();
+ },
+ onError: handleError,
+ }),
+ );
+
+ return (
+ <ModalContent className="max-w-3xl">
+ <ModalHeader title="Edit cohort" />
+ <form
+ className="flex flex-col gap-4"
+ onSubmit={handleSubmit((data) => {
+ mutation.mutate({
+ id: props.id,
+ name: data.name,
+ description: data.description,
+ definition: data.definition as CohortDefinition,
+ isStatic: data.isStatic,
+ });
+ })}
+ >
+ <InputWithLabel
+ label="Name"
+ placeholder="Name of the cohort"
+ {...register('name')}
+ />
+
+ <WithLabel label="Description">
+ <Textarea
+ placeholder="Optional description"
+ {...register('description')}
+ />
+ </WithLabel>
+
+ <div className="flex items-center gap-2">
+ <Controller
+ name="isStatic"
+ control={control}
+ render={({ field }) => (
+ <Switch
+ id="isStatic"
+ checked={field.value}
+ onCheckedChange={field.onChange}
+ />
+ )}
+ />
+ <Label htmlFor="isStatic" className="cursor-pointer text-sm">
+ Freeze snapshot (don&apos;t auto-refresh)
+ </Label>
+ </div>
+
+ <div>
+ <Label className="mb-2 block">Cohort Criteria</Label>
+ <Controller
+ name="definition"
+ control={control}
+ render={({ field }) => (
+ <CohortCriteriaBuilder
+ definition={field.value as CohortDefinition}
+ onChange={field.onChange}
+ />
+ )}
+ />
+ </div>
+
+ <ButtonContainer>
+ <Button type="button" variant="outline" onClick={() => popModal()}>
+ Cancel
+ </Button>
+ <Button type="submit" disabled={!formState.isDirty}>
+ Save changes
+ </Button>
+ </ButtonContainer>
+ </form>
+ </ModalContent>
+ );
+}
diff --git a/apps/start/src/modals/index.tsx b/apps/start/src/modals/index.tsx
index 36188f4a0..36d9f27a9 100644
--- a/apps/start/src/modals/index.tsx
+++ b/apps/start/src/modals/index.tsx
@@ -1,5 +1,6 @@
import { createPushModal } from 'pushmodal';
import AddClient from './add-client';
+import AddCohort from './add-cohort';
import AddDashboard from './add-dashboard';
import AddGroup from './add-group';
import AddImport from './add-import';
@@ -14,6 +15,7 @@ import CreateInvite from './create-invite';
import DateRangerPicker from './date-ranger-picker';
import DateTimePicker from './date-time-picker';
import EditClient from './edit-client';
+import EditCohort from './edit-cohort';
import EditDashboard from './edit-dashboard';
import EditEvent from './edit-event';
import EditGroup from './edit-group';
@@ -40,6 +42,8 @@ const modals = {
PageDetails,
AddGroup,
EditGroup,
+ AddCohort,
+ EditCohort,
OverviewTopPagesModal,
OverviewTopGenericModal,
RequestPasswordReset,
diff --git a/apps/start/src/routeTree.gen.ts b/apps/start/src/routeTree.gen.ts
index f706c68f4..6881e99d4 100644
--- a/apps/start/src/routeTree.gen.ts
+++ b/apps/start/src/routeTree.gen.ts
@@ -50,6 +50,7 @@ import { Route as AppOrganizationIdProjectIdPagesRouteImport } from './routes/_a
import { Route as AppOrganizationIdProjectIdInsightsRouteImport } from './routes/_app.$organizationId.$projectId.insights'
import { Route as AppOrganizationIdProjectIdGroupsRouteImport } from './routes/_app.$organizationId.$projectId.groups'
import { Route as AppOrganizationIdProjectIdDashboardsRouteImport } from './routes/_app.$organizationId.$projectId.dashboards'
+import { Route as AppOrganizationIdProjectIdCohortsRouteImport } from './routes/_app.$organizationId.$projectId.cohorts'
import { Route as AppOrganizationIdProfileTabsIndexRouteImport } from './routes/_app.$organizationId.profile._tabs.index'
import { Route as AppOrganizationIdMembersTabsIndexRouteImport } from './routes/_app.$organizationId.members._tabs.index'
import { Route as AppOrganizationIdIntegrationsTabsIndexRouteImport } from './routes/_app.$organizationId.integrations._tabs.index'
@@ -370,6 +371,12 @@ const AppOrganizationIdProjectIdDashboardsRoute =
path: '/dashboards',
getParentRoute: () => AppOrganizationIdProjectIdRoute,
} as any)
+const AppOrganizationIdProjectIdCohortsRoute =
+ AppOrganizationIdProjectIdCohortsRouteImport.update({
+ id: '/cohorts',
+ path: '/cohorts',
+ getParentRoute: () => AppOrganizationIdProjectIdRoute,
+ } as any)
const AppOrganizationIdProjectIdProfilesProfileIdRoute =
AppOrganizationIdProjectIdProfilesProfileIdRouteImport.update({
id: '/$profileId',
@@ -656,6 +663,7 @@ export interface FileRoutesByFullPath {
'/share/overview/$shareId': typeof ShareOverviewShareIdRoute
'/share/report/$shareId': typeof ShareReportShareIdRoute
'/$organizationId/': typeof AppOrganizationIdIndexRoute
+ '/$organizationId/$projectId/cohorts': typeof AppOrganizationIdProjectIdCohortsRoute
'/$organizationId/$projectId/dashboards': typeof AppOrganizationIdProjectIdDashboardsRoute
'/$organizationId/$projectId/groups': typeof AppOrganizationIdProjectIdGroupsRoute
'/$organizationId/$projectId/insights': typeof AppOrganizationIdProjectIdInsightsRoute
@@ -734,6 +742,7 @@ export interface FileRoutesByTo {
'/share/overview/$shareId': typeof ShareOverviewShareIdRoute
'/share/report/$shareId': typeof ShareReportShareIdRoute
'/$organizationId': typeof AppOrganizationIdIndexRoute
+ '/$organizationId/$projectId/cohorts': typeof AppOrganizationIdProjectIdCohortsRoute
'/$organizationId/$projectId/dashboards': typeof AppOrganizationIdProjectIdDashboardsRoute
'/$organizationId/$projectId/groups': typeof AppOrganizationIdProjectIdGroupsRoute
'/$organizationId/$projectId/insights': typeof AppOrganizationIdProjectIdInsightsRoute
@@ -810,6 +819,7 @@ export interface FileRoutesById {
'/share/overview/$shareId': typeof ShareOverviewShareIdRoute
'/share/report/$shareId': typeof ShareReportShareIdRoute
'/_app/$organizationId/': typeof AppOrganizationIdIndexRoute
+ '/_app/$organizationId/$projectId/cohorts': typeof AppOrganizationIdProjectIdCohortsRoute
'/_app/$organizationId/$projectId/dashboards': typeof AppOrganizationIdProjectIdDashboardsRoute
'/_app/$organizationId/$projectId/groups': typeof AppOrganizationIdProjectIdGroupsRoute
'/_app/$organizationId/$projectId/insights': typeof AppOrganizationIdProjectIdInsightsRoute
@@ -901,6 +911,7 @@ export interface FileRouteTypes {
| '/share/overview/$shareId'
| '/share/report/$shareId'
| '/$organizationId/'
+ | '/$organizationId/$projectId/cohorts'
| '/$organizationId/$projectId/dashboards'
| '/$organizationId/$projectId/groups'
| '/$organizationId/$projectId/insights'
@@ -979,6 +990,7 @@ export interface FileRouteTypes {
| '/share/overview/$shareId'
| '/share/report/$shareId'
| '/$organizationId'
+ | '/$organizationId/$projectId/cohorts'
| '/$organizationId/$projectId/dashboards'
| '/$organizationId/$projectId/groups'
| '/$organizationId/$projectId/insights'
@@ -1054,6 +1066,7 @@ export interface FileRouteTypes {
| '/share/overview/$shareId'
| '/share/report/$shareId'
| '/_app/$organizationId/'
+ | '/_app/$organizationId/$projectId/cohorts'
| '/_app/$organizationId/$projectId/dashboards'
| '/_app/$organizationId/$projectId/groups'
| '/_app/$organizationId/$projectId/insights'
@@ -1465,6 +1478,13 @@ declare module '@tanstack/react-router' {
preLoaderRoute: typeof AppOrganizationIdProjectIdDashboardsRouteImport
parentRoute: typeof AppOrganizationIdProjectIdRoute
}
+ '/_app/$organizationId/$projectId/cohorts': {
+ id: '/_app/$organizationId/$projectId/cohorts'
+ path: '/cohorts'
+ fullPath: '/$organizationId/$projectId/cohorts'
+ preLoaderRoute: typeof AppOrganizationIdProjectIdCohortsRouteImport
+ parentRoute: typeof AppOrganizationIdProjectIdRoute
+ }
'/_app/$organizationId/$projectId/profiles/$profileId': {
id: '/_app/$organizationId/$projectId/profiles/$profileId'
path: '/$profileId'
@@ -2027,6 +2047,7 @@ const AppOrganizationIdProjectIdGroupsGroupIdRouteWithChildren =
)
interface AppOrganizationIdProjectIdRouteChildren {
+ AppOrganizationIdProjectIdCohortsRoute: typeof AppOrganizationIdProjectIdCohortsRoute
AppOrganizationIdProjectIdDashboardsRoute: typeof AppOrganizationIdProjectIdDashboardsRoute
AppOrganizationIdProjectIdGroupsRoute: typeof AppOrganizationIdProjectIdGroupsRoute
AppOrganizationIdProjectIdInsightsRoute: typeof AppOrganizationIdProjectIdInsightsRoute
@@ -2049,6 +2070,8 @@ interface AppOrganizationIdProjectIdRouteChildren {
const AppOrganizationIdProjectIdRouteChildren: AppOrganizationIdProjectIdRouteChildren =
{
+ AppOrganizationIdProjectIdCohortsRoute:
+ AppOrganizationIdProjectIdCohortsRoute,
AppOrganizationIdProjectIdDashboardsRoute:
AppOrganizationIdProjectIdDashboardsRoute,
AppOrganizationIdProjectIdGroupsRoute:
diff --git a/apps/start/src/routes/_app.$organizationId.$projectId.cohorts.tsx b/apps/start/src/routes/_app.$organizationId.$projectId.cohorts.tsx
new file mode 100644
index 000000000..bae875661
--- /dev/null
+++ b/apps/start/src/routes/_app.$organizationId.$projectId.cohorts.tsx
@@ -0,0 +1,216 @@
+import { Card, CardActions, CardActionsItem } from '@/components/card';
+import { FullPageEmptyState } from '@/components/full-page-empty-state';
+import FullPageLoadingState from '@/components/full-page-loading-state';
+import { PageContainer } from '@/components/page-container';
+import { PageHeader } from '@/components/page-header';
+import { Button } from '@/components/ui/button';
+import { handleError, useTRPC } from '@/integrations/trpc/react';
+import { pushModal, showConfirm } from '@/modals';
+import { cn } from '@/utils/cn';
+import { cohortMembersToCSV, downloadCSV } from '@/utils/csv-download';
+import { PAGE_TITLES, createProjectTitle } from '@/utils/title';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { createFileRoute } from '@tanstack/react-router';
+import { format } from 'date-fns';
+import {
+ DownloadIcon,
+ PencilIcon,
+ PlusIcon,
+ RefreshCwIcon,
+ TrashIcon,
+ UsersIcon,
+} from 'lucide-react';
+import { toast } from 'sonner';
+
+export const Route = createFileRoute(
+ '/_app/$organizationId/$projectId/cohorts',
+)({
+ component: Component,
+ head: () => ({
+ meta: [{ title: createProjectTitle(PAGE_TITLES.COHORTS) }],
+ }),
+ async loader({ context, params }) {
+ await context.queryClient.prefetchQuery(
+ context.trpc.cohort.list.queryOptions({
+ projectId: params.projectId,
+ includeCount: true,
+ }),
+ );
+ },
+ pendingComponent: FullPageLoadingState,
+});
+
+function Component() {
+ const { projectId } = Route.useParams();
+ const trpc = useTRPC();
+ const query = useQuery(
+ trpc.cohort.list.queryOptions({
+ projectId,
+ includeCount: true,
+ }),
+ );
+ const cohorts = query.data ?? [];
+
+ const deletion = useMutation(
+ trpc.cohort.delete.mutationOptions({
+ onError: handleError,
+ onSuccess() {
+ query.refetch();
+ toast('Success', { description: 'Cohort deleted.' });
+ },
+ }),
+ );
+
+ const refresh = useMutation(
+ trpc.cohort.refresh.mutationOptions({
+ onError: handleError,
+ onSuccess() {
+ query.refetch();
+ toast('Success', { description: 'Cohort refresh queued.' });
+ },
+ }),
+ );
+
+ const queryClient = useQueryClient();
+
+ async function handleDownload(cohortId: string, cohortName: string) {
+ try {
+ const result = await queryClient.fetchQuery(
+ trpc.cohort.exportProfiles.queryOptions({ cohortId }),
+ );
+ const csv = cohortMembersToCSV(result.profileIds);
+ downloadCSV(csv, `${cohortName}-members.csv`);
+ } catch {
+ toast.error('Failed to download cohort members');
+ }
+ }
+
+ if (cohorts.length === 0) {
+ return (
+ <FullPageEmptyState title="No cohorts" icon={UsersIcon}>
+ <p>You have not created any cohorts for this project yet</p>
+ <Button
+ onClick={() => pushModal('AddCohort')}
+ className="mt-14"
+ icon={PlusIcon}
+ >
+ Create cohort
+ </Button>
+ </FullPageEmptyState>
+ );
+ }
+
+ return (
+ <PageContainer>
+ <PageHeader
+ title="Cohorts"
+ description="Create and manage user segments based on events and properties"
+ className="mb-8"
+ actions={
+ <Button icon={PlusIcon} onClick={() => pushModal('AddCohort')}>
+ <span className="max-sm:hidden">Create cohort</span>
+ <span className="sm:hidden">Cohort</span>
+ </Button>
+ }
+ />
+ <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 md:grid-cols-3">
+ {cohorts.map((cohort) => {
+ const count =
+ 'currentCount' in cohort ? cohort.currentCount : cohort.profileCount;
+ const displayCount = count ?? 0;
+ return (
+ <Card key={cohort.id} hover>
+ <div className="flex flex-col p-4">
+ <div className="col gap-2">
+ <div className="font-medium">{cohort.name}</div>
+ {cohort.description && (
+ <div className="line-clamp-2 text-sm text-muted-foreground">
+ {cohort.description}
+ </div>
+ )}
+ <div className="mt-2 flex items-center gap-4 text-sm text-muted-foreground">
+ <div className="flex items-center gap-1">
+ <UsersIcon size={14} />
+ <span>
+ {displayCount.toLocaleString()}{' '}
+ {displayCount === 1 ? 'member' : 'members'}
+ </span>
+ </div>
+ {cohort.lastComputedAt && (
+ <div className={cn('text-xs')}>
+ Updated{' '}
+ {format(cohort.lastComputedAt, 'MMM d, HH:mm')}
+ </div>
+ )}
+ </div>
+ {cohort.isStatic && (
+ <div className="mt-1 inline-flex w-fit rounded bg-blue-100 px-2 py-0.5 text-xs text-blue-700">
+ Static
+ </div>
+ )}
+ </div>
+ </div>
+
+ <CardActions>
+ <CardActionsItem className="w-full" asChild>
+ <button
+ type="button"
+ onClick={() => handleDownload(cohort.id, cohort.name)}
+ >
+ <DownloadIcon size={16} />
+ Download
+ </button>
+ </CardActionsItem>
+ {!cohort.isStatic && (
+ <CardActionsItem className="w-full" asChild>
+ <button
+ type="button"
+ onClick={() => {
+ refresh.mutate({ cohortId: cohort.id });
+ }}
+ >
+ <RefreshCwIcon size={16} />
+ Refresh
+ </button>
+ </CardActionsItem>
+ )}
+ <CardActionsItem className="w-full" asChild>
+ <button
+ type="button"
+ onClick={() => {
+ pushModal('EditCohort', {
+ id: cohort.id,
+ name: cohort.name,
+ description: cohort.description,
+ definition: cohort.definition as never,
+ isStatic: cohort.isStatic,
+ });
+ }}
+ >
+ <PencilIcon size={16} />
+ Edit
+ </button>
+ </CardActionsItem>
+ <CardActionsItem className="w-full text-destructive" asChild>
+ <button
+ type="button"
+ onClick={() => {
+ showConfirm({
+ title: 'Delete cohort',
+ text: 'Are you sure you want to delete this cohort? This action cannot be undone.',
+ onConfirm: () => deletion.mutate({ id: cohort.id }),
+ });
+ }}
+ >
+ <TrashIcon size={16} />
+ Delete
+ </button>
+ </CardActionsItem>
+ </CardActions>
+ </Card>
+ );
+ })}
+ </div>
+ </PageContainer>
+ );
+}
diff --git a/apps/start/src/utils/csv-download.ts b/apps/start/src/utils/csv-download.ts
new file mode 100644
index 000000000..379ac8734
--- /dev/null
+++ b/apps/start/src/utils/csv-download.ts
@@ -0,0 +1,29 @@
+function escapeCsvValue(value: string | number | null | undefined): string {
+ if (value === null || value === undefined) return '';
+ const str = String(value);
+ if (str.includes(',') || str.includes('"') || str.includes('\n')) {
+ return `"${str.replace(/"/g, '""')}"`;
+ }
+ return str;
+}
+
+function buildCSV(rows: (string | number | null | undefined)[][]): string {
+ return rows.map((row) => row.map(escapeCsvValue).join(',')).join('\n');
+}
+
+export function downloadCSV(content: string, filename: string): void {
+ const blob = new Blob([content], { type: 'text/csv;charset=utf-8;' });
+ const url = URL.createObjectURL(blob);
+ const link = document.createElement('a');
+ link.href = url;
+ link.download = filename;
+ document.body.appendChild(link);
+ link.click();
+ document.body.removeChild(link);
+ URL.revokeObjectURL(url);
+}
+
+export function cohortMembersToCSV(profileIds: string[]): string {
+ if (!profileIds.length) return '';
+ return buildCSV([['profile_id'], ...profileIds.map((id) => [id])]);
+}
diff --git a/apps/start/src/utils/title.ts b/apps/start/src/utils/title.ts
index 1d310735e..7d88dd98d 100644
--- a/apps/start/src/utils/title.ts
+++ b/apps/start/src/utils/title.ts
@@ -98,6 +98,8 @@ export const PAGE_TITLES = {
// Groups
GROUPS: 'Groups',
GROUP_DETAILS: 'Group details',
+ // Cohorts
+ COHORTS: 'Cohorts',
// Sub-sections
CONVERSIONS: 'Conversions',
diff --git a/apps/worker/src/boot-cron.ts b/apps/worker/src/boot-cron.ts
index f49a14355..383006357 100644
--- a/apps/worker/src/boot-cron.ts
+++ b/apps/worker/src/boot-cron.ts
@@ -88,6 +88,11 @@ export async function bootCron() {
type: 'gscSync',
pattern: '0 3 * * *',
},
+ {
+ name: 'cohortRefresh',
+ type: 'cohortRefresh',
+ pattern: '*/30 * * * *',
+ },
];
if (process.env.SELF_HOSTED && process.env.NODE_ENV === 'production') {
diff --git a/apps/worker/src/boot-workers.ts b/apps/worker/src/boot-workers.ts
index f63955650..f58d4881f 100644
--- a/apps/worker/src/boot-workers.ts
+++ b/apps/worker/src/boot-workers.ts
@@ -1,6 +1,7 @@
import { performance } from 'node:perf_hooks';
import { setTimeout as sleep } from 'node:timers/promises';
import {
+ cohortComputeQueue,
cronQueue,
EVENTS_GROUP_QUEUES_SHARDS,
type EventsQueuePayloadIncomingEvent,
@@ -17,6 +18,7 @@ import { getRedisQueue } from '@openpanel/redis';
import type { Queue, WorkerOptions } from 'bullmq';
import { Worker } from 'bullmq';
import { Worker as GroupWorker } from 'groupmq';
+import { cohortComputeJob } from './jobs/cohort.compute';
import { cronJob } from './jobs/cron';
import { incomingEvent } from './jobs/events.incoming-event';
import { gscJob } from './jobs/gsc';
@@ -59,6 +61,7 @@ function getEnabledQueues(): QueueName[] {
'import',
'insights',
'gsc',
+ 'cohortCompute',
];
}
@@ -221,6 +224,21 @@ export function bootWorkers() {
logger.info('Started worker for gsc', { concurrency });
}
+ // Start cohortCompute worker
+ if (enabledQueues.includes('cohortCompute')) {
+ const concurrency = getConcurrencyFor('cohortCompute', 2);
+ const cohortComputeWorker = new Worker(
+ cohortComputeQueue.name,
+ cohortComputeJob,
+ {
+ ...workerOptions,
+ concurrency,
+ },
+ );
+ workers.push(cohortComputeWorker);
+ logger.info('Started worker for cohortCompute', { concurrency });
+ }
+
if (workers.length === 0) {
logger.warn(
'No workers started. Check ENABLED_QUEUES environment variable.'
diff --git a/apps/worker/src/index.ts b/apps/worker/src/index.ts
index 1223153dd..ff9c98270 100644
--- a/apps/worker/src/index.ts
+++ b/apps/worker/src/index.ts
@@ -3,6 +3,7 @@ import { BullMQAdapter } from '@bull-board/api/bullMQAdapter';
import { ExpressAdapter } from '@bull-board/express';
import { createInitialSalts } from '@openpanel/db';
import {
+ cohortComputeQueue,
cronQueue,
eventsGroupQueues,
gscQueue,
@@ -48,6 +49,7 @@ async function start() {
new BullMQAdapter(importQueue),
new BullMQAdapter(insightsQueue),
new BullMQAdapter(gscQueue),
+ new BullMQAdapter(cohortComputeQueue),
],
serverAdapter,
});
diff --git a/apps/worker/src/jobs/cohort.compute.ts b/apps/worker/src/jobs/cohort.compute.ts
new file mode 100644
index 000000000..9665ef1e1
--- /dev/null
+++ b/apps/worker/src/jobs/cohort.compute.ts
@@ -0,0 +1,8 @@
+import type { Job } from 'bullmq';
+
+import { updateCohortMembership } from '@openpanel/db';
+import type { CohortComputePayload } from '@openpanel/queue';
+
+export async function cohortComputeJob(job: Job<CohortComputePayload>) {
+ await updateCohortMembership(job.data.cohortId);
+}
diff --git a/apps/worker/src/jobs/cron.cohort-refresh.ts b/apps/worker/src/jobs/cron.cohort-refresh.ts
new file mode 100644
index 000000000..3c9736acf
--- /dev/null
+++ b/apps/worker/src/jobs/cron.cohort-refresh.ts
@@ -0,0 +1,23 @@
+import { db } from '@openpanel/db';
+import { cohortComputeQueue } from '@openpanel/queue';
+
+export async function cohortRefreshCronJob() {
+ const cohorts = await db.cohort.findMany({
+ where: { isStatic: false },
+ select: { id: true },
+ });
+
+ await Promise.all(
+ cohorts.map((cohort) =>
+ cohortComputeQueue.add(
+ 'cohortCompute',
+ { cohortId: cohort.id },
+ {
+ jobId: `cohort-${cohort.id}`,
+ removeOnComplete: { age: 3600 },
+ removeOnFail: { age: 86400 },
+ },
+ ),
+ ),
+ );
+}
diff --git a/apps/worker/src/jobs/cron.ts b/apps/worker/src/jobs/cron.ts
index c6614d150..1cc45758f 100644
--- a/apps/worker/src/jobs/cron.ts
+++ b/apps/worker/src/jobs/cron.ts
@@ -3,6 +3,7 @@ import type { Job } from 'bullmq';
import { eventBuffer, groupBuffer, profileBackfillBuffer, profileBuffer, replayBuffer, sessionBuffer } from '@openpanel/db';
import type { CronQueuePayload } from '@openpanel/queue';
+import { cohortRefreshCronJob } from './cron.cohort-refresh';
import { jobdeleteProjects } from './cron.delete-projects';
import { gscSyncAllJob } from './gsc';
import { onboardingJob } from './cron.onboarding';
@@ -48,5 +49,8 @@ export async function cronJob(job: Job<CronQueuePayload>) {
case 'gscSync': {
return await gscSyncAllJob();
}
+ case 'cohortRefresh': {
+ return await cohortRefreshCronJob();
+ }
}
}
diff --git a/packages/constants/index.ts b/packages/constants/index.ts
index 48c47618a..45c694942 100644
--- a/packages/constants/index.ts
+++ b/packages/constants/index.ts
@@ -93,6 +93,8 @@ export const operators = {
lt: 'Less than',
gte: 'Greater than or equal to',
lte: 'Less than or equal to',
+ inCohort: 'In cohort',
+ notInCohort: 'Not in cohort',
} as const;
export const chartTypes = {
diff --git a/packages/db/code-migrations/13-cohorts.ts b/packages/db/code-migrations/13-cohorts.ts
new file mode 100644
index 000000000..ef3a4c361
--- /dev/null
+++ b/packages/db/code-migrations/13-cohorts.ts
@@ -0,0 +1,152 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { TABLE_NAMES } from '../src/clickhouse/client';
+import {
+ createMaterializedView,
+ createTable,
+ dropTable,
+ getExistingTables,
+ runClickhouseMigrationCommands,
+} from '../src/clickhouse/migration';
+import { getIsCluster } from './helpers';
+
+export async function up() {
+ const replicatedVersion = '1';
+ const existingTables = await getExistingTables();
+ const isClustered = getIsCluster();
+
+ const sqls: string[] = [];
+
+ // 1. cohort_members — which profile_ids belong to which cohorts.
+ // ReplacingMergeTree(version) = newer compute wins on merge.
+ if (
+ !existingTables.includes(`${TABLE_NAMES.cohort_members}_distributed`) &&
+ !existingTables.includes(TABLE_NAMES.cohort_members)
+ ) {
+ sqls.push(
+ ...createTable({
+ name: TABLE_NAMES.cohort_members,
+ columns: [
+ '`project_id` String CODEC(ZSTD(3))',
+ '`cohort_id` String CODEC(ZSTD(3))',
+ '`profile_id` String CODEC(ZSTD(3))',
+ '`matched_at` DateTime DEFAULT now()',
+ '`matching_properties` Map(String, String) CODEC(ZSTD(3))',
+ '`version` UInt64 DEFAULT 1',
+ ],
+ indices: [
+ 'INDEX idx_profile profile_id TYPE bloom_filter GRANULARITY 1',
+ 'INDEX idx_cohort cohort_id TYPE bloom_filter GRANULARITY 1',
+ ],
+ engine: 'ReplacingMergeTree(version)',
+ orderBy: ['project_id', 'cohort_id', 'profile_id'],
+ partitionBy: 'toYYYYMM(matched_at)',
+ settings: {
+ index_granularity: 8192,
+ },
+ distributionHash: 'cityHash64(project_id, cohort_id)',
+ replicatedVersion,
+ isClustered,
+ }),
+ );
+ }
+
+ // 2. cohort_metadata — cached member count + sample profiles per cohort.
+ if (
+ !existingTables.includes(`${TABLE_NAMES.cohort_metadata}_distributed`) &&
+ !existingTables.includes(TABLE_NAMES.cohort_metadata)
+ ) {
+ sqls.push(
+ ...createTable({
+ name: TABLE_NAMES.cohort_metadata,
+ columns: [
+ '`project_id` String',
+ '`cohort_id` String',
+ '`member_count` UInt64',
+ '`last_computed_at` DateTime',
+ '`sample_profiles` Array(String)',
+ '`version` UInt64 DEFAULT 1',
+ ],
+ engine: 'ReplacingMergeTree(version)',
+ orderBy: ['project_id', 'cohort_id'],
+ settings: {
+ index_granularity: 8192,
+ },
+ distributionHash: 'cityHash64(project_id, cohort_id)',
+ replicatedVersion,
+ isClustered,
+ }),
+ );
+ }
+
+ // 3. profile_event_summary_mv — aggregates events per (profile, event, day).
+ // Used by cohort compute when frequency filters are present.
+ // populate: false — we have a cluster with lots of events; backfill ad-hoc.
+ if (
+ !existingTables.includes(
+ `${TABLE_NAMES.profile_event_summary_mv}_distributed`,
+ ) &&
+ !existingTables.includes(TABLE_NAMES.profile_event_summary_mv)
+ ) {
+ sqls.push(
+ ...createMaterializedView({
+ name: TABLE_NAMES.profile_event_summary_mv,
+ tableName: 'events',
+ engine: 'AggregatingMergeTree()',
+ orderBy: ['project_id', 'profile_id', 'name', 'event_date'],
+ partitionBy: 'toYYYYMM(event_date)',
+ query: `SELECT
+ project_id,
+ profile_id,
+ name,
+ toStartOfDay(created_at) AS event_date,
+ countState() AS event_count,
+ minState(created_at) AS first_event_time,
+ maxState(created_at) AS last_event_time,
+ sumState(duration) AS total_duration
+ FROM {events}
+ WHERE profile_id != device_id
+ GROUP BY project_id, profile_id, name, event_date`,
+ distributionHash: 'cityHash64(project_id, profile_id)',
+ replicatedVersion,
+ isClustered,
+ populate: false,
+ }),
+ );
+ }
+
+ fs.writeFileSync(
+ path.join(import.meta.filename.replace('.ts', '.sql')),
+ sqls
+ .map((sql) =>
+ sql
+ .trim()
+ .replace(/;$/, '')
+ .replace(/\n{2,}/g, '\n')
+ .concat(';'),
+ )
+ .join('\n\n---\n\n'),
+ );
+
+ if (!process.argv.includes('--dry')) {
+ await runClickhouseMigrationCommands(sqls);
+ }
+}
+
+export async function down() {
+ const isClustered = getIsCluster();
+
+ const sqls = [
+ dropTable(`${TABLE_NAMES.profile_event_summary_mv}_distributed`, isClustered),
+ dropTable(`${TABLE_NAMES.profile_event_summary_mv}_replicated`, isClustered),
+ dropTable(TABLE_NAMES.profile_event_summary_mv, isClustered),
+ dropTable(`${TABLE_NAMES.cohort_metadata}_distributed`, isClustered),
+ dropTable(`${TABLE_NAMES.cohort_metadata}_replicated`, isClustered),
+ dropTable(TABLE_NAMES.cohort_metadata, isClustered),
+ dropTable(`${TABLE_NAMES.cohort_members}_distributed`, isClustered),
+ dropTable(`${TABLE_NAMES.cohort_members}_replicated`, isClustered),
+ dropTable(TABLE_NAMES.cohort_members, isClustered),
+ ];
+
+ await runClickhouseMigrationCommands(sqls);
+}
diff --git a/packages/db/code-migrations/14-profile-event-property-summary-mv.ts b/packages/db/code-migrations/14-profile-event-property-summary-mv.ts
new file mode 100644
index 000000000..34e0e6a85
--- /dev/null
+++ b/packages/db/code-migrations/14-profile-event-property-summary-mv.ts
@@ -0,0 +1,102 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { TABLE_NAMES } from '../src/clickhouse/client';
+import {
+ createMaterializedView,
+ dropTable,
+ getExistingTables,
+ runClickhouseMigrationCommands,
+} from '../src/clickhouse/migration';
+import { getIsCluster } from './helpers';
+
+// Per-property breakdown of profile events, used when cohort event criteria
+// filter on properties.<key> AND as a future fast path for property breakdowns
+// in chart queries. populate: false — backfill ad-hoc.
+//
+// NOTE: fork references this MV but never shipped a migration for it; we own
+// the authoritative DDL.
+export async function up() {
+ const replicatedVersion = '1';
+ const existingTables = await getExistingTables();
+ const isClustered = getIsCluster();
+
+ const sqls: string[] = [];
+
+ if (
+ !existingTables.includes(
+ `${TABLE_NAMES.profile_event_property_summary_mv}_distributed`,
+ ) &&
+ !existingTables.includes(TABLE_NAMES.profile_event_property_summary_mv)
+ ) {
+ sqls.push(
+ ...createMaterializedView({
+ name: TABLE_NAMES.profile_event_property_summary_mv,
+ tableName: 'events',
+ engine: 'AggregatingMergeTree()',
+ orderBy: [
+ 'project_id',
+ 'profile_id',
+ 'name',
+ 'property_key',
+ 'event_date',
+ ],
+ partitionBy: 'toYYYYMM(event_date)',
+ query: `SELECT
+ project_id,
+ profile_id,
+ name,
+ property_key,
+ property_value,
+ toStartOfDay(created_at) AS event_date,
+ countState() AS event_count,
+ minState(created_at) AS first_event_time,
+ maxState(created_at) AS last_event_time
+ FROM {events}
+ ARRAY JOIN mapKeys(properties) AS property_key, mapValues(properties) AS property_value
+ WHERE profile_id != device_id
+ AND property_key != ''
+ AND property_value != ''
+ GROUP BY project_id, profile_id, name, property_key, property_value, event_date`,
+ distributionHash: 'cityHash64(project_id, profile_id)',
+ replicatedVersion,
+ isClustered,
+ populate: false,
+ }),
+ );
+ }
+
+ fs.writeFileSync(
+ path.join(import.meta.filename.replace('.ts', '.sql')),
+ sqls
+ .map((sql) =>
+ sql
+ .trim()
+ .replace(/;$/, '')
+ .replace(/\n{2,}/g, '\n')
+ .concat(';'),
+ )
+ .join('\n\n---\n\n'),
+ );
+
+ if (!process.argv.includes('--dry')) {
+ await runClickhouseMigrationCommands(sqls);
+ }
+}
+
+export async function down() {
+ const isClustered = getIsCluster();
+
+ const sqls = [
+ dropTable(
+ `${TABLE_NAMES.profile_event_property_summary_mv}_distributed`,
+ isClustered,
+ ),
+ dropTable(
+ `${TABLE_NAMES.profile_event_property_summary_mv}_replicated`,
+ isClustered,
+ ),
+ dropTable(TABLE_NAMES.profile_event_property_summary_mv, isClustered),
+ ];
+
+ await runClickhouseMigrationCommands(sqls);
+}
diff --git a/packages/db/index.ts b/packages/db/index.ts
index c2e6752c5..781f959fe 100644
--- a/packages/db/index.ts
+++ b/packages/db/index.ts
@@ -9,6 +9,7 @@ export * from './src/prisma-client';
export * from './src/services/access.service';
export * from './src/services/chart.service';
export * from './src/services/clients.service';
+export * from './src/services/cohort.service';
export * from './src/services/conversation.service';
export * from './src/services/conversion.service';
export * from './src/services/dashboard.service';
diff --git a/packages/db/prisma/migrations/20260417120136_add_cohorts_table/migration.sql b/packages/db/prisma/migrations/20260417120136_add_cohorts_table/migration.sql
new file mode 100644
index 000000000..493ed56c4
--- /dev/null
+++ b/packages/db/prisma/migrations/20260417120136_add_cohorts_table/migration.sql
@@ -0,0 +1,21 @@
+-- CreateTable
+CREATE TABLE "public"."cohorts" (
+ "id" UUID NOT NULL DEFAULT gen_random_uuid(),
+ "name" TEXT NOT NULL,
+ "description" TEXT,
+ "projectId" TEXT NOT NULL,
+ "definition" JSONB NOT NULL DEFAULT '{}',
+ "isStatic" BOOLEAN NOT NULL DEFAULT false,
+ "profileCount" INTEGER NOT NULL DEFAULT 0,
+ "lastComputedAt" TIMESTAMP(3),
+ "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ "updatedAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+ CONSTRAINT "cohorts_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "cohorts_projectId_idx" ON "public"."cohorts"("projectId");
+
+-- AddForeignKey
+ALTER TABLE "public"."cohorts" ADD CONSTRAINT "cohorts_projectId_fkey" FOREIGN KEY ("projectId") REFERENCES "public"."projects"("id") ON DELETE CASCADE ON UPDATE CASCADE;
diff --git a/packages/db/prisma/schema.prisma b/packages/db/prisma/schema.prisma
index b428052f9..a1083cabe 100644
--- a/packages/db/prisma/schema.prisma
+++ b/packages/db/prisma/schema.prisma
@@ -225,6 +225,7 @@ model Project {
notifications Notification[]
imports Import[]
gscConnection GscConnection?
+ cohorts Cohort[]
// When deleteAt > now(), the project will be deleted
deleteAt DateTime?
@@ -236,6 +237,24 @@ model Project {
@@map("projects")
}
+model Cohort {
+ id String @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
+ name String
+ description String?
+ projectId String
+ project Project @relation(fields: [projectId], references: [id], onDelete: Cascade)
+ /// [IPrismaCohortDefinition]
+ definition Json @default("{}")
+ isStatic Boolean @default(false)
+ profileCount Int @default(0)
+ lastComputedAt DateTime?
+ createdAt DateTime @default(now())
+ updatedAt DateTime @default(now()) @updatedAt
+
+ @@index([projectId])
+ @@map("cohorts")
+}
+
enum AccessLevel {
read
diff --git a/packages/db/src/clickhouse/client.ts b/packages/db/src/clickhouse/client.ts
index dd81877a5..88f9eca10 100644
--- a/packages/db/src/clickhouse/client.ts
+++ b/packages/db/src/clickhouse/client.ts
@@ -62,6 +62,10 @@ export const TABLE_NAMES = {
gsc_pages_daily: 'gsc_pages_daily',
gsc_queries_daily: 'gsc_queries_daily',
groups: 'groups',
+ cohort_members: 'cohort_members',
+ cohort_metadata: 'cohort_metadata',
+ profile_event_summary_mv: 'profile_event_summary_mv',
+ profile_event_property_summary_mv: 'profile_event_property_summary_mv',
};
/**
diff --git a/packages/db/src/engine/fetch.ts b/packages/db/src/engine/fetch.ts
index ecc377686..6e8056dde 100644
--- a/packages/db/src/engine/fetch.ts
+++ b/packages/db/src/engine/fetch.ts
@@ -57,7 +57,7 @@ export async function fetch(plan: Plan): Promise<ConcreteSeries[]> {
// Execute query
let queryResult = await chQuery<ISerieDataItem>(
- getChartSql({ ...queryInput, timezone: plan.timezone }),
+ await getChartSql({ ...queryInput, timezone: plan.timezone }),
{
session_timezone: plan.timezone,
},
@@ -66,7 +66,7 @@ export async function fetch(plan: Plan): Promise<ConcreteSeries[]> {
// Fallback: if no results with breakdowns, try without breakdowns
if (queryResult.length === 0 && plan.input.breakdowns.length > 0) {
queryResult = await chQuery<ISerieDataItem>(
- getChartSql({
+ await getChartSql({
...queryInput,
breakdowns: [],
timezone: plan.timezone,
diff --git a/packages/db/src/engine/index.ts b/packages/db/src/engine/index.ts
index b6da4fd4d..88a7e7bd6 100644
--- a/packages/db/src/engine/index.ts
+++ b/packages/db/src/engine/index.ts
@@ -133,7 +133,7 @@ export async function executeAggregateChart(
// Execute aggregate query
let queryResult = await chQuery<ISerieDataItem>(
- getAggregateChartSql(queryInput),
+ await getAggregateChartSql(queryInput),
{
session_timezone: timezone,
}
@@ -142,7 +142,7 @@ export async function executeAggregateChart(
// Fallback: if no results with breakdowns, try without breakdowns
if (queryResult.length === 0 && normalized.breakdowns.length > 0) {
queryResult = await chQuery<ISerieDataItem>(
- getAggregateChartSql({
+ await getAggregateChartSql({
...queryInput,
breakdowns: [],
}),
@@ -258,7 +258,7 @@ export async function executeAggregateChart(
};
let queryResult = await chQuery<ISerieDataItem>(
- getAggregateChartSql(queryInput),
+ await getAggregateChartSql(queryInput),
{
session_timezone: timezone,
}
@@ -266,7 +266,7 @@ export async function executeAggregateChart(
if (queryResult.length === 0 && normalized.breakdowns.length > 0) {
queryResult = await chQuery<ISerieDataItem>(
- getAggregateChartSql({
+ await getAggregateChartSql({
...queryInput,
breakdowns: [],
}),
diff --git a/packages/db/src/services/chart.service.ts b/packages/db/src/services/chart.service.ts
index 1f9291d5b..626b6bd9d 100644
--- a/packages/db/src/services/chart.service.ts
+++ b/packages/db/src/services/chart.service.ts
@@ -1,14 +1,95 @@
/** biome-ignore-all lint/style/useDefaultSwitchClause: switch cases are exhaustive by design */
import { stripLeadingAndTrailingSlashes } from '@openpanel/common';
import type {
+ CohortDefinition,
+ IChartBreakdown,
IChartEventFilter,
IGetChartDataInput,
IReportInput,
} from '@openpanel/validation';
import sqlstring from 'sqlstring';
import { formatClickhouseDate, TABLE_NAMES } from '../clickhouse/client';
+import { db } from '../prisma-client';
import { createSqlBuilder } from '../sql-builder';
+export type CohortMetadata = {
+ id: string;
+ name: string;
+};
+
+export async function fetchCohortsMetadata(
+ cohortIds: string[],
+): Promise<Map<string, CohortMetadata>> {
+ if (cohortIds.length === 0) {
+ return new Map();
+ }
+
+ const cohorts = await db.cohort.findMany({
+ where: { id: { in: cohortIds } },
+ select: { id: true, name: true },
+ });
+
+ return new Map(
+ cohorts.map((c) => [c.id, { id: c.id, name: c.name }]),
+ );
+}
+
+export function getCohortCteName(cohortId: string): string {
+ return `\`cohort-${cohortId}\``;
+}
+
+export function getCohortAlias(cohortId: string): string {
+ return `cohort_${cohortId.replace(/-/g, '_')}`;
+}
+
+export function buildCohortMembershipQuery(
+ cohortId: string,
+ projectId: string,
+): string {
+ return `
+ SELECT profile_id
+ FROM ${TABLE_NAMES.cohort_members} FINAL
+ WHERE cohort_id = ${sqlstring.escape(cohortId)}
+ AND project_id = ${sqlstring.escape(projectId)}
+ `;
+}
+
+export function buildInlineCohortJoin(
+ cohortId: string,
+ projectId: string,
+ tableAlias: string,
+): string {
+ const cohortAlias = getCohortAlias(cohortId);
+ const cohortQuery = buildCohortMembershipQuery(cohortId, projectId);
+ return `LEFT ANY JOIN (${cohortQuery}) AS ${cohortAlias} ON ${cohortAlias}.profile_id = ${tableAlias}.profile_id`;
+}
+
+export function extractCohortId(breakdownName: string): string | null {
+ if (breakdownName.startsWith('cohort:')) {
+ return breakdownName.split(':')[1] ?? null;
+ }
+ return null;
+}
+
+export function collectCohortIds(
+ filters: IChartEventFilter[],
+ breakdowns: IChartBreakdown[],
+): string[] {
+ const ids = new Set<string>();
+ for (const filter of filters) {
+ if (filter.cohortId) {
+ ids.add(filter.cohortId);
+ }
+ }
+ for (const breakdown of breakdowns) {
+ const id = extractCohortId(breakdown.name);
+ if (id) {
+ ids.add(id);
+ }
+ }
+ return Array.from(ids);
+}
+
export function transformPropertyKey(property: string) {
const propertyPatterns = ['properties', 'profile.properties'];
const match = propertyPatterns.find((pattern) =>
@@ -93,7 +174,25 @@ export function getProfilePropertySelect(property: string): string {
return 'id';
}
-export function getSelectPropertyKey(property: string, projectId?: string) {
+export function getSelectPropertyKey(
+ property: string,
+ projectId?: string,
+ cohortId?: string,
+ cohortName?: string,
+) {
+ const extractedCohortId = cohortId || extractCohortId(property);
+
+ if (extractedCohortId && projectId) {
+ const cohortAlias = getCohortAlias(extractedCohortId);
+ const inLabel = cohortName
+ ? sqlstring.escape(cohortName)
+ : "'In Cohort'";
+ const notInLabel = cohortName
+ ? sqlstring.escape(`Not ${cohortName}`)
+ : "'Not In Cohort'";
+ return `if(notEmpty(${cohortAlias}.profile_id), ${inLabel}, ${notInLabel})`;
+ }
+
if (property === 'has_profile') {
return `if(profile_id != device_id, 'true', 'false')`;
}
@@ -121,7 +220,7 @@ export function getSelectPropertyKey(property: string, projectId?: string) {
return `${match}['${property.replace(new RegExp(`^${match}.`), '')}']`;
}
-export function getChartSql({
+export async function getChartSql({
event,
breakdowns,
interval,
@@ -144,6 +243,18 @@ export function getChartSql({
with: addCte,
} = createSqlBuilder();
+ const cohortIds = collectCohortIds(event.filters, breakdowns);
+ const cohortMetadata = await fetchCohortsMetadata(cohortIds);
+
+ for (const cohortId of cohortIds) {
+ addCte(
+ getCohortCteName(cohortId),
+ buildCohortMembershipQuery(cohortId, projectId),
+ );
+ sb.joins[`cohort_${cohortId}`] =
+ `LEFT ANY JOIN ${getCohortCteName(cohortId)} AS ${getCohortAlias(cohortId)} ON ${getCohortAlias(cohortId)}.profile_id = e.profile_id`;
+ }
+
sb.where = getEventFiltersWhereClause(event.filters, projectId);
sb.where.projectId = `project_id = ${sqlstring.escape(projectId)}`;
@@ -315,8 +426,12 @@ export function getChartSql({
breakdowns.forEach((breakdown, index) => {
// Breakdowns start at label_1 (label_0 is reserved for event name)
const key = `label_${index + 1}`;
+ const breakdownCohortId = extractCohortId(breakdown.name);
+ const breakdownCohortName = breakdownCohortId
+ ? cohortMetadata.get(breakdownCohortId)?.name
+ : undefined;
sb.select[key] =
- `${getSelectPropertyKey(breakdown.name, projectId)} as ${key}`;
+ `${getSelectPropertyKey(breakdown.name, projectId, breakdownCohortId ?? undefined, breakdownCohortName)} as ${key}`;
sb.groupBy[key] = `${key}`;
});
@@ -373,10 +488,14 @@ export function getChartSql({
return sql;
}
- // Note: The profile CTE (if it exists) is available in subqueries, so we can reference it directly
+ // Note: The profile CTE (if it exists) is available in subqueries, so we can reference it directly.
+ // Cohort CTEs cannot be referenced from nested CTEs in ClickHouse, so we inline them.
const subqueryGroupJoins = needsGroupArrayJoin
? 'ARRAY JOIN groups AS _group_id LEFT ANY JOIN _g ON _g.id = _group_id '
: '';
+ const inlineCohortJoinsSql = cohortIds
+ .map((id) => buildInlineCohortJoin(id, projectId, 'e'))
+ .join(' ');
if (breakdowns.length > 0) {
// Pre-compute unique counts per breakdown group in a CTE, then JOIN it.
@@ -385,7 +504,14 @@ export function getChartSql({
// which resolve in the subquery's scope, making the condition a tautology.
// 2. Correlated subqueries aren't supported on distributed/remote tables.
const ucSelectParts: string[] = breakdowns.map((breakdown, index) => {
- const propertyKey = getSelectPropertyKey(breakdown.name, projectId);
+ const bId = extractCohortId(breakdown.name);
+ const bName = bId ? cohortMetadata.get(bId)?.name : undefined;
+ const propertyKey = getSelectPropertyKey(
+ breakdown.name,
+ projectId,
+ bId ?? undefined,
+ bName,
+ );
return `${propertyKey} as _uc_label_${index + 1}`;
});
ucSelectParts.push('uniq(profile_id) as total_count');
@@ -398,12 +524,19 @@ export function getChartSql({
addCte(
'_uc',
- `SELECT ${ucSelectParts.join(', ')} FROM ${TABLE_NAMES.events} e ${subqueryGroupJoins}${profilesJoinRef ? `${profilesJoinRef} ` : ''}${ucWhere} GROUP BY ${ucGroupByParts.join(', ')}`
+ `SELECT ${ucSelectParts.join(', ')} FROM ${TABLE_NAMES.events} e ${subqueryGroupJoins}${profilesJoinRef ? `${profilesJoinRef} ` : ''}${inlineCohortJoinsSql ? `${inlineCohortJoinsSql} ` : ''}${ucWhere} GROUP BY ${ucGroupByParts.join(', ')}`
);
const ucJoinConditions = breakdowns
.map((b, index) => {
- const propertyKey = getSelectPropertyKey(b.name, projectId);
+ const bId = extractCohortId(b.name);
+ const bName = bId ? cohortMetadata.get(bId)?.name : undefined;
+ const propertyKey = getSelectPropertyKey(
+ b.name,
+ projectId,
+ bId ?? undefined,
+ bName,
+ );
return `_uc._uc_label_${index + 1} = ${propertyKey}`;
})
.join(' AND ');
@@ -415,7 +548,7 @@ export function getChartSql({
addCte(
'_uc',
- `SELECT uniq(profile_id) as total_count FROM ${TABLE_NAMES.events} e ${subqueryGroupJoins}${profilesJoinRef ? `${profilesJoinRef} ` : ''}${ucWhere}`
+ `SELECT uniq(profile_id) as total_count FROM ${TABLE_NAMES.events} e ${subqueryGroupJoins}${profilesJoinRef ? `${profilesJoinRef} ` : ''}${inlineCohortJoinsSql ? `${inlineCohortJoinsSql} ` : ''}${ucWhere}`
);
sb.select.total_unique_count =
@@ -429,7 +562,7 @@ export function getChartSql({
return sql;
}
-export function getAggregateChartSql({
+export async function getAggregateChartSql({
event,
breakdowns,
startDate,
@@ -441,6 +574,18 @@ export function getAggregateChartSql({
}) {
const { sb, join, getJoins, with: addCte, getSql } = createSqlBuilder();
+ const cohortIds = collectCohortIds(event.filters, breakdowns);
+ const cohortMetadata = await fetchCohortsMetadata(cohortIds);
+
+ for (const cohortId of cohortIds) {
+ addCte(
+ getCohortCteName(cohortId),
+ buildCohortMembershipQuery(cohortId, projectId),
+ );
+ sb.joins[`cohort_${cohortId}`] =
+ `LEFT ANY JOIN ${getCohortCteName(cohortId)} AS ${getCohortAlias(cohortId)} ON ${getCohortAlias(cohortId)}.profile_id = e.profile_id`;
+ }
+
sb.where = getEventFiltersWhereClause(event.filters, projectId);
sb.where.projectId = `project_id = ${sqlstring.escape(projectId)}`;
@@ -573,8 +718,12 @@ export function getAggregateChartSql({
breakdowns.forEach((breakdown, index) => {
// Breakdowns start at label_1 (label_0 is reserved for event name)
const key = `label_${index + 1}`;
+ const breakdownCohortId = extractCohortId(breakdown.name);
+ const breakdownCohortName = breakdownCohortId
+ ? cohortMetadata.get(breakdownCohortId)?.name
+ : undefined;
sb.select[key] =
- `${getSelectPropertyKey(breakdown.name, projectId)} as ${key}`;
+ `${getSelectPropertyKey(breakdown.name, projectId, breakdownCohortId ?? undefined, breakdownCohortName)} as ${key}`;
sb.groupBy[key] = `${key}`;
});
@@ -665,7 +814,17 @@ export function getEventFiltersWhereClause(
const where: Record<string, string> = {};
filters.forEach((filter, index) => {
const id = `f${index}`;
- const { name, value, operator } = filter;
+ const { name, value, operator, cohortId } = filter;
+
+ if (operator === 'inCohort' && cohortId && projectId) {
+ where[id] = `notEmpty(${getCohortAlias(cohortId)}.profile_id)`;
+ return;
+ }
+
+ if (operator === 'notInCohort' && cohortId && projectId) {
+ where[id] = `empty(${getCohortAlias(cohortId)}.profile_id)`;
+ return;
+ }
if (
value.length === 0 &&
diff --git a/packages/db/src/services/cohort.service.ts b/packages/db/src/services/cohort.service.ts
new file mode 100644
index 000000000..fa10029be
--- /dev/null
+++ b/packages/db/src/services/cohort.service.ts
@@ -0,0 +1,588 @@
+import sqlstring from 'sqlstring';
+import type {
+ CohortDefinition,
+ EventBasedCohortDefinition,
+ EventCriteria,
+ Frequency,
+ IChartEventFilter,
+ PropertyBasedCohortDefinition,
+ Timeframe,
+} from '@openpanel/validation';
+
+import { cohortComputeQueue } from '@openpanel/queue';
+import { TABLE_NAMES, ch, chQuery } from '../clickhouse/client';
+import { db } from '../prisma-client';
+
+export const COHORT_MATERIALIZE_LIMIT = 10000;
+
+function buildTimeConstraint(timeframe: Timeframe): string {
+ if (timeframe.type === 'relative') {
+ const match = timeframe.value.match(/^(\d+)d$/);
+ if (!match) {
+ throw new Error(`Invalid relative timeframe: ${timeframe.value}`);
+ }
+ const days = Number.parseInt(match[1]!, 10);
+ return `created_at >= toDate(now() - INTERVAL ${days} DAY)`;
+ }
+
+ const start = timeframe.start;
+ if (timeframe.end) {
+ return `created_at BETWEEN toDate('${start}') AND toDate('${timeframe.end}')`;
+ }
+ return `created_at >= toDate('${start}')`;
+}
+
+function getFrequencyOperator(frequency: Frequency): string {
+ switch (frequency.operator) {
+ case 'gte':
+ return `>= ${frequency.count}`;
+ case 'eq':
+ return `= ${frequency.count}`;
+ case 'lte':
+ return `<= ${frequency.count}`;
+ default:
+ return `>= ${frequency.count}`;
+ }
+}
+
+export function buildEventCriteriaQuery(
+ projectId: string,
+ criteria: EventCriteria,
+): string {
+ const { name, filters, timeframe, frequency } = criteria;
+ const timeConstraint = buildTimeConstraint(timeframe);
+ const hasEventPropertyFilters = filters.some(
+ (f) =>
+ f.name.startsWith('properties.') &&
+ !f.name.startsWith('profile.properties.'),
+ );
+
+ if (hasEventPropertyFilters) {
+ const propertyFilters = filters.filter((f) =>
+ f.name.startsWith('properties.'),
+ );
+
+ const propertyConditions = propertyFilters
+ .map((filter) => {
+ const propertyKey = filter.name.replace('properties.', '');
+ const { value, operator } = filter;
+
+ switch (operator) {
+ case 'is':
+ if (value.length === 1) {
+ return `(property_key = ${sqlstring.escape(propertyKey)} AND property_value = ${sqlstring.escape(String(value[0]).trim())})`;
+ }
+ return `(property_key = ${sqlstring.escape(propertyKey)} AND property_value IN (${value
+ .map((val) => sqlstring.escape(String(val).trim()))
+ .join(', ')}))`;
+ case 'isNot':
+ if (value.length === 1) {
+ return `(property_key = ${sqlstring.escape(propertyKey)} AND property_value != ${sqlstring.escape(String(value[0]).trim())})`;
+ }
+ return `(property_key = ${sqlstring.escape(propertyKey)} AND property_value NOT IN (${value
+ .map((val) => sqlstring.escape(String(val).trim()))
+ .join(', ')}))`;
+ case 'contains':
+ return `(property_key = ${sqlstring.escape(propertyKey)} AND (${value
+ .map(
+ (val) =>
+ `property_value LIKE ${sqlstring.escape(`%${String(val).trim()}%`)}`,
+ )
+ .join(' OR ')}))`;
+ case 'doesNotContain':
+ return `(property_key = ${sqlstring.escape(propertyKey)} AND (${value
+ .map(
+ (val) =>
+ `property_value NOT LIKE ${sqlstring.escape(`%${String(val).trim()}%`)}`,
+ )
+ .join(' AND ')}))`;
+ default:
+ return `(property_key = ${sqlstring.escape(propertyKey)} AND property_value IN (${value
+ .map((val) => sqlstring.escape(String(val).trim()))
+ .join(', ')}))`;
+ }
+ })
+ .join(' OR ');
+
+ if (frequency) {
+ const frequencyOp = getFrequencyOperator(frequency);
+ return `
+ SELECT profile_id
+ FROM ${TABLE_NAMES.profile_event_property_summary_mv}
+ WHERE project_id = ${sqlstring.escape(projectId)}
+ AND name = ${sqlstring.escape(name)}
+ AND ${timeConstraint.replace('created_at', 'event_date')}
+ AND (${propertyConditions})
+ GROUP BY profile_id
+ HAVING countMerge(event_count) ${frequencyOp}
+ `;
+ }
+
+ return `
+ SELECT DISTINCT profile_id
+ FROM ${TABLE_NAMES.profile_event_property_summary_mv}
+ WHERE project_id = ${sqlstring.escape(projectId)}
+ AND name = ${sqlstring.escape(name)}
+ AND ${timeConstraint.replace('created_at', 'event_date')}
+ AND (${propertyConditions})
+ `;
+ }
+
+ if (frequency) {
+ const frequencyOp = getFrequencyOperator(frequency);
+ return `
+ SELECT profile_id
+ FROM ${TABLE_NAMES.profile_event_summary_mv}
+ WHERE project_id = ${sqlstring.escape(projectId)}
+ AND name = ${sqlstring.escape(name)}
+ AND ${timeConstraint.replace('created_at', 'event_date')}
+ GROUP BY profile_id
+ HAVING countMerge(event_count) ${frequencyOp}
+ `;
+ }
+
+ return `
+ SELECT DISTINCT profile_id
+ FROM ${TABLE_NAMES.profile_event_summary_mv}
+ WHERE project_id = ${sqlstring.escape(projectId)}
+ AND name = ${sqlstring.escape(name)}
+ AND ${timeConstraint.replace('created_at', 'event_date')}
+ `;
+}
+
+export function buildPropertyBasedCohortQuery(
+ projectId: string,
+ definition: PropertyBasedCohortDefinition,
+): string {
+ const { properties, operator } = definition.criteria;
+ const filterWhere = getProfileFiltersWhereClause(properties);
+ const filterClauses = Object.values(filterWhere);
+
+ if (filterClauses.length === 0) {
+ return `SELECT id as profile_id FROM ${TABLE_NAMES.profiles} FINAL WHERE 1=0`;
+ }
+
+ const filterClause = filterClauses.join(
+ operator === 'and' ? ' AND ' : ' OR ',
+ );
+
+ return `
+ SELECT id as profile_id
+ FROM ${TABLE_NAMES.profiles} FINAL
+ WHERE project_id = ${sqlstring.escape(projectId)}
+ AND (${filterClause})
+ `;
+}
+
+export async function computeEventBasedCohort(
+ projectId: string,
+ definition: EventBasedCohortDefinition,
+ limit?: number,
+): Promise<string[]> {
+ const { events, operator } = definition.criteria;
+
+ const queries = events.map((eventCriteria) =>
+ buildEventCriteriaQuery(projectId, eventCriteria),
+ );
+
+ const combinedQuery =
+ operator === 'and'
+ ? queries.join(' INTERSECT ')
+ : queries.join(' UNION DISTINCT ');
+
+ const finalQuery = limit ? `${combinedQuery} LIMIT ${limit}` : combinedQuery;
+
+ const results = await chQuery<{ profile_id: string }>(finalQuery);
+ return results.map((r) => r.profile_id);
+}
+
+export async function countEventBasedCohort(
+ projectId: string,
+ definition: EventBasedCohortDefinition,
+): Promise<number> {
+ const { events, operator } = definition.criteria;
+
+ const queries = events.map((eventCriteria) =>
+ buildEventCriteriaQuery(projectId, eventCriteria),
+ );
+
+ const combinedQuery =
+ operator === 'and'
+ ? queries.join(' INTERSECT ')
+ : queries.join(' UNION DISTINCT ');
+
+ const countQuery = `SELECT count() as count FROM (${combinedQuery})`;
+ const results = await chQuery<{ count: number }>(countQuery);
+ return results[0]?.count ?? 0;
+}
+
+function getProfileFiltersWhereClause(
+ filters: IChartEventFilter[],
+): Record<string, string> {
+ const where: Record<string, string> = {};
+
+ filters.forEach((filter, index) => {
+ const id = `pf${index}`;
+ const { name, value, operator } = filter;
+
+ if (
+ value.length === 0 &&
+ operator !== 'isNull' &&
+ operator !== 'isNotNull'
+ ) {
+ return;
+ }
+
+ const normalizedName = name.replace(/^profile\./, 'profiles.');
+ let columnAccess: string;
+
+ if (normalizedName.startsWith('profiles.properties.')) {
+ const propKey = normalizedName.replace('profiles.properties.', '');
+ columnAccess = `profiles.properties['${propKey}']`;
+ } else {
+ columnAccess = normalizedName;
+ }
+
+ switch (operator) {
+ case 'is': {
+ if (value.length === 1) {
+ where[id] = `${columnAccess} = ${sqlstring.escape(String(value[0]).trim())}`;
+ } else {
+ where[id] = `${columnAccess} IN (${value
+ .map((val) => sqlstring.escape(String(val).trim()))
+ .join(', ')})`;
+ }
+ break;
+ }
+ case 'isNot': {
+ if (value.length === 1) {
+ where[id] = `${columnAccess} != ${sqlstring.escape(String(value[0]).trim())}`;
+ } else {
+ where[id] = `${columnAccess} NOT IN (${value
+ .map((val) => sqlstring.escape(String(val).trim()))
+ .join(', ')})`;
+ }
+ break;
+ }
+ case 'contains': {
+ where[id] = `(${value
+ .map(
+ (val) =>
+ `${columnAccess} LIKE ${sqlstring.escape(`%${String(val).trim()}%`)}`,
+ )
+ .join(' OR ')})`;
+ break;
+ }
+ case 'doesNotContain': {
+ where[id] = `(${value
+ .map(
+ (val) =>
+ `${columnAccess} NOT LIKE ${sqlstring.escape(`%${String(val).trim()}%`)}`,
+ )
+ .join(' OR ')})`;
+ break;
+ }
+ case 'startsWith': {
+ where[id] = `(${value
+ .map(
+ (val) =>
+ `${columnAccess} LIKE ${sqlstring.escape(`${String(val).trim()}%`)}`,
+ )
+ .join(' OR ')})`;
+ break;
+ }
+ case 'endsWith': {
+ where[id] = `(${value
+ .map(
+ (val) =>
+ `${columnAccess} LIKE ${sqlstring.escape(`%${String(val).trim()}`)}`,
+ )
+ .join(' OR ')})`;
+ break;
+ }
+ case 'isNull': {
+ where[id] = `(${columnAccess} IS NULL OR ${columnAccess} = '')`;
+ break;
+ }
+ case 'isNotNull': {
+ where[id] = `(${columnAccess} IS NOT NULL AND ${columnAccess} != '')`;
+ break;
+ }
+ case 'gt': {
+ if (value[0] !== undefined) {
+ where[id] = `toFloat64OrNull(${columnAccess}) > ${Number(value[0])}`;
+ }
+ break;
+ }
+ case 'lt': {
+ if (value[0] !== undefined) {
+ where[id] = `toFloat64OrNull(${columnAccess}) < ${Number(value[0])}`;
+ }
+ break;
+ }
+ case 'gte': {
+ if (value[0] !== undefined) {
+ where[id] = `toFloat64OrNull(${columnAccess}) >= ${Number(value[0])}`;
+ }
+ break;
+ }
+ case 'lte': {
+ if (value[0] !== undefined) {
+ where[id] = `toFloat64OrNull(${columnAccess}) <= ${Number(value[0])}`;
+ }
+ break;
+ }
+ }
+ });
+
+ return where;
+}
+
+export async function computePropertyBasedCohort(
+ projectId: string,
+ definition: PropertyBasedCohortDefinition,
+ limit?: number,
+): Promise<string[]> {
+ const { properties, operator } = definition.criteria;
+ const filterWhere = getProfileFiltersWhereClause(properties);
+ const filterClauses = Object.values(filterWhere);
+
+ if (filterClauses.length === 0) {
+ return [];
+ }
+
+ const filterClause = filterClauses.join(
+ operator === 'and' ? ' AND ' : ' OR ',
+ );
+
+ const query = `
+ SELECT id as profile_id
+ FROM ${TABLE_NAMES.profiles} FINAL
+ WHERE project_id = ${sqlstring.escape(projectId)}
+ AND (${filterClause})
+ ${limit ? `LIMIT ${limit}` : ''}
+ `;
+
+ const results = await chQuery<{ profile_id: string }>(query);
+ return results.map((r) => r.profile_id);
+}
+
+export async function countPropertyBasedCohort(
+ projectId: string,
+ definition: PropertyBasedCohortDefinition,
+): Promise<number> {
+ const { properties, operator } = definition.criteria;
+ const filterWhere = getProfileFiltersWhereClause(properties);
+ const filterClauses = Object.values(filterWhere);
+
+ if (filterClauses.length === 0) {
+ return 0;
+ }
+
+ const filterClause = filterClauses.join(
+ operator === 'and' ? ' AND ' : ' OR ',
+ );
+
+ const query = `
+ SELECT count() as count
+ FROM ${TABLE_NAMES.profiles} FINAL
+ WHERE project_id = ${sqlstring.escape(projectId)}
+ AND (${filterClause})
+ `;
+
+ const results = await chQuery<{ count: number }>(query);
+ return results[0]?.count ?? 0;
+}
+
+export async function storeCohortMembership(
+ projectId: string,
+ cohortId: string,
+ profileIds: string[],
+ version: number,
+): Promise<void> {
+ const now = new Date().toISOString().slice(0, 19).replace('T', ' ');
+
+ if (profileIds.length > 0) {
+ const data = profileIds.map((profileId) => ({
+ project_id: projectId,
+ cohort_id: cohortId,
+ profile_id: profileId,
+ matched_at: now,
+ matching_properties: {},
+ version,
+ }));
+
+ await ch.insert({
+ table: TABLE_NAMES.cohort_members,
+ values: data,
+ format: 'JSONEachRow',
+ });
+ }
+
+ const sampleProfiles = profileIds.slice(0, 10);
+ await ch.insert({
+ table: TABLE_NAMES.cohort_metadata,
+ values: [
+ {
+ project_id: projectId,
+ cohort_id: cohortId,
+ member_count: profileIds.length,
+ last_computed_at: now,
+ sample_profiles: sampleProfiles,
+ version,
+ },
+ ],
+ format: 'JSONEachRow',
+ });
+}
+
+export async function getCohortMembers(
+ cohortId: string,
+ projectId: string,
+ opts?: { limit?: number; offset?: number },
+): Promise<{ profileIds: string[]; total: number }> {
+ const cohort = await db.cohort.findUnique({ where: { id: cohortId } });
+
+ if (!cohort) {
+ throw new Error('Cohort not found');
+ }
+
+ const query = `
+ SELECT
+ profile_id,
+ count() OVER() as total
+ FROM ${TABLE_NAMES.cohort_members} FINAL
+ WHERE project_id = ${sqlstring.escape(projectId)}
+ AND cohort_id = ${sqlstring.escape(cohortId)}
+ ORDER BY matched_at DESC
+ ${opts?.limit ? `LIMIT ${opts.limit}` : ''}
+ ${opts?.offset ? `OFFSET ${opts.offset}` : ''}
+ `;
+
+ const results = await chQuery<{ profile_id: string; total: number }>(query);
+ return {
+ profileIds: results.map((r) => r.profile_id),
+ total: results[0]?.total || 0,
+ };
+}
+
+export async function getCohortCount(
+ cohortId: string,
+ projectId: string,
+): Promise<number> {
+ const cohort = await db.cohort.findUnique({ where: { id: cohortId } });
+
+ if (!cohort) {
+ throw new Error('Cohort not found');
+ }
+
+ if (cohort.lastComputedAt) {
+ const age = Date.now() - cohort.lastComputedAt.getTime();
+ if (age < 15 * 60 * 1000) {
+ return cohort.profileCount;
+ }
+ }
+
+ const result = await chQuery<{ count: number }>(`
+ SELECT count() as count
+ FROM ${TABLE_NAMES.cohort_members} FINAL
+ WHERE project_id = ${sqlstring.escape(projectId)}
+ AND cohort_id = ${sqlstring.escape(cohortId)}
+ `);
+ return result[0]?.count || 0;
+}
+
+export async function computeCohort(
+ projectId: string,
+ definition: CohortDefinition,
+ limit?: number,
+): Promise<string[]> {
+ if (definition.type === 'event') {
+ return computeEventBasedCohort(projectId, definition, limit);
+ }
+ if (definition.type === 'property') {
+ return computePropertyBasedCohort(projectId, definition, limit);
+ }
+ return [];
+}
+
+export async function countCohort(
+ projectId: string,
+ definition: CohortDefinition,
+): Promise<number> {
+ if (definition.type === 'event') {
+ return countEventBasedCohort(projectId, definition);
+ }
+ if (definition.type === 'property') {
+ return countPropertyBasedCohort(projectId, definition);
+ }
+ return 0;
+}
+
+export async function updateCohortMembership(
+ cohortId: string,
+): Promise<void> {
+ const cohort = await db.cohort.findUnique({ where: { id: cohortId } });
+
+ if (!cohort) {
+ return;
+ }
+
+ const definition = cohort.definition as CohortDefinition;
+ const profileIds = await computeCohort(
+ cohort.projectId,
+ definition,
+ COHORT_MATERIALIZE_LIMIT,
+ );
+
+ const version = Date.now();
+
+ await storeCohortMembership(
+ cohort.projectId,
+ cohort.id,
+ profileIds,
+ version,
+ );
+
+ await db.cohort.update({
+ where: { id: cohortId },
+ data: {
+ profileCount: profileIds.length,
+ lastComputedAt: new Date(),
+ },
+ });
+}
+
+export async function deleteCohortMembership(
+ cohortId: string,
+ projectId: string,
+): Promise<void> {
+ await ch.command({
+ query: `ALTER TABLE ${TABLE_NAMES.cohort_members} DELETE WHERE cohort_id = ${sqlstring.escape(cohortId)} AND project_id = ${sqlstring.escape(projectId)}`,
+ });
+ await ch.command({
+ query: `ALTER TABLE ${TABLE_NAMES.cohort_metadata} DELETE WHERE cohort_id = ${sqlstring.escape(cohortId)} AND project_id = ${sqlstring.escape(projectId)}`,
+ });
+}
+
+export async function getProfilesInCohort(
+ cohortId: string,
+ projectId: string,
+): Promise<Set<string>> {
+ const { profileIds } = await getCohortMembers(cohortId, projectId, {
+ limit: 100000,
+ });
+ return new Set(profileIds);
+}
+
+export async function enqueueCohortCompute(cohortId: string): Promise<void> {
+ await cohortComputeQueue.add(
+ 'cohortCompute',
+ { cohortId },
+ {
+ jobId: `cohort-${cohortId}`,
+ removeOnComplete: { age: 3600 },
+ removeOnFail: { age: 86400 },
+ },
+ );
+}
diff --git a/packages/db/src/services/conversion.service.ts b/packages/db/src/services/conversion.service.ts
index 5d3017c8b..89ac8e7a8 100644
--- a/packages/db/src/services/conversion.service.ts
+++ b/packages/db/src/services/conversion.service.ts
@@ -5,6 +5,10 @@ import sqlstring from 'sqlstring';
import { TABLE_NAMES, ch } from '../clickhouse/client';
import { clix } from '../clickhouse/query-builder';
import {
+ buildInlineCohortJoin,
+ collectCohortIds,
+ extractCohortId,
+ fetchCohortsMetadata,
getEventFiltersWhereClause,
getSelectPropertyKey,
} from './chart.service';
@@ -30,9 +34,21 @@ export class ConversionService {
const funnelGroup = funnelOptions?.funnelGroup;
const funnelWindow = funnelOptions?.funnelWindow ?? 24;
const group = funnelGroup === 'profile_id' ? 'profile_id' : 'session_id';
- const breakdownExpressions = breakdowns.map(
- (b) => getSelectPropertyKey(b.name, projectId),
+
+ const allFilters = series.flatMap((s) =>
+ s.type === 'event' ? s.filters ?? [] : [],
);
+ const cohortIds = collectCohortIds(allFilters, breakdowns);
+ const cohortMetadata = await fetchCohortsMetadata(cohortIds);
+ const cohortJoinsSql = cohortIds
+ .map((id) => buildInlineCohortJoin(id, projectId, 'events'))
+ .join(' ');
+
+ const breakdownExpressions = breakdowns.map((b) => {
+ const bId = extractCohortId(b.name);
+ const bName = bId ? cohortMetadata.get(bId)?.name : undefined;
+ return getSelectPropertyKey(b.name, projectId, bId ?? undefined, bName);
+ });
const breakdownSelects = breakdownExpressions.map(
(expr, index) => `${expr} as b_${index}`,
);
@@ -140,6 +156,7 @@ export class ConversionService {
FROM ${TABLE_NAMES.events}
${profileJoin}
${groupJoin}
+ ${cohortJoinsSql}
WHERE project_id = '${projectId}'
AND events.name IN ('${eventA.name}', '${eventB.name}')
AND created_at BETWEEN toDateTime('${startDate}') AND toDateTime('${endDate}')
diff --git a/packages/db/src/services/delete.service.ts b/packages/db/src/services/delete.service.ts
index 9df45bd12..eb2f23e1e 100644
--- a/packages/db/src/services/delete.service.ts
+++ b/packages/db/src/services/delete.service.ts
@@ -47,6 +47,10 @@ export async function deleteFromClickhouse(projectIds: string[]) {
TABLE_NAMES.dau_mv,
TABLE_NAMES.event_names_mv,
TABLE_NAMES.event_property_values_mv,
+ TABLE_NAMES.cohort_members,
+ TABLE_NAMES.cohort_metadata,
+ TABLE_NAMES.profile_event_summary_mv,
+ TABLE_NAMES.profile_event_property_summary_mv,
];
for (const table of tables) {
diff --git a/packages/db/src/services/funnel.service.ts b/packages/db/src/services/funnel.service.ts
index 4d587aadb..f84704e3b 100644
--- a/packages/db/src/services/funnel.service.ts
+++ b/packages/db/src/services/funnel.service.ts
@@ -7,6 +7,10 @@ import { TABLE_NAMES } from '../clickhouse/client';
import { clix } from '../clickhouse/query-builder';
import { createSqlBuilder } from '../sql-builder';
import {
+ buildInlineCohortJoin,
+ collectCohortIds,
+ extractCohortId,
+ fetchCohortsMetadata,
getEventFiltersWhereClause,
getSelectPropertyKey,
} from './chart.service';
@@ -245,10 +249,16 @@ export class FunnelService {
const needsGroupArrayJoin =
anyFilterOnGroup || anyBreakdownOnGroup || funnelGroup === 'group';
+ const allFilters = eventSeries.flatMap((e) => e.filters ?? []);
+ const cohortIds = collectCohortIds(allFilters, breakdowns);
+ const cohortMetadata = await fetchCohortsMetadata(cohortIds);
+
// Create the funnel CTE (session-level)
- const breakdownSelects = breakdowns.map(
- (b, index) => `${getSelectPropertyKey(b.name, projectId)} as b_${index}`,
- );
+ const breakdownSelects = breakdowns.map((b, index) => {
+ const bId = extractCohortId(b.name);
+ const bName = bId ? cohortMetadata.get(bId)?.name : undefined;
+ return `${getSelectPropertyKey(b.name, projectId, bId ?? undefined, bName)} as b_${index}`;
+ });
const breakdownGroupBy = breakdowns.map((b, index) => `b_${index}`);
const funnelCte = this.buildFunnelCte({
@@ -290,6 +300,10 @@ export class FunnelService {
funnelCte.rawJoin('LEFT ANY JOIN _g ON _g.id = _group_id');
}
+ for (const cohortId of cohortIds) {
+ funnelCte.rawJoin(buildInlineCohortJoin(cohortId, projectId, 'events'));
+ }
+
// Base funnel query with CTEs
const funnelQuery = clix(this.client, timezone);
diff --git a/packages/db/src/types.ts b/packages/db/src/types.ts
index 464d707fa..aacd6d1e7 100644
--- a/packages/db/src/types.ts
+++ b/packages/db/src/types.ts
@@ -1,4 +1,5 @@
import type {
+ CohortDefinition,
IImportConfig,
IIntegrationConfig,
INotificationRuleConfig,
@@ -25,6 +26,7 @@ declare global {
type IPrismaClickhouseEvent = IClickhouseEvent;
type IPrismaClickhouseProfile = IClickhouseProfile;
type IPrismaClickhouseBotEvent = IClickhouseBotEvent;
+ type IPrismaCohortDefinition = CohortDefinition;
// Each ChatMessage row stores one Better Agent `ConversationItem`
// (message, tool call, or tool result) as JSON. Typed as `unknown[]`
// here to avoid pulling `@better-agent/core` into @openpanel/db's
diff --git a/packages/queue/src/queues.ts b/packages/queue/src/queues.ts
index 007e99541..94d6577fa 100644
--- a/packages/queue/src/queues.ts
+++ b/packages/queue/src/queues.ts
@@ -138,6 +138,10 @@ export type CronQueuePayloadFlushGroups = {
type: 'flushGroups';
payload: undefined;
};
+export type CronQueuePayloadCohortRefresh = {
+ type: 'cohortRefresh';
+ payload: undefined;
+};
export type CronQueuePayload =
| CronQueuePayloadSalt
| CronQueuePayloadFlushEvents
@@ -150,7 +154,8 @@ export type CronQueuePayload =
| CronQueuePayloadProject
| CronQueuePayloadInsightsDaily
| CronQueuePayloadOnboarding
- | CronQueuePayloadGscSync;
+ | CronQueuePayloadGscSync
+ | CronQueuePayloadCohortRefresh;
export type MiscQueuePayloadTrialEndingSoon = {
type: 'trialEndingSoon';
@@ -297,3 +302,20 @@ export const gscQueue = new Queue<GscQueuePayload>(getQueueName('gsc'), {
removeOnFail: 100,
},
});
+
+export type CohortComputePayload = {
+ cohortId: string;
+};
+
+export const cohortComputeQueue = new Queue<CohortComputePayload>(
+ getQueueName('cohortCompute'),
+ {
+ connection: getRedisQueue(),
+ defaultJobOptions: {
+ attempts: 3,
+ backoff: { type: 'exponential', delay: 5000 },
+ removeOnComplete: { age: 3600 },
+ removeOnFail: { age: 86400 },
+ },
+ },
+);
diff --git a/packages/trpc/src/root.ts b/packages/trpc/src/root.ts
index 657fb7ada..0c461beec 100644
--- a/packages/trpc/src/root.ts
+++ b/packages/trpc/src/root.ts
@@ -2,6 +2,7 @@ import { authRouter } from './routers/auth';
import { chartRouter } from './routers/chart';
import { chatRouter } from './routers/chat';
import { clientRouter } from './routers/client';
+import { cohortRouter } from './routers/cohort';
import { conversationRouter } from './routers/conversation';
import { dashboardRouter } from './routers/dashboard';
import { emailRouter } from './routers/email';
@@ -59,6 +60,7 @@ export const appRouter = createTRPCRouter({
email: emailRouter,
gsc: gscRouter,
group: groupRouter,
+ cohort: cohortRouter,
});
// export type definition of API
diff --git a/packages/trpc/src/routers/cohort.ts b/packages/trpc/src/routers/cohort.ts
new file mode 100644
index 000000000..577b32a08
--- /dev/null
+++ b/packages/trpc/src/routers/cohort.ts
@@ -0,0 +1,325 @@
+import { z } from 'zod';
+
+import {
+ TABLE_NAMES,
+ chQuery,
+ computeCohort,
+ countCohort,
+ db,
+ deleteCohortMembership,
+ enqueueCohortCompute,
+ getCohortCount,
+ getCohortMembers,
+} from '@openpanel/db';
+import {
+ type CohortDefinition,
+ zCohortDefinition,
+ zCohortInput,
+ zCohortUpdate,
+} from '@openpanel/validation';
+import sqlstring from 'sqlstring';
+
+import { getProjectAccess } from '../access';
+import { TRPCAccessError, TRPCNotFoundError } from '../errors';
+import { createTRPCRouter, protectedProcedure } from '../trpc';
+
+export const cohortRouter = createTRPCRouter({
+ list: protectedProcedure
+ .input(
+ z.object({
+ projectId: z.string(),
+ includeCount: z.boolean().optional().default(false),
+ }),
+ )
+ .query(async ({ input }) => {
+ const cohorts = await db.cohort.findMany({
+ where: { projectId: input.projectId },
+ orderBy: { createdAt: 'desc' },
+ });
+
+ if (input.includeCount) {
+ return cohorts.map((cohort) => ({
+ ...cohort,
+ currentCount: cohort.profileCount ?? 0,
+ }));
+ }
+
+ return cohorts;
+ }),
+
+ get: protectedProcedure
+ .input(z.object({ id: z.string() }))
+ .query(async ({ input, ctx }) => {
+ const cohort = await db.cohort.findUnique({
+ where: { id: input.id },
+ });
+
+ if (!cohort) {
+ throw TRPCNotFoundError('Cohort not found');
+ }
+
+ const access = await getProjectAccess({
+ projectId: cohort.projectId,
+ userId: ctx.session.userId!,
+ });
+
+ if (!access) {
+ throw TRPCAccessError('You do not have access to this cohort');
+ }
+
+ return cohort;
+ }),
+
+ create: protectedProcedure
+ .input(zCohortInput)
+ .mutation(async ({ input }) => {
+ const cohort = await db.cohort.create({
+ data: {
+ name: input.name,
+ description: input.description,
+ projectId: input.projectId,
+ definition: input.definition,
+ isStatic: input.isStatic,
+ },
+ });
+
+ await enqueueCohortCompute(cohort.id);
+
+ return cohort;
+ }),
+
+ update: protectedProcedure
+ .input(zCohortUpdate)
+ .mutation(async ({ input, ctx }) => {
+ const { id, ...data } = input;
+
+ const existingCohort = await db.cohort.findUnique({ where: { id } });
+
+ if (!existingCohort) {
+ throw TRPCNotFoundError('Cohort not found');
+ }
+
+ const access = await getProjectAccess({
+ projectId: existingCohort.projectId,
+ userId: ctx.session.userId!,
+ });
+
+ if (!access) {
+ throw TRPCAccessError('You do not have access to this cohort');
+ }
+
+ const cohort = await db.cohort.update({
+ where: { id },
+ data: {
+ ...(data.name && { name: data.name }),
+ ...(data.description !== undefined && {
+ description: data.description,
+ }),
+ ...(data.definition && { definition: data.definition }),
+ ...(data.isStatic !== undefined && { isStatic: data.isStatic }),
+ },
+ });
+
+ if (data.definition) {
+ await enqueueCohortCompute(cohort.id);
+ }
+
+ return cohort;
+ }),
+
+ delete: protectedProcedure
+ .input(z.object({ id: z.string() }))
+ .mutation(async ({ input, ctx }) => {
+ const cohort = await db.cohort.findUnique({ where: { id: input.id } });
+
+ if (!cohort) {
+ throw TRPCNotFoundError('Cohort not found');
+ }
+
+ const access = await getProjectAccess({
+ projectId: cohort.projectId,
+ userId: ctx.session.userId!,
+ });
+
+ if (!access) {
+ throw TRPCAccessError('You do not have access to this cohort');
+ }
+
+ await db.cohort.delete({ where: { id: input.id } });
+
+ deleteCohortMembership(input.id, cohort.projectId).catch((err) => {
+ console.error('Failed to cleanup cohort CH data:', err);
+ });
+
+ return { success: true };
+ }),
+
+ getProfiles: protectedProcedure
+ .input(
+ z.object({
+ cohortId: z.string(),
+ limit: z.number().int().min(1).max(500).default(50),
+ offset: z.number().int().min(0).default(0),
+ }),
+ )
+ .query(async ({ input, ctx }) => {
+ const cohort = await db.cohort.findUnique({
+ where: { id: input.cohortId },
+ });
+
+ if (!cohort) {
+ throw TRPCNotFoundError('Cohort not found');
+ }
+
+ const access = await getProjectAccess({
+ projectId: cohort.projectId,
+ userId: ctx.session.userId!,
+ });
+
+ if (!access) {
+ throw TRPCAccessError('You do not have access to this cohort');
+ }
+
+ const result = await getCohortMembers(input.cohortId, cohort.projectId, {
+ limit: input.limit,
+ offset: input.offset,
+ });
+
+ if (result.profileIds.length > 0) {
+ const profiles = await chQuery<{
+ id: string;
+ email: string;
+ first_name: string;
+ last_name: string;
+ properties: Record<string, string>;
+ created_at: string;
+ }>(`
+ SELECT id, email, first_name, last_name, properties, created_at
+ FROM ${TABLE_NAMES.profiles} FINAL
+ WHERE project_id = ${sqlstring.escape(cohort.projectId)}
+ AND id IN (${result.profileIds.map((id) => sqlstring.escape(id)).join(',')})
+ `);
+
+ return {
+ profiles,
+ total: result.total,
+ };
+ }
+
+ return {
+ profiles: [],
+ total: result.total,
+ };
+ }),
+
+ getCount: protectedProcedure
+ .input(z.object({ cohortId: z.string() }))
+ .query(async ({ input, ctx }) => {
+ const cohort = await db.cohort.findUnique({
+ where: { id: input.cohortId },
+ });
+
+ if (!cohort) {
+ throw TRPCNotFoundError('Cohort not found');
+ }
+
+ const access = await getProjectAccess({
+ projectId: cohort.projectId,
+ userId: ctx.session.userId!,
+ });
+
+ if (!access) {
+ throw TRPCAccessError('You do not have access to this cohort');
+ }
+
+ const count = await getCohortCount(input.cohortId, cohort.projectId);
+ return { count };
+ }),
+
+ preview: protectedProcedure
+ .input(
+ z.object({
+ projectId: z.string(),
+ definition: zCohortDefinition,
+ }),
+ )
+ .query(async ({ input }) => {
+ const definition = input.definition as CohortDefinition;
+ const count = await countCohort(input.projectId, definition);
+ const sampleProfiles = await computeCohort(
+ input.projectId,
+ definition,
+ 10,
+ );
+ return { count, sampleProfiles };
+ }),
+
+ exportProfiles: protectedProcedure
+ .input(
+ z.object({
+ cohortId: z.string(),
+ limit: z.number().int().min(1).max(10000).default(10000),
+ offset: z.number().int().min(0).default(0),
+ }),
+ )
+ .query(async ({ input, ctx }) => {
+ const cohort = await db.cohort.findUnique({
+ where: { id: input.cohortId },
+ });
+
+ if (!cohort) {
+ throw TRPCNotFoundError('Cohort not found');
+ }
+
+ const access = await getProjectAccess({
+ projectId: cohort.projectId,
+ userId: ctx.session.userId!,
+ });
+
+ if (!access) {
+ throw TRPCAccessError('You do not have access to this cohort');
+ }
+
+ const result = await getCohortMembers(input.cohortId, cohort.projectId, {
+ limit: input.limit,
+ offset: input.offset,
+ });
+
+ return {
+ profileIds: result.profileIds,
+ total: result.total,
+ cohortName: cohort.name,
+ };
+ }),
+
+ refresh: protectedProcedure
+ .input(z.object({ cohortId: z.string() }))
+ .mutation(async ({ input, ctx }) => {
+ const cohort = await db.cohort.findUnique({
+ where: { id: input.cohortId },
+ });
+
+ if (!cohort) {
+ throw TRPCNotFoundError('Cohort not found');
+ }
+
+ const access = await getProjectAccess({
+ projectId: cohort.projectId,
+ userId: ctx.session.userId!,
+ });
+
+ if (!access) {
+ throw TRPCAccessError('You do not have access to this cohort');
+ }
+
+ if (cohort.isStatic) {
+ throw new Error(
+ 'Cannot refresh static cohorts — they are one-time snapshots',
+ );
+ }
+
+ await enqueueCohortCompute(input.cohortId);
+
+ return { success: true };
+ }),
+});
diff --git a/packages/validation/src/cohort.validation.ts b/packages/validation/src/cohort.validation.ts
new file mode 100644
index 000000000..cc79c6b85
--- /dev/null
+++ b/packages/validation/src/cohort.validation.ts
@@ -0,0 +1,146 @@
+import { operators } from '@openpanel/constants';
+import { z } from 'zod';
+
+// Defined locally to avoid a runtime TDZ from cohort.validation being
+// imported before index.ts has finished initializing zChartEventFilter.
+// Keep in sync with zChartEventFilter in ./index.ts.
+function objectToZodEnums<K extends string>(obj: Record<K, unknown>): [K, ...K[]] {
+ const [firstKey, ...otherKeys] = Object.keys(obj) as K[];
+ return [firstKey!, ...otherKeys];
+}
+
+const zChartEventFilter = z.object({
+ id: z.string().optional().describe('Unique identifier for the filter'),
+ name: z.string().describe('The property name to filter on'),
+ operator: z
+ .enum(objectToZodEnums(operators))
+ .describe('The operator to use for the filter'),
+ value: z
+ .array(z.string().or(z.number()).or(z.boolean()).or(z.null()))
+ .describe('The values to filter on'),
+ cohortId: z
+ .string()
+ .optional()
+ .describe('Cohort ID when using inCohort/notInCohort operators'),
+});
+
+export const zRelativeTimeframe = z.object({
+ type: z.literal('relative'),
+ value: z.enum(['7d', '30d', '90d', '180d', '365d']),
+});
+
+export const zAbsoluteTimeframe = z.object({
+ type: z.literal('absolute'),
+ start: z.string(),
+ end: z.string().optional(),
+});
+
+export const zTimeframe = z.discriminatedUnion('type', [
+ zRelativeTimeframe,
+ zAbsoluteTimeframe,
+]);
+
+export type Timeframe = z.infer<typeof zTimeframe>;
+
+export const zFrequency = z.object({
+ operator: z.enum(['gte', 'eq', 'lte']),
+ count: z.number().int().min(1),
+});
+
+export type Frequency = z.infer<typeof zFrequency>;
+
+export const zEventCriteria = z.object({
+ name: z.string().min(1).describe('The event name to match'),
+ filters: z
+ .array(zChartEventFilter)
+ .default([])
+ .describe('Filters applied to event properties'),
+ timeframe: zTimeframe.describe('When the event should have occurred'),
+ frequency: zFrequency
+ .optional()
+ .describe('How many times the event should have occurred'),
+});
+
+export type EventCriteria = z.infer<typeof zEventCriteria>;
+
+export const zEventBasedCohortDefinition = z.object({
+ type: z.literal('event'),
+ criteria: z.object({
+ operator: z.enum(['and', 'or']).describe('How to combine multiple events'),
+ events: z
+ .array(zEventCriteria)
+ .min(1)
+ .describe('Array of event criteria to match'),
+ }),
+});
+
+export type EventBasedCohortDefinition = z.infer<
+ typeof zEventBasedCohortDefinition
+>;
+
+export const zPropertyBasedCohortDefinition = z.object({
+ type: z.literal('property'),
+ criteria: z.object({
+ operator: z
+ .enum(['and', 'or'])
+ .describe('How to combine multiple properties'),
+ properties: z
+ .array(zChartEventFilter)
+ .min(1)
+ .describe('Array of profile property filters'),
+ }),
+});
+
+export type PropertyBasedCohortDefinition = z.infer<
+ typeof zPropertyBasedCohortDefinition
+>;
+
+export const zCohortDefinition = z.discriminatedUnion('type', [
+ zEventBasedCohortDefinition,
+ zPropertyBasedCohortDefinition,
+]);
+
+export type CohortDefinition = z.infer<typeof zCohortDefinition>;
+
+export const zCohortInput = z.object({
+ name: z
+ .string()
+ .min(1)
+ .max(255)
+ .describe('User-friendly name for the cohort'),
+ description: z
+ .string()
+ .max(1000)
+ .optional()
+ .describe('Optional description of the cohort'),
+ projectId: z.string().describe('The project this cohort belongs to'),
+ definition: zCohortDefinition.describe('The cohort criteria definition'),
+ isStatic: z
+ .boolean()
+ .default(false)
+ .describe(
+ 'Whether this cohort is frozen — if true, membership is computed once and not auto-refreshed',
+ ),
+});
+
+export type CohortInput = z.infer<typeof zCohortInput>;
+
+export const zCohortUpdate = z.object({
+ id: z.string().describe('The cohort ID to update'),
+ name: z.string().min(1).max(255).optional(),
+ description: z.string().max(1000).optional().nullable(),
+ definition: zCohortDefinition.optional(),
+ isStatic: z.boolean().optional(),
+});
+
+export type CohortUpdate = z.infer<typeof zCohortUpdate>;
+
+export const zCohortFilter = z.object({
+ cohortId: z.string().describe('The cohort ID to filter by'),
+ operator: z
+ .enum(['inCohort', 'notInCohort'])
+ .default('inCohort')
+ .describe('Whether to include or exclude cohort members'),
+});
+
+export type CohortFilter = z.infer<typeof zCohortFilter>;
diff --git a/packages/validation/src/index.ts b/packages/validation/src/index.ts
index eaf0de842..119388a68 100644
--- a/packages/validation/src/index.ts
+++ b/packages/validation/src/index.ts
@@ -28,6 +28,10 @@ export const zChartEventFilter = z.object({
value: z
.array(z.string().or(z.number()).or(z.boolean()).or(z.null()))
.describe('The values to filter on'),
+ cohortId: z
+ .string()
+ .optional()
+ .describe('Cohort ID when using inCohort/notInCohort operators'),
});
export const zChartEventSegment = z
@@ -640,3 +644,4 @@ export * from './types.insights';
export * from './track.validation';
export * from './event-blocklist';
export * from './chat';
+export * from './cohort.validation';