fill [frame(...)]?, [columnbinding: expression]*

Adds rows on an aligned temporal grid wherever a group has no row in an alignment bucket, keeps values from real observations on those rows, and optionally replaces nulls on chosen metric columns using compile-time values (including typed nulls and expressions that fold to constants at compile time).

Use this after verbs that establish alignment and grouping, such as timechart or align followed by aggregate, when you want an explicit row for every bucket instead of gaps in the series.

Input requirements

The input must be an Event or Interval dataset with alignment metadata. make_table outputs, make_resource datasets, and temporal data without alignment (including packed sessions without a grid) are rejected.

Column bindings

Bindings use column: value syntax. Each column must already exist in the schema, must not be the configured valid_from, valid_to, or part of the grouping key, and cannot appear twice. The value must be coercible to the column’s type, must not reference other columns, and must pass compile-time constant evaluation (so literals, null, arithmetic, and calls such as pow that reduce to a constant are allowed).

If there is at least one eligible metric column (any column outside valid_from, valid_to, and the grouping key), you must supply at least one binding. Bindings may be omitted only when the schema has no such columns left to synthesize.

Columns you do not bind keep their observed values on original rows and are null on rows the verb adds only to complete the grid; grouping keys and time columns still identify each bucket.

Frame argument

An optional frame argument caps how far the verb extends synthetic alignment buckets beyond the observed data. When present, frame must be the first argument, and at least one of ahead or back must be set to a non-zero duration:

• ahead adds buckets after each observed bucket, up to that duration ahead of it.
• back adds buckets before each observed bucket, up to that duration behind it.

Each provided duration must be at least the alignment step and at most one week; values of zero, values smaller than the step, or values greater than one week are rejected. ahead and back may be combined to extend the grid in both directions. No other frame fields are honored — only ahead and back participate in fill.

Without frame, the verb still completes the grid across the entire query window for ad-hoc queries, but acceleration is disabled.

Categories

• Aggregate

Accelerable

fill is sometimes accelerable, depending on options used. A dataset that only uses accelerable verbs can be accelerated, making queries on the dataset respond faster.

Examples

align 1m,
  cpu:avg(m("container_cpu_usage_seconds_total"))
aggregate load:sum(cpu), group_by(cluster)
fill load:null

Illustrates binding a typed null to a single aggregated metric so newly materialized alignment buckets show an explicit null instead of omitting those timestamps from the result.

align 5m,
  hits:sum(m("http_requests_total"))
aggregate hits:sum(hits), group_by(route)
fill frame(ahead:15m), hits:0

Passes frame(ahead:…) first so the forward horizon for synthetic buckets is bounded relative to observed points rather than spanning the entire ad-hoc query window.

timechart 10m, errors:sum(m("errors_total")), group_by(service)
fill errors:int64(0), rate:null

Shows several column: value bindings in one stage, mixing a numeric literal and a typed null so different metrics can each define how synthetic buckets should be populated.

align 1h,
  mem:avg(m("node_memory_MemAvailable_bytes"))
fill frame(ahead:2h), mem:null

Uses a wider ahead duration than the alignment step so the frame covers multiple future buckets, which is typical when the horizon should span several grid intervals.

timechart 1m, qps:rate(m("rpc_server_duration_count"), 1m), group_by(method)
fill qps:float64_null()

Applies a typed null binding to a rate column produced by a prior charting stage so missing buckets still appear with a well-typed placeholder value.

timechart 5m, avg_latency:avg(latency_ms), group_by(service)
fill frame(back:15m), avg_latency:float64_null()

Uses frame(back:…) so synthetic buckets extend behind each observed point rather than ahead of it, with avg_latency set to a typed null on the added buckets.

timechart 5m, avg_latency:avg(latency_ms), group_by(service)
fill frame(ahead:5m, back:15m), avg_latency:float64_null()

Combines ahead and back in a single frame so synthetic buckets extend on both sides of each observed point, with avg_latency set to a typed null on the added buckets.