COHORT

A cohort report follows people from their first record. Each row is a cohort, the people whose first record fell in the same week, month, or quarter; each column is a period after that.

-- Of the contacts who bought for the first time each month, how many bought again?
FROM invoices
SHOW customers, retention_rate
COHORT contact BY month
DURING last_12_months
VISUALIZE retention_rate TYPE cohort_grid

Syntax

COHORT <who> [BY week | month | quarter] [STARTING WITH <conditions>] [INCLUDING FIRST]

Part	What it does
`<who>`	Who to follow: the object itself (`COHORT contact` on contacts) or a reference on it (`contact`, `account`, `owner`)
`BY`	The cohort interval; `month` by default
`STARTING WITH`	Only people whose first record matches start a cohort. Their later records all count.
`INCLUDING FIRST`	Adds a First column with the first records themselves

LIMIT sets how many periods each cohort follows (12 by default). WHERE filters every record a cohort counts. GROUP BY and TIMESERIES don’t apply: a cohort report groups by cohort and period itself.

The periods

First (with INCLUDING FIRST): the records that put each person in the cohort.
Period 0: people who came back in the same period as their first record.
Period 1, 2, …: people active in each period after that.

Periods that haven’t happened yet are left out, so recent cohorts have fewer columns.

Metrics

Metric	Meaning
`customers`	People active in the period
`retention_rate`	Active people as a share of the cohort
`cohort_size`	People in the cohort
Counts and totals of the object	For example `count`, `total`, `won_value`, `sum(amount)`
Math	For example `total / cohort_size AS per_customer`

Show it as cohort_grid (one row per cohort, shaded by value) or retention_curve (one line per cohort). The All cohorts row averages each period over the cohorts that have reached it, weighted by size.

Who starts a cohort

STARTING WITH takes the same conditions as WHERE, applied to each person’s first record:

-- Retention of customers whose first order was paid online
FROM orders
SHOW customers, retention_rate
COHORT contact STARTING WITH payment_status = "paid"
DURING last_12_months

The difference from WHERE: WHERE payment_status = "paid" would also drop their later unpaid orders, while STARTING WITH only decides who is in.

Comparing totals

COMPARE TO previous_period

Runs the same cohorts for the period before and shows the earlier value and the change in the headline and the All cohorts row (in points for retention).

In the report builder

Switch a report from Freeform to Cohorts to build one without writing it:

Metric, Records, Follow, Chart, Interval, and Periods.
Cohort starts with: the filter icon sets the STARTING WITH conditions.
Show first record: the INCLUDING FIRST column.
Filters: the WHERE conditions.
Compare (at the top): individual cohorts, or totals against the previous period.

Like in Shopify, switching between Freeform and Cohorts starts a new report.