The model taxonomy

A model name is a small sentence

Names in this project normally contain three parts: a layer prefix, the domain subject, and a suffix where the model's shape needs to be made explicit.

Not every name needs all three parts. A staging model mirrors its source, so stg_olids_observation is complete. A canonical dimension such as dim_person needs no suffix.

The grammar spans every dataset the project models, not just OLIDS primary-care records. The same three parts name SUS hospital activity (fct_person_sus_apc_recent), GP appointments (fct_person_gp_recent), waiting-list pathways (int_wl_current) and resource use (fct_person_resource_index). Learning to read it once makes every source's models legible.

Prefix: the model's role

The prefix follows the model's responsibility, not its size or its grain.

Facts are subjects; dimensions describe them

The difference between the two reporting prefixes is the role a model plays in an analysis. A fact is the subject: the thing being counted or assessed. A dimension describes a subject: its attributes are joined on to group, filter and explain. When unsure which you are looking at, ask what an analyst does with the rows: do they count them? Or use them to break something else down?

The textbook fact is an event — an appointment, an admission. Many of this project's facts are states instead: fct_person_diabetes_register holds one row per person currently meeting the register definition, and analysts count those rows just the same. What the fact records has changed; the roles have not. The fact is still the subject, and dimensions such as dim_person_ethnicity still describe it.

How a role is chosen — when a transformation stays int_, when a subject deserves a supported fct_ or dim_ mart, and why a register is a fact — is design work, covered in Facts, dimensions and the reporting taxonomy.

Suffix: the model's shape

A suffix is useful when it distinguishes models about the same subject or warns that one row means something different.

Joining int_hba1c_all to a person-grain model can multiply its rows. The _all/_latest pair makes that grain difference visible before the join is written.

Families make the project searchable

Consistent names allow one search to enumerate a whole group of related models:

Families work because names put the entity first: dim_person_age, dim_person_ethnicity and dim_person_housebound_status sort together, search together and can be compared side by side. A new synonym breaks the family, which is why models reuse the vocabulary already in the project.

Read a family sideways

The repository already contains dozens of person dimensions, latest-event models and person-register facts. Looking across one family is often the fastest way to understand its taxonomy because the repeated parts stay fixed while the meaningful differences become visible.

Search before you build

Search the domain concept in VS Code, the project documentation and Snowflake. You may find that the model already exists. If it does not, nearby results show the vocabulary and naming family to follow. The next lesson turns this convention into a complete method for finding and evaluating models.

The command reference keeps the prefix, suffix and family tables available as a quick lookup. When you come to name a model of your own, Designing models finishes the job: choosing the analytical role, the subject vocabulary and a suffix that carries information.