Grafana / Basic: sources, fields, and interpretation / Lesson 3

Data frames, fields, and null values

Interpret tabular and time-series results through typed fields, aligned values, labels, and null semantics before selecting a visualization or transformation.

About 4 min readContent reviewed 2026-10-28

On this page

Lesson goals

Explain field types and row alignment.
Compare wide and long result shapes.
Keep null, empty result, and numeric zero distinct.

A field has type and meaning, not just a name

Grafana integrations exchange structured data that panels and transformations interpret through frames and fields. A field can carry a name, type, values, labels, and display configuration, while the exact transport and plugin model vary. A numeric-looking string is not automatically a numeric field, and a field named Time is not sufficient proof of correct timestamp semantics. Record units, source population, and null meaning alongside types. A valid-looking table can still represent the wrong event boundary. Inspect the response before applying transformations that may conceal a source mismatch.

Understand wide and long representations

A wide time-series shape can have one time field and separate numeric fields for routes r1 and r2. A long shape can have time, route, and delay columns with multiple rows at one timestamp. Both can represent useful evidence, but a chosen panel or transformation may require a particular shape or conversion. Multiple frames can also represent separate query results. Do not concatenate them merely because field names match; labels, timestamps, units, and populations may differ. The teaching JSON below is a conceptual field representation, not an asserted Grafana wire protocol or importable panel.

json Conceptual two-field frame example

{"fields":[{"name":"Time","type":"time","values":[1720000000000,1720000060000]},{"name":"delay_seconds","type":"number","values":[4,null]}]}

The illustrative time values are epoch milliseconds and the delay is seconds. null means unavailable in this fixture, not a measured zero; this is not a validated plugin payload.

Check row alignment before arithmetic

Fields belonging to one tabular frame need aligned rows under the applicable data model. A missing value should occupy an explicit position rather than shifting later observations into the wrong timestamp. The offline fixture validates equal column lengths and counts available numeric delays without replacing null. It shows two time positions but only one observed delay. The function does not validate a Grafana frame schema or render a panel. Real integrations also need timestamp parsing, type consistency, labels, and source-specific semantics that this small list comparison does not cover.

python Offline field-alignment and null fixture

times = [1720000000000, 1720000060000]
delays = [4.0, None]
assert len(times) == len(delays)
observed = [value for value in delays if value is not None]
print("rows", len(times))
print("observed_values", len(observed))
print("observed_mean_seconds", sum(observed) / len(observed))

Expected output

rows 2
observed_values 1
observed_mean_seconds 4.0

Only fixed lists are checked. The mean uses observed values and does not claim that ignoring missing data is the right policy for every dashboard.

Do not repair missing evidence with a cosmetic zero

Null can mean missing observation, unsupported value, failed conversion, or another source-defined state. An empty result can instead mean no eligible rows or a filtered population. A measured zero can be valid evidence of no delay. Replacing all these states with zero can make a broken source look punctual. Conversely, treating every null as a failure may misrepresent intentionally sparse data. Define the policy with the data owner, preserve counts and freshness, and review reduction and value mappings separately. Connecting gaps in a graph does not create the unobserved measurements.

Match visualization requirements to the frame

A time-series panel needs a compatible time and value structure, while a table can display different dimensions and a stat reduces selected values. A panel can therefore be empty even though a query returned data in an unsupported shape. Check source fields, types, transformations, and selected visualization in that order before changing backend access. This lesson runs only local list arithmetic and provides conceptual JSON. No plugin schema, timestamp converter, Grafana frame API, data-source query, or renderer is executed, and the expected output belongs only to the fixed fixture.

Common errors and fixes

A number is invisible because it arrived as text

Why it happens: The source type differs from the visualization requirement.
How to fix it: Review explicit conversion and its failure cases.
Prevent it next time: Keep known-value type fixtures.

Rows shift after a missing observation

Why it happens: Columns were shortened independently.
How to fix it: Preserve aligned positions with explicit missing values.
Prevent it next time: Assert compatible field lengths.

Missing delay becomes on-time performance

Why it happens: Null and zero were merged for display convenience.
How to fix it: Preserve the source-defined unknown state.
Prevent it next time: Test empty, null, zero, and stale evidence separately.

Check your understanding

1. A query returns a table with a textual timestamp and numeric delay. Does selecting a time-series panel guarantee a correct chart?

Show worked solution

No. The timestamp must have supported type and meaning, and the field shape must match the panel’s requirements. Verify parsing, timezone, units, and transformation behavior through the selected integration. A column name alone is not proof of a valid time field.

2. Should the missing second delay in the fixture be replaced with zero before reporting the average?