2026年5月17日

InfluxDB 3 Coreで時系列データを管理する方法｜導入・書き込み・SQL集計・保存期間

Q: 1.x の influx コマンドの手順が動きません

InfluxDB 3 Core のコマンドは influxdb3 で、1.x の influx -execute や CREATE RETENTION POLICY はありません。データベースは influxdb3 create database、保存期間は --retention-period で指定します。InfluxQL の SELECT 文は --language influxql で実行できます。

Q: 書き込みが「invalid column type」で失敗します

同じ列に、最初と異なる型の値を書いています。整数のフィールドは毎回 i を付けて送る、小数のフィールドに整数を送るときも 120.0 のように小数で書く、など型をそろえてください。

Q: 72 時間より前のデータが問い合わせで読めません

既定の問い合わせファイル数の上限によるものです。範囲を短くして分けて問い合わせるか、メモリに余裕があれば --query-file-limit を上げて起動します。

データベースサーバー

InfluxDB は、時刻つきの数値（サーバーの CPU 使用率、Web サイトの応答時間、センサーの値など）を大量に記録し、期間で絞り込んだり集計したりするためのデータベースです。2026年11月時点で新しく始めるなら、オープンソース版の最新系列は InfluxDB 3 Core（確認した版は 3.12.2）です。この記事では、InfluxDB 3 Core を Docker で起動し、データベースを作り、データを書き込んで SQL で集計するまでを、実際に動かした手順で説明します。

先に要点をまとめます。

InfluxDB 3 Core は influxdb3 という 1 つのコマンドでサーバーの起動と操作を行います。HTTP API の既定ポートは 8181 です。
最初に管理トークン（admin token）を作ります。トークンは作成時に一度だけ表示されます。
保存期間（retention period）はデータベースを作るときに指定します。InfluxDB 3 Core では後から変更できません。
書き込みは「ラインプロトコル」、問い合わせは SQL（既定）または InfluxQL です。1.x の influx コマンドや 2.x の Flux は使いません。
既定の設定では、1 回の問い合わせで参照できる範囲がおおよそ 72 時間までに制限されます。長期間の集計が中心なら、この制限を理解したうえで選びます。

InfluxDB の版による違い

InfluxDB は版ごとに操作方法が大きく異なります。古い記事の手順をそのまま使えないことが多いので、最初に確認してください。

版	操作の単位	問い合わせ	保存期間
1.x	データベースとリテンションポリシー	InfluxQL（`influx` コマンド）	`CREATE RETENTION POLICY`
2.x	組織・バケット・API トークン	Flux（InfluxQL は互換 API 経由）	バケットごとに設定
3 Core	データベース・トークン	SQL と InfluxQL（Flux は非対応）	データベース作成時に指定

1.x 向けの influx -execute 'CREATE DATABASE …' や、UDP の 8089 番へ送る方法は、3 Core にはありません。2.x の使い方や、タグとフィールドの設計を詳しく知りたい場合は「InfluxDBの時系列データ管理方法」も参照してください。

手順 1: InfluxDB 3 Core を起動する

公式の Docker イメージ influxdb:3-core を使う方法が、OS を問わず同じ手順で試せます。データはボリューム influxdb3-data に保存し、ポートはまず自分のマシン（127.0.0.1）だけに公開します。

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

オプション	意味
`--node-id`	このサーバーの識別名。保存先のパスの一部になる
`--object-store file`	データをローカルのファイルとして保存する（ほかに `s3`、`google`、`azure` など）
`--data-dir`	`file` を選んだときの保存先

起動したら版を確認します。

docker exec influxdb3 influxdb3 --version

Docker を使わずに入れる場合は、公式のインストールスクリプト、または InfluxData のリポジトリを追加したうえで influxdb3-core パッケージ（apt / yum）を使います。リポジトリの追加手順は公式ドキュメントの「Install InfluxDB 3 Core」に従ってください。

手順 2: 管理トークンを作る

