Every reading is a key and a value, for example "temperature": 21.5. This page lists the rules keys and values must follow, what happens to one that breaks a rule, and how to plan your key names.
Key rules
| Rule | Detail |
|---|---|
| Characters | A-Z, a-z, 0-9, _, . and - only |
| Length | 1 to 64 characters |
| Case | Case-sensitive: Temp and temp are two keys |
| Reserved prefixes | A key may not start with _, fw_, current_fw_ or cfg.. These belong to attributes (firmware state, desired configuration) and to the platform. |
A key that breaks a rule is left out of the record; the other keys of the same record are kept. The drop is reported in the flow’s run record (see the reasons below).
Value rules
| Value | Stored as | Limit |
|---|---|---|
| A finite number | A number (charted and aggregated) | |
true / false | A flag | |
| Text | Text | 1,024 characters |
| A JSON object or array | JSON | 4 KiB when written as JSON |
null | Nothing: “no reading”, not an error |
A value over its limit drops its key only. See Numbers, text and true/false values.
A message’s size
A message may hold at most 1,000 key-value points after it is split into records. A message with more is refused as a whole (bad_form); nothing of it is stored. The device’s profile also limits the payload size (64 KiB by default). See Device profiles.
The raw key
A body that is not JSON (binary data, plain text, or a JSON scalar or array on a custom topic) is stored under the single key raw, as text. The raw key is exempt from the 1,024-character limit and is capped by the profile’s Max raw payload (bytes) instead: 4,096 bytes by default, 256 to 65,536 bytes. A binary body arrives base64-encoded (msg.metadata.encoding is base64).
Decode raw in a flow (for example with the Base64, Hex or Bytes blocks, or a script) and save named keys. See Data transform blocks.
Topic-prefixed keys
With the profile setting Prefix keys with the topic, data on a custom topic is stored as <topic>.<key>:
/in the topic becomes.; any other character outside the key rule becomes_.- The reserved-prefix rule and the 64-character limit apply to the joined key. A joined key over 64 characters is dropped.
rawbecomes<topic>.raw, with the same raw limits.
Example: topic site1/boiler and key temp give site1.boiler.temp. Without the prefix, the same key arriving on two topics is one key, and the last write wins.
The key cap
Your plan can limit how many distinct keys your organisation stores:
| IoT plan tier | Distinct telemetry keys |
|---|---|
| Starter | 250 |
| Growth | 400 |
| Scale | 2,050 |
- A key counts once, however many devices send it.
- A key stays counted after the devices that sent it are deleted: the key dictionary is never pruned.
- The count is read at most once a minute.
- A new key over the cap is not stored; the other keys of the record are. When nothing of a record is left, Save telemetry reports
key_limit.
Keep key names stable and shared across device types (temperature, not temp_dev42). Put a device’s identity in the device, never in the key.
Profile key settings
The Telemetry keys list of a device profile (up to 500 keys) describes the keys its devices send:
| Field | Use |
|---|---|
| Type | Number, Whole number, Yes / no, Text or JSON |
| Unit | Up to 32 characters; shown next to values and on chart axes |
| Label | Up to 128 characters; the name shown instead of the key |
| Min, Max | The expected range; a gauge takes it as its default scale |
| Decimals | 0 to 10 |
The list does not filter what is stored: a key that is not listed is still stored. It names and formats keys on the Telemetry tab, in dashboards and in SCADA bindings. See Device profiles.
Why a value was left out
The run record of the root flow and the error of Save telemetry use these codes:
| Code | Meaning |
|---|---|
key_invalid | A character outside the key rule, or an empty key |
key_too_long | Over 64 characters (also after the topic prefix) |
key_reserved | Starts with _, fw_, current_fw_ or cfg. |
string_too_long | Text over 1,024 characters |
value_too_large | JSON over 4 KiB, raw over its cap, or a number that is not finite |
bad_form | Not a form the store reads, or more than 1,000 points in one message |
bad_ts | A timestamp that is not epoch milliseconds, too far in the future or too old for the settings |
too_old | Older than your retention class keeps raw data |
key_limit | A new key over the plan’s key cap |
no_values | Nothing in the record could be stored |
Naming tips
- Use lower case and underscores:
flow_rate,pump_1_running. - Use dots for structure you want to group:
p1.running,p1.value(SCADA element keys use this form). - Keep units out of key names; put them in the profile’s Unit.
- Store states as numeric codes when you need their history. See Numbers, text and true/false values.
See also Reserved keys and attributes.