> For the complete documentation index, see [llms.txt](https://docs.dbnetsoft.com/dbnetsoft/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dbnetsoft.com/dbnetsoft/finalscore/expressions/fields.md).

# Fields

Every name you can read in an expression - by where the expression is used.

A **field** is a name you read in an expression: `lastName`, `timeValue`, `ranks.class`, `splits.km10.time`. Many fields are objects with sub-fields, written with a dot: `class.name`, `splits.km10.rank`. Keys you choose in the setup - splits, special results, rankings, heats, rounds - are written as they are, in lower case.

## Which fields exist where

| Where                                                                         | Fields                                                                                                                                                                                                                                                                                                                                                                            |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Athlete lists (Rows: Athletes), Heats → Add athletes, the editor's test value | [athlete data](#athlete-data), [state and result](#state-and-result), [ranks](#ranks-and-gaps), [splits](#splits), [special results](#special-results), [heats](#heats-and-runs), [rounds](#rounds), [objects](#competition-class-team-event), your [functions and additional fields](https://docs.dbnetsoft.com/dbnetsoft/finalscore/expressions/custom-functions-and-fields.md) |
| Heat lists (Rows: an athlete per heat), or an athlete list shown for one heat | the same - but time, splits, laps, results, ranks, `status` and `penalty` are those of the run in that heat; `heat`, `round`, `position` and `entryComment` are that heat's                                                                                                                                                                                                       |
| Team lists                                                                    | [team fields](#team-lists) and your functions                                                                                                                                                                                                                                                                                                                                     |
| Bracket lists (parallel)                                                      | athlete fields plus `heat`, `round`, `lane` and `laneColor` in their [bracket meaning](#bracket-lists)                                                                                                                                                                                                                                                                            |
| Formulas, rankings, started / finished rules, offsets                         | a [smaller set](#formulas-rankings-and-rules)                                                                                                                                                                                                                                                                                                                                     |
| List title, sub title                                                         | `event`, `competition`, `heat`, `now`                                                                                                                                                                                                                                                                                                                                             |
| Group header                                                                  | the group's first row plus the list's names                                                                                                                                                                                                                                                                                                                                       |
| HTML layout                                                                   | `list`, `defaultHtml`, `event`, `competition`, `heat`, `now`                                                                                                                                                                                                                                                                                                                      |
| PDF header / footer cells                                                     | `list`, `event`, `page`, `pages`                                                                                                                                                                                                                                                                                                                                                  |
| Bracket round / heat header                                                   | `round`, `heat`, `event`, `competition`, `now`                                                                                                                                                                                                                                                                                                                                    |

## Athlete data

| Field                   | Meaning                                                                                                                                                                   |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | internal athlete id                                                                                                                                                       |
| `bib`                   | bib (text)                                                                                                                                                                |
| `firstName`, `lastName` | first and last name                                                                                                                                                       |
| `name`                  | "Last First"                                                                                                                                                              |
| `displayName`           | "First Last"                                                                                                                                                              |
| `sex`                   | `M`, `W`, `X` or empty                                                                                                                                                    |
| `yearOfBirth`, `yob`    | year of birth                                                                                                                                                             |
| `age`                   | age in the year of the event                                                                                                                                              |
| `nation`                | nation (IOC code)                                                                                                                                                         |
| `club`                  | club                                                                                                                                                                      |
| `code`                  | licence / federation code                                                                                                                                                 |
| `transponder`           | chip code                                                                                                                                                                 |
| `comment`               | comment                                                                                                                                                                   |
| `teamKey`               | the team key from the registration                                                                                                                                        |
| `custom`                | additional fields as text: `custom.<key>` (see [Custom functions and fields](https://docs.dbnetsoft.com/dbnetsoft/finalscore/expressions/custom-functions-and-fields.md)) |
| `entryComment`          | the comment on the heat entry                                                                                                                                             |
| `position`              | start order / position in the heat                                                                                                                                        |

## State and result

| Field                             | Meaning                                                                                                                                        |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`                          | `OK`, `DNS`, `DNF`, `DSQ`, `NPS`, `OOC` - in a competition list the heat's status when it is not OK, else the athlete's                        |
| `statusText`                      | the status in words ("Did not finish")                                                                                                         |
| `statusOrder`                     | for sorting: OK 0, then the order set on page Event (default DNF, DSQ, DNS, NPS, OOC)                                                          |
| `state`                           | `notStarted`, `onCourse`, `finished`, `out`                                                                                                    |
| `started`, `finished`, `onCourse` | true / false - by the passings, the started / finished rules or set by hand                                                                    |
| `startTime`                       | start time of day (the athlete's own start when there is one)                                                                                  |
| `ownStart`                        | the athlete's own start, time of day                                                                                                           |
| `finishTod`                       | finish time of day                                                                                                                             |
| `time`                            | the result, formatted in the competition's precision (gross or net by the timing mode, with the penalty; a lap race: the time at the last lap) |
| `timeValue`                       | the same in seconds - for sorting and calculating                                                                                              |
| `gross`, `net`                    | gun time and chip time, formatted                                                                                                              |
| `penalty`                         | penalty, formatted; empty without one                                                                                                          |
| `laps`                            | completed laps                                                                                                                                 |
| `lapCount`                        | laps where they matter (a lap race or course), else empty                                                                                      |
| `bestLap`, `bestLapValue`         | the fastest lap, formatted / in seconds                                                                                                        |
| `lastLap`, `lastLapValue`         | the last lap, formatted / in seconds                                                                                                           |
| `lapTimes`                        | every lap as a list: `lapTimes[0]` is lap 1, `lapTimes.size` the number, `lapTimes \| array.join " / "` all of them                            |
| `place`                           | the overall rank as "1.", or the status when not OK                                                                                            |
| `stage`                           | parallel: the bracket round reached (Final, Small Final, Semi Finals, ..., Qualification)                                                      |

## Ranks and gaps

| Field      | Meaning                                                                                                                                                  |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ranks`    | the ranks by ranking key: `ranks.overall`, `ranks.sex`, `ranks.class` and `ranks.<key>` for your own rankings (Setup → Ranks); empty when not ranked     |
| `gap`      | gap to the winner, formatted (`+1:05.4`); empty for the winner and when laps apart                                                                       |
| `gapValue` | gap to the winner in seconds                                                                                                                             |
| `gapPrev`  | gap to the athlete ranked before, formatted                                                                                                              |
| `behind`   | lap race: laps behind the leader as text ("-2 Laps"), per ranking: `behind.overall`, `behind.sex`, `behind.class`, `behind.<key>`; empty on the lead lap |
| `autoRank` | rank within the list's innermost group, by the list's sorting (equal values share)                                                                       |
| `row`      | row number in the list                                                                                                                                   |
| `groupRow` | row number within the innermost group                                                                                                                    |

`autoRank`, `row` and `groupRow` are set while the columns are written - use them in columns, not in the filter, sorting or grouping.

## Splits

`splits.<key>` holds every split of the athlete's course except the start, passed or not: `splits.km10.time`. `lastSplit` is the last split passed, with the same sub-fields; it is empty before the first split, so write `lastSplit?.name`.

| Sub-field                  | Meaning                                                                    |
| -------------------------- | -------------------------------------------------------------------------- |
| `.key`, `.name`            | key and name of the split                                                  |
| `.distance`                | distance from the start in metres (Setup → Course)                         |
| `.order`                   | place on the course: 1 = the first split after the start                   |
| `.passed`                  | true when passed                                                           |
| `.tod`                     | time of day                                                                |
| `.time`                    | time at the split (gross or net by the timing mode), formatted             |
| `.timeValue`               | the same in seconds                                                        |
| `.gross`, `.net`           | formatted                                                                  |
| `.sector`                  | time since the previous split passed, formatted                            |
| `.speedSincePreviousSplit` | km/h since the previous split passed (the start for the first), 2 decimals |
| `.speedSinceStart`         | km/h since the start, 2 decimals                                           |
| `.rank`                    | rank at this split                                                         |
| `.gap`                     | gap to the first at this split, formatted                                  |

The speeds need a distance on the splits (Setup → Course → Distance); without one they are empty.

## Special results

`results.<key>` holds each special result (Setup → Results): laps, start and finish reads, formulas. A result that belongs to another competition is missing - in lists that mix competitions write `results.lap1?.time`.

| Sub-field                   | Meaning                                                               |
| --------------------------- | --------------------------------------------------------------------- |
| `.key`, `.name`             | key and name                                                          |
| `.passed`                   | true when it has a value                                              |
| `.fixed`                    | the passing is fixed to this result                                   |
| `.time`                     | the value formatted: a run time, a time of day or a number            |
| `.timeValue`, `.value`      | the value in seconds (or the number)                                  |
| `.tod`                      | time of day of the passing                                            |
| `.todValue`                 | the same in seconds since midnight                                    |
| `.gross`, `.net`, `.sector` | formatted                                                             |
| `.sectorValue`              | the sector in seconds                                                 |
| `.rank`                     | rank                                                                  |
| `.source`, `.sourceName`    | best / worst of several: where the value comes from (`LAP7`, "Lap 7") |
| `.error`                    | why the result has no value, when it failed                           |

## Heats and runs

`heats.<key>` holds the athlete's run in each heat of the competition (keys from Setup → Heats). In a heat the athlete is not in, it is empty and `.entered` is false.

| Sub-field                  | Meaning                                                                       |
| -------------------------- | ----------------------------------------------------------------------------- |
| `.key`, `.name`            | key and name of the heat                                                      |
| `.entered`                 | the athlete is in this heat                                                   |
| `.position`                | position in the heat                                                          |
| `.lane`, `.laneColor`      | parallel: the lane's name and colour                                          |
| `.status`, `.statusOrder`  | status in the heat, for sorting                                               |
| `.time`, `.timeValue`      | the run's time, formatted / in seconds                                        |
| `.gross`, `.net`           | formatted                                                                     |
| `.startTime`, `.finishTod` | times of day                                                                  |
| `.laps`                    | laps                                                                          |
| `.started`, `.finished`    | true / false                                                                  |
| `.state`                   | `notStarted`, `onCourse`, `finished`, `out`                                   |
| `.rank`                    | rank in the heat                                                              |
| `.rankOrState`             | "1." or the status                                                            |
| `.resultOrState`           | the time or the status                                                        |
| `.gap`                     | gap in the heat                                                               |
| `.counted`                 | the run counts for the competition's result (best run, best N, sum, last run) |
| `.splits.<key>`            | the run's splits, as above: `heats.final.splits.mid.time`                     |

## Rounds

`rounds.<key>` holds the athlete's result in each round of the competition - a duel, a stage of the bracket, a qualification.

| Sub-field                      | Meaning                                                                |
| ------------------------------ | ---------------------------------------------------------------------- |
| `.key`, `.name`                | key and name of the round                                              |
| `.stage`                       | `QuarterFinal`, `SemiFinal`, ...                                       |
| `.entered`                     | the athlete is in this round                                           |
| `.rank`                        | rank in the round                                                      |
| `.rankOrState`                 | "1." or the status                                                     |
| `.status`, `.statusOrder`      | when out of the round: DNS, DNF, DSQ; for sorting                      |
| `.time`, `.timeValue`          | the round's time by its scoring                                        |
| `.resultOrState`               | the time or the status                                                 |
| `.finished`                    | number of finished runs                                                |
| `.wins`                        | runs won                                                               |
| `.started`, `.decided`, `.won` | true / false                                                           |
| `.runs`                        | the runs, each like a heat above: `rounds.qf1.runs[0].time`            |
| `.splits.<key>`                | the splits of the run that decides (last or best run)                  |
| `.parent`                      | the athlete in the round above: `rounds.semifinal1.parent.rankOrState` |

In athlete lists two more fields describe where the row's run belongs:

* `heat` - the list's heat, else the heat whose run is the competition's result: `.id`, `.name`, `.key`, `.startTime`, `.sortOrder`, `.round` (the round's name). Write `heat?.name`.
* `round` - that heat's round: `.id`, `.name`, `.key`, `.sortOrder`, `.path` (every round from the competition down, joined with " · "), `.parent` (the round it is in). `rounds[round.parent.key].rankOrState` gives the athlete's result in the round above.

## Competition, class, team, event

| Field         | Sub-fields                                                                                                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `competition` | `.id`, `.name`, `.shortName`, `.laps`, `.startTime`, `.minLapTime` / `.minLapTimeValue`, `.startWindow` / `.startWindowValue`, `.sortOrder`, `.format`, `.timingMode`, `.color` |
| `class`       | `.id`, `.name`, `.shortName`, `.sortOrder`                                                                                                                                      |
| `team`        | `.id`, `.key`, `.name`, `.shortName`, `.nation` - `team.key` is what an athlete's `teamKey` matches                                                                             |
| `event`       | `.name`, `.date`, `.location`, `.organizer`, `.description`                                                                                                                     |
| `now`         | when the list was made, as text                                                                                                                                                 |

`class` and `team` are empty for an athlete without one: write `class?.name`, `team?.name`.

## Team lists

| Field                                      | Meaning                                                                               |
| ------------------------------------------ | ------------------------------------------------------------------------------------- |
| `id`, `name`, `shortName`, `nation`, `key` | the team                                                                              |
| `competition`                              | the competition of the team score                                                     |
| `rank`                                     | team rank; empty while incomplete                                                     |
| `place`                                    | "1."                                                                                  |
| `time`, `timeValue`                        | the scoring times added up, formatted / in seconds                                    |
| `gap`                                      | gap to the leading team                                                               |
| `complete`                                 | enough members finished                                                               |
| `scoringCount`                             | number of scoring members                                                             |
| `members`                                  | the members, each with `.bib`, `.name`, `.displayName`, `.time`, `.place`, `.scoring` |
| `autoRank`, `row`, `groupRow`              | as in athlete lists                                                                   |

```
{{ for m in members }}{{ m.name }} {{ m.time }}{{ if m.scoring }}*{{ end }}; {{ end }}
```

## Bracket lists

The columns of a bracket list describe one athlete in a duel box. Besides all athlete fields:

* `heat` - the athlete in the duel: `.time`, `.resultOrState`, `.rankOrState`, `.rank`, `.won`, `.wins`, `.finished`, `.decided`, `.name`, and each run as `heat.runs[0]` (`.time`, `.resultOrState`, `.rank`, `.rankOrState`, `.gap`, `.status`, `.finishTod`, `.lane`, `.name`).
* `round` - the stage: `.name`, `.type` ("Quarter finals"), `.kind` (`QuarterFinal`), `.heats` (number of duels), `.number` (the column, 1 = the first).
* `lane`, `laneColor` - the athlete's lane in the duel's first run (Blue / Red) and its colour.

The **round header** sees `round` as above. The **heat header** also sees `heat` as the duel: `.name`, `.key`, `.number` (its place in the round), `.round` (the round's type), `.runs` (the runs' names - `array.size(heat.runs)` is how many), `.decided`, `.scoring` ("Last run", "Best run", "Sum of runs", "Most runs won"), `.winner` (the winner's name once decided).

## List and page

| Field           | Where                    | Sub-fields                                                                                                                |
| --------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `heat`          | title, sub title, layout | the heat the list is shown for (empty: the whole competition)                                                             |
| `list`          | HTML layout              | `.name`, `.title`, `.subTitle`, `.landscape`, `.rowCount`, `.columns`, `.items`, `.isBracket`, `.errors`, `.generatedUtc` |
| `defaultHtml`   | HTML layout              | the built-in layout's HTML                                                                                                |
| `list`          | PDF cells                | `.title`, `.subTitle`, `.createdAt`, `.createdDate`, `.createdTime`, `.rows`, `.page`, `.pages`                           |
| `page`, `pages` | PDF cells                | page number and page count - to print, not to calculate with                                                              |

## Formulas, rankings and rules

Rankings, formula results, started / finished rules and offsets are worked out while the results are calculated. They see:

* **as in lists:** `bib`, `id`, `firstName`, `lastName`, `name`, `displayName`, `code`, `teamKey`, `sex`, `yearOfBirth` / `yob`, `age`, `nation`, `club`, `status`, `custom`, `class`, `team`, `competition`, `state`, `started`, `onCourse`, `finished`, `laps`, `time`, `timeValue`, `splits`, `lastSplit`, your functions and additional fields;
* **as numbers in seconds:** `startTime`, `ownStart`, `finishTod`, `gross`, `net`, `penalty`;
* **`results`** - in a formula only the results calculated before it;
* **`ranks.<key>`, `behind.<key>`** - only in rankings, and only of the rankings already calculated; `behind` is a number of laps there.

Not available there: `transponder`, `comment`, `statusText`, `statusOrder`, `place`, the gaps, `heats`, `rounds`, `heat`, `round`, `position`, the lap fields, `stage`, `row`, `autoRank`.

{% hint style="warning" %}
The editor checks these inputs against the athlete list fields, so it does not warn when a ranking or formula uses a list-only field - it just stays empty.
{% endhint %}