InfluxDB 3 Core は、最初の管理トークンが作られるまで、トークン作成の API が認証なしで受け付けられます。起動したらすぐに作成してください（手順 1 でポートを 127.0.0.1 に限ったのはこのためです）。

docker exec influxdb3 influxdb3 create token --admin

apiv3_ で始まる文字列が表示されます。この 1 回しか表示されないので、パスワード管理ツールなどに保管します。以降のコマンドでは環境変数に入れておくと --token を省略できます。

export INFLUXDB3_AUTH_TOKEN=apiv3_ここに表示されたトークン

Docker で動かしている場合、以降の influxdb3 … のコマンドは、コンテナーの中で環境変数を渡して実行します。毎回書くのは長いので、エイリアスにしておくと記事のコマンドをそのまま使えます。

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

トークンなしで問い合わせると、HTTP 401 が返ります。

手順 3: 保存期間つきのデータベースを作る

WordPress サイトの監視データを 30 日間保存するデータベース wpmon を作ります。

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

保存期間は 30d（日）、24h（時間）、4w（週）などで指定します。省略すると、データは期限切れになりません。
InfluxDB 3 Core では、作成後に保存期間を変える手段がありません。変えたいときは新しいデータベースを作ってデータを移します。
データベース名に使えるのは英数字・_・- で、英字か数字で始めます。大文字と小文字は区別されます。
InfluxDB 3 Core で作れるデータベースは 5 個までです。

データベースは最初の書き込みで自動的に作られもしますが、その場合は保存期間を指定できないため、先に作っておきます。

手順 4: ラインプロトコルでデータを書き込む

InfluxDB への書き込みは「ラインプロトコル」という 1 行 1 データの書式です。

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

部分	例	意味
テーブル名	`nginx_requests`	データの種類（1.x / 2.x の measurement）
タグ	`host=web01,site=example.com`	絞り込みやグループ化に使う属性。値は文字列
フィールド	`count=125i,resp_time=0.084`	記録する値。整数は末尾に `i`、文字列は `"…"` で囲む
タイムスタンプ	`1793000000`	時刻。精度は書き込み時に指定する

テーブル名とタグはカンマでつなぎ、空白のあとにフィールド、さらに空白のあとにタイムスタンプを書きます。タグの値に空白やカンマを含めるときは \ でエスケープします。

CLI から書き込む例です（タイムスタンプは秒単位なので --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)"

HTTP API から書き込む場合は /api/v3/write_lp を使います。成功すると 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)"

precision に指定できるのは auto（既定）、nanosecond、microsecond、millisecond、second です。

型は最初の書き込みで決まる

InfluxDB 3 Core では、テーブルの列とその型が最初の書き込みで決まり、以後の書き込みはその型と照合されます。たとえば整数で作った count に文字列を書くと、次のように拒否されます（HTTP 400）。

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

新しいタグやフィールドを後から足すことはできます。公式の設計指針では、次の点が勧められています。

発生元や文脈を表すもの（ホスト名、サイト名、地域）はタグ、測った値はフィールドにする
1 つのテーブルに、タグとフィールドの組み合わせが異なるデータを混ぜない（空の値が増えて問い合わせが遅くなる）
同じ時刻に測った値は、同じタグ・同じタイムスタンプの 1 行にまとめて書く
名前に SQL や InfluxQL の予約語・記号を使わない

手順 5: SQL と InfluxQL で問い合わせる

influxdb3 query の既定の言語は SQL です。直近 1 時間のデータを時刻順に出します。

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

一定間隔で集計するには date_bin を使います。5 分ごと・ホストごとに、応答時間の平均とリクエスト数の合計を出す例です。

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

1.x で使っていた InfluxQL の問い合わせも、--language influxql を付ければ実行できます。

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

テーブルと列の一覧は SQL で確認できます。

SHOW TABLES;
SHOW COLUMNS FROM nginx_requests;

HTTP API で問い合わせる場合は /api/v3/query_sql を使い、format に json、jsonl、csv、pretty、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"

問い合わせ範囲の制限

