Most of what a business keeps on file is a record: a profile, a request, a report. But some information is different — it’s the same measurement, taken again and again. A meter reading. A soil moisture level. A weekly score. A count of visits.
Atlas models this kind of information as samples.
Records vs. samples
| Records | Samples |
|---|---|
| What you keep on file about a thing | A measurement captured against a subject |
| Built from a record schema | Built from a sample schema |
| Usually updated, occasionally replaced | Accumulate over time |
| Example: Property Profile | Example: irrigation reading |
In the Atlas tutorials, a classification holds both: record schemas say what one record of that kind looks like, while sample schemas describe measurements taken over time. Inside a topic, samples are listed alongside its data records.
Defining a sample schema
A sample schema describes the measurement you collect — what’s measured, in what form. Define one per kind of measurement, the same way you’d define a data schema for a group of fields.
Keeping measurements out of record schemas matters. Putting “latest reading” on a profile record loses the history; modeling readings as samples keeps every value.
Aggregations
Raw samples are useful; derived values are often more useful. Averages, running totals, thresholds crossed. Atlas’s Enginuity engine provides a visual aggregation canvas for computing them:
- An Entry node seeds a value — setting the mode and an initial value.
- Each Operation folds the running value forward: arithmetic, conditionals, thresholds.
- Once saved, the aggregation computes automatically as new samples arrive.
Atlas’s documentation describes the steps:
- Define a sample schema for the measurement you collect.
- Open the aggregation canvas and set the Entry mode and initial value.
- Add operations that transform the running value.
- Save the aggregation; it now computes automatically as new samples arrive.
Example uses
- Field services: average irrigation reading per property per month; flag properties that fall below a threshold.
- Equipment: running total of hours used, to schedule maintenance.
- Programs: cumulative attendance per participant.
- Quality: a count of failed checks, raising attention when it crosses a limit.
Why model measurements this way
Treating measurements as their own kind of data keeps history intact, makes trends easy to compute, and separates “what we know about this thing” (records) from “what we’ve observed about it over time” (samples). It’s one more way Atlas lets the data model follow how the business actually works.
Deciding between a record field and a sample
The test is whether you’ll want the history. Ask: if this value changes next month, do I need to know what it was before?
- Yes → a sample. Each measurement is kept, so trends and history survive.
- No → a field on a record, updated in place.
Examples that are almost always samples: readings, counts, scores, temperatures, hours used, attendance. Examples that are usually record fields: an address, a gate code, a contact name.
Designing a sample schema
Keep sample schemas narrow. A sample describes one kind of measurement, captured repeatedly. If you find yourself adding unrelated fields to a sample schema, that’s a sign there are really two measurements.
Think about:
- What exactly is measured, in what unit.
- How often it’s captured, and by whom.
- What derived values you’ll want — an average, a total, a threshold crossing — since those become aggregations.
Designing an aggregation
The aggregation canvas folds a running value forward: an Entry node seeds the value, and each Operation transforms it — arithmetic, conditionals, thresholds.
A practical approach:
- Write the calculation in a sentence first: “average of the last readings”, “running total of hours”, “count of readings below the threshold”.
- Set the Entry mode and initial value to match the starting point of that sentence.
- Add one operation per step of the calculation, in order.
- Save, then check the result against a few known samples.
Once saved, the aggregation computes automatically as new samples arrive.
Common mistakes
- Storing only the latest value on a record, losing the history you’ll later want.
- Mixing units in one sample schema, so aggregations produce meaningless numbers.
- Over-complex aggregations. Several simple ones are easier to understand than one long chain.
- Aggregating across unrelated subjects. Samples are captured against a subject; keep comparisons within the same kind of thing.
Frequently asked questions
Where do samples appear? Inside the topic they were captured against, alongside its data records.
Can a classification have several sample schemas? Yes — sample schemas describe measurements taken over time, and a classification can define more than one.
Do aggregations recalculate automatically? Yes; once saved, an aggregation computes as new samples arrive.
Planning measurements before you collect them
Measurements are easier to use when a few decisions are made up front:
- Decide the unit and stick to it. Mixing litres and gallons in one sample schema makes every aggregation wrong.
- Decide who captures it and when. A measurement nobody is responsible for taking quickly becomes patchy, and patchy data makes trends misleading.
- Decide how much history you need. That informs whether a value belongs in a sample at all.
- Decide what “unusual” looks like. If you know the threshold that should prompt attention, you can build it into an aggregation from the start.
Writing those four answers down takes minutes and prevents months of unusable measurements.
