Skip to main content

InfluxDB client

Project description

influx-client

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.

Prerequisites

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.

Installation

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

Usage

This section describes basic usage.

Quickstart Example

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 clean up after yourself, for example in testing environments
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

Development

This section describes development and contribution for influx-client.

Contributors

This section lists everyone who has contributed to this project.

Repository Layout

There are a few important pieces in this repository:

  • influx/ - The influx Python package
  • test/ - Python nosetests
  • Dockerfile, docker-compose.yml - Docker configuration for testing
  • LICENSE, README.md - Documentation and legal

Running Tests

You 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

Making Pull Requests

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.

API

This section describes the public API for influx-client.

InfluxDB(url)

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.

  • url (str) - URL to InfluxDB API (such as 'http://127.0.0.1:8086')

.create_database(database)

Issues a CREATE DATABASE ... request to the InfluxDB API. This is an idempotent operation.

  • database (str) - Database name

.drop_database(database)

Issues a DROP DATABASE ... request to the InfluxDB API. This will raise a 404 HTTPError if the database does not exist.

  • database (str) - Database name

.write(database, measurement, fields, tags={}, time=None)

Write data points to the specified database and measurement.

  • database (str) - Database name
  • measurement (str) - Measurement name
  • fields (dict) - Dictionary of field_name: value data points
  • tags (dict, optional) - Dictionary of tag_name: value tags to associate with the data points
  • time (datetime, optional) - Datetime to use instead of InfluxDB's server-side "now"

.write_many(database, measurement, fields, tags={}, time=None)

Write data points to the specified database and measurement.

  • database (str) - Database name
  • measurement (str) - Measurement name
  • fields (list) - List of field names, ordered the same as values
  • values (list) - List of values (list of lists)
  • tags (dict, optional) - Dictionary of tag_name: value tags to associate with the data points
  • time_field (str, optional) - Field name to extract and use as timestamp

.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.

  • database (str) - Database name
  • measurement (str) - Measurement name
  • fields (str, default '*') - String formatted fields for SELECT query
  • tags (dict, optional) - Dictionary of tag_name: value tags to match
  • relative_time (str, default '15m') - Relative time string

License

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.

Changelog

See Releases for detailed release notes.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

influx-client-1.1.0.tar.gz (9.4 kB view details)

Uploaded Source

Built Distribution

influx_client-1.1.0-py3-none-any.whl (9.4 kB view details)

Uploaded Python 3

File details

Details for the file influx-client-1.1.0.tar.gz.

File metadata

  • Download URL: influx-client-1.1.0.tar.gz
  • Upload date:
  • Size: 9.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for influx-client-1.1.0.tar.gz
Algorithm Hash digest
SHA256 0350183136c8040f5b33f91181c286d296b381c50dbb89646f63c1ec4cf7f212
MD5 06f3a280c1138b33959bc778e8eaad8d
BLAKE2b-256 4a34c33cd990c8acbde5bb3dc6aa0f1f6f9238143479e2da8b2294600a75e6e5

See more details on using hashes here.

File details

Details for the file influx_client-1.1.0-py3-none-any.whl.

File metadata

File hashes

Hashes for influx_client-1.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 c3d62e0eb99c4b7c9281f0f0a49eed65ba4bf435ecb31e3afef37aa251c1857f
MD5 c0150d49ab4f083f59a4d69ff786978a
BLAKE2b-256 5eb2aac7c1b005ec418965b5988d4419841601274b11338a911c4ff881565e05

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page