InfluxDB data elements
InfluxDB 2.0 includes the following data elements:
- field key
- field value
- field set
- tag key
- tag value
- tag set
The sample data below is used to illustrate data elements concepts. Hover over highlighted terms to get acquainted with InfluxDB terminology and layout.
All data stored in InfluxDB has a
_time column that stores timestamps. On disk, timestamps are stored in epoch nanosecond format. InfluxDB formats timestamps show the date and time in RFC3339 UTC associated with data. Timestamp precision is important when you write data.
_measurement column shows the name of the measurement
census. Measurement names are strings. A measurement acts as a container for tags, fields, and timestamps. Use a measurement name that describes your data. The name
census tells us that the field values record the number of
A field includes a field key stored in the
_field column and a field value stored in the
A field key is a string that represents the name of the field. In the sample data above,
ants are field keys.
A field value represents the value of an associated field. Field values can be strings, floats, integers, or booleans. The field values in the sample data show the number of
bees at specified times:
28 and the number of
ants at a specified time:
A field set is a collection of field key-value pairs associated with a timestamp. The sample data includes the following field sets:
census bees=23i,ants=30i 1566086400000000000 census bees=28i,ants=32i 1566086760000000000 ----------------- Field set
Fields aren’t indexed: Fields are required in InfluxDB data and are not indexed. Queries that filter field values must scan all field values to match query conditions. As a result, queries on tags > are more performant than queries on fields. Store commonly queried metadata in tags.
The columns in the sample data,
scientist, are tags.
Tags include tag keys and tag values that are stored as strings and metadata.
The tag keys in the sample data are
The tag key
location has two tag values:
The tag key
scientist also has two tag values:
The collection of tag key-value pairs make up a tag set. The sample data includes the following four tag sets:
location = klamath, scientist = anderson location = portland, scientist = anderson location = klamath, scientist = mullen location = portland, scientist = mullen
Tags are indexed: Tags are optional. You don’t need tags in your data structure, but it’s typically a good idea to include tags. Because tags are indexed, queries on tags are faster than queries on fields. This makes tags ideal for storing commonly-queried metadata.
Why your schema matters
If most of your queries focus on values in the fields, for example, a query to find when 23 bees were counted:
from(bucket: "bucket-name") |> range(start: 2019-08-17T00:00:00Z, stop: 2019-08-19T00:00:00Z) |> filter(fn: (r) => r._field == "bees" and r._value == 23)
InfluxDB scans every field value in the dataset for
bees before the query returns a response. If our sample
census data grew to millions of rows, to optimize your query, you could rearrange your schema so the fields (
ants) becomes tags and the tags (
scientist) become fields:
ants are tags, InfluxDB doesn’t have to scan all
_value columns. This makes your queries faster.
Now that you’re familiar with measurements, field sets, and tag sets, it’s time to discuss series keys and series. A series key is a collection of points that share a measurement, tag set, and field key. For example, the sample data includes two unique series keys:
A series includes timestamps and field values for a given series key. From the sample data, here’s a series key and the corresponding series:
# series key census,location=klamath,scientist=anderson bees # series 2019-08-18T00:00:00Z 23 2019-08-18T00:06:00Z 28
Understanding the concept of a series is essential when designing your schema and working with your data in InfluxDB.
A point includes the series key, a field value, and a timestamp. For example, a single point from the sample data looks like this:
2019-08-18T00:00:00Z census ants 30 portland mullen
All InfluxDB data is stored in a bucket. A bucket combines the concept of a database and a retention period (the duration of time that each data point persists). A bucket belongs to an organization. For more information about buckets, see Manage buckets.
If you’re just starting out, we recommend taking a look at the following guides:
Bug Reports and Feedback
Thank you for being willing to help test InfluxDB v2.0 alpha! Feedback and bug reports are welcome and encouraged both for InfluxDB and this documentation. Submit feedback using one of the following methods: