Reference/stats.md
stats: the numbers
Properties
code block
statskeys
9 on the block, 23 on each card
checked on
Dashy 2.2.0
Number cards: one value per card, computed over a selection of notes.
Prefer to have your agent write it? Build a dashboard with an AI agent.
From the demo vault
```stats
columns: 4
items:
- { label: Days logged, source: Diary, agg: count, icon: 📔 }
- { label: Average sleep, source: Diary, field: sleep_score, agg: avg, precision: 1, trend: 30d }
- { label: Steps this week, source: Diary, field: steps, agg: sum, unit: steps, period: week }
- { label: Best night, source: Diary, field: sleep_score, agg: max, trend: 90d }
- { label: Longest streak, source: Diary, field: sleep_score, agg: streak, unit: days }
- { label: Latest steps, source: Diary, field: steps, agg: latest, sub: most recent note }
- { label: Great nights, source: Diary, where: "sleep_score >= 90", agg: count }
- { label: Books read, source: Books, period: year, date_field: finished, agg: count, icon: 📚 }
```
renders as
A minimal block
The shortest config worth pasting. Change the folder and the property names to yours.
```stats
columns: 3
source: Diary
items:
- { label: Notes, source: 01-Areas, agg: count }
- { label: Sleep, field: sleep_score, agg: avg, precision: 1, trend: 30d }
- { label: Best streak, field: sleep_score, agg: streak }
- { label: Gym this week, field: gym, agg: sum, period: week, compare: true, better: up }
```
Keys on the block
| Key | What it does | Type | Default |
|---|---|---|---|
columns |
columns in the grid, 1 to 6. On a phone a block never shows more than two columns | number | 3 |
layout |
cards draws a grid of cards; inline draws the same numbers as one line of text, like 1001 notes · 188 journal entries · 14 open tasks, for a page header. Inline keeps icon, unit and the compare delta, but draws no trend, no sub and no group_by card and ignores columns, with one warning for each. An unrecognised value warns and falls back to cards |
text | cards |
items required |
the list of cards | list | none |
sourcealso folder, from |
folder for every card that names none of its own; includes nested ones. A card's own source replaces it |
text | none |
tag |
tag for every card that names none of its own, with or without the hash. A card's own tag replaces it |
text | none |
where |
conditions every card must meet, written like a card's where. A card's own where does not replace it but narrows further: both must hold |
text or list | none |
period |
window for every card that sets none of its own, written like a card's period. A card's own period replaces it |
text or number or map | none |
date_field |
date property for every card that sets none of its own, written like a card's date_field. A card's own date_field replaces it |
text | none |
date_format |
date format for every card that sets none of its own, written like a card's date_format. A card's own date_format replaces it |
text | none |
Keys on each card
Each entry under items is one card.
labelsourcetagwhereperioddate_fielddate_formatcomparebetterfieldaggat_leastat_mostdaysskip_fieldunitprecisiontrendiconsuborigingroup_bylimit| Key | What it does | Type | Default |
|---|---|---|---|
label requiredalso title, name |
caption under the number, or after it with layout: inline |
text | none |
sourcealso folder, from |
folder; includes nested ones | text | none |
tag |
tag, with or without the hash | text | none |
where |
a condition like year = 2026, rating >= 4, tags contains books, or several that must all hold: joined with and (year = 2026 and rating >= 4) or written as a list ([year = 2026, "rating >= 4"]). The field name may be a dotted path into a nested property, like health.sleep > 70. date empty keeps the notes where a property is missing, blank or an empty list, and date not empty the notes where it holds a value, 0 and an unticked checkbox included. or is not supported; quote a value holding the word and or or. One unreadable condition drops the whole filter with a warning, and the numbers are drawn unfiltered |
text or list | none |
period |
narrow to a window: week, month, year (the current calendar one) or a rolling count of days like 30d, all ending today; note, the day, week, month, quarter or year the name of the note this block sits in stands for, like 2026-W40; a period written out the same way: 2026-10-01, 2026-W40, 2026-10, 2026-Q4 or 2026; or { from: 2026-09-01, to: 2026-09-30 }, both days included, from alone running to today. Notes without a date are left out first, then every agg, count included, runs on what remains. A week starts on the first day of the interface language, Dashy's own when one is picked in its settings, otherwise Obsidian's: Sunday in English, Monday in most European languages; a week named like 2026-W40 is the seven days its name stands for |
text or number or map | none |
date_field |
a date frontmatter property to read instead of the note name: 2026-03-02 or 2026-03-02T10:30, or in date_format, or a dotted path into a nested property like meta.date. Feeds period's window, the streak, current_streak, latest and trend readings and the date origin shows; has no effect on count, sum, avg, min or max without period or origin |
text | none |
date_format |
a date format for note names and date_field values not written as YYYY-MM-DD, in moment notation: DD.MM.YYYY, MM/DD/YYYY, YYYYMMDD. Tried after YYYY-MM-DD and before the day format of the Daily notes or Periodic Notes settings, which is read without this key. A name or a value only has to start with the date (05.10.2026 Monday and 05.10.2026 14:30 count); the match is strict, so 5.10.2026 and 31.02.2026 are no date under DD.MM.YYYY. Needs a year, a month and a day, and warns when no selected note fits it. Steers the same readings date_field does. Month and weekday names (MMMM, dddd) are read in Obsidian's language, or in the Plugin language setting when one is picked |
text | none |
compare |
true shows the delta against the same stretch of the previous period, to date, and the previous value after it, formatted like the card: ▲ +1 (was 3). This week compares against the same weekdays last week, not the whole of last week. A fixed period already over compares against the whole period before it, June against all of May; a from/to against as many days right before from. usual shows the delta against the usual level instead: the average of the same field over every note in the card's selection dated before the window starts, the window itself left out. usual works with agg: avg only and warns with any other aggregate; with no note before the window the card says there is no history yet instead of a delta, as a tooltip on the number under layout: inline. Only with period set, and not with agg: streak or current_streak |
true or false or text | none |
better |
up colours a rise green and a fall red; down reverses that for a number where less is better. No change stays neutral either way. Only with compare: true or compare: usual |
text | none |
fieldalso property, prop |
numeric frontmatter property, or a checkbox (ticked counts as 1, unticked as 0), dotted for a nested one like health.sleep; required for everything but count, streak and current_streak. A field missing from the whole selection, or holding text rather than a number, shows a dash and a warning naming it; count text instead with where: "field contains ..." and agg: count. A duration string like 5h 58min, 1h30m, 45m, 90 min, 7:30 or ISO 8601 PT1H45M counts as minutes (ISO years and months, like P1M, are not durations; PT1M is a minute), and sum, avg, min, max or latest over a field of durations shows 5h 58m. When every value of the field across the selected notes carries seconds, like 2:16:32 or 2h 16m 32s, the card shows a clock to the second instead: 2:16:32, 0:18:51, and so does a compare delta. H:MM is always hours and minutes, never a time of day or minutes and seconds: a 5 km time written 18:51 reads as 18 hours, so write race times as 0:18:51. A field mixing durations and plain numbers counts both as minutes, shows a plain number and warns naming a note of each kind. Also takes a list, like [run_min, bike_min, swim_min], for one number over several properties: each note's value is the sum of the listed properties it holds, a note holding none of them is left out rather than counted as 0, and agg then works on those per-note totals, so avg is the average of the notes' totals and max the biggest one. A list of one is that one field. For streak and current_streak a day is filled when any listed property is, and at_least/at_most compare the day's total. Durations and plain numbers add up as minutes, under the same mixing rule as one field. Each listed property missing from the selection, or holding only text, warns by name, and the others still count; an empty list or an item that is not a property name is an error, and a name listed twice counts once and warns. This differs from a list in the field of a chart series entry or of a heatmap, which pools every single value, so a chart's avg or a heatmap's per_day: avg averages properties rather than notes |
text or list | none |
aggalso aggregate |
count sum avg min max latest streak current_streak | text | count |
at_least |
with agg: streak or current_streak only: a day counts only once its notes' field values, summed for that day, reach this, like at_least: 5000 steps; combine with at_most for a range. Needs field; ignored on any other aggregate. Takes a duration like 7h or 7:30 too, read as minutes; a plain number against a field of durations means minutes |
number or text | none |
at_most |
with agg: streak or current_streak only: a day counts only while its notes' field values, summed for that day, stay at or under this, like at_most: 5 cigarettes; combine with at_least for a range. Needs field; ignored on any other aggregate. Takes a duration like 7h or 7:30 too, read as minutes; a plain number against a field of durations means minutes |
number or text | none |
days |
with agg: streak or current_streak only: weekdays makes Saturday and Sunday transparent, so they neither break the run nor add to it, whatever they hold; all, the default, counts every day. Ignored on any other aggregate |
text | all |
skip_field |
with agg: streak or current_streak only: a property marking a day special, like vacation: true or sick: flu; a day is special once any note landing on it sets the property to anything other than false, a blank string, 0 or absent. A special day neither breaks the run nor adds to it, whatever field holds, the same way days: weekdays treats a weekend, and the two combine. Ignored on any other aggregate |
text | none |
unit |
a suffix after the number: km, %, d. Ignored, with a warning, on a value shown as a duration, which carries its own units. The count nouns day, week, month, year, night and time agree with the number: 1 day, 2 days; any other unit stays as written. |
text | none |
precision |
decimal places, 0 to 6; by default a whole number stays whole and a fraction gets one decimal; no effect on a value shown as a duration | number | none |
trend |
sketch the last N days ending today, or on the last day of a period window already over: 30d. Needs field. Its own trailing window, independent of period |
text or number | none |
iconalso emoji |
emoji | text | none |
sub |
small caption under the title | text | none |
origin |
with agg: latest, min or max only: say where the value came from, under the label. note shows the name of the note it was taken from, as a link; date shows that note's date in the interface language, read like the rest of the card (date_field, date_format, the note name). When several notes share the smallest or largest value, the newest of them is named. After sub when both are set. A card key only, not inherited from the block root; not shown with layout: inline |
text | none |
group_by |
a property whose values each get a row: the card ranks them, the value's name and its number, best first, instead of showing one number. agg and field work per value, count by default: { label: Games by platform, source: Games, group_by: platform } counts the games on each platform, { label: Best rating by genre, source: Games, group_by: genre, field: rating, agg: max } shows each genre's best rating. Ranked from the largest number down, except agg: min, ranked from the smallest up, the best time first; a tie goes to the value's name in alphabetical order. A note whose property is a list, like genres: [rpg, indie], counts in each of its values, and a line under the card then says the rows can add up to more than the number of notes. Values group regardless of case and show in the spelling most notes use; a link like [[Switch]] or [[Consoles/Switch|my Switch]] shows as the note's name, Switch, and groups with the plain text Switch; numbers and checkboxes group by their text. The notes where the property is missing or empty form one muted no value row, always last, outside the ranking and limit; leave them out with where: "platform not empty". precision, unit and the duration format apply to every row. compare, better, trend and origin describe one number and are ignored on such a card, with a warning; it is not drawn with layout: inline. A property no selected note has warns: every note would land under no value. A card key only, not inherited from the block root |
text | none |
limit |
with group_by only: how many rows to show, the best ones; the rest fold into one line, +3 more values. A whole number of 1 or more; anything else warns and shows 10. The no value row does not count towards it |
number | 10 |
How it behaves
streakcounts the longest run of consecutive days andlatesttakes the value from the newest note, a tie on the same date broken by path. Both resolve a note's date the same wayperioddoes, below, and two or more notes landing on the same day count as one day. With afield:set,streakis a field aggregate likesumoravg: nothing to count shows a dash, even over an empty selection. Without afield:it counts every selected note's own date instead, and reads a plain0when there is nothing, the same ascount.streakis the best run on record: label the card "Best streak" or "Longest streak".current_streakis the run going on now, counted back from today by the same rules: label the card "Current streak" or "Days in a row". Today never breaks it: a day not filled yet leaves the run counted up to yesterday, and only a gap on yesterday or earlier resets it to0. It counts within the selection afterperiod,where,tagandsource, soperiod: monthstops it at the first of the month.countover nothing reads a plain0, the number of notes found; every other aggregate, andstreakorcurrent_streakwith afieldset, shows a dash instead: "no data" and "zero" are different answers.trendsketches the days of a trailing window ending today, scaled between the smallest and largest value in that window rather than from zero. A day without a note is left out, not drawn as a zero, and two or more notes on the same day are summed into that one day's bar.periodnarrows to a calendar week, month, year or a rollingNd, ending today, or to a fixed window, below. A note's date is its name, as long as it starts withYYYY-MM-DD(2026-03-02 Mondaycounts,2026-03-021does not) or with a date indate_formator in the Daily notes day format, unlessdate_fieldnames a property instead; a note with no date under either rule is left out before counting.compare: truekeeps the previous period's number in sight for a review table:{ label: Gym days, field: gym, agg: sum, period: week, compare: true, better: up }reads 4 with▲ +1 (was 3)beside it, the previous value in the card's own format andunit; for a window that is still running it is the same days of the previous period to date, and the whole period once it is over. On a narrow card(was 3)wraps to its own line whole.compareneeds a note in both windows; when either the current or the previous stretch has none at all, the card shows its number alone with no delta and no previous value.streakandcurrent_streakhave no value of their own to compare and refusecompareoutright, the waytrendrefusescount.- Durations written in ISO 8601, as some apps and exports store them, count as minutes like any other:
focus: PT1H45Mis 105 minutes, so{ label: Focus, field: focus, agg: sum, period: week }overPT1H45M,PT45MandPT6H58Mreads9h 28m. Any non-empty subset ofPnWnDTnHnMnSin that order works, in either case:PT90S,PT0.5H,P1DT2H,P2W. Years and months (P1Y,P1M) are not durations, their length varies, and such a value reads as text;PT1Mis a minute. compare: usualanswers "is this week normal for me":{ label: Sleep, field: sleep_score, agg: avg, period: week, compare: usual, better: up }reads 82 with▼ −3beside it when every earlier note averages 85, and the tooltip saysvs usual: 85. In a weekly review note named2026-W40,period: noteat the block root does the same for that week:period: notewithitems: [{ label: Sleep, field: sleep_score, agg: avg, compare: usual, better: up }]. The usual level is the average over every note in the card's selection dated before the window, however old, so the week is never measured against an average it is part of; it is formatted like the card,6h 12mfor durations. It needsagg: avgand aperiod, written on the card or at the block root.at_least/at_mostturnstreakinto a threshold: a day counts only when its notes'fieldvalues, summed for that day, satisfy the bound,at_least: 5000on steps for example.days: weekdaysmakes Saturday and Sunday transparent forstreakandcurrent_streak: they neither break the run nor extend it, whatever they hold, so a Friday followed by a Monday is a run of two.skip_fielddoes the same for a day any note marks special,vacation: trueorsick: flufor example, and combines withdays: weekdays. All three keys apply toagg: streakandagg: current_streakonly and are ignored on every other aggregate.source,tag,where,period,date_fieldanddate_formatwritten at the block root, next toitems:, apply to every card, so a folder shared by the whole block is written once. A card's ownsource,tag,period,date_fieldordate_formatreplaces the root's for that card;whereis the exception: the root's conditions and the card's own both hold. A root folder that does not exist, a rootwhereorperiodthat cannot be read, a blank rootsourceortag, a rootdate_fieldthat no note selected underperiodhas a date in, or a rootdate_formatthat none of the notes its cards select fits is reported once for the block, not once per card. A card's ownsource:ortag:left empty still replaces the root's, so the card reads the whole vault or drops the tag filter, and it warns: to inherit the root's value, remove the key. Withoutitems:the block is a single card and these keys are simply its own.layout: inlinedraws every card as one item of a single line, its number first and its label after, joined by a middle dot:items: [{ label: notes, agg: count }, { label: journal entries, source: Journal, agg: count }]withlayout: inlinereads1001 notes · 188 journal entries, so a lowercase label reads best there. Acomparedelta follows the label, coloured the way it is on a card. A narrow pane wraps the line between items, never inside one. A card whose number cannot be computed shows a dash in its place and the rest of the line still draws.- Daily notes named another way, like
05.10.2026, are read in the day format set in the Daily notes or Periodic Notes settings, with no key at all. Without that setting, name the format:date_format: DD.MM.YYYY. A time after the date is fine (2026-10-05-14:30), but an order that could be read two ways, like05-10-2026, is never guessed: without a format it is not a date. - A weekly review: in a note named
2026-W40,period: noteat the block root counts that week and no other, however late the note is opened:period: notewithitems: [{ label: Gym, field: gym, agg: sum, compare: true }, { label: Sleep, field: sleep_score, agg: avg }]. A period written out works anywhere:period: 2026-Q4, orperiod: { from: 2026-06-01, to: 2026-08-31 }for a season. The name is read in the formats set in Periodic Notes for each period (one switched on there with no format saved, in the plugin's default, so a week is the locale weekgggg-[W]ww), the day falling back to Daily notes, then as ISO:YYYY-MM-DD,GGGG-[W]WW,YYYY-MM,YYYY-[Q]Q,YYYY, the day first, so2026never takes2026-10. The note's name may go on after the day, week, month or quarter, past a space,_or-and not straight into a digit (so a time after the day,2026-10-05 14:30, is not read here):2026-W41 Weeklyis that week,2026-10 Monthly Reviewthat month; a year takes nothing after it, so2026 goalsis no period, and a period written in the block,period: 2026-W41, takes nothing after it either. In a weekly formatwwwithggggis the week by the rules of Obsidian's language,WWwithGGGGthe ISO week.YYYYis the calendar year: paired withwworWWit names a week across New Year with the wrong year, and a block in such a week warns and suggestsggggorGGGG. A note named otherwise is an error that lists those formats; nothing is guessed. In a template, a note in the template folder of the core Templates plugin or of Templater, a name that is no period is no error: the block draws no numbers but a line saying the note is a template, under any other problem the config has, and a note made from it and named for a period counts that period. A window already over compares against the whole period before it, June against all of May however long each is; afrom/toagainst as many days right beforefrom; one still running against the same days of the period before, asperiod: weekdoes.current_streakcounts back from the window's last day, andtrendends there. A window already over does not forgive that day the way a running one forgives today: a closed week with its last day unticked reads0. A window that has not started yet, a note on next week, draws no cards, only the day it starts.period: 2026is the year 2026; write2026dfor a count of days. - One number over several properties:
{ label: Workout minutes, field: [run_min, bike_min, swim_min], agg: sum, period: week }adds up the three in each note, a note holding onlybike_mincounting that alone and a note with none of them left out;agg: avgon the same list averages those per-note totals. Without alabelthe card is namedrun_min + bike_min + swim_min. - Records with the race name:
{ label: Best 10k, source: Races, field: time, agg: min, origin: note }reads0:48:05with the note it came from,2025-09-14 Autumn 10k, linked under the label;{ label: Ferritin, source: Labs, field: ferritin, agg: latest, origin: date }shows the date of the last analysis instead, likeSep 22, 2026.originworks withlatest,minandmaxonly and describes the value in the card's own window, never the previous onecomparereads. Two races with the same best time name the newer one. Withorigin: date, a note with no readable date shows no caption and a warning naming it. A hand-writtensubstays and comes first:sub: personal bestwithorigin: notereadspersonal best · 2025-09-14 Autumn 10k. - Counting notes by a property:
{ label: Games by platform, source: Games, group_by: platform, limit: 5 }draws one card with a row per platform,Switch 12,PC 9,PS5 4, the largest first, and+2 more valuesunder the fifth.aggandfieldwork per value:{ label: Hours by platform, source: Games, group_by: platform, field: hours, agg: sum }adds up each platform's hours, and{ label: Best time per course, source: Races, group_by: course, field: time, agg: min }shows each course's best time, smallest first. The selection, on the card or at the block root (source,tag,where,period), narrows the notes before they are grouped. This is a number per value; a list of the notes themselves is Obsidian Bases.
Guides that use it
- A habit tracker in Obsidian without Dataview
- A habit streak in Obsidian that skips weekends
- A weekly review in Obsidian, without Dataview
- Books per year: a reading log chart in Obsidian
- An Obsidian homepage dashboard without code
Dashy is in Obsidian's community plugins. Search for Dashy, install, enable, then run Dashy: Insert block and pick stats.