2026年11月14日

InfluxDB 3 Core: Manage Time-Series Data with SQL and Retention

Database Servers

This article is a localized edition of the Japanese original. Read the Japanese original

InfluxDB is a database built to record large volumes of timestamped values (server CPU usage, website response times, sensor readings and so on) and to filter and aggregate them by time range. If you are starting fresh as of November 2026, the latest open source line is InfluxDB 3 Core (the version checked here is 3.12.2). This article walks through running InfluxDB 3 Core in Docker, creating a database, writing data and aggregating it with SQL, using steps that were actually run.

Here are the key points up front.

InfluxDB 3 Core uses a single command, influxdb3, both to run the server and to operate it. The default HTTP API port is 8181.
Create an admin token first. The token is displayed only once, when it is created.
The retention period is set when you create a database. In InfluxDB 3 Core it cannot be changed afterward.
You write with "line protocol" and query with SQL (the default) or InfluxQL. You do not use the 1.x influx command or the 2.x Flux language.
With the default settings, a single query can cover only about 72 hours of data. If long-range aggregation is your main use, factor this limit into your choice.

Differences between InfluxDB versions

How you operate InfluxDB differs a lot from version to version, and steps from older articles often do not work as written. Check this first.

Version	Unit of management	Queries	Retention
1.x	Databases and retention policies	InfluxQL (the `influx` command)	`CREATE RETENTION POLICY`
2.x	Organizations, buckets, API tokens	Flux (InfluxQL through the compatibility API)	Set per bucket
3 Core	Databases, tokens	SQL and InfluxQL (no Flux)	Set when the database is created

The 1.x style influx -execute 'CREATE DATABASE …' and sending data to UDP port 8089 do not exist in 3 Core. For 2.x usage and a deeper look at tag and field design, see "Managing time-series data in InfluxDB".

Step 1: Start InfluxDB 3 Core

The official Docker image influxdb:3-core lets you follow the same steps on any OS. Data is stored in the volume influxdb3-data, and the port is published only to your own machine (127.0.0.1) at first.

docker run -d --name influxdb3 \
  -p 127.0.0.1:8181:8181 \
  -v influxdb3-data:/var/lib/influxdb3 \
  influxdb:3-core influxdb3 serve \
    --node-id host01 \
    --object-store file \
    --data-dir /var/lib/influxdb3/data

Option	Meaning
`--node-id`	An identifier for this server. It becomes part of the storage path
`--object-store file`	Store data as local files (other options include `s3`, `google` and `azure`)
`--data-dir`	Where data is stored when you choose `file`

Once it is running, check the version.

docker exec influxdb3 influxdb3 --version

To install without Docker, use the official install script, or add the InfluxData repository and install the influxdb3-core package (apt / yum). Follow "Install InfluxDB 3 Core" in the official documentation to add the repository.

Step 2: Create an admin token

Until the first admin token exists, InfluxDB 3 Core accepts the token creation API without authentication. Create one right after starting the server (this is why Step 1 limited the port to 127.0.0.1).

docker exec influxdb3 influxdb3 create token --admin

A string starting with apiv3_ is displayed. It is shown only this once, so store it somewhere safe, such as a password manager. If you put it in an environment variable, you can omit --token in the commands that follow.

export INFLUXDB3_AUTH_TOKEN=apiv3_YOUR_TOKEN_HERE

If you run InfluxDB in Docker, the influxdb3 … commands below run inside the container with the environment variable passed in. Typing that every time is tedious, so set up an alias and you can use the commands in this article as written.

alias influxdb3='docker exec -e INFLUXDB3_AUTH_TOKEN influxdb3 influxdb3'

A query without a token returns HTTP 401.

Step 3: Create a database with a retention period

Create a database named wpmon that keeps monitoring data for a WordPress site for 30 days.

influxdb3 create database --retention-period 30d wpmon
influxdb3 show databases

Specify the retention period as 30d (days), 24h (hours), 4w (weeks) and so on. If you omit it, data never expires.
InfluxDB 3 Core has no way to change the retention period after creation. To change it, create a new database and move the data.
Database names may contain alphanumeric characters, _ and -, and must start with a letter or digit. Names are case-sensitive.
InfluxDB 3 Core allows up to 5 databases.

