Elements of Data in TinyFlux

Data elements and terms in TinyFlux mostly mirror those of InfluxDB. The following is a list of TinyFlux terms and concepts. Click on a term, or read on below.

Point

The atomic data unit of TinyFlux. Consists of a Measurement, Timestamp, Tag Set, and a Field Set. In the primary disk CSV storage, all attributes are serialized to unicode using the system default encoding.

In Python:

>>> from tinyflux import Point
>>> from datetime import datetime, timezone
>>> p = Point(
...     time=datetime.now(timezone.utc),
...     measurement="thermostat home",
...     tags={
...         "location": "bedroom",
...         "scale": "fahrenheit",
...     },
...     fields={
...         "temp": "70.0",
...     }
... )

On disk:

2022-05-13T23:19:46.573233,thermostat home,_tag_location,bedroom,_tag_scale,fahrenheit,_field_temp,70.0

Timestamp

The time associated with a Point. As an attribute of a Point, it is a Python datetime object. Regardless of its state, when it is inserted into a TinyFlux database, it will become a timezone aware object cast to the UTC timezone.

On disk, it is serialized as a ISO 8601 formatted string and occupies the first column of the default CSV storage class.

In Python:

>>> Point()

On disk:

2022-05-13T23:19:46.573233,_default

For details on time’s relationship with TinyFlux, see Timezones in TinyFlux.

Measurement

A measurement is a collection of Points, much like a table in a relational database. It is a string in memory and on disk. TinyFlux provides a convenient method for interacting with the Points through the db.measurement(...) method.

In Python:

>>> Point(measurement="cities")

On disk:

2022-05-13T23:19:46.573233,cities

See Working with Measurements for more details.

Tag Set

A tag set (or “tags”) is the collection of tag keys and tag values belonging to a Point. TinyFlux is schemaless, so any Point can contain zero, one, or more tag keys and associated tag values. Tag keys and tag values are both strings. Tag keys and their values map to Points with a hashmap in a TinyFlux index, providing for efficient retrieval. In a well-designed TinyFlux database, the number of distinct tag values should not be as numerous as the field values. On disk, tag sets occupy side-by-side columns- one for the tag key and one for the tag value.

In Python:

>>> Point(
...     tags={
...         "city": "LA",
...         "neighborhood": "Chinatown",
...         "food": "good",
...     }
... )

On disk:

2022-05-13T23:19:46.573233,_default,_tag_city,LA,_tag_neighborhood,Chinatown,_tag_food,good

Tag Key

A tag key is the identifier for a Tag Value in a Tag Set. On disk, a tag key is prefixed with _tag_ (default) or t_ (compact).

In the following, the tag key is city.

>>> tags = {"city": "Los Angeles"}

Tag Value

A tag value is the associated value for a tag key in a Tag Set. On disk, it occupies the column next to that of the its tag key.

In the following, the tag value is Los Angeles.

>>> tags = {"city": "Los Angeles"}

Field Set

A field set (or “fields”) is the collection of field keys and field values belonging to a Point. TinyFlux is schemaless, so any Point can contain zero, one, or more field keys and associated field values. Field keys are strings while field values are numeric (in Python, float or int). Field keys and their values do not map to Points in a TinyFlux index as it is assumed that the number of their distinct values is too numerous. On disk, field sets occupy side-by-side columns- one for the field key and one for the field value.

In Python:

>>> Point(
...     fields={
...         "num_restaurants": 12,
...         "num_boba_shops": 3,
...     }
... )

On disk:

2022-05-13T23:19:46.573233,_default,_field_num_restaurants,12,_field_num_boba_shops,3

Field Key

A field key is the identifier for a Field Value in a Field Set. On disk, a field key is prefixed with _field_ (default) or f_ (compact).

In the following, the field key is num_restaurants.

>>> fields = {"num_restaurants": 12}

Field Value

A field value is the associated value for a Field Key in a Field Set. On disk, it occupies the column next to that of the its field key.

In the following, the field value is 12.

>>> fields = {"num_restaurants": 12}