influxdb-client-python

The influxdb-client-python provides comprehensive support for InfluxDB 2.x and Flux.

Core Capabilities:

Querying

Data can be queried using the Flux language and returned in several formats:

• CSV (via query_csv)
• Raw data
• Table structure (via flux_table)
• Pandas DataFrame

Writing

Data can be written using multiple methods:

• Line Protocol
• Data Point objects
• RxPY Observables
• Pandas DataFrames

Management

The client includes a management API (generated from InfluxDB's Swagger/OpenAPI spec) for:

• Organizations and Users management
• Buckets management
• Tasks management
• Authorizations
• Health checks

Compatibility Note:

• For InfluxDB 3.x, use the v3 client library.
• For InfluxDB 1.x, use the v1 client library.
• This client is not backwards-compatible with the old influxdb-python library.

The InfluxDBClient supports three authentication methods:

1. Token (Preferred): Pass a token to the constructor. An Authorization header will be sent with the value Token <your-token> (the word Token is case-sensitive).
2. Username & Password: Pass username and password. This uses HTTP Basic authentication and creates a session. Note that sessions expire based on the InfluxDB TTL (default 60 minutes).
3. HTTP Basic: Use auth_basic=True and a token (representing the proxy secret) when connecting to an InfluxDB 1.8.x instance protected by a reverse proxy. Do not use this for InfluxDB 2.x.

# Token authentication (Preferred)
with InfluxDBClient(url="http://localhost:8086", token="my-token") as client:
    pass

# Username & Password authentication
with InfluxDBClient(url="http://localhost:8086", username="my-user", password="my-password") as client:
    pass

# HTTP Basic (for 1.8.x behind a proxy)
with InfluxDBClient(url="http://localhost:8086", auth_basic=True, token="my-proxy-secret") as client:
    pass

You can attach static or environment-based tags to every measurement written by the client. This is useful for metadata like hostname or customer_id.

Via PointSettings API

Use PointSettings to add tags programmatically. You can use the syntax ${env.VARIABLE_NAME} to pull values from environment variables.

Via Configuration File

In an init configuration file (supporting INI, TOML, or JSON), specify tags under a [tags] segment.

Via Environment Properties

Set environment variables with the prefix INFLUXDB_V2_TAG_ (e.g., INFLUXDB_V2_TAG_HOSTNAME).

from influxdb_client import InfluxDBClient, PointSettings

# Via API
point_settings = PointSettings()
point_settings.add_default_tag("id", "132-987-655")
point_settings.add_default_tag("data_center", "${env.data_center}")

write_client = client.write_api(point_settings=point_settings)

# Via Environment Properties
# Set INFLUXDB_V2_TAG_HOSTNAME=my-host in your shell
client = InfluxDBClient.from_env_properties()

The WriteApi supports synchronous, asynchronous, and batching writes. Data can be provided in several formats:

1. Line Protocol: A string or bytes formatted as InfluxDB Line Protocol.
2. Data Point: Using the Point class.
3. Dictionary: A mapping with keys measurement, tags, fields, and time.
4. Other structures: NamedTuple, Data Classes, or Pandas DataFrame.
5. Streams: An Observable stream (using reactivex) that produces any of the above.

Important: The WriteApi in batching mode (the default) should be treated as a singleton. To ensure all data is flushed, use a with statement or call write_api.close() at the end of your script.

from influxdb_client import InfluxDBClient, Point, WriteOptions

with InfluxDBClient(url="http://localhost:8086", token="my-token", org="my-org") as _client:
    with _client.write_api(write_options=WriteOptions(batch_size=500)) as _write_client:
        # Write Line Protocol
        _write_client.write("my-bucket", "my-org", "h2o_feet,location=coyote_creek water_level=1.0 1")
        
        # Write Data Point
        _write_client.write("my-bucket", "my-org", Point("h2o_feet").tag("location", "coyote_creek").field("water_level", 4.0).time(4))
        
        # Write Dictionary
        _write_client.write("my-bucket", "my-org", {"measurement": "h2o_feet", "tags": {"location": "coyote_creek"}, "fields": {"water_level": 1.0}, "time": 1})

        # Write Pandas DataFrame
        import pandas as pd
        _df = pd.DataFrame(data=[["coyote_creek", 1.0]], columns=["location", "water_level"])
        _write_client.write("my-bucket", "my-org", record=_df, data_frame_measurement_name='h2o_feet', data_frame_tag_columns=['location'])