aioinflux 0.1.0

Writing dictionary-like objects

Aioinflux accepts any dictionary-like object (mapping) as input. However, that dictionary must be properly formated and contain the following keys:

1. measurement: Optional. Must be a string-like object. If ommited, must be specified when calling AsyncInfluxDBClient.write by passing a measurement argument.

2. time: Optional. The value can be datetime.datetime, date-like string (e.g., 2017-01-01, 2009-11-10T23:00:00Z) or anything else that can be parsed by Pandas’ Timestamp class initializer.

3. tags: Optional. This must contain another mapping of field names and values. Both tag keys and values should be strings.

4. fields: Mandatory. This must contain another mapping of field names and values. Field keys should be strings. Field values can be float, int, str, or bool or any equivalent type.

Any fields other then the above will be ignored when writing data to InfluxDB.

A typical dictionary-like point would look something like the following:

{'time': '2009-11-10T23:00:00Z',
'measurement': 'cpu_load_short',
'tags': {'host': 'server01', 'region': 'us-west'},
'fields': {'value1': 0.64, 'value2': True, 'value3': 10}}

Writing DataFrames

Aioinflux also accepts Pandas dataframes as input. The only requirements for the dataframe is that the index must be of type DatetimeIndex. Also, any column whose dtype is object will be converted to a string representation.

A typical DataFrame input should look something like the following:

                                       LUY       BEM       AJW tag
2017-06-24 08:45:17.929097+00:00  2.545409  5.173134  5.532397   B
2017-06-24 10:15:17.929097+00:00 -0.306673 -1.132941 -2.130625   E
2017-06-24 11:45:17.929097+00:00  0.894738 -0.561979 -1.487940   B
2017-06-24 13:15:17.929097+00:00 -1.799512 -1.722805 -2.308823   D
2017-06-24 14:45:17.929097+00:00  0.390137 -0.016709 -0.667895   E

The measurement name must be specified with the measurement argument when calling AsyncInfluxDBClient.write. Additional tags can also be passed using arbitrary keyword arguments.

Example:

client = AsyncInfluxDBClient(db='testdb', mode='blocking')
client.write(df, measurement='prices', tag_columns=['tag'], asset_class='equities')

In the example above, df is the DataFrame we are trying to write to InfluxDB and measurement is the measurement we are writing to.

tag_columns is in an optional iterable telling which of the dataframe columns should be parsed as tag values. If tag_columns is not explicitly passed, all columns in the dataframe will be treated as InfluxDB field values.

Any other keyword arguments passed to AsyncInfluxDBClient.write are treated as extra tags which will be attached to the data being written to InfluxDB. Any string which is a valid InfluxDB identifier and valid Python identifier can be used as an extra tag key (with the exception of they strings data, measurement and tag_columns).

See AsyncInfluxDBClient.write docstring for details.

Retrieving DataFrames

                                  Price  Volume
2017-04-12 02:17:04.224703+00:00   5783     100
2017-04-12 02:17:04.375146+00:00   5783     200
2017-04-12 02:17:08.374895+00:00   5783     100
2017-04-12 02:17:09.645478+00:00   5783    1100
2017-04-12 02:17:09.655289+00:00   5783     100
2017-04-12 02:17:17.084443+00:00   5783     100
2017-04-12 02:17:22.274656+00:00   5783     900
2017-04-12 02:17:22.274657+00:00   5782    5500
2017-04-12 02:17:22.274658+00:00   5781    3200
2017-04-12 02:17:22.314710+00:00   5782     100

Chunked responses

TODO

Convenience functions

Aioinflux provides some wrappers around AsyncInfluxDBClient.query in order to provide convenient access to commonly used query patterns. Appropriate named arguments must be passed (e.g.: db, measurement, etc).

Examples:

client.create_database(db='foo')
client.drop_measurement(measurement='bar')
client.show_users()

For more complex queries, pass a raw query to AsyncInfluxDBClient.query.

Please refer to the source for argument information and to InfluxDB documentation for further query-related information.

Authentication

TODO

Database selection

After the instantiation of the AsyncInfluxDBClient object, database can be switched by changing the db attribute:

client = AsyncInfluxDBClient(db='db1')  # instantiate client
client.db = 'db2'  # switch database

Beaware that differently from some NoSQL databases (such as MongoDB), InfluxDB requires that a databases is explicitly created (by using the CREATE DATABASE query) before doing any operations on it.

Debugging

TODO