A database is also created automatically on the first write, but then you cannot set a retention period, so create it in advance.

Step 4: Write data with line protocol

Writes to InfluxDB use "line protocol", a format with one data point per line.

nginx_requests,host=web01,site=example.com count=125i,resp_time=0.084 1793000000

Part	Example	Meaning
Table name	`nginx_requests`	The kind of data (the measurement in 1.x / 2.x)
Tags	`host=web01,site=example.com`	Attributes used for filtering and grouping. Values are strings
Fields	`count=125i,resp_time=0.084`	The values you record. Integers end with `i`; strings are wrapped in `"…"`
Timestamp	`1793000000`	The time. The precision is specified when writing

Join the table name and tags with commas, then a space and the fields, then another space and the timestamp. Escape spaces or commas in tag values with \.

Here is a write from the CLI (the timestamps are in seconds, so add --precision s).

influxdb3 write --database wpmon --precision s \
"nginx_requests,host=web01,site=example.com count=125i,resp_time=0.084 $(date +%s)
nginx_requests,host=web02,site=example.com count=98i,resp_time=0.120 $(date +%s)"

To write through the HTTP API, use /api/v3/write_lp. A successful write returns HTTP 204.

curl "http://127.0.0.1:8181/api/v3/write_lp?db=wpmon&precision=second" \
  -H "Authorization: Bearer ${INFLUXDB3_AUTH_TOKEN}" \
  --data-raw "nginx_requests,host=web01,site=example.com count=130i,resp_time=0.091 $(date +%s)"

Valid values for precision are auto (the default), nanosecond, microsecond, millisecond and second.

Column types are fixed by the first write

In InfluxDB 3 Core, a table's columns and their types are set by the first write, and later writes are validated against those types. For example, writing a string to count, which was created as an integer, is rejected like this (HTTP 400).

invalid column type for column 'count', expected iox::column_type::field::integer, got iox::column_type::field::string

You can add new tags and fields later. The official schema design guidance recommends the following.

Use tags for things that describe the source or context (host name, site name, region) and fields for measured values
Do not mix data with different tag and field sets in one table (empty values pile up and queries slow down)
Write values measured at the same moment as one line with the same tags and the same timestamp
Do not use SQL or InfluxQL reserved words or symbols in names

Step 5: Query with SQL and InfluxQL

The default language of influxdb3 query is SQL. This lists the last hour of data in time order.

influxdb3 query --database wpmon \
  "SELECT * FROM nginx_requests WHERE time >= now() - INTERVAL '1 hour' ORDER BY time"

To aggregate by fixed intervals, use date_bin. This example returns the average response time and the total request count per 5 minutes and per host.

SELECT
  date_bin(INTERVAL '5 minutes', time) AS bucket,
  host,
  avg(resp_time) AS avg_resp,
  sum(count) AS total
FROM nginx_requests
WHERE time >= now() - INTERVAL '1 hour'
GROUP BY 1, host
ORDER BY 1, host

InfluxQL queries you used with 1.x also run if you add --language influxql.

influxdb3 query --database wpmon --language influxql \
  "SELECT MEAN(resp_time) FROM nginx_requests WHERE time > now() - 1h GROUP BY host"

You can list tables and columns with SQL.

SHOW TABLES;
SHOW COLUMNS FROM nginx_requests;

To query through the HTTP API, use /api/v3/query_sql; set format to json, jsonl, csv, pretty or parquet.

curl -G "http://127.0.0.1:8181/api/v3/query_sql" \
  -H "Authorization: Bearer ${INFLUXDB3_AUTH_TOKEN}" \
  --data-urlencode "db=wpmon" \
  --data-urlencode "q=SELECT host, resp_time FROM nginx_requests LIMIT 5" \
  --data-urlencode "format=csv"

Query range limit

