Getting Started

Initialize a new TinyFlux database (or connect to an existing file store) with the following:

>>> from tinyflux import TinyFlux
>>> db = TinyFlux('db.csv')

db is now a reference to the TinyFlux database that stores its data in a file called db.csv.

An individual instance of data in a TinyFlux database is known as a “Point”. In a traditional relational database, this would called called a “row”, and in a document-oriented database it is called a “document”. A TinyFlux Point is a convenient object for storing its four main attributes:


Python Type




"california air quality"




Dict of str keys and str values

{"city": "Los Angeles", "parameter": "PM2.5"}


Dict of str keys and float or int values

{"aqi": 112.0}

In keeping with the analogy of a traditional RDMS, a measurement is like a table.

time is a field with the requirement that it is a datetime type, tags is a collection of string attributes, and fields is a collection of numeric attributes. TinyFlux is “schemaless”, so tags and fields can be added/removed to any Point.

To make a Point, import the Point definition and annotate the Point with the desired attributes. If measurement is not defined, it takes the default table name of _default.

>>> from tinyflux import Point
>>> p1 = Point(
...     time=datetime.fromisoformat("2020-08-28T00:00:00-07:00"),
...     tags={"city": "LA"},
...     fields={"aqi": 112}
... )
>>> p2 = Point(
...     time=datetime.fromisoformat("2020-12-05T00:00:00-08:00"),
...     tags={"city": "SF"},
...     fields={"aqi": 128}
... )

To write to TinyFlux, simply:

>>> db.insert(p1)
>>> db.insert(p2)

All points can be retrieved from the database with the following:

>>> db.all()
[Point(time=2020-01-01T00:08:00-00:00, measurement=_default, tags=city:LA, fields=aqi:112), Point(time=2020-12-05T00:08:00-00:00, measurement=_default, tags=city:SF, fields=aqi:128)]


TinyFlux will convert all time to UTC. Read more about it here: Timezones in TinyFlux.

TinyFlux also allows iteration over stored Points:

>>> for point in db:
>>>     print(point)
Point(time=2020-08-28T00:07:00-00:00, measurement=_default, tags=city:LA, fields=aqi:112)
Point(time=2020-12-05T00:08:00-00:00, measurement=_default, tags=city:SF, fields=aqi:128)

To query for Points, there are four query types- one for each of a Point’s four attributes.

>>> from tinyflux import FieldQuery, MeasurementQuery, TagQuery, TimeQuery
>>> Time = TimeQuery()
>>> < datetime.fromisoformat("2020-11-00T00:00:00-08:00"))
[Point(time=2020-08-28T00:07:00-00:00, measurement=_default, tags=city:LA, fields=aqi:112)]
>>> Field = FieldQuery()
>>> > 120)
[Point(time=2020-12-05T00:08:00-00:00, measurement=_default, tags=city:SF, fields=aqi:128)]
>>> Tag = TagQuery()
>>> == "LA")
[Point(time=2020-08-28T00:07:00-00:00, measurement=_default, tags=city:LA, fields=aqi:112)]
>>> Measurement = MeasurementQuery()
>>> db.count(Measurement == "_default")

Points can also be updated:

>>> # Update the ``aqi`` field of the Los Angeles point.
>>> db.update( == "LA", tags={"aqi": 118})
>>> for point in db:
>>>     print(point)
Point(time=2020-08-28T00:07:00-00:00, measurement=_default, tags=city:LA, fields=aqi:118)
Point(time=2020-12-05T00:08:00-00:00, measurement=_default, tags=city:SF, fields=aqi:128)

Points can also be removed:

>>> db.remove( == "SF")
>>> db.all()
[Point(time=2020-01-01T00:08:00-00:00, measurement=_default, tags=city:LA, fields=aqi:112)]

Here is the basic syntax covered in this section:

Initialize a new TinyFlux Database

db = TinyFlux("my_db.csv")

Initialize or connect to existing with TinyFlux()

Creating New Points


Initialize a new point.

Inserting Points Into the Database


Insert a point.

Retrieving Points


Get all points


Iterate over all points

Get a list of points matching the query


Count the number of points matching the query

Updating Points

db.update(query, ...)

Update all points matching the query

Removing Points


Remove all points matching the query


Remove all points

Querying TinyFlux


Create a new time query object

FieldQuery().f_key == 2

Match any point that has a field f_key with value == 2 (also possible: !=, >, >=, <, <=)

To continue with the introduction to TinyFlux, proceed to the next section, Preparing Data.