InfluxDB 3 Explained: A Beginner’s Guide to Time-Series Data in the AI Era

Why Time Series Databases Matter More Than Ever in 2025

AI is everywhere — but what powers AI behind the scenes? It’s not just big models; it’s the data feeding them. Especially data that changes every second: server logs, IoT sensors, API calls, user clicks. This is time-series data — and InfluxDB 3 is built to handle exactly that. Without fast, scalable time-series storage, AI can’t learn from the world in real-time.

Diving Into InfluxDB 3

There are plenty of time-series databases out there, each with its own strengths and trade-offs. Over the next few articles, I’ll be exploring some of them in detail — starting today with InfluxDB 3.

Why InfluxDB 3 first? Honestly, no dramatic reason. It’s simply one of the most popular choices in the time-series space, widely used in monitoring, IoT, and analytics. With the latest release, InfluxDB has made a big leap forward in performance and developer experience.

Understanding InfluxDB 3

It starts with a Database — the top-level container. If you’re familiar with relational databases, you can think of it a bit like a schema. You can have multiple databases to keep different projects or environments separate.

Inside a database, you’ll find Tables. Each table represents one kind of measurement. For example, you might have a table for api_requests or another one for sensor_data.

And then, within each table, everything comes down to the Point. A point is just a single record of data — one event that happened at a specific moment in time.

What makes a point special is how it’s structured:

• Tags are key-value pairs that describe the event. For instance, region=us-east or status=200. Tags are indexed, which makes them perfect for fast filtering when you query your data.
• Fields hold the actual values you want to measure, such as response_time=45.6 or temperature=22.3. Fields aren’t indexed, so they’re better for metrics than for filtering.
• Timestamp is the anchor. It’s the exact time the event occurred — the backbone that turns regular data into time-series data.

Getting Hands-On with InfluxDB 3

Step 1: Deploy InfluxDB 3 and DB Explorer with Docker

To make things simple, we’ll run InfluxDB 3 locally using Docker Compose. This setup also includes the DB Explorer UI, which gives us a handy web interface to interact with our data.

Here’s the compose.yaml file:

name: influxdb3
services:
  influxdb3-core:
    container_name: influxdb3-core
    image: influxdb:3-core
    ports:
      - 8181:8181
    command:
      - influxdb3
      - serve
      - --node-id=node0
      - --object-store=file
      - --data-dir=/var/lib/influxdb3/data
      - --plugin-dir=/var/lib/influxdb3/plugins
    volumes:
      - ./.influxdb3/core/data:/var/lib/influxdb3/data
      - ./.influxdb3/core/plugins:/var/lib/influxdb3/plugins
    restart: unless-stopped

  influxdb3-explorer:
    image: influxdata/influxdb3-ui:latest
    container_name: influxdb3-explorer
    ports:
      - "8888:80"
    volumes:
      - ./.influxdb3-ui/db:/db:rw
      - ./.influxdb3-ui/config:/app-root/config:ro
    environment:
      SESSION_SECRET_KEY: "${SESSION_SECRET_KEY:-$(openssl rand -hex 32)}"
    restart: unless-stopped
    command: ["--mode=admin"]

Start the containers with:

$ docker compose up -d 

Step 2: Configure BD Explorer with Admin Token

Once your containers are up, create an admin token to authenticate API requests:

$ docker exec influxdb3-core influxdb3 create token --admin

You’ll see output like this:

New token created successfully!

Token: apiv3_R-8qac4pooG_L-Xqc6fEZu-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
HTTP Requests Header: Authorization: Bearer apiv3_R-8qac4pooG_L-Xqc6fEZu-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

IMPORTANT: Store this token securely, as it will not be shown again.

Create a file at ./.influxdb3-ui/config/config.json and paste in your token:

{
  "DEFAULT_INFLUX_SERVER": "http://influxdb3-core:8181",
  "DEFAULT_INFLUX_DATABASE": "mydb",
  "DEFAULT_API_TOKEN": "apiv3_R-8qac4pooG_L-Xqc6fEZu-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "DEFAULT_SERVER_NAME": "Local InfluxDB 3"
}

Then restart the containers:

$ docker compose restart

That’s it — you now have InfluxDB 3 running locally with a UI. Head to http://localhost:8888 in your browser and you’ll be ready to explore.

Step 3: Talk to InfluxDB 3 from Python

Now that our database is running, let’s connect to it from Python and start playing with some data.

Install the client

First, grab the official Python client:

$ pip install influxdb3-python

Connect to InfluxDB 3

Here’s a simple helper function to create a client. Replace the TOKEN value with the admin token you generated earlier:

import pandas as pd
from datetime import datetime, timezone
from influxdb_client_3 import InfluxDBClient3, write_client_options, SYNCHRONOUS, Point
import random
import time
from tqdm import tqdm