InfluxDB 3 Core caps the number of Parquet files a single query can read (--query-file-limit, default 432). With the default settings this works out to about 72 hours of data, and querying a wider range returns an error. You can change the cap with an influxdb3 serve option, but the official documentation explains that raising it increases memory use and can reduce performance. If aggregating several months at once is your main use, take this into account when choosing a version.

Example: record WordPress response time every minute

This sample script records the HTTP status and response time of the site's front page every minute from cron. Put the token in /etc/wpmon.env as INFLUXDB3_AUTH_TOKEN=… and run chmod 600 so other users cannot read it.

#!/bin/sh
# /usr/local/bin/wp-resp-to-influx.sh
# Record the response time of the WordPress front page in InfluxDB 3 Core
. /etc/wpmon.env   # file containing INFLUXDB3_AUTH_TOKEN=... (permissions 600)

URL="https://example.com/"
SITE="example.com"

# Get the HTTP status and the response time (seconds)
set -- $(curl -o /dev/null -s --max-time 20 -w '%{http_code} %{time_total}' "$URL")

curl -s --max-time 10 \
  "http://127.0.0.1:8181/api/v3/write_lp?db=wpmon&precision=second" \
  -H "Authorization: Bearer ${INFLUXDB3_AUTH_TOKEN}" \
  --data-raw "wp_response,site=${SITE} status=${1}i,resp_time=${2} $(date +%s)"

sudo chmod 755 /usr/local/bin/wp-resp-to-influx.sh
# Add the following line with crontab -e
* * * * * /usr/local/bin/wp-resp-to-influx.sh

You can then check the recorded values as hourly averages and maximums.

SELECT
  date_bin(INTERVAL '1 hour', time) AS hour,
  avg(resp_time) AS avg_resp,
  max(resp_time) AS max_resp
FROM wp_response
WHERE time >= now() - INTERVAL '1 day'
GROUP BY 1
ORDER BY 1

For graphs, the usual approach is to add InfluxDB as a data source in Grafana. For building monitoring dashboards overall, see "Visualizing Prometheus metrics with Grafana".

Operational notes

Do not expose it publicly: Port 8181 is protected by tokens, but if data is written only from the same server or your internal network, block outside connections with the firewall.
Token handling: In 3.12.2, influxdb3 create token can create only admin tokens (--admin), and such a token can also create and delete databases. If you place it in a script, set the file permissions to 600 and keep port 8181 unreachable from outside.
Decide the retention period before creating the database: Core cannot change it later, so decide how many days to keep first.
Backups: With --object-store file, the data is the files under --data-dir. In the Docker example, copy the influxdb3-data volume while the server is stopped.

FAQ

Steps using the 1.x `influx` command do not work

The InfluxDB 3 Core command is influxdb3; the 1.x influx -execute and CREATE RETENTION POLICY do not exist. Create databases with influxdb3 create database and set retention with --retention-period. InfluxQL SELECT statements run with --language influxql.

Writes fail with “invalid column type”

You are writing a value of a different type than the first one written to that column. Keep types consistent: always send integer fields with the i suffix, and when sending a whole number to a float field, write it as a decimal such as 120.0.

Queries cannot read data older than 72 hours

This comes from the default cap on the number of files per query. Split the query into shorter ranges, or, if you have memory to spare, start the server with a higher --query-file-limit.

Summary

Start InfluxDB 3 Core with influxdb3 serve, then create and store an admin token with influxdb3 create token --admin.
Create databases with influxdb3 create database --retention-period 30d NAME; the retention period is fixed at creation.
Write with line protocol (influxdb3 write or /api/v3/write_lp) and aggregate by interval with SQL's date_bin. Keep in mind that by default a query covers only about 72 hours.

References: InfluxDB 3 Core documentation – Set up, Install InfluxDB 3 Core, Create a database, Query data, Schema design recommendations, Configuration options

Revision history: 2026-11-10 full revision (replaced outdated CentOS 7 and InfluxDB 1.x steps and non-working commands with steps verified on InfluxDB 3 Core 3.12.2).

Questions about WordPress? The publisher of this site is based in Japan and replies in Japanese. Contact (Japanese)