.. figure:: ./artwork/logo.svg :alt:

Influxable

A lightweight python ORM / ODM / Client for InfluxDB

Note <#note>__
Genesis <#genesis>__
Changelog <#changelog>__
Features <#features>__
Dependencies <#dependencies>__
Installation <#installation>__
Getting started <#getting-started>__
- Connection <#connection>__
- Measurement <#measurement>__
- Simple Measurement <#simple-measurement>__
- Instanciation <#instanciation>__
- Query <#query>__
- Saving Data <#saving-data>__
Auto Generation of Measurements <#auto-generation-of-measurements>__
Influxable commands <#influxable-commands>__
Influxable API <#influxable-api>__
- Influxable Class <#influxable-class>__
- InfluxDBApi Class <#influxdbapi-class>__
- Connection Class <#connection-class>__
- Measurement Class <#measurement-class>__
- Attributes <#attributes>__
- InfluxDBResponse <#influxdbresponse>__
- Serializers <#serializers>__
- Raw Query <#raw-query>__
- Query Class <#query-class>__
- Query aggregations function <#query-aggregations-function>__
- Query selectors function <#query-selectors-function>__
- Query transformations function <#query-transformations-function>__
- InfluxDBAdmin <#influxdbadmin>__
- Exceptions <#exceptions>__
Testing <#testing>__
Supporting <#supporting>__
Versioning <#versioning>__
Contributors <#contributors>__
Credits <#credits>__
References <#references>__
License <#license>__

Note

This project is currently in development.

A better documentation and testing scripts will be added in the next release.

Genesis

I worked on a project with InfluxDB. I needed to build an API for InfluxDB and to plug with Python libraries (scipy, pandas, etc ...).

That's why I decided to create this repository in order to deal with InfluxDB in a smooth way and to manipulate Python object.

Changelog

1.4.0


-  Add integration with Influxdb OSS 2.0 Authentication (Experimental)

1.3.0

Add group_by() method for GROUP BY tags instructions
Add range() method for GROUP BY time() instructions
Add into() method for INTO instructions
Add tz() method

1.2.1


-  Handle chinese characters.

Features
--------

-  Add automation for measurement class generation (command: *autogenerate*)

-  Admin commands allowing to manage the database (ex: *create\_user()*, *show\_series()*).

-  Measurement class allowing to make queries in order to fetch/save points (ex: *Measurement.where()*, *Measurement.bulk\_save()*).

-  Group by commands

-  Different serializers for easy data manipulation (ex: *PandasSerializer*).

Dependencies
------------

-  Python 3 (Tested with Python 3.7.3)

-  InfluxDB (Tested with InfluxDB 1.5.4)

Installation
------------

The package is available in pypi. You can install it via pip :

::

    pip install influxable

Getting started
---------------

Connection

You can set your environment variable for the connection of InfluxDB in order to override the default values :

INFLUXDB_URL=http://localhost:8086
INFLUXDB_DATABASE_NAME=default

#Optional
INFLUXDB_USER=admin
INFLUXDB_PASSWORD=changme
INFLUXDB_PASSWORD=changme

# OSS 2.0
INFLUXDB_AUTH_TOKEN=mytoken

Then you just have to import the influxable package and create an instance of Influxable :

.. code:: python

from influxable import Influxable

client = Influxable()

You can also set connection variable in Influxable constructor :

.. code:: python

# Without authentication

client = Influxable(
    base_url='http://localhost:8086',
    database_name='default',
)

# With authentication

client = Influxable(
    base_url='http://localhost:8086',
    database_name='default',
    user='admin',
    password='changeme',
)

# With token authentication

client = Influxable(
    base_url='http://localhost:8086',
    database_name='default',
    token='my_token',
)

Measurement


.. code:: python

    from influxable import attributes, serializers
    from influxable.measurement import Measurement

    class TemperatureMeasurement(Measurement):
        parser_class = serializers.MeasurementPointSerializer # Default
        measurement_name = 'temperature'

        time = attributes.TimestampFieldAttribute()
        phase = attributes.TagFieldAttribute()
        value = attributes.FloatFieldAttribute()

Fields :

-  GenericFieldAttribute (IntegerFieldAttribute, FloatFieldAttribute, StringFieldAttribute, BooleanFieldAttribute)

-  TagFieldAttribute

-  TimestampFieldAttribute, DateTimeFieldAttribute

Parser Classes :

-  MeasurementPointSerializer (default)

-  JsonSerializer

-  FormattedSerieSerializer

-  FlatFormattedSerieSerializer

-  FlatSimpleResultSerializer

-  PandasSerializer

Simple Measurement

.. code:: python

