Package: influx-client
influx-clientInfluxDB client compatible with 1.5. This client uses the awesomerequestslibrary to provide
connection pooling for each unique InfluxDB URL given.This InfluxDB client is created, maintained, and supported byAxiom
Exergy.PrerequisitesThis 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.InstallationYou can install this clientvia PyPI:$pipinstallinflux-clientOr by cloning this repository:$gitclonehttps://github.com/AxiomExergy/influx-client.git
$cdinflux-client
$pipinstall.# For a regular install$pythonsetup.pydevelop# OR for a development installUsageThis section describes basic usage.Quickstart ExampleThis InfluxDB client is designed to be very simple. It takes a URL to the
InfluxDB API on creation, and otherwise supplies all parameters perwrite()call.If the InfluxDB API returns an error that the chosen database does not exist,
the client will issue aCREATE DATABASE ...query, followed by retrying the
write request.frominfluximportInfluxDB# 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 pointsclient.write('mydatabase','mymeasurement',fields={'value':1.0},tags={'env':'example'})# You can write multiple datapoints at a timeclient.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 LIMITsdata=client.select_where('mydatabase','mymeasurement',where='time > 0',limit=1)# You can clean up after yourself, for example in testing environmentsclient.drop_measurement('mymeasurement','mydatabase')# You can also drop the entire database, if necessaryclient.drop_database('mydatabase')# Subsequent client creation will give the same instanceclient2=InfluxDB('http://127.0.0.1:8086')clientisclient2# This is TrueDevelopmentThis section describes development and contribution forinflux-client.Development ison GitHub.Installation isvia PyPI.Issues areon Github.Releases areon
GitHub.ContributorsThis section lists everyone who has contributed to this project.shakefu(Creator, Maintainer)Repository LayoutThere 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 legalRunning TestsYou can run the full test suite with supporting InfluxDB instance usingdocker-compose.The following command will build the test image and run all tests:docker-composeup--build--force-recreate--remove-orphans--exit-code-frominfluxWhen tests are complete, you can clean up supporting services using:docker-composedownMaking Pull RequestsPull requests must pass CI to be considered for inclusion. If your pull request
does not have squashed commits, your commits should follow thetopic:
descriptionstyle. See the commit history for examples.APIThis section describes the public API forinflux-client.influx.client(url, timeout=60, precision='u')Helper method to allow you to instantiate an InfluxDB client directly from the
top level package.url(str) - URL to InfluxDB API (required)timeout(int, default60) - Timeout in seconds for requestsprecision(str, default'u') - Precision string to use for queryingInfluxDB(url, timeout=60, precision='u')This is the main InfluxDB client. It works as a singleton instance perurl.
In threaded or event loop based environments it relies on therequestslibrary connection pooling (which in turn relies onurllib3) for thread
safety.url(str) - URL to InfluxDB API (such as'http://127.0.0.1:8086')timeout(int, default60) - Timeout in seconds for requestsprecision(str, default'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 aCREATE DATABASE ...request to the InfluxDB API. This is an
idempotent operation.database(str) - Database name.drop_database(database)Issues aDROP DATABASE ...request to the InfluxDB API. This will raise a 404
HTTPError if the database does not exist.database(str) - Database name.drop_measurement(measurement, database)Issues aDROP MEASUREMENT ...request to the InfluxDB API for the specified database.measurement(str) - Measurement namedatabase(str) - Database in whichmeasurementresides.write(database, measurement, fields, tags={}, time=None)Write data points to the specifieddatabaseandmeasurement.database(str) - Database namemeasurement(str) - Measurement namefields(dict) - Dictionary offield_name: valuedata pointstags(dict, optional) - Dictionary oftag_name: valuetags to
associate with the data pointstime(datetime, optional) - Datetime to use instead of InfluxDB's
server-side "now".write_many(database, measurement, fields, values, tags={}, time_field=None)Write data points to the specifieddatabaseandmeasurement.database(str) - Database namemeasurement(str) - Measurement namefields(list) - List of field names, ordered the same asvaluesvalues(list) - List of values (list of lists)tags(dict, optional) - Dictionary oftag_name: valuetags to
associate with the data pointstime_field(str, optional) - Field name to extract and use as timestamp.select_recent(database, measurement, fields='*', tags={}, relative_time='15m')Query the InfluxDB API formeasurementindatabase, using thefieldsstring, limited to matchingtagsfor the recentrelative_time.Returns the raw JSON response from InfluxDB.database(str) - Database namemeasurement(str) - Measurement namefields(str, default'*') - String formatted fields forSELECTquerytags(dict, optional) - Dictionary oftag_name: valuetags to matchrelative_time(str, default'15m') - Relative time string.select_where(database, measurement, fields='*', tags={}, where='time > now() - 15m', desc=False, limit=None)Query the InfluxDB API formeasurementindatabase, using thefieldsstring, limited to matchingtagswith thewhereclause andlimitapplied.Returns the raw JSON response from InfluxDB.database(str) - Database namemeasurement(str) - Measurement namefields(str, default'*') - String formatted fields forSELECTquerytags(dict, optional) - Dictionary oftag_name: valuetags to matchwhere(str, default'time > now() - 15m') Where clause to adddesc(bool, defaultFalse) Add theORDER BY time DESCclauselimit(int, optional) Limit to this number of data points.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.database(str) Database name (optional)target(str) Target measurementsource(str) Source measurementfields(str) Fields portion of the SELECT clause (optional,
default: '*')where(str) WHERE portion of the SELECT clause (optional)group_by(str) GROUP BY portion of the SELECT clause (optional,
default: '*')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 asInfluxDB().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 indatabaseandmeasurement.database(str) - Database namemeasurement(str) - Measurement name.show_fields(database, measurement)Query the InfluxDB API and return a list of field names indatabaseandmeasurement.database(str) - Database namemeasurement(str) - Measurement nameLicenseThis repository and its codebase are made public under theApache License
v2.0. We ask that if you do use this work please attributeAxiom
Exergyand link to the original repository.ChangelogSeeReleasesfor
detailed release notes.