To connect to a InfluxDB, you must create a
InfluxDBClient object. The default configuration
connects to InfluxDB on localhost with the default
ports. The below instantiation statements are all equivalent:
from influxdb import InfluxDBClient
# using Http
client = InfluxDBClient(database='dbname')
client = InfluxDBClient(host='127.0.0.1', port=8086, database='dbname')
client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname')
# using UDP
client = InfluxDBClient(host='127.0.0.1', database='dbname', use_udp=True, udp_port=4444)
To write pandas DataFrames or to read data into a
pandas DataFrame, use a DataFrameClient object.
These clients are initiated in the same way as the
InfluxDBClient:
from influxdb import DataFrameClient
client = DataFrameClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname')
Note
Only when using UDP (use_udp=True) the connection is established.
InfluxDBClient¶influxdb.InfluxDBClient(host=u'localhost', port=8086, username=u'root', password=u'root', database=None, ssl=False, verify_ssl=False, timeout=None, retries=3, use_udp=False, udp_port=4444, proxies=None, pool_size=10, path=u'', cert=None, gzip=False, session=None, headers=None, socket_options=None)¶InfluxDBClient primary client object to connect InfluxDB.
The InfluxDBClient object holds information necessary to
connect to InfluxDB. Requests can be made to InfluxDB directly through
the client.
The client supports the use as a context manager.
| Parameters: |
|
|---|---|
| Raises: | ValueError – if cert is provided but ssl is disabled (set to False) |
alter_retention_policy(name, database=None, duration=None, replication=None, default=None, shard_duration=None)¶Modify an existing retention policy for a database.
| Parameters: |
|
|---|
Note
at least one of duration, replication, or default flag should be set. Otherwise the operation will fail.
close()¶Close http session.
create_continuous_query(name, select, database=None, resample_opts=None)¶Create a continuous query for a database.
| Parameters: |
|
|---|---|
| Example: |
>> select_clause = 'SELECT mean("value") INTO "cpu_mean" ' \
... 'FROM "cpu" GROUP BY time(1m)'
>> client.create_continuous_query(
... 'cpu_mean', select_clause, 'db_name', 'EVERY 10s FOR 2m'
... )
>> client.get_list_continuous_queries()
[
{
'db_name': [
{
'name': 'cpu_mean',
'query': 'CREATE CONTINUOUS QUERY "cpu_mean" '
'ON "db_name" '
'RESAMPLE EVERY 10s FOR 2m '
'BEGIN SELECT mean("value") '
'INTO "cpu_mean" FROM "cpu" '
'GROUP BY time(1m) END'
}
]
}
]
create_database(dbname)¶Create a new database in InfluxDB.
| Parameters: | dbname (str) – the name of the database to create |
|---|
create_retention_policy(name, duration, replication, database=None, default=False, shard_duration=u'0s')¶Create a retention policy for a database.
| Parameters: |
|
|---|
create_user(username, password, admin=False)¶Create a new user in InfluxDB.
| Parameters: |
|
|---|
delete_series(database=None, measurement=None, tags=None)¶Delete series from a database.
Series must be filtered by either measurement and tags. This method cannot be used to delete all series, use drop_database instead.
| Parameters: |
|
|---|
drop_continuous_query(name, database=None)¶Drop an existing continuous query for a database.
| Parameters: |
|
|---|
drop_database(dbname)¶Drop a database from InfluxDB.
| Parameters: | dbname (str) – the name of the database to drop |
|---|
drop_measurement(measurement)¶Drop a measurement from InfluxDB.
| Parameters: | measurement (str) – the name of the measurement to drop |
|---|
drop_retention_policy(name, database=None)¶Drop an existing retention policy for a database.
| Parameters: |
|
|---|
drop_user(username)¶Drop a user from InfluxDB.
| Parameters: | username (str) – the username to drop |
|---|
from_dsn(dsn, **kwargs)¶Generate an instance of InfluxDBClient from given data source name.
Return an instance of InfluxDBClient from the provided
data source name. Supported schemes are “influxdb”, “https+influxdb”
and “udp+influxdb”. Parameters for the InfluxDBClient
constructor may also be passed to this method.
| Parameters: |
|
|---|---|
| Raises: | ValueError – if the provided DSN has any unexpected values |
| Example: |
>> cli = InfluxDBClient.from_dsn('influxdb://username:password@\
localhost:8086/databasename', timeout=5)
>> type(cli)
<class 'influxdb.client.InfluxDBClient'>
>> cli = InfluxDBClient.from_dsn('udp+influxdb://username:pass@\
localhost:8086/databasename', timeout=5, udp_port=159)
>> print('{0._baseurl} - {0.use_udp} {0.udp_port}'.format(cli))
http://localhost:8086 - True 159
Note
parameters provided in **kwargs may override dsn parameters
Note
when using “udp+influxdb” the specified port (if any) will be used for the TCP connection; specify the UDP port with the additional udp_port parameter (cf. examples).
get_list_continuous_queries()¶Get the list of continuous queries in InfluxDB.
| Returns: | all CQs in InfluxDB |
|---|---|
| Return type: | list of dictionaries |
| Example: |
>> cqs = client.get_list_cqs()
>> cqs
[
{
u'db1': []
},
{
u'db2': [
{
u'name': u'vampire',
u'query': u'CREATE CONTINUOUS QUERY vampire ON '
'mydb BEGIN SELECT count(dracula) INTO '
'mydb.autogen.all_of_them FROM '
'mydb.autogen.one GROUP BY time(5m) END'
}
]
}
]
get_list_database()¶Get the list of databases in InfluxDB.
| Returns: | all databases in InfluxDB |
|---|---|
| Return type: | list of dictionaries |
| Example: |
>> dbs = client.get_list_database()
>> dbs
[{u'name': u'db1'}, {u'name': u'db2'}, {u'name': u'db3'}]
get_list_measurements()¶Get the list of measurements in InfluxDB.
| Returns: | all measurements in InfluxDB |
|---|---|
| Return type: | list of dictionaries |
| Example: |
>> dbs = client.get_list_measurements()
>> dbs
[{u'name': u'measurements1'},
{u'name': u'measurements2'},
{u'name': u'measurements3'}]
get_list_privileges(username)¶Get the list of all privileges granted to given user.
| Parameters: | username (str) – the username to get privileges of |
|---|---|
| Returns: | all privileges granted to given user |
| Return type: | list of dictionaries |
| Example: |
>> privileges = client.get_list_privileges('user1')
>> privileges
[{u'privilege': u'WRITE', u'database': u'db1'},
{u'privilege': u'ALL PRIVILEGES', u'database': u'db2'},
{u'privilege': u'NO PRIVILEGES', u'database': u'db3'}]
get_list_retention_policies(database=None)¶Get the list of retention policies for a database.
| Parameters: | database (str) – the name of the database, defaults to the client’s current database |
|---|---|
| Returns: | all retention policies for the database |
| Return type: | list of dictionaries |
| Example: |
>> ret_policies = client.get_list_retention_policies('my_db')
>> ret_policies
[{u'default': True,
u'duration': u'0',
u'name': u'default',
u'replicaN': 1}]
get_list_series(database=None, measurement=None, tags=None)¶Query SHOW SERIES returns the distinct series in your database.
FROM and WHERE clauses are optional.
| Parameters: |
|
|---|
get_list_users()¶Get the list of all users in InfluxDB.
| Returns: | all users in InfluxDB |
|---|---|
| Return type: | list of dictionaries |
| Example: |
>> users = client.get_list_users()
>> users
[{u'admin': True, u'user': u'user1'},
{u'admin': False, u'user': u'user2'},
{u'admin': False, u'user': u'user3'}]
grant_admin_privileges(username)¶Grant cluster administration privileges to a user.
| Parameters: | username (str) – the username to grant privileges to |
|---|
Note
Only a cluster administrator can create/drop databases and manage users.
grant_privilege(privilege, database, username)¶Grant a privilege on a database to a user.
| Parameters: |
|
|---|
ping()¶Check connectivity to InfluxDB.
| Returns: | The version of the InfluxDB the client is connected to |
|---|
query(query, params=None, bind_params=None, epoch=None, expected_response_code=200, database=None, raise_errors=True, chunked=False, chunk_size=0, method=u'GET')¶Send a query to InfluxDB.
Danger
In order to avoid injection vulnerabilities (similar to SQL
injection
vulnerabilities), do not directly include untrusted data into the
query parameter, use bind_params instead.
| Parameters: |
|
|---|---|
| Returns: | the queried data |
| Return type: |
request(url, method=u'GET', params=None, data=None, stream=False, expected_response_code=200, headers=None)¶Make a HTTP request to the InfluxDB API.
| Parameters: |
|
|---|---|
| Returns: | the response from the request |
| Return type: |
|
| Raises: |
|
revoke_admin_privileges(username)¶Revoke cluster administration privileges from a user.
| Parameters: | username (str) – the username to revoke privileges from |
|---|
Note
Only a cluster administrator can create/ drop databases and manage users.
revoke_privilege(privilege, database, username)¶Revoke a privilege on a database from a user.
| Parameters: |
|
|---|
send_packet(packet, protocol=u'json', time_precision=None)¶Send an UDP packet.
| Parameters: |
|
|---|
set_user_password(username, password)¶Change the password of an existing user.
| Parameters: |
|
|---|
switch_database(database)¶Change the client’s database.
| Parameters: | database (str) – the name of the database to switch to |
|---|
switch_user(username, password)¶Change the client’s username.
| Parameters: |
|
|---|
write(data, params=None, expected_response_code=204, protocol=u'json')¶Write data to InfluxDB.
| Parameters: |
|
|---|---|
| Returns: | True, if the write operation is successful |
| Return type: | bool |
write_points(points, time_precision=None, database=None, retention_policy=None, tags=None, batch_size=None, protocol=u'json', consistency=None)¶Write to multiple time series names.
| Parameters: |
|
|---|---|
| Returns: | True, if the operation is successful |
| Return type: | bool |
Note
if no retention policy is specified, the default retention policy for the database is used
DataFrameClient¶influxdb.DataFrameClient(host=u'localhost', port=8086, username=u'root', password=u'root', database=None, ssl=False, verify_ssl=False, timeout=None, retries=3, use_udp=False, udp_port=4444, proxies=None, pool_size=10, path=u'', cert=None, gzip=False, session=None, headers=None, socket_options=None)¶DataFrameClient instantiates InfluxDBClient to connect to the backend.
The DataFrameClient object holds information necessary to connect
to InfluxDB. Requests can be made to InfluxDB directly through the client.
The client reads and writes from pandas DataFrames.
EPOCH = Timestamp('1970-01-01 00:00:00+0000', tz='UTC')¶query(query, params=None, bind_params=None, epoch=None, expected_response_code=200, database=None, raise_errors=True, chunked=False, chunk_size=0, method=u'GET', dropna=True, data_frame_index=None)¶Query data into a DataFrame.
Danger
In order to avoid injection vulnerabilities (similar to SQL
injection
vulnerabilities), do not directly include untrusted data into the
query parameter, use bind_params instead.
| Parameters: |
|
|---|---|
| Returns: | the queried data |
| Return type: |
write_points(dataframe, measurement, tags=None, tag_columns=None, field_columns=None, time_precision=None, database=None, retention_policy=None, batch_size=None, protocol=u'line', numeric_precision=None)¶Write to multiple time series names.
| Parameters: |
|
|---|
SeriesHelper¶influxdb.SeriesHelper(**kw)¶Subclass this helper eases writing data points in bulk.
All data points are immutable, ensuring they do not get overwritten. Each subclass can write to its own database. The time series names can also be based on one or more defined fields. The field “time” can be specified when creating a point, and may be any of the time types supported by the client (i.e. str, datetime, int). If the time is not specified, the current system time (utc) will be used.
Annotated example:
class MySeriesHelper(SeriesHelper):
class Meta:
# Meta class stores time series helper configuration.
series_name = 'events.stats.{server_name}'
# Series name must be a string, curly brackets for dynamic use.
fields = ['time', 'server_name']
# Defines all the fields in this time series.
### Following attributes are optional. ###
client = TestSeriesHelper.client
# Client should be an instance of InfluxDBClient.
:warning: Only used if autocommit is True.
bulk_size = 5
# Defines the number of data points to write simultaneously.
# Only applicable if autocommit is True.
autocommit = True
# If True and no bulk_size, then will set bulk_size to 1.
retention_policy = 'your_retention_policy'
# Specify the retention policy for the data points
time_precision = "h"|"m"|s"|"ms"|"u"|"ns"
# Default is ns (nanoseconds)
# Setting time precision while writing point
# You should also make sure time is set in the given precision
commit(client=None)¶Commit everything from datapoints via the client.
| Parameters: | client – InfluxDBClient instance for writing points to InfluxDB. |
|---|---|
| Attention: | any provided client will supersede the class client. |
| Returns: | result of client.write_points. |
ResultSet¶See the Query response object: ResultSet page for more information.
influxdb.resultset.ResultSet(series, raise_errors=True)¶A wrapper around a single InfluxDB query result.
error¶Error returned by InfluxDB.
get_points(measurement=None, tags=None)¶Return a generator for all the points that match the given filters.
| Parameters: |
|
|---|---|
| Returns: | Points generator |
items()¶Return the set of items from the ResultSet.
| Returns: | List of tuples, (key, generator) |
|---|
keys()¶Return the list of keys in the ResultSet.
| Returns: | List of keys. Keys are tuples (series_name, tags) |
|---|
point_from_cols_vals(cols, vals)¶Create a dict from columns and values lists.
| Parameters: |
|
|---|---|
| Returns: | Dict where keys are columns. |
raw¶Raw JSON from InfluxDB.