Influx Module

The influx module provides functionality for interacting with InfluxDB time series databases.

tide.influx.get_influx_data(start, stop, bucket, measurement, tide_tags, url, org, token, split_td=None, tz_info='UTC', request_timeout=10000, max_retry=5, waited_seconds_at_retry=5, verbose=False)[source]

Fetch time series data from an InfluxDB instance.

This function retrieves data from InfluxDB and formats it according to Tide’s hierarchical column naming convention. It supports:

Flexible time range specification

Automatic query splitting for large time ranges

Retry mechanism for handling timeouts

Timezone-aware data handling

Parameters:

start (str or pd.Timestamp or datetime.datetime) –
Start time for the query. Can be:
- A relative time string (e.g., “-1d”, “-2h”)
- A pandas Timestamp
- A datetime object
If using relative time strings, they are interpreted relative to the current time.
stop (str or pd.Timestamp or datetime.datetime) – End time for the query. Accepts the same formats as start.
bucket (str) – Name of the InfluxDB bucket to query.
measurement (str) – Name of the InfluxDB measurement to filter data.
tide_tags (list[str]) – List of InfluxDB fields/tags to combine into Tide column names. Must be specified in order: [name, unit, bloc, sub_bloc]. Example: [“name”, “unit”, “location”, “room”] will create columns like “temperature__°C__zone1__room1”
url (str) – URL of the InfluxDB instance (e.g., “http://localhost:8086”)
org (str) – InfluxDB organization name
token (str) – Authentication token for InfluxDB access
split_td (str or datetime.timedelta or pd.Timedelta, optional) – Time interval for splitting large queries into smaller chunks. Useful for handling large time ranges or rate limits. Example: “1d” for daily chunks, “12h” for half-day chunks. If None, queries the entire time range at once.
tz_info (str, default "UTC") – Timezone for interpreting start and stop times. Must be a valid timezone name from the IANA Time Zone Database.
request_timeout (int, default 10 000) – Number of ms to wait before the request timeout
max_retry (int, default 5) – Maximum number of retry attempts for failed queries. Only applies to ReadTimeoutError exceptions.
waited_seconds_at_retry (int, default 5) – Number of seconds to wait between retry attempts.
verbose (bool, default False) – Whether to print progress information during data fetching.

Returns:

DataFrame containing the fetched data with:

Datetime index in UTC
Columns named according to Tide’s convention (name__unit__bloc__sub_bloc)
Values from the InfluxDB _value field

Return type:

pd.DataFrame

Raises:

ReadTimeoutError – If all retry attempts fail to fetch data
ValueError – If tz_info is required but not provided for naive datetime objects

Examples

>>> from tide.influx import get_influx_data
>>> import pandas as pd
>>> # Fetch last 24 hours of data
>>> df = get_influx_data(
...     start="-24h",
...     stop="now",
...     bucket="my_bucket",
...     measurement="sensors",
...     tide_tags=["name", "unit", "location"],
...     url="http://localhost:8086",
...     org="my_org",
...     token="my_token",
... )
>>> # Fetch specific time range with daily splitting
>>> df = get_influx_data(
...     start="2023-01-01",
...     stop="2023-01-07",
...     bucket="my_bucket",
...     measurement="sensors",
...     tide_tags=["name", "unit", "location", "room"],
...     url="http://localhost:8086",
...     org="my_org",
...     token="my_token",
...     split_td="1d",
...     verbose=True,
... )
>>> # Fetch data with custom timezone
>>> df = get_influx_data(
...     start="2023-01-01T00:00:00",
...     stop="2023-01-01T23:59:59",
...     bucket="my_bucket",
...     measurement="sensors",
...     tide_tags=["name", "unit", "location"],
...     url="http://localhost:8086",
...     org="my_org",
...     token="my_token",
...     tz_info="Europe/Paris",
... )

tide.influx.push_influx_data(data, tide_tags, bucket, url, org, token, measurement='tide')[source]

Pushes data from a pandas DataFrame to an InfluxDB bucket.

This function processes a DataFrame indexed by datetime and writes the data to an InfluxDB bucket. Each row in the DataFrame is expanded based on Tide tags extracted from a specific column and written to InfluxDB with corresponding timestamp and tag values.

Parameters:

data (pd.DataFrame): Input DataFrame with a datetime index and: one or more columns of values.
tide_tags (list[str]): List of tag names to extract from the: “full_index” column after splitting it. For exemple : [“Name”, “Unit”, “bloc”, “sub_bloc”

bucket (str): InfluxDB bucket name where the data will be written.

url (str): URL of the InfluxDB instance.

org (str): InfluxDB organization name.

token (str): Authentication token for the InfluxDB instance.

measurement (str, optional): Name of the measurement to use in InfluxDB.: Defaults to “tide”.

Raises:

ValueError: If the input data is not a DataFrame with a datetime index.

Example:

>>> data = pd.DataFrame(
    {
        "name1__°C__bloc1": [1.0, 2.0],
        "name2__W__bloc1": [3.0, 4.0],
    },
    index=pd.to_datetime(["2009-01-01T00:00:00Z", "2009-01-01T01:00:00Z"]),
)

>>> push_influx_data(
        data=data,
        tide_tags=['Name', 'Unit', "bloc"],
        bucket='my-bucket',
        url='http://localhost:8086',
        org='my-org',
        token='my-token'
    )