Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 39 ยท Performance and Scaling

Schema Design for Performance

Design time-series schemas that stay fast. Choose tags versus fields, wide versus narrow layouts, naming conventions and units. Runnable SQL comparisons.

A good time-series schema makes the common query cheap and the rare query possible. A bad one makes every query expensive and cannot be fixed without rewriting data, because you cannot rename tags or change field types in place on stored points. This lesson gives you a practical checklist for designing measurements, tags and fields, with runnable examples that compare layouts.

It builds on series cardinality: tags are indexed and multiply series, fields are values. Everything you decide here is about which side of that line each piece of information falls on.

Tags versus fields, revisited

Tag Field
Purpose Identify and filter Hold the measurement
Indexed Yes (in 1.x/2.x) No
Type String Float, integer, unsigned, string, boolean
Changes over time Rarely Every point
Used in GROUP BY Yes Not directly

Decide with three questions:

  1. Do I filter or group by it? If yes, tag candidate.
  2. Is the number of distinct values small and stable? If no, field.
  3. Is it numeric and aggregated (mean, sum, max)? If yes, field.

host, region, service, sensor_id, unit are tags. temperature, bytes_sent, latency_ms, error_message are fields.

Measurement design

A measurement groups related values that are collected together and share the same tags. Good measurement names describe what is measured, not where it came from: cpu, disk, http_requests, room_climate.

  • Do not encode tag information into the name (cpu_web1). That multiplies measurements instead of using a tag.
  • Do not put unrelated data into one giant measurement just to "keep it simple"; queries then scan data they do not need.
  • Keep names lowercase with underscores, and agree on them across teams.

Wide versus narrow layouts

You can store several readings from one sensor in two shapes.

Wide: one point per timestamp with a field for each reading.

TEXT
climate,room=lab temperature=21.4,humidity=48.1,co2=612 1750000000000000000

Narrow: one point per reading, with the reading's name stored as a tag (or in _field).

TEXT
reading,room=lab,name=temperature value=21.4 1750000000000000000
reading,room=lab,name=humidity value=48.1 1750000000000000000

The wide form is smaller (one timestamp and one tag set for three values) and lets you compute across fields in one row, such as temperature - dew_point. The narrow form is flexible when readings come and go, but it multiplies rows and series. For fixed sets of readings collected together, prefer wide. InfluxDB 2.x internally represents each field as its own row in query results anyway, and you reshape with pivot() when needed.

This runnable comparison counts rows and shows how a cross-field calculation looks in each shape.

SQL Stand-in: wide versus narrow

Press Run (or Ctrl + Enter) to see the result here.

Both give the same answer; the wide form is a simple filter, the narrow form is a join. The narrow form also stores room and ts three times.

Naming and units

  • Put the unit in the field name when it is not obvious: latency_ms, disk_used_bytes, power_w. Avoid a field that is "seconds" in one agent and "milliseconds" in another.
  • Use base units (bytes, seconds) where you can, and convert in the dashboard.
  • Keep one type per field forever. Writing a string to a field that already holds floats is rejected or creates a conflict. Writing 1 (float) and 1i (integer) to the same field is a classic error.
  • Use consistent tag keys across measurements (host, not hostname in one and server in another) so joins and dashboards work.

Time and precision

Each point's timestamp is part of its identity. Two points in the same series with the same timestamp overwrite each other. If you store several events in the same second for the same series, either use nanosecond timestamps with real event times, or add a distinguishing tag, or you will lose data silently. Use the coarsest precision that is honest, because coarser timestamps compress better and write precision is declared per request.

JS Stand-in: same series and timestamp means overwrite

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Merging happens per field: writing a new field to an existing point adds that field, while writing the same field replaces the value.

A design checklist

  1. List the queries you will run first (dashboards, alerts, reports).
  2. Choose tags from the filters and groupings in those queries.
  3. Estimate cardinality: multiply the distinct values of the tags.
  4. Put measured values in fields, one measurement per related group.
  5. Prefer the wide layout when values are collected together.
  6. Name fields with units and keep their types fixed.
  7. Decide the retention and rollup plan before data arrives (see downsampling).
  8. Write a short schema document and share it with everyone who writes data.

Common mistakes

  • Tags for numbers you average (temperature=21 as a tag), which makes it a string and unusable in mean().
  • Free-text tags such as error messages.
  • Changing a field's type later; you must create a new field name.
  • One measurement per host.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which belongs in a tag?

    Tags hold small, stable identifying values used in filters and grouping.
  2. 2. When is a wide layout best?

    One point carries all readings, saving storage and making cross-field calculations simple.
  3. 3. Two writes have the same series and timestamp. What happens to a field they both set?

    Point identity is series plus timestamp; the later write replaces matching fields.
  4. 4. What is a good field name for a latency in milliseconds?

    A descriptive lowercase name with a unit avoids ambiguity.

Summary

  • Tags identify and filter, are few and stable; fields hold measured values.
  • One measurement per group of values collected together; no data in names.
  • Prefer wide layouts for fixed readings; keep consistent names, units and types.
  • Same series and timestamp means overwrite.
  • Design from the queries, then estimate cardinality and plan retention.

Next: Batching and Write Performance