Administering Cohort Builder

Cohort Builder is disabled by default on each dataset, so that Data Owners control the use of it on their datasets.

This is managed from the dataset Administration tab using the Cohort Selection Permissions.

Cohort Permissions.png

The cohort permissions are:

Allow users to create private cohorts for this datasetAllows users to create cohorts that can be shared with named users.
Allow users to create internal cohorts for this datasetAllows users to create cohorts that are visible to all users with permission to view the parent dataset
Allow users to view cohort counts for this datasetEnables/disables the count feature of the cohort UI
Allow users to view cohort charts and visualisations for this datasetEnables/disables the visualisation feature of the cohort UI
Minimum number of records for cohort charts and visualisationsAllows data owner to set a minimum cohort size below which cohort visualisations are disabled in the UI

Cohort Builder is enabled on a dataset when users are given the permission to create private or internal cohorts. If both of these permissions are disabled then Cohort Builder will not be available on a dataset.

Dictionary and Field visibility

Data Owners also have the ability to exclude sensitive fields from Cohort Builder when it is enabled.

This is managed in the Cohort Filter column of each dictionary table in a dataset:

Cohort Filter.png

The Data Owner can enable or disable all the fields in a dictionary at the same time using the tick box in the column header, or they can use the toggles to enable or disable each field individually.

Fields disabled in the Cohort Builder cannot be selected as filters in the query builder and are not available to view as visualisations. However, they will still be included in any data transfers of the cohort.

When a new dataset is created all fields are excluded from Cohort Builder by default.

Entity Flag


The Data Owner can also choose to mark dictionary fields with the entity flag. This identifies the field as a unique value within the dictionary, and when applied records that share the value will only be counted once in cohort counts.

For example, if a dictionary contains the field Patient ID, then the data owner may want to apply the entity flag to this field. If the dataset contains three records with the same Patient ID when the entity flag is not applied the records will be counted individually, if the entity flag is applied then the three records will be counted together as one entity within the cohort.

Cohort Builder and User Roles

Like all FAIR permissions, access to Cohort Builder is determined by the user's role.

The following system roles have Cohort Builder access by default:

  • Data Manager
  • Data Steward
  • Standard User

Reviewing Cohort Requests

Cohort requests are reviewed and approved in the same way as dataset requests, and can be viewed on the My Requests screen.

However, when a cohort request is submitted, the reviewer is provided with a link to the cohort.

Summary Section.png

Dictionary Management

Query Builder

Cohort Builder uses the dataset dictionaries to build its queries of the underlying data. Therefore, any mismatches between the dictionary and the data will degrade the performance of Cohort Builder.

The Validation Report allows users to identify the following errors:

  • Field exists in data but not in dictionary
  • Field exists in dictionary but not in data
  • Database and Dictionary Types do not match up

Where a field exists in the data but not the dictionary users will not be able to query the field in Cohort Builder.

Where a field exists in the dictionary but not the data, or where there is a type mismatch between the dictionary and data fields, this may cause the cohort query builder to error.

In all cases, the data owner must decide the appropriate resolution for an error.


The dictionary is also used to define and display cohort visualisations.

The field type determines which visualisations are available for a particular field. At present, the Cohort Builder supports four types of visualisation:

VisualisationData Type Supported
Bar ChartText fields
Stacked Bar ChartText fields
Box PlotX Axis - Text fields/Y Axis - Numeric fields
HistogramNumeric fields

Dictionary information is also used to populate the visualisations, with the field label used on the chart display.

Where a field has lookup values, the Description is used in the visualisation, not the Name:

Lookup values.png

In this example, the descriptions 'No family history of dementia' and 'Family history of dementia' are used to label the values in a bar chart generated from the data:

Lookup viz.png

Updated on August 21, 2023

Was this article helpful?