> For the complete documentation index, see [llms.txt](https://docs.lucernahealth.com/guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lucernahealth.com/guide/insights-studio/population-builder/reference-guides/how-to-build-populations.md). # How to build populations A population is a defined group of members built from conditions across the data. Building one means translating a business question into rules the system can run. A request like *"diabetic members who are overdue on their care"* needs to be broken into parts before any rule is written: what defines diabetic, what counts as overdue, and who should be left out. This guide covers that process: how to structure a query, when to reuse existing content, and how the AND/OR logic determines your results. *** ### Three Ways to Add a Rule Every rule in a population comes from one of three places. #### Add Field Build a rule directly from the data model — select a field, choose an operator, enter a value. * **Use when:** The condition is simple and specific to this population * **Example:** Deceased = true, Age between 50 and 74

#### Add Block Reference an existing block, pulling in reusable logic. * **Use when:** The logic is common and already defined * **Example:** Active Roster Member

#### Add Population Reference another population as a building block. * **Use when:** The logic is complex enough to have been built as a standalone population * **Example:** Diabetic Eye Exam – Open

Before building anything from scratch, search what already exists. Complex logic that spans several conditions is more likely to exist as a population than a block. *** ### Creating a Population 1\. Click Add Population button to start creating a new population. If you're exploring and don't need to keep the result, you can skip the details and go straight to the Definition tab. | Field | Notes | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | Name | Clear title, visible wherever the population appears | | Key | Generates automatically and can be edited at creation, but not changed once saved. Two populations can share a name, but each population key must be unique | | Category | Business area used for grouping and filtering | | Description | Short summary of what the population contains and any caveats | | Run Schedule | Set up after the population is saved. Adding a run schedule requires fine grain permissions | 2\. Go to the Definition tab. This is where the query is built. It has two panels: * Left: the query builder, where rules are added * Right**:** the count and funnel breakdown, which updates as you build The root table sits above the query builder panel. It's the table the population is counted against. Leave it alone unless you have a specific reason to change it Once you save the population, you can access other tabs like Preview Data, References, Destinations and Run History
*** ### Creating a Simple Population #### Goal: Build a population for all members with diabetes who are overdue for an A1c test and haven't been seen recently #### Step 1. Break the question down Split the request into parts. Working out the parts first tells you what to search for 1. All members 2. Members with an open A1C care gap 3. Members with an appointment in the last six months #### Step 2. All members Start with "all members." Blocks are reusable logic, so there's a good chance one already exists for something this common. * Click Add Block to check.

* Type 'members' in the search box to see relevant blocks. "All members" could map to the **Active Roster Member** block. Active roster is how we define who currently counts as a member.

* To view the added block, click it and it opens in a new tab. #### Step 3. The A1C care gap The second part: diabetics overdue for an A1C, is too specific and complex to work as a reusable block. It fits better as its own population, so click Add Population to check.

* Type 'A1c' in the search box to see relevant populations. Care gap measures usually appear as three separate populations. A1C Control – Open is the one we need.

| Version | What it contains | | --------- | --------------------------------------- | | Eligible | Everyone who should receive the service | | Completed | Everyone who already has | | Open | Eligible, but not yet done — the gap | #### Step 4. Recent appointments (in last 6 months) The last part is specific to this query, so building it from scratch makes the most sense. * Click Add Field, then Select Column.

* Type 'appointment' in the search bar for selecting a column. If you know the table you are looking for, you can start with selecting 'Search by table' option

* 'Appointment' search term has many results, lets narrow it down. Checking when a member was last seen means looking at their appointment dates. Let's try 'appointment date'

* Here we have the same column from two different tables. Always select the one on the top. You can hover over the info icon next to table name to learn more about the table.

* Then set the operator. "Last six months" should always mean six months from whenever the population runs, a fixed date would need updating every time. So a relative operator works best here.

* Select order: Last N Calendar

* Select interval: months and type 6

#### Step 5. Read the result The finished query has three rules, each labelled with where it came from:

#	Rule	Label
1	Active Roster Member	Block
2	A1C Control – Open	Population
3	Last 6 months of appointments	Fct Appointment Provider Detail

The system auto-generates names for rules built from scratch. Rule 3 here becomes "Last 6 months of appointments." These names match across both panels, so you can trace any rule in the query to its effect on the funnel.

*** ### Add Group The example we jsut saw uses a single group, where all conditions must be true. When you need either/or logic, you need more than one group.

Logic	Applies	Meaning
AND	Within a group	A member passes only if they meet every condition in that group
OR	Between groups	A member passes if they match any one group

The word **either** in a request is the signal that you need a second group. If you want members who have either an open eye exam gap or an open kidney evaluation gap, those go in separate groups. Putting both in the same group would require members to have both. **Note:** Because groups are joined by OR, each group must independently define a complete population. If a condition applies to both groups, it needs to appear in both. #### Working With Groups Group names generate automatically based on their contents. To rename one, use the menu icon and select Update Group Name. Once renamed manually, automatic naming stops for that group, even if you add or remove conditions later. **Reordering:** Drag conditions to reorder them within a group. **Duplicating:** Use the copy icon to duplicate a condition. Only rules can be duplicated — not blocks or populations. **Removing:** Removing a group updates the count immediately. *** ### Exclude Everything in the Include section defines who's in the population. Exclude takes members back out. Anyone matching an Exclude condition is removed from the list, regardless of which group qualified them. **Note:** For a single condition such as Deceased = true, building from scratch is quicker than searching for something to reuse. *** ### Managing Populations #### Saving Saving a population unlocks the remaining tabs: Preview Data, References, Destinations, and Run History. To save, make sure all required fields on the Details tab are filled in. If you're just exploring and don't want to keep the population, click Cancel to return to the Populations tab. #### Editing the definition Once a population is saved, you can edit its Definition using the pencil icon on the right. Changes go live in two steps. Save your changes and review them, then Publish to push that version live. Until you publish, the live population is unchanged. Every edit is saved as its own version, and any previous version can be previewed and restored. #### Scheduling Run schedules are configured after the population is saved. Scheduling requires team-level permission, granted under Fine Grain Permissions in Teams. *** ### Best Practices #### Structure * Break the business question into parts before building anything * Search for existing blocks and populations before building from scratch * Keep each group independently complete, groups are joined by OR * Use relative operators for anything time-based #### Naming * Name the population for what it contains, not how it was built * Complete the description, it's what tells the next person whether this is the population they need