InfluxDB 3 Core には、1 回の問い合わせで読める Parquet ファイルの数の上限（--query-file-limit、既定 432）があります。既定の設定では、これはおおよそ 72 時間分のデータに相当し、超える範囲を問い合わせるとエラーになります。上限は influxdb3 serve のオプションで変えられますが、公式ドキュメントでは値を上げるとメモリの使用量が増え、性能が落ちることがあると説明されています。数か月分をまとめて集計する用途が中心なら、この点を踏まえて版を選んでください。

例: WordPress の応答時間を 1 分ごとに記録する

サイトのトップページの HTTP ステータスと応答時間を、cron で 1 分ごとに記録するスクリプトの例です。トークンは /etc/wpmon.env に INFLUXDB3_AUTH_TOKEN=… の形で書き、chmod 600 で他のユーザーから読めないようにしておきます。

#!/bin/sh
# /usr/local/bin/wp-resp-to-influx.sh
# WordPress のトップページの応答時間を InfluxDB 3 Core に記録する
. /etc/wpmon.env   # INFLUXDB3_AUTH_TOKEN=... を書いたファイル（権限 600）

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

# HTTP ステータスと応答時間（秒）を取得
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
# crontab -e で次の 1 行を追加
* * * * * /usr/local/bin/wp-resp-to-influx.sh

記録した値は、次のように 1 時間ごとの平均と最大で確認できます。

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

グラフにする場合は Grafana のデータソースに InfluxDB を追加して使うのが一般的です。監視の可視化全体の組み立ては「GrafanaでPrometheusのメトリクスを可視化する方法」を参照してください。

運用の注意

外部に公開しない: 8181 番はトークンで保護されますが、監視データの書き込み元が同じサーバーや社内だけなら、ファイアウォールで外部からの接続を止めておきます。
トークンの扱い: 3.12.2 の influxdb3 create token で作れるのは管理トークン（--admin）だけで、このトークンはデータベースの作成・削除もできます。スクリプトに置く場合はファイルの権限を 600 にし、8181 番を外部から使えないようにしておきます。
保存期間を決めてから作る: Core では保存期間を後から変えられないため、何日分を残すかを先に決めます。
バックアップ: --object-store file の場合、データは --data-dir 以下のファイルです。Docker の例ではボリューム influxdb3-data を、サーバーを止めた状態でコピーします。

よくある質問

1.x の `influx` コマンドの手順が動きません

InfluxDB 3 Core のコマンドは influxdb3 で、1.x の influx -execute や CREATE RETENTION POLICY はありません。データベースは influxdb3 create database、保存期間は --retention-period で指定します。InfluxQL の SELECT 文は --language influxql で実行できます。

書き込みが「invalid column type」で失敗します

同じ列に、最初と異なる型の値を書いています。整数のフィールドは毎回 i を付けて送る、小数のフィールドに整数を送るときも 120.0 のように小数で書く、など型をそろえてください。

72 時間より前のデータが問い合わせで読めません

既定の問い合わせファイル数の上限によるものです。範囲を短くして分けて問い合わせるか、メモリに余裕があれば --query-file-limit を上げて起動します。

まとめ

InfluxDB 3 Core は influxdb3 serve で起動し、最初に influxdb3 create token --admin で管理トークンを作って保管します。
データベースは influxdb3 create database --retention-period 30d 名前 で作り、保存期間は作成時に決めます。
書き込みはラインプロトコル（influxdb3 write か /api/v3/write_lp）、問い合わせは SQL の date_bin で間隔ごとに集計します。既定では問い合わせ範囲がおおよそ 72 時間までになる点に注意します。

参考: InfluxDB 3 Core ドキュメント – Set up、Install InfluxDB 3 Core、Create a database、Query data、Schema design recommendations、Configuration options

更新履歴: 2026-11-10 全面改訂（CentOS 7 と InfluxDB 1.x の古い手順・動かないコマンドを、InfluxDB 3 Core 3.12.2 で動作を確かめた手順に置き換え）。