:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { DateTime } from 'luxon'
import { Properties } from '~/plugin-scaffold'
import { Group, GroupTypeIndex, ProjectId, PropertiesLastOperation, PropertiesLastUpdatedAt, TeamId } from '~/types'
import { GroupRepositoryTransaction } from './group-repository-transaction.interface'
/**
* Read-only group lookups backed by personhog gRPC. Used by services that
* only need to fetch group data (CDP, error tracking). Always uses eventual
* consistency. Independent of GroupRepository — the two interfaces have
* different parameter shapes reflecting their different backends and consumers.
*/
export interface GroupReadRepository {
fetchGroupsByKeys(
teamIds: TeamId[],
groupTypeIndexes: GroupTypeIndex[],
groupKeys: string[],
callerTag?: string
): Promise<
{
team_id: TeamId
group_type_index: GroupTypeIndex
group_key: string
group_properties: Record<string, any>
}[]
>
fetchGroupTypesByTeamIds(
teamIds: TeamId[],
callerTag?: string
): Promise<Record<string, { group_type: string; group_type_index: GroupTypeIndex }[]>>
fetchGroupTypesByProjectIds(
projectIds: ProjectId[],
callerTag?: string
): Promise<Record<string, { group_type: string; group_type_index: GroupTypeIndex }[]>>
}
/** Identity of a single group row: (team_id, group_type_index, group_key). */
export interface GroupKey {
teamId: TeamId
groupTypeIndex: GroupTypeIndex
groupKey: string
}
/**
* A batched, merge-semantics group update: `propertiesToSet` is applied on top
* of the stored `group_properties` server-side (jsonb `||`), so concurrent
* writers can't lose each other's keys and no version assertion is needed.
*/
export interface GroupPropertiesToSetUpdate {
teamId: TeamId
groupTypeIndex: GroupTypeIndex
groupKey: string
propertiesToSet: Properties
createdAt: DateTime
}
/** A batched group creation: one new row at version 1 per entry. */
export interface GroupCreate {
teamId: TeamId
groupTypeIndex: GroupTypeIndex
groupKey: string
groupProperties: Properties
createdAt: DateTime
}
/**
* Result row of insertGroupsBatch: `inserted` is false when the row already
* existed and the creation's properties were merged onto it instead.
*/
export type GroupCreateResult = Group & { inserted: boolean }
/**
* Full group repository with read and write operations. Used by the
* ingestion pipeline which creates, updates, and manages groups.
* Postgres-backed with support for consistency control and row locking.
*/
export interface GroupRepository {
fetchGroup(
teamId: TeamId,
groupTypeIndex: GroupTypeIndex,
groupKey: string,
options?: { forUpdate?: boolean; useReadReplica?: boolean; callerTag?: string }
): Promise<Group | undefined>
fetchGroupsByKeys(
keys: GroupKey[],
callerTag?: string
): Promise<
{
team_id: TeamId
group_type_index: GroupTypeIndex
group_key: string
group_properties: Record<string, any>
created_at: DateTime
version: number
}[]
>
/**
* Applies all updates in a single statement and returns the updated rows.
* Rows whose group doesn't exist are absent from the result — callers
* handle those individually (typically by creating the group).
*/
updateGroupsBatch(updates: GroupPropertiesToSetUpdate[]): Promise<Group[]>
/**
* Inserts all groups in a single statement and returns one row per input.
* Rows that already exist (a lost cross-pod race) are merged server-side
* with the same jsonb semantics as updateGroupsBatch and come back with
* `inserted: false`, so callers can tell creations from merges without a
* second round trip. Creates must be unique by (team, type, key) —
* duplicates make the whole statement fail.
*/
insertGroupsBatch(creates: GroupCreate[]): Promise<GroupCreateResult[]>
insertGroup(
teamId: TeamId,
groupTypeIndex: GroupTypeIndex,
groupKey: string,
groupProperties: Properties,
createdAt: DateTime,
propertiesLastUpdatedAt: PropertiesLastUpdatedAt,
propertiesLastOperation: PropertiesLastOperation
): Promise<number>
updateGroup(
teamId: TeamId,
groupTypeIndex: GroupTypeIndex,
groupKey: string,
groupProperties: Properties,
createdAt: DateTime,
propertiesLastUpdatedAt: PropertiesLastUpdatedAt,
propertiesLastOperation: PropertiesLastOperation,
tag: string
): Promise<number | undefined>
updateGroupOptimistically(
teamId: TeamId,
groupTypeIndex: GroupTypeIndex,
groupKey: string,
expectedVersion: number,
groupProperties: Properties,
createdAt: DateTime,
propertiesLastUpdatedAt: PropertiesLastUpdatedAt,
propertiesLastOperation: PropertiesLastOperation
): Promise<number | undefined>
// Group Type Methods
fetchGroupTypesByProjectIds(
projectIds: ProjectId[],
callerTag?: string
): Promise<Record<string, { group_type: string; group_type_index: GroupTypeIndex }[]>>
fetchGroupTypesByTeamIds(
teamIds: TeamId[],
callerTag?: string
): Promise<Record<string, { group_type: string; group_type_index: GroupTypeIndex }[]>>
insertGroupType(
teamId: TeamId,
projectId: ProjectId,
groupType: string,
index: number,
createdAt: DateTime
): Promise<[GroupTypeIndex | null, boolean]>
// Transaction Methods
inTransaction<T>(description: string, transaction: (tx: GroupRepositoryTransaction) => Promise<T>): Promise<T>
}