# Configuration
HOST = "http://localhost:8181"
DATABASE = "my_database_demo"
TOKEN = "apiv3_R-8qac4pooG_L-Xqc6fEZu-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"  # Replace with your actual token

# Write options for synchronous writes
wco = write_client_options(write_options=SYNCHRONOUS)

def create_client():
    """Create and return an InfluxDB 3 client"""
    return InfluxDBClient3(
        host=HOST,
        database=DATABASE,
        token=TOKEN,
        write_client_options=wco,

    )

Write your first points

Let’s imagine we’re collecting climate data from sensors around the house. Each point will have:

• tags → location, sensor_id
• fields → temperature, humidity
• timestamp → when the reading was taken

table_name = "climate"

# ============== Write One point to DB ============== #
# Create a point with tags, fields, and timestamp
temperature = round(random.uniform(15.0, 30.0), 1)
humidity = round(random.uniform(30.0, 70.0), 1)
point = Point(table_name) \
    .tag("location", "office") \
    .tag("sensor_id", "sensor_001") \
    .field("temperature", temperature) \
    .field("humidity", humidity) \
    .time(datetime.now(timezone.utc))

with create_client() as client:
    # Write the point
    client.write(record=point)

# ============== Batch write to DB ============== #
points = []
locations = ["office", "kitchen", "bedroom", "living_room"]

# Generate sample data points
for i in range(num_points):
    point = Point(table_name) \
        .tag("location", random.choice(locations)) \
        .tag("sensor_id", f"sensor_{i:03d}") \
        .field("temperature", round(random.uniform(18.0, 28.0), 1)) \
        .field("humidity", round(random.uniform(30.0, 70.0), 1)) \
        .time(datetime.now(timezone.utc))
    points.append(point)

with create_client() as client:    
    # Write all points in batch
    client.write(record=points)

InfluxDB 3 creates the climate table automatically when you first write to it.

Query with SQL:

# ============== Query 10 reading from DB ============== #
with create_client() as client:
    # Simple SELECT query
    query = """
    SELECT humidity, temperature 
    FROM climate
    ORDER BY time DESC
    LIMIT 10
    """

    try:
        result = client.query(query)
        df = result.to_pandas()
        print("Latest 10 humidity and temperature readings:")
        print(df.to_string(index=False))
    except Exception as e:
        print(f"Query error: {e}")

# ============== Aggregation Query from DB ============== #
with create_client() as client:
    # Aggregation query with GROUP BY
    query = """
    SELECT 
        location,
        AVG(temperature) as avg_temperature,
        MIN(temperature) as min_temperature,
        MAX(temperature) as max_temperature,
        COUNT(*) as measurement_count
    FROM climate
    WHERE time >= NOW() - INTERVAL '1 hour'
    GROUP BY location
    ORDER BY avg_temperature DESC
    """

    try:
        result = client.query(query)
        df = result.to_pandas()
        print("Temperature statistics by location (last hour):")
        print(df.to_string(index=False))
    except Exception as e:
        print(f"Aggregation query error: {e}")

Here is the output:

=== Basic Queries ===
Latest 10 temperature readings:
 humidity  temperature
     46.7         20.5
     43.5         26.7
     47.8         26.5
     46.5         20.1
     49.7         26.7
     44.3         27.6
     68.0         24.8
     39.9         22.5
     66.2         25.8
     44.0         23.5

=== Aggregation Queries ===
Temperature statistics by location (last hour):
   location  avg_temperature  min_temperature  max_temperature  measurement_count
    bedroom          25.0500             22.5             27.6                  2
    kitchen          24.7000             23.5             25.8                  3
living_room          23.6000             20.5             26.7                  2
     office          22.2625             16.5             29.7                 24

And there you go — you’ve just written and queried your first time-series dataset in InfluxDB 3, using nothing more than SQL and Python.

Pro Tips for Working with InfluxDB 3

Tags vs. Fields — use them wisely

• Tags are for things you filter or group by: region, status, method, env. They’re indexed, which makes queries fast.
• Fields are for the values you measure: temperature, latency_ms, cpu_usage. They’re not indexed, which makes them perfect for math and aggregations.
• Rule of thumb: “Will I filter/group on it?” → tag. “Will I average/sum it?” → field.

👉 Watch out for tag cardinality — millions of unique values (like request_id or user_id) will slow things down.

Reuse your client connection

Creating a new connection on every write is expensive. Instead, reuse the client across your app. Keep it alive and only close when you’re done.

Batch write wherever you can

One-by-one writes are fine for demos, but in production, they’ll crush performance. Collect points in small batches and write them together.

Always start queries with time

Time is your best filter. Scope queries with a time window first, then add tags. This narrows the dataset quickly and makes queries fly.