> 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-blocks.md).
# How to build blocks
A block is a reusable set of filter conditions that can be referenced inside populations and other blocks.
Blocks don't run on their own. They produce no member lists and no saved counts. They take effect only as part of whatever references them.
That's what makes them useful. Logic like "active roster member" appears across dozens of populations and teams. Defining it once as a block means everyone references the same definition, and a correction made in one place carries everywhere it's used. Without blocks, the same logic gets rebuilt each time it's needed, and small differences creep in.
***
### Two Ways to Add a Rule
Blocks are built from two kinds of component. Unlike populations, blocks cannot reference populations.
**Add Block** Reference an existing block, pulling in reusable logic.
* Use when: The logic is common and already defined
* Example: Active Roster Member
**Add Field** Build a rule directly from the data model — select a field, choose an operator, enter a value.
* Use when: The condition is specific to what you're building
* Example: Plan State = FL
Before building anything from scratch, search what already exists. Reusing a block is faster and keeps definitions consistent.
***
### Creating a Block
1. Click Add Block button in Blocks tab to start creating a new block
2. Complete the Details tab.
| Field | Notes |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | Clear title, visible wherever the block appears |
| Key | A unique identifier for your block. It auto-generates as you type the name, and cannot be changed after saving. |
| Category | Categories for blocks include Care Continuity, Care Gaps, Clinical & Risk, Demographics, Eligibility & Coverage, Outreach Channels, and Utilization. |
| Description | Short summary of what the population contains and any caveats |
**2.** Go to the Definition tab. This is where the query is built. It has two panels:
* **Left:** the query builder panel, where rules are added
* **Right:** the funnel panel, showing the simulated count as you build
The simulated root table sits above the query builder panel. It's the table the block's count is calculated against, an estimate to help you understand your data as you build, not a live run.
Once the block is saved, it shows the latest version. Every edit is saved as its own version, and you can go back to any of them.
***
### Creating a Simple Block
#### Goal: Build a block for all active roster members in Florida.
#### Step 1. Break the question down
Split the request into parts:
1. Active roster members
2. Members in Florida
#### Step 2. Active roster members
* Click Add Field, then Select Column. The selection modal starts empty, type a column name to search, or search by table if you know which one you need.
* Start by typing `roster`. If you're not sure of the exact column name, type what you're looking for and pick from the results.
* The results for `roster` alone aren't quite right. We want *active* members, and active is a status — so add `status` next to it.
* Searching `roster status` returns Roster Status from two tables: Fct Roster and Fct Roster Calendar. Select the top result.
* Then complete the rule by choosing an operator and value: Roster Status = Active.
#### Step 3. Members in Florida
* Click Add Field, then Select Column, and search `state`.
* The first result, Facility State, refers to a facility's location, not the member's. Choose **Plan State** instead.
* The column name tells you what the field is, but the table tells you what it's about. Hover the info icon next to a table name to learn more about it before selecting.
* Complete the rule by choosing an operator and value: Plan State = FL.
#### Step 4. Read the result
The system auto-generates a name for every query that isn't a block. That same name shows up on the right panel, so you can trace any rule in the query to its effect on the count.
***
### Add Group
The example above uses a single group, where all conditions must be true.
Conditions within a group are joined by AND. Conditions between groups are joined by OR.
The word *either* in a request is the signal that you need a second group. Because groups are joined by OR, each group must independently define a complete set of conditions. 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.
**Removing:** Removing a group updates the count immediately.
***
### Exclude
Everything in the Include section defines what the block matches. Exclude removes matches from that.
Anyone matching an Exclude condition is removed, regardless of which group qualified them.
***
### Saving
Save the block if the logic is something you'll reuse across other blocks and populations. To save, make sure all required fields on the Details tab are filled in. Once saved, the References tab becomes available.
Editing works the same way as it does for populations. Use the pencil icon on the right to edit the Definition.
Changes go live in two steps. Save your changes and review them, then Publish to push that version live. Until you publish, the live block is unchanged.
Every edit is saved as its own version, and any previous version can be previewed and restored.
***
### Best Practices
**Structure**
* Break the request into parts before building anything
* Search for existing blocks before building from scratch
* Keep blocks narrow — one block should represent one idea
* If a block only makes sense inside a single population, that logic is usually better left as rules in that population
**Naming**
* Block names appear inside other people's queries, often without context. Write the name for someone who'll encounter it six months from now
* Name what the block contains, not how it was built: *Active Roster Member*, not *Roster filter v2*
* Avoid version numbers in names — version history already tracks changes