from influxable.measurement import SimpleMeasurement

my_measurement = SimpleMeasurement('temperature', ['value'], ['phase'])

Instanciation


.. code:: python

    point = TemperatureMeasurement(
      time=1568970572,
      phase="HOT",
      value=23.5,
    )

Query
~~~~~

You can query with *Measurement.get\_query()* :

.. code:: python

    from influxable.db import Field

    points = TemperatureMeasurement\
      .get_query()\
      .select('phase', 'value')\
      .where(
         Field('value') > 15.2,
         Field('value') < 30.5,
      )\
      .limit(100)
      .evaluate()

You can also query with *Query* :

.. code:: python

    from influxable.db import Query, Field

    points = Query()\
      .select('phase', 'value')\
      .from_measurements('temperature')\
      .where(
         Field('value') > 15.2,
         Field('value') < 30.5,
      )\
      .limit(100)
      .execute()

Saving Data
~~~~~~~~~~~

You can create data by using *Measurement.bulk\_save()*

.. code:: python

    points = [
        TemperatureMeasurement(phase="HOT",value=10,time=1463289075),
        TemperatureMeasurement(phase="COLD",value=10,time=1463289076),
    ]
    TemperatureMeasurement.bulk_save(points)

You can also create data with *BulkInsertQuery*

.. code:: python

    str_query = '''
    temperature,phase=HOT value=10 1463289075000000000
    temperature,phase=COLD value=10 1463289076000000000
    '''

    raw_query = BulkInsertQuery(str_query)
    res = raw_query.execute()

Integration with OSS 2.0 (Experimental)

.. code:: bash

# Create the user
influx user create --name admin -- password admin

# Create the auth (in order to retrieve the token)
influx auth create --user admin --operator

# List yours tokens
influx auth list

# (Optional) export the INFLUXDB_AUTH_TOKEN
INFLUXDB_AUTH_TOKEN=my-token

# Create the config
influx config create --config-name defaut --host-url http://localhost:8086 --token NjIYagimNbX5MaZfisDsvuGGvtULdqIY-Wt8EP4eGk-3P9KftDtZjxXU4GocTMTfM0eglkuFJQyA9uF82ZeEoA== --org MyOrganisation

# Create the bucket
influx bucket create --name default

# List your bucket
influx bucket list

ID          Name        Retention   Shard group duration    Organization ID     Schema Type
4688727b9c388f5f    default     infinite    168h0m0s        b89cbec9670f29f8    implicit

# Create the dbrp (link database api v1 with bucket api v2)
influx v1 dbrp create --db default --rp default --bucket-id  4688727b9c388f5f --default

Auto Generation of Measurements

You can automatically generate measurement classes file with the bash command autogenerate

.. code:: bash

influxable autogenerate #(default to auto_generate_measurement.py)
influxable autogenerate -o measurement.py

Here is the output generated file :

.. code:: python

# auto_generate_measurement.py

from influxable import attributes
from influxable.measurement import Measurement


class CpuMeasurement(Measurement):
    measurement_name = 'cpu'

    time = attributes.TimestampFieldAttribute(precision='s')
    value = attributes.FloatFieldAttribute()
    host = attributes.TagFieldAttribute()

Influxable commands

autogenerate : automatic generation of measurement classes

.. code:: bash

influxable autogenerate #(default to auto_generate_measurement.py)
influxable autogenerate -o measurement.py

populate : create a measurement filled with a set of random data

.. code:: bash

influxable populate
influxable populate --min_value 5 --max_value 35 -s 2011-01-01T00:00:00 -id 1
influxable populate --help

Influxable API

Influxable Class


The Influxable main app class is a singleton. You can access it via the method *Influxable.get\_instance()*

\_\_init\_\_():
^^^^^^^^^^^^^^^

-  base\_url : url to connect to the InfluxDB server (default = 'http://localhost:8086')

-  user : authentication user name (default = 'admin')

-  password : authentication user password (default = 'changeme')

-  database\_name : name of the database (default = 'default')

create\_connection() -> Connection:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-  base\_url : url to connect to the InfluxDB server (default = 'http://localhost:8086')

-  user : authentication user name (default = 'admin')

-  password : authentication user password (default = 'changeme')

-  database\_name : name of the database (default = 'default')

ping() -> bool:
^^^^^^^^^^^^^^^

-  verbose : enables verbose mode (default = True)

execute\_query() -> json():
^^^^^^^^^^^^^^^^^^^^^^^^^^^

-  query: influxdb query to execute
-  method: http method of

Influxable

Install / Use

README

Influxable

Table of Contents

Note

Genesis

Changelog

Auto Generation of Measurements

Influxable commands

Influxable API