Segments and Cohorts

Relevant source files

The following files were used as context for generating this wiki page:

• src/app/(main)/websites/[websiteId]/segments/SegmentsPage.tsx
• src/app/(main)/websites/[websiteId]/cohorts/CohortsPage.tsx
• src/app/api/websites/[websiteId]/segments/route.ts
• src/queries/prisma/segment.ts
• prisma/schema.prisma
• src/lib/constants.ts
• src/app/(main)/websites/[websiteId]/segments/SegmentsTable.tsx
• src/components/messages.ts

Segments and Cohorts are powerful features within Umami that allow for the creation of saved user groups based on specific criteria. These features enable deeper data analysis by allowing users to filter website analytics data by these predefined groups. While they are presented as distinct concepts in the UI, "Segments" and "Cohorts" are implemented as a single, unified system distinguished by a type property.

This system provides a way to define, store, and manage these user groupings. The core functionality includes creating, reading, updating, and deleting (CRUD) segments and cohorts, which are then available for filtering in various reports and dashboards. The definitions for these groups, including their filter criteria, are stored in the database and associated with a specific website.

Data Model

The foundation of the Segments and Cohorts system is the Segment table in the database, defined in the Prisma schema. This single model serves both features, with the type field acting as the discriminator.

Sources: prisma/schema.prisma:224-234

Segment Table Schema

The following table details the columns of the Segment model.

Field	Type	Description
id	String	A unique UUID for the segment record.
websiteId	String	A foreign key linking to the Website this segment belongs to.
type	String	Discriminator field. Can be 'segment' or 'cohort'.
name	String	The user-defined name for the segment or cohort.
parameters	Json	A JSON object containing the filter criteria that define the segment.
createdAt	DateTime?	Timestamp for when the record was created.
updatedAt	DateTime?	Timestamp for the last update to the record.

Sources: prisma/schema.prisma:224-234

Entity Relationship Diagram

This diagram shows the relationship between the Website and Segment tables. Each website can have multiple segments/cohorts, but each segment belongs to exactly one website.

Core Logic and Services

All database interactions for segments and cohorts are managed through a set of functions defined in src/queries/prisma/segment.ts. These functions provide a clear abstraction layer for performing CRUD operations on the Segment model.

Sources: src/queries/prisma/segment.ts

Key Functions

Function	Description
getSegment(segmentId)	Retrieves a single segment by its unique ID.
getSegments(criteria, filters)	Retrieves a paginated list of segments, with support for searching by name.
getWebsiteSegment(websiteId, segmentId)	Retrieves a specific segment belonging to a specific website.
getWebsiteSegments(websiteId, type, filters)	Retrieves all segments for a given website, filtered by type ('segment' or 'cohort').
createSegment(data)	Creates a new segment record in the database.
updateSegment(segmentId, data)	Updates an existing segment record.
deleteSegment(segmentId)	Deletes a segment record from the database.

Sources: src/queries/prisma/segment.ts:9-45

Data Retrieval Flow

The following diagram illustrates the typical flow for retrieving a list of segments.

API Endpoints

A single API route, /api/websites/[websiteId]/segments, handles all HTTP requests related to both segments and cohorts. It uses the request method (GET, POST) and query parameters to determine the appropriate action.

Sources: src/app/api/websites/[websiteId]/segments/route.ts

GET /api/websites/{websiteId}/segments

This endpoint retrieves a list of segments or cohorts for a given website.

• Description: Fetches a paginated and searchable list of segments or cohorts.
• Query Parameters:
  • type: (Required) A string to filter by type. Must be either segment or cohort.
  • search: (Optional) A string to search for segments by name.
• Authorization: Requires a valid authentication token.

Sequence Diagram

This diagram shows the flow for a GET request to retrieve all cohorts for a website.

POST /api/websites/{websiteId}/segments

This endpoint creates a new segment or cohort.

• Description: Creates a new segment or cohort associated with the specified website.
• Request Body: A JSON object with the following properties:
  • name (string): The name of the segment/cohort.
  • type (string): The type, either segment or cohort.
  • parameters (object): The JSON object defining the filter rules.
• Authorization: Requires a valid authentication token.

Sequence Diagram

User Interface

The UI for managing segments and cohorts consists of two main pages, which are nearly identical in structure and functionality, and a reusable table component.

Segments & Cohorts Pages

The application provides two distinct pages for management:

• Segments Page: Located at src/app/(main)/websites/[websiteId]/segments/SegmentsPage.tsx. This page is responsible for displaying and managing items where type is 'segment'.
• Cohorts Page: Located at src/app/(main)/websites/[websiteId]/cohorts/CohortsPage.tsx. This page handles items where type is 'cohort'.

Both pages use a PageHeader component to display the title ("Segments" or "Cohorts") and an action button. They fetch their respective data by calling the GET /api/websites/{websiteId}/segments endpoint with the appropriate type parameter and display the results in a table.

Sources: src/app/(main)/websites/[websiteId]/segments/SegmentsPage.tsx, src/app/(main)/websites/[websiteId]/cohorts/CohortsPage.tsx, src/components/messages.ts:133-134

SegmentsTable Component

This reusable component is used to render the list of segments or cohorts.

• File Path: src/app/(main)/websites/[websiteId]/segments/SegmentsTable.tsx
• Description: It displays the data in a DataTable with three columns:
  1. Name: The name of the segment. This is a link that, when clicked, applies the segment as a filter to the main website analytics view.
  2. Created: The creation date of the segment, displayed as a relative time (e.g., "2 days ago").
  3. Action: Contains buttons to edit or delete the segment (SegmentEditButton, SegmentDeleteButton).

Sources: src/app/(main)/websites/[websiteId]/segments/SegmentsTable.tsx:9-32

Key Constants and Types

The distinction between a "segment" and a "cohort" is defined by a constant object.

Sources: src/lib/constants.ts:64-67

Constant	Value
SEGMENT_TYPES.segment	'segment'
SEGMENT_TYPES.cohort	'cohort'

This constant is used throughout the application, from the API to the UI, to ensure consistent handling of the two types.

Summary

The Segments and Cohorts system is a unified feature for creating and managing saved user filters. Although presented as two different features in the UI, they share the same underlying data model, API endpoints, and database query logic, differentiated only by a type field. This architecture promotes code reuse and simplifies maintenance, providing a robust mechanism for advanced data analysis within the Umami platform.