# COHORT

> Follow people from their first record: retention by week, month, or quarter, who starts a cohort, the first-record column, and comparisons.

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.

```sql
-- 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

```sql
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](https://workstation.repzo.com/docs/analytics/repzoql/where), applied to each person's first record:

```sql
-- 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

```sql
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.

## Related pages

- [Report queries](https://workstation.repzo.com/docs/analytics/report-queries)
- [WHERE](https://workstation.repzo.com/docs/analytics/repzoql/where)
- [COMPARE TO](https://workstation.repzo.com/docs/analytics/repzoql/compare-to)