InfluxDB client compatible with 1.5. This client uses the awesome requests library to provide connection pooling for each unique InfluxDB URL given.
This InfluxDB client is created, maintained, and supported by Axiom Exergy.
This client has only been tested and used against InfluxDB 1.5 and Python 3.5. If you want to support any other environments, please submit a pull request.
You can install this client via PyPI:
$ pip install influx-client
Or by cloning this repository:
$ git clone https://github.com/AxiomExergy/influx-client.git
$ cd influx-client
$ pip install . # For a regular install
$ python setup.py develop # OR for a development install
This section describes basic usage.
This InfluxDB client is designed to be very simple. It takes a URL to the
InfluxDB API on creation, and otherwise supplies all parameters per write()
call.
If the InfluxDB API returns an error that the chosen database does not exist,
the client will issue a CREATE DATABASE ... query, followed by retrying the
write request.
from influx import InfluxDB
# This creates the client instance... subsequent calls with the same URL will
# return the exact same instance, allowing you to use socket pooling for faster
# requests with less resources.
client = InfluxDB('http://127.0.0.1:8086')
# Creating the database is optional - calls to write() will try to create the
# database if it does not exist.
client.create_database('mydatabase')
# You can write as many fields and tags as you like, or override the *time* for
# the data points
client.write('mydatabase', 'mymeasurement', fields={'value': 1.0},
tags={'env': 'example'})
# You can write multiple datapoints at a time
client.write_many('mydatabase', 'mymeasurement', fields=['value', 'alpha'],
values=[[1.0, 0.5], [1.1, 0.6]], tags={'env': 'example'})
# You can query for data relative to now()
data = client.select_recent('mydatabase', 'mymeasurement', time_relative='1h')
# You can query with arbitrary WHERE clauses and LIMITs
data = client.select_where('mydatabase', 'mymeasurement', where='time > 0', limit=1)
# You can clean up after yourself, for example in testing environments
client.drop_measurement('mymeasurement', 'mydatabase')
# You can also drop the entire database, if necessary
client.drop_database('mydatabase')
# Subsequent client creation will give the same instance
client2 = InfluxDB('http://127.0.0.1:8086')
client is client2 # This is True
This section describes development and contribution for influx-client.
This section lists everyone who has contributed to this project.
There are a few important pieces in this repository:
influx/ - The influx Python packagetest/ - Python nosetestsDockerfile, docker-compose.yml - Docker configuration for testingLICENSE, README.md - Documentation and legalYou can run the full test suite with supporting InfluxDB instance using docker-compose.
The following command will build the test image and run all tests:
docker-compose up --build --force-recreate --remove-orphans --exit-code-from influx
When tests are complete, you can clean up supporting services using:
docker-compose down
Pull requests must pass CI to be considered for inclusion. If your pull request does not have squashed commits, your commits should follow the topic: description style. See the commit history for examples.
This section describes the public API for influx-client.
influx.client(url, timeout=60, precision='u')Helper method to allow you to instantiate an InfluxDB client directly from the top level package.
60) - Timeout in seconds for requests'u') - Precision string to use for queryingInfluxDB(url, timeout=60, precision='u')This is the main InfluxDB client. It works as a singleton instance per url. In threaded or event loop based environments it relies on the requests library connection pooling (which in turn relies on urllib3) for thread safety.
'http://127.0.0.1:8086')60) - Timeout in seconds for requests'u') - Precision string to use for querying
InfluxDB. ([See the documentation]
(https://docs.influxdata.com/influxdb/v1.5/tools/api/#query) for what is
available.).create_database(database)Issues a CREATE DATABASE ... request to the InfluxDB API. This is an
idempotent operation.
.drop_database(database)Issues a DROP DATABASE ... request to the InfluxDB API. This will raise a 404
HTTPError if the database does not exist.
.drop_measurement(measurement, database)Issues a DROP MEASUREMENT ... request to the InfluxDB API for the specified database.
.write(database, measurement, fields, tags={}, time=None)Write data points to the specified database and measurement.
.write_many(database, measurement, fields, values, tags={}, time_field=None)Write data points to the specified database and measurement.
.select_recent(database, measurement, fields='*', tags={}, relative_time='15m')Query the InfluxDB API for measurement in database, using the fields string, limited to matching tags for the recent relative_time.
Returns the raw JSON response from InfluxDB.
'*') - String formatted fields for SELECT
query'15m') - Relative time string.select_where(database, measurement, fields='*', tags={}, where='time > now() - 15m', desc=False, limit=None)Query the InfluxDB API for measurement in database, using the fields string, limited to matching tags with the where clause and limit applied.
Returns the raw JSON response from InfluxDB.
'*') - String formatted fields for SELECT
query'time > now() - 15m') Where clause to addFalse) Add the ORDER BY time DESC clause.select_into([database,] target, source, fields='*', where=None, group_by='*')Returns count of data points moved by a SELECT ... INTO ... FROM ... query.
The query will follow the format:
SELECT *fields* INTO *target* FROM *source* WHERE *where* GROUP BY *group_by*
The WHERE and GROUP BY clauses are optional.
Note that if you do not include GROUP BY * or explicitly call out tags, tags will be recorded as fields.
This method may be called with variable arguments, if you wish to specify the full qualified measurement name with database.
Example:
InfluxDB().select_into('database', 'target', 'source')
# Is the same as
InfluxDB().select_into('database.default.target', 'database.default.source')
# Where often the default is 'autogen'
.show_tags(database, measurement)Query the InfluxDB API and return a list of tag names in database and measurement.
.show_fields(database, measurement)Query the InfluxDB API and return a list of field names in database and measurement.
This repository and its codebase are made public under the Apache License v2.0. We ask that if you do use this work please attribute Axiom Exergy and link to the original repository.
See Releases for detailed release notes.
FAQs
InfluxDB client
We found that influx-client demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
pnpm 10.12.1 introduces a global virtual store for faster installs and new options for managing dependencies with version catalogs.
Security News
Amaro 1.0 lays the groundwork for stable TypeScript support in Node.js, bringing official .ts loading closer to reality.
Research
A deceptive PyPI package posing as an Instagram growth tool collects user credentials and sends them to third-party bot services.