Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 39 ยท Concepts and Data Model

Measurements, Tags and Fields

Learn the InfluxDB data model: measurements, tag keys and values, field keys and values, the timestamp, and how to decide what should be a tag.

Every point in InfluxDB has the same four ingredients: a measurement, zero or more tags, one or more fields and a timestamp. Choosing which piece of your data goes where is the most important design decision you will make, because it affects query speed, storage cost and how easily you can ask questions later.

This lesson defines each ingredient, gives a rule for choosing between tags and fields, and shows common mistakes.

The four ingredients

TEXT
cpu,host=web-01,region=eu usage_user=41.0,usage_system=7.5 1772359200000000000
 |  \_________ ________/   \___________ ______________/    \_____ ______/
 |            V                        V                          V
measurement  tags                    fields                   timestamp
Part Purpose Type Indexed?
Measurement Names the kind of data (like a table) String Yes
Tag set Labels that identify the series Strings only Yes
Field set The measured values Float, integer, unsigned integer, string, boolean No
Timestamp When it happened Nanosecond precision by default Yes

In InfluxDB 3 the same idea appears as a table (the measurement) whose columns are time, the tag columns and the field columns. Tags and fields are both just columns when you query with SQL; the difference matters mainly at write time and for storage layout.

Measurements

A measurement is a name for a family of points that are measured the same way: cpu, disk, room, http_requests. Good measurements are:

  • Specific: cpu and mem rather than one giant metrics.
  • Stable: the name does not change when a host or customer changes.
  • Free of data: never put values in the name (cpu_web01 is wrong; host=web-01 is a tag).

Tags

Tags are key-value pairs of strings that describe the source of a point: host, region, sensor ID, room, status code. Two properties make them special:

  1. They are indexed, so filtering and grouping by a tag is fast.
  2. Together with the measurement they define the series. A different tag value is a different series.

Use tags for values you will filter by or group by and that have a limited number of distinct values.

Fields

Fields hold the values you measure. Field values can be a float, integer, unsigned integer, string or boolean. Fields are not indexed in the traditional sense, so filtering by a field value (WHERE usage > 80) scans data, while filtering by a tag is a quick lookup. A point must have at least one field.

Deciding: tag or field?

Question Tag Field
Will I group or filter by it? Yes Rarely
Is it a number I aggregate (mean, sum)? No Yes
How many distinct values? Few to thousands Unlimited
Does it describe the source? Yes No
Is it a unique identifier, such as a request ID? No Often a string field

The most common mistake is making a high-variety value a tag (user ID, session ID, URL with query string). Every new value creates a new series and series cardinality is the main performance risk (Series and Cardinality). When in doubt about a value that is mostly unique, make it a field.

Modeling a real example

A smart-home system measures rooms. Which parts are tags?

  • room name (limited set, group by it): tag
  • sensor_id (a few dozen, identifies the source): tag
  • temperature, humidity (aggregated numbers): fields
  • firmware_version (limited, useful to filter by): tag
  • last_error_message (free text, mostly unique): field

Written as line protocol (covered fully later):

TEXT
room,room=kitchen,sensor_id=s-17,firmware=2.4.1 temperature=21.5,humidity=48i 1772359200

Note: the measurement and a tag can share the name room; they live in different namespaces. In InfluxDB 3 it is cleaner to avoid duplicate names within one table.

Stand-in: see the model as a table

The next block builds the model with SQLite. The "tag" columns get an index and the "field" columns do not, mirroring how InfluxDB treats them. The query plan shows that filtering by a tag can use the index while filtering by a field must scan. This is a SQLite stand-in; InfluxDB's real storage engine is different, but the lesson about which columns are searchable carries over.

SQL Tags are searchable, fields are measured (SQLite stand-in)

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

Stand-in: split a record into the four parts

Given a flat record from your application, decide where each key goes. This JavaScript helper applies the rule "listed keys are tags, numbers are fields". It is only a teaching tool.

JS Split a record into tags and fields (stand-in)

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

No output.

Naming rules and conventions

  • Use lowercase snake_case for measurement, tag and field keys; consistency beats cleverness.
  • Avoid keys that begin with an underscore: Flux uses _measurement, _field, _value and _time for its own columns.
  • Do not use time as a tag or field key; it is reserved for the timestamp.
  • Do not give a tag and a field the same key in the same measurement: queries become ambiguous and in 3.x the write is rejected.
  • Keep units in the field name when useful: temp_c, latency_ms.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which part of a point is optional?

    A point needs a measurement and at least one field; tags are optional.
  2. 2. Which should usually be a tag?

    Tags are for limited-variety identifying labels you filter or group by.
  3. 3. What data types can a tag value have?

    Tag keys and values are always strings.
  4. 4. Why is putting a session ID in a tag risky?

    Each unique tag combination is a new series; unbounded values overload the index.

Summary

  • A point has a measurement, optional tags, at least one field and a timestamp.
  • Tags are indexed string labels that define the series; fields are the measured values with typed data.
  • Use tags for limited-variety values you filter or group by, and fields for measured and high-variety data.
  • Avoid reserved names, keep keys consistent and never encode data inside measurement names.

Next: Series and Cardinality