[技术调研/TSDB] Apache IoTDB 2.0.11 树模式下,写入Points时自动创建 Schema
0 序
0. 调研信息
更新时间:2026-11-20 14:40
文档类型:技术调研报告
调研时间:2026-11-20
目标版本:Apache IoTDB 2.0.11(Docker Compose 部署,1C1D)
调研范围:树模型(Tree Model)写入路径上的 Schema 自动创建(database / device / timeseries / 数据类型推断)
核心结论:2.0.11 默认启用enable_auto_create_schema(默认值 true)。写入不存在的库、设备、序列时,会自动建库、建序列并按首写值推断类型;该参数为重启生效项,且默认iotdb-system.properties中不显式写出,因此默认的SHOW CONFIGURATION结果里查不到它,需用SHOW ALL CONFIGURATION。
1 调研报告
1. 结论速览
| 编号 | 问题 | 结论 | 证据强度 |
|---|---|---|---|
| Q1 | 2.0.11 默认是否启用自动创建 Schema | 是,enable_auto_create_schema 配置项默认值 true;关联的配置项:default_storage_group_level、boolean_string_infer_type / integer_string_infer_type / long_string_infer_type / floating_string_infer_type / nan_string_infer_type 等 |
官方配置手册(明确默认值) |
| Q2 | 实测能否自动建库、建序列 | 能,三条探针写入全部成功并自动落地 | 实测(2026-11-20) |
| Q3 | 为什么 SHOW CONFIGURATION 查不到该配置项 |
该语句默认只返回配置文件中显式配置过的项;该项在默认配置里未写出的,走默认值 | 官方运维语句手册 + 实测 |
| Q4 | 要看它的值该用什么语句 | SHOW ALL CONFIGURATION ON <nodeId> [WITH DESC] |
官方运维语句手册(2.0.10 起支持) |
| Q5 | 修改后如何生效 | 必须重启(effectiveMode: restart),SET CONFIGURATION 只负责落盘。 |
官方配置手册 |
| Q6 | 「不预建序列(树模式的TimeSeries)」方案是否成立 | 成立,可依赖首写自动建序列;代价是首写决定类型 | 实测 + 机制分析 |
2. 背景与问题
(传感器多行模式)时序写入时,在测点的设备ID值及数量动态、难以提前建模的写入场景中,常见做法是「不预建序列」,依赖首次写入自动创建序列:
- 预建条数 =
V(设备数)×S(每设备测点数); - 当
S达到数百至数千时,V×S的预建成本不可接受; - 因此需要依赖「首次写入即自动创建序列」。
需要闭环回答的问题:
- enable_auto_create_schema 参数是否存在、默认值是什么?
- 该参数在 2.0.11 中当前是否真的生效(而非仅停留在配置文件)?
- 除 timeseries 外,database 是否也会自动创建、按哪一层切分?
- 自动创建出来的 timeseries,数据类型/编码/压缩由什么决定?
- 若被关闭,写入行为是"失败"还是"静默丢弃"?
- Docker Compose 部署下如何查询、如何配置、如何保证不随容器重建丢失?
3. 机制说明
3.1 写入时的判定顺序
要点:关闭自动创建时,写入是直接报错,不是丢弃数据。这也是关闭该参数后 SeaTunnel 任务会整体失败的原因。
3.2 三个联动配置项
| 配置项 | 作用 | 默认值 | 生效方式 | 备注 |
|---|---|---|---|---|
enable_auto_create_schema |
序列不存在时是否自动创建 | true |
重启 | 归属「自动推断数据类型」配置组 |
default_storage_group_level(或:default_database_level) |
自动创建时把路径第几层作为 database | 1 |
重启 | root 为第 0 层;路径长度不足时创建/写入失败 |
boolean_string_infer_type / integer_string_infer_type / floating_string_infer_type / nan_string_infer_type |
首写字符串值的类型推断目标 | BOOLEAN / DOUBLE / DOUBLE / DOUBLE |
热加载 | 自动创建模式下的类型由它们决定 |
default_text_encoding / text_compressor / default_double_encoding 等 |
自动创建序列的编码与压缩 | PLAIN / LZ4 / 实测 GORILLA |
热加载 | 实测值见第 5 节 |
特别注意: Apache IotDB 2.0.11 中,
default_database_level(旧配置项名default_storage_group_level仍可识别,优先级更低)
结论:
S较大时真正"不可控"的不是建不建序列,而是建出来的类型和编码——它们由首写值与上述推断配置共同决定。
3.3 基于 default_storage_group_level=1 的路径切分
写入 root.zz_probe_db.dev1.s1 时:
| 路径片段 | 角色 | 说明 |
|---|---|---|
root |
第 0 层,固定根 | — |
zz_probe_db |
database(第 1 层) | 库不存在则自动创建 |
dev1 |
设备(device) | 由序列路径前缀决定 |
s1 |
测点(timeseries) | 不存在则自动创建 |
实测 SHOW TIMESERIES 的 Database 列返回 root.zz_probe_db,与上述切分一致。
4. 如何确认是否启用
按可靠性从低到高,共三层证据。
4.1 配置层查询(2.0.10 及以上支持,推荐)
SHOW CONFIGURATION; -- 直连 DataNode 的已配置项
SHOW CONFIGURATION ON 1; -- 指定 nodeId
SHOW ALL CONFIGURATION ON 1; -- 全部配置项(未显式配置的 value 为 null)
SHOW CONFIGURATION ON 1 WITH DESC; -- 附 description(含 effectiveMode / Datatype)
语法:
showConfigurationStatement : SHOW (ALL)? CONFIGURATION (ON nodeId=INTEGER_VALUE)? (WITH DESC)? ;
返回列:name / value / default_value / description(仅 WITH DESC)。
语义要点:
- 不带
ALL时,只返回「配置文件中已配置的项」——这正是enable_auto_create_schema默认查不到的原因; - 带
ALL时返回所有配置项,未配置项的value为null; - 带
WITH DESC时,描述里直接给出effectiveMode,可当场确认是否为restart。
判读规则:
| 返回形态 | 含义 |
|---|---|
value = true |
显式开启 |
value = false |
显式关闭 |
value = null 且 default_value = true |
未显式配置,按默认值 true 生效(即已启用) |
| 结果中完全没有该行 | 该项未在配置描述清单中暴露,以行为探针为准 |
nodeId 获取方式:SHOW CLUSTER DETAILS 查看 NodeID 列;0/2/3 一般为 ConfigNode,DataNode 常为 1。
4.2 文件层核对
| 部署形态 | 文件路径 |
|---|---|
| 2.0.x | $IOTDB_HOME/conf/iotdb-system.properties(模板 iotdb-system.properties.template) |
| 1.x | conf/iotdb-common.properties |
| 0.13.x | conf/iotdb-engine.properties |
# Linux
grep -n "enable_auto_create_schema" $IOTDB_HOME/conf/iotdb-system.properties \
$IOTDB_HOME/conf/iotdb-system.properties.template
# Windows PowerShell
Select-String -Path "$env:IOTDB_HOME\conf\iotdb-system.properties" -Pattern "enable_auto_create_schema"
判读:整行被注释或不存在 → 取默认 true;出现多条同名键 → 以最后一条未注释的为准。
4.3 行为探针(最终判定,唯一能证明"运行中已生效"的手段)
-- 使用不与业务冲突的探针路径
INSERT INTO root.zz_probe_db.dev1(time, s1) VALUES (now(), 1.0);
SHOW TIMESERIES root.zz_probe_db.dev1.s1;
-- 清理(探针会自动建库,因此删库)
DELETE DATABASE root.zz_probe_db;
判读:写入成功且能查到序列 → 已启用;写入报序列/库不存在 → 未生效。
为什么配置层证据不够:对
effectiveMode: restart的配置项,SET CONFIGURATION之后配置值可能已显示为新值,但进程仍是旧值,只有重启 + 探针才能闭环。
5. 实测记录(2026-11-20,IoTDB 2.0.11)
执行方式
执行方式:Docker Compose 部署的实例,容器内 CLI(start-cli.sh)执行。
| 用例 | 执行语句 | 返回 | 验证点 |
|---|---|---|---|
| U1 | INSERT INTO root.zz_probe_db.dev1(time, s1) VALUES (now(), 1.0); |
The statement is executed successfully. |
库、设备、序列均不存在时写入成功 → 自动建库 + 自动建序列 |
| U2 | INSERT INTO root.zz_probe_db.dev1(time, s2) VALUES (now(), 1); |
同上 | 整型字面量 1 被推断为 DOUBLE |
| U3 | INSERT INTO root.zz_probe_db.dev1(time, s3) VALUES (now(), "ABC"); |
同上 | 字符串被推断为 TEXT |
自动创建的序列元数据
自动创建的序列元数据(SHOW TIMESERIES 实测):
| 序列 | Database | DataType | Encoding | Compression | ViewType |
|---|---|---|---|---|---|
root.zz_probe_db.dev1.s1 |
root.zz_probe_db |
DOUBLE |
GORILLA |
LZ4 |
BASE |
root.zz_probe_db.dev1.s2 |
root.zz_probe_db |
DOUBLE |
GORILLA |
LZ4 |
BASE |
root.zz_probe_db.dev1.s3 |
root.zz_probe_db |
TEXT |
PLAIN |
LZ4 |
BASE |
实测记录 - 情况1
实测记录:
情况1(不太倾向于这种方式作为【传感器多行模式】的数据模型 —— 不好搞 树转表的视图)
//注 | 树模式下:未提前建库、建表(timeseries)
IoTDB> INSERT INTO root.zz_probe_db.dev1(time, s1) VALUES (now(), 1.0);
Msg: The statement is executed successfully.
IoTDB> SHOW TIMESERIES root.zz_probe_db.dev1.s1;
+------------------------+-----+----------------+--------+--------+-----------+----+----------+--------+------------------+--------+
| Timeseries|Alias| Database|DataType|Encoding|Compression|Tags|Attributes|Deadband|DeadbandParameters|ViewType|
+------------------------+-----+----------------+--------+--------+-----------+----+----------+--------+------------------+--------+
|root.zz_probe_db.dev1.s1| null|root.zz_probe_db| DOUBLE| GORILLA| LZ4|null| null| null| null| BASE|
+------------------------+-----+----------------+--------+--------+-----------+----+----------+--------+------------------+--------+
Total line number = 1
It costs 0.004s
IoTDB> INSERT INTO root.zz_probe_db.dev1(time, s2) VALUES (now(), 1);
Msg: The statement is executed successfully.
IoTDB> SHOW TIMESERIES root.zz_probe_db.dev1.s2;
+------------------------+-----+----------------+--------+--------+-----------+----+----------+--------+------------------+--------+
| Timeseries|Alias| Database|DataType|Encoding|Compression|Tags|Attributes|Deadband|DeadbandParameters|ViewType|
+------------------------+-----+----------------+--------+--------+-----------+----+----------+--------+------------------+--------+
|root.zz_probe_db.dev1.s2| null|root.zz_probe_db| DOUBLE| GORILLA| LZ4|null| null| null| null| BASE|
+------------------------+-----+----------------+--------+--------+-----------+----+----------+--------+------------------+--------+
Total line number = 1
It costs 0.004s
IoTDB> INSERT INTO root.zz_probe_db.dev1(time, s3) VALUES (now(), "ABC");
Msg: The statement is executed successfully.
IoTDB> SHOW TIMESERIES root.zz_probe_db.dev1.s3;
+------------------------+-----+----------------+--------+--------+-----------+----+----------+--------+------------------+--------+
| Timeseries|Alias| Database|DataType|Encoding|Compression|Tags|Attributes|Deadband|DeadbandParameters|ViewType|
+------------------------+-----+----------------+--------+--------+-----------+----+----------+--------+------------------+--------+
|root.zz_probe_db.dev1.s3| null|root.zz_probe_db| TEXT| PLAIN| LZ4|null| null| null| null| BASE|
+------------------------+-----+----------------+--------+--------+-----------+----+----------+--------+------------------+--------+
Total line number = 1
It costs 0.004s
IoTDB> show timeseries WHERE TIMESERIES contains 'zz_';
+------------------------+-----+----------------+--------+--------+-----------+----+----------+--------+------------------+--------+
| Timeseries|Alias| Database|DataType|Encoding|Compression|Tags|Attributes|Deadband|DeadbandParameters|ViewType|
+------------------------+-----+----------------+--------+--------+-----------+----+----------+--------+------------------+--------+
|root.zz_probe_db.dev1.s3| null|root.zz_probe_db| TEXT| PLAIN| LZ4|null| null| null| null| BASE|
|root.zz_probe_db.dev1.s1| null|root.zz_probe_db| DOUBLE| GORILLA| LZ4|null| null| null| null| BASE|
|root.zz_probe_db.dev1.s2| null|root.zz_probe_db| DOUBLE| GORILLA| LZ4|null| null| null| null| BASE|
+------------------------+-----+----------------+--------+--------+-----------+----+----------+--------+------------------+--------+
Total line number = 3
It costs 0.023s
//注:和传感器多列模式(设备模板 + timeseries)做个对比:↓↓↓
IoTDB> show timeseries WHERE TIMESERIES contains 'LSGKB52HPG3N1GLDA';
+-----------------------------------------------------------------------------------+-----+----------------------------------------------------+--------+--------+-----------+----+----------+--------+------------------+--------+
| Timeseries|Alias| Database|DataType|Encoding|Compression|Tags|Attributes|Deadband|DeadbandParameters|ViewType|
+-----------------------------------------------------------------------------------+-----+----------------------------------------------------+--------+--------+-----------+----+----------+--------+------------------+--------+
|root.db_123.ods_vhr_vehicle_can_sensors_timeseries.LSGKB52HPG3N1GLDA.sensor_value| null|root.db_123.ods_vhr_vehicle_can_sensors_timeseries| DOUBLE| GORILLA| LZ4|null| null| null| null| BASE|
| root.db_123.ods_vhr_vehicle_can_sensors_timeseries.LSGKB52HPG3N1GLDA.sensor_name| null|root.db_123.ods_vhr_vehicle_can_sensors_timeseries| STRING| PLAIN| LZ4|null| null| null| null| BASE|
| root.db_123.ods_vhr_vehicle_can_signals.LSGKB52HPG3N1GLDA.total_mileage| null| root.db_123.ods_vhr_vehicle_can_signals| FLOAT| GORILLA| LZ4|null| null| null| null| BASE|
| root.db_123.ods_vhr_vehicle_can_signals.LSGKB52HPG3N1GLDA.bms_soh| null| root.db_123.ods_vhr_vehicle_can_signals| FLOAT| GORILLA| LZ4|null| null| null| null| BASE|
| root.db_123.ods_vhr_vehicle_can_signals.LSGKB52HPG3N1GLDA.remaing_oil_percent| null| root.db_123.ods_vhr_vehicle_can_signals| FLOAT| GORILLA| LZ4|null| null| null| null| BASE|
| root.db_123.ods_vhr_vehicle_can_signals.LSGKB52HPG3N1GLDA.drive_speed| null| root.db_123.ods_vhr_vehicle_can_signals| FLOAT| GORILLA| LZ4|null| null| null| null| BASE|
| root.db_123.ods_vhr_vehicle_can_signals.LSGKB52HPG3N1GLDA.bms_soc| null| root.db_123.ods_vhr_vehicle_can_signals| FLOAT| GORILLA| LZ4|null| null| null| null| BASE|
| root.db_123.ods_vhr_vehicle_can_signals.LSGKB52HPG3N1GLDA.online_status| null| root.db_123.ods_vhr_vehicle_can_signals| INT32|TS_2DIFF| LZ4|null| null| null| null| BASE|
| root.db_123.ods_vhr_vehicle_can_signals.LSGKB52HPG3N1GLDA.subtotal_mileage| null| root.db_123.ods_vhr_vehicle_can_signals| FLOAT| GORILLA| LZ4|null| null| null| null| BASE|
| root.db_123.ods_vhr_vehicle_can_signals.LSGKB52HPG3N1GLDA.skylight_status| null| root.db_123.ods_vhr_vehicle_can_signals| INT32|TS_2DIFF| LZ4|null| null| null| null| BASE|
| root.db_123.ods_vhr_vehicle_can_signals.LSGKB52HPG3N1GLDA.engine_speed| null| root.db_123.ods_vhr_vehicle_can_signals| FLOAT| GORILLA| LZ4|null| null| null| null| BASE|
+-----------------------------------------------------------------------------------+-----+----------------------------------------------------+--------+--------+-----------+----+----------+--------+------------------+--------+
Total line number = 21
It costs 0.009s
实测记录 - 情况2(推荐)
情况2(倾向于这种方式作为【传感器多行模式】的数据模型 —— 方便搞 树转表的视图)
INSERT INTO root.probe_db2.ods_vehicle_can_conditions.device01.sensor1(time, value) VALUES (now(), 1.0);
INSERT INTO root.probe_db2.ods_vehicle_can_conditions.device01.sensor2(time, value) VALUES (now(), 2);
INSERT INTO root.probe_db2.ods_vehicle_can_conditions.device01.sensor3(time, value) VALUES (now(), "ABC");
IoTDB> SHOW TIMESERIES root.probe_db2.ods_vehicle_can_conditions.device01.sensor1.value;
+----------------------------------------------------------------+-----+--------------+--------+--------+-----------+----+----------+--------+------------------+--------+
| Timeseries|Alias| Database|DataType|Encoding|Compression|Tags|Attributes|Deadband|DeadbandParameters|ViewType|
+----------------------------------------------------------------+-----+--------------+--------+--------+-----------+----+----------+--------+------------------+--------+
|root.probe_db2.ods_vehicle_can_conditions.device01.sensor1.value| null|root.probe_db2| DOUBLE| GORILLA| LZ4|null| null| null| null| BASE|
+----------------------------------------------------------------+-----+--------------+--------+--------+-----------+----+----------+--------+------------------+--------+
Total line number = 1
It costs 0.003s
IoTDB> SHOW TIMESERIES root.probe_db2.ods_vehicle_can_conditions.device01.sensor2.value;
+----------------------------------------------------------------+-----+--------------+--------+--------+-----------+----+----------+--------+------------------+--------+
| Timeseries|Alias| Database|DataType|Encoding|Compression|Tags|Attributes|Deadband|DeadbandParameters|ViewType|
+----------------------------------------------------------------+-----+--------------+--------+--------+-----------+----+----------+--------+------------------+--------+
|root.probe_db2.ods_vehicle_can_conditions.device01.sensor2.value| null|root.probe_db2| DOUBLE| GORILLA| LZ4|null| null| null| null| BASE|
+----------------------------------------------------------------+-----+--------------+--------+--------+-----------+----+----------+--------+------------------+--------+
Total line number = 1
It costs 0.003s
IoTDB> SHOW TIMESERIES root.probe_db2.ods_vehicle_can_conditions.device01.sensor3.value;
+----------------------------------------------------------------+-----+--------------+--------+--------+-----------+----+----------+--------+------------------+--------+
| Timeseries|Alias| Database|DataType|Encoding|Compression|Tags|Attributes|Deadband|DeadbandParameters|ViewType|
+----------------------------------------------------------------+-----+--------------+--------+--------+-----------+----+----------+--------+------------------+--------+
|root.probe_db2.ods_vehicle_can_conditions.device01.sensor3.value| null|root.probe_db2| TEXT| PLAIN| LZ4|null| null| null| null| BASE|
+----------------------------------------------------------------+-----+--------------+--------+--------+-----------+----+----------+--------+------------------+--------+
Total line number = 1
It costs 0.004s
IoTDB> show timeseries WHERE TIMESERIES contains 'probe';
+----------------------------------------------------------------+-----+----------------+--------+--------+-----------+----+----------+--------+------------------+--------+
| Timeseries|Alias| Database|DataType|Encoding|Compression|Tags|Attributes|Deadband|DeadbandParameters|ViewType|
+----------------------------------------------------------------+-----+----------------+--------+--------+-----------+----+----------+--------+------------------+--------+
|root.probe_db2.ods_vehicle_can_conditions.device01.sensor2.value| null| root.probe_db2| DOUBLE| GORILLA| LZ4|null| null| null| null| BASE|
|root.probe_db2.ods_vehicle_can_conditions.device01.sensor3.value| null| root.probe_db2| TEXT| PLAIN| LZ4|null| null| null| null| BASE|
|root.probe_db2.ods_vehicle_can_conditions.device01.sensor1.value| null| root.probe_db2| DOUBLE| GORILLA| LZ4|null| null| null| null| BASE|
+----------------------------------------------------------------+-----+----------------+--------+--------+-----------+----+----------+--------+------------------+--------+
Total line number = 7
It costs 0.018s
-- 删除(Schema + 数据): DELETE TIMESERIES root.probe_db2.**;
//树模型 转 表模型下的视图:
SET SQL_DIALECT=TABLE;
CREATE DATABASE viewdb_probe_db2;
CREATE OR REPLACE VIEW viewdb_probe_db2.ods_vehicle_can_conditions ( //即使目前还不存在 root.probe_db2.ods_vehicle_can_conditions.** ,也支持创建,只是查询此表时会没有数据(不会报错);等后面树模型 root.probe_db2.ods_vehicle_can_conditions.** 创建了schema、或insert 有数据了,自然就会查出数据
vin STRING TAG,
sensor_name STRING TAG,
value Double FIELD
)
AS root.probe_db2.ods_vehicle_can_conditions.**;
select * from viewdb_probe_db2.ods_vehicle_can_conditions where vin = 'device01';
IoTDB> select * from viewdb_probe_db2.ods_vehicle_can_conditions where vin = 'device01';;
+-----------------------------+--------+-----------+-----+
| time| vin|sensor_name|value|
+-----------------------------+--------+-----------+-----+
|2026-11-20T15:12:18.495+08:00|device01| sensor1| 1.0|
|2026-11-20T15:12:21.223+08:00|device01| sensor2| 2.0|
+-----------------------------+--------+-----------+-----+
Total line number = 2
It costs 0.015s
IoTDB> select * from viewdb_probe_db2.ods_vehicle_can_conditions where vin = 'device01';
+-----------------------------+--------+-----------+-----+
| time| vin|sensor_name|value|
+-----------------------------+--------+-----------+-----+
|2026-11-20T15:12:18.495+08:00|device01| sensor1| 1.0|
|2026-11-20T15:12:21.223+08:00|device01| sensor2| 2.0|
+-----------------------------+--------+-----------+-----+
Total line number = 2
It costs 0.012s
- 换言之,【树转表视图】的动态性已验证,可行。
树模式的空子树(一条序列都还没有)能否先建视图? 能 → 建树模型的timeseries表时、或甚至还没有创建,就支持创建表模型的树转表视图、乃至查询数据(只是查不出任何数据);
树模式在新增TimeSeries后,表模式的视图是否立即可见?这是 树模式的**的语义问题,实际写入后查询确认(确认OK、立即可见)。
实测结论
实测结论:
enable_auto_create_schema在 2.0.11 默认环境确实生效,行为侧无疑义;default_storage_group_level=1生效,root.zz_probe_db被作为 database 自动创建;- 类型推断符合默认配置:浮点 →
DOUBLE、整型 →DOUBLE、文本 →TEXT; - 自动创建序列的编码/压缩为
GORILLA/PLAIN+LZ4(实测值,可能与预建序列的显式声明不同); - 实测环境中
SHOW CONFIGURATION结果中未出现该项,与"默认只列显式配置项"的语义一致。
6. 未启用时如何配置启用
6.1 修改配置文件(单机 / 无 SQL 通道)
- 打开
conf/iotdb-system.properties; - 已有则改为
enable_auto_create_schema=true;没有则新增一行(可从iotdb-system.properties.template对应段落复制);
enable_auto_create_schema=false
- 每台 ConfigNode、每台 DataNode 均需修改、且保持一致(公共配置不一致会出现"部分写入成功、部分报错");
- 重启(顺序:先 DataNode,后 ConfigNode;启动反序)。
6.2 通过 SQL 修改(集群首选)
SET CONFIGURATION 'enable_auto_create_schema' = 'true';
-- 指定节点:
SET CONFIGURATION 'enable_auto_create_schema' = 'true' ON 1;
-- 恢复默认值:
SET CONFIGURATION 'enable_auto_create_schema' = DEFAULT;
- 对所有节点永久生效,并写回各节点的
iotdb-system.properties,避免手改造成不一致; - 该参数为
restart级,落盘后仍需重启才真正生效; - 若返回
ignored config items: [...],说明被当作不可改项拒绝,退回 6.1。
6.3 Docker Compose 场景(三种方式与持久性)
| 方式 | 操作 | 持久性 | 适用 |
|---|---|---|---|
A. compose environment |
- enable_auto_create_schema=true 加入 environment,docker compose up -d 重建容器 |
随 compose 文件持久 | 官方 compose 未挂载 /iotdb/conf 时的首选 |
| B. 挂载 conf 后改文件 | docker cp iotdb:/iotdb/conf ./iotdb/conf → volumes 加 - ./iotdb/conf:/iotdb/conf → 改宿主机文件 → up -d |
随宿主机文件持久 | 官方文档 3.7 节做法,确定性强 |
C. SET CONFIGURATION |
容器内 CLI 执行 | 写容器内文件,down/重建即丢 |
临时验证、集群统一 |
# 验证 env 是否被入口脚本写入配置
docker exec iotdb sh -c "grep -n 'enable_auto_create_schema' /iotdb/conf/iotdb-system.properties"
# 改 env 必须重建容器,restart 不生效
docker compose -f docker-compose-standalone.yml up -d
6.4 修改后复验(四步闭环)
SHOW ALL CONFIGURATION ON <nodeId> WITH DESC→ 确认value为期望值;(表模式下)
SHOW CLUSTER DETAILS;可知悉 nodeId (表模式 or 树模式下)
- 重启相应服务;
- 再次
SHOW ALL CONFIGURATION→ 确认未回退; (表模式下) - 行为探针 → 确认写入行为符合预期。
7. 边界与风险
| 编号 | 风险 | 说明 | 应对 |
|---|---|---|---|
| R1 | 首写决定类型,且不可回改 | 序列类型由首个写入值推断,后续写入需兼容该类型 | 关键测点预建序列;或统一写入值类型 |
| R2 | 整型被推成 DOUBLE | integer_string_infer_type 默认 DOUBLE,业务上要求 INT32/BIGINT 的测点会类型不符 |
预建序列,或将该配置项改为 INT32/INT64(热加载) |
| R3 | 编码/压缩与预建不一致 | 自动创建走默认编码压缩(实测 GORILLA/PLAIN + LZ4),混写场景下与预建序列不一致,影响压缩率与查询特征 |
以压测数据决定是否统一预建 |
| R4 | 自动建库的层数约束 | 依赖 default_storage_group_level(默认 1);路径短于该层数时创建/写入失败 |
写入路径必须包含足够的层级 |
| R5 | 关闭后是"报错"而非"丢弃" | 未预建序列的首次写入直接失败,SeaTunnel 任务整体失败 | 上线检查清单中固化该校验;变更前先做探针 |
| R6 | 元数据膨胀 | 高基数设备 + 动态测点会持续新增序列,元数据与内存压力上升 | 规划 device 粒度与测点上限,评估 cluster_device_limit_threshold |
| R7 | 与表模型混淆 | 表模型下 INSERT 语句不会自动建表,自动建表只发生在 Session 写入路径 |
表模型探针必须用 ITableSession |
| R8 | Docker 重建丢失配置 | 未挂载 conf 时,容器内改动随 down/重建失效 |
用 compose environment 或挂载 conf |
8. 工程结论与适用边界
结论:在 2.0.11 上,「不预建序列、依赖首写自动创建」的路径成立,"预建条数 = V×S"只适用于 S ≤ 约 50 且设备规模可控的场景;S 到数百/数千时必须依赖自动创建。
结论表述:
enable_auto_create_schema在 2.0.11 中默认true且实测生效(SHOW ALL CONFIGURATION中value=null、default_value=true,effectiveMode=restart)。写入root.<db>.<dev>.<s>会自动创建 database(default_storage_group_level=1)、device 与 timeseries,并按首写值推断类型(浮点/整型 →DOUBLE,文本 →TEXT)。因此"不预建序列"方案成立,但首写类型即最终类型,关键测点仍需预建以保证类型与编码可控。
上线检查清单:
SHOW ALL CONFIGURATION ON <DataNodeId>确认enable_auto_create_schema非false;- 重启后以 Session 首写探针确认实际生效(不用 SQL
INSERT测表模型); - 关键测点清单化预建,覆盖需要 INT32/INT64 或指定编码的场景;
- SeaTunnel 任务首跑使用影子库,确认自动建序列无报错;
- Docker 部署确认配置来源(env / 挂载文件 / SQL),避免重建失配。
9. 未闭环事项
| 编号 | 事项 | 建议验证方式 |
|---|---|---|
| O1 | SHOW ALL CONFIGURATION ON 1 是否列出 enable_auto_create_schema 行 |
在实测环境执行并记录输出 |
| O2 | compose environment 是否被镜像入口脚本写入 iotdb-system.properties |
重建容器后 grep 配置文件 |
| O3 | 自动创建序列的编码压缩是否随 default_*_encoding 热加载改变 |
改配置后新建序列对比 SHOW TIMESERIES |
| O4 | 关闭该参数后的具体错误码与提示文案 | 影子环境置 false 后跑一次首写探针 |
Z 附件/附录
A. 常用命令清单
-- 集群与节点
SHOW CLUSTER DETAILS;
-- 配置查询
SHOW CONFIGURATION ON 1 WITH DESC;
SHOW ALL CONFIGURATION ON 1 WITH DESC;
-- 配置修改(restart 级,需重启)
SET CONFIGURATION 'enable_auto_create_schema' = 'true';
-- 行为探针
INSERT INTO root.zz_probe_db.dev1(time, s1) VALUES (now(), 1.0);
SHOW TIMESERIES root.zz_probe_db.dev1.s1;
DELETE DATABASE root.zz_probe_db;
# Docker 场景
docker compose -f docker-compose-standalone.yml ps
docker compose -f docker-compose-standalone.yml config | grep -n -A8 "environment:"
docker inspect iotdb --format '{{range .Config.Env}}{{println .}}{{end}}'
docker inspect iotdb --format '{{range .Mounts}}{{println .Source " -> " .Destination}}{{end}}'
docker exec iotdb sh -c "grep -n 'enable_auto_create_schema' /iotdb/conf/iotdb-system.properties"
docker exec -it iotdb /bin/bash
cd /iotdb && ./sbin/start-cli.sh -h 127.0.0.1 -p 6667 -u root -pw root
B. 参考文档
| 主题 | 链接 |
|---|---|
配置参数(enable_auto_create_schema 默认 true、restart) |
https://iotdb.apache.org/zh/UserGuide/latest-Table/Reference/System-Config-Manual_apache.html |
运维语句(SHOW CONFIGURATION 语法、2.0.10 起支持) |
https://iotdb.apache.org/zh/UserGuide/latest-Table/User-Manual/Maintenance-statement_apache.html |
配置项修改(SET CONFIGURATION / LOAD CONFIGURATION) |
https://www.timecho.com/docs/zh/UserGuide/latest/Reference/Modify-Config-Manual.html |
| Docker 部署(conf 映射、部署形态) | https://iotdb.apache.org/zh/UserGuide/latest/Deployment-and-Maintenance/Docker-Deployment_apache.html |
表模型写入(INSERT 不自动建表) |
https://iotdb.apache.org/UserGuide/latest-Table/Basic-Concept/Write-Updata-Data.html |
C. 版本与文件名矩阵
| 版本 | 公共配置文件 | SHOW CONFIGURATION |
|---|---|---|
| 2.0.10 及以上(含 2.0.11) | conf/iotdb-system.properties |
支持 |
| 1.x | conf/iotdb-common.properties |
不支持(无该语句) |
| 0.13.x | conf/iotdb-engine.properties |
不支持(无该语句) |
D. 自动创建Schema的核心源码 (Apache IoTDB 2.0.11)
提示:GitHub 上该版本的 tag 是
v2.0.11,直接按2.0.11访问会返回 404;若要直接拉取裸文件,把github.com/apache/iotdb/blob/换成raw.githubusercontent.com/apache/iotdb/,并去掉#L锚点即可。
配置定义(模版)
- 模版中的定义位置(第 1017 行,
Configurations for creating schema automatically段)
- 发行版随附的精简配置文件(只有 72 行,不含这一项)
核心源码
- 配置字段与普通操作:
IoTDBConfig.java:644(字段)、:2415、:2419(isAutoCreateSchemaEnabled、setAutoCreateSchemaEnabled)
- 配置加载与热加载:
IoTDBDescriptor.java:1873中的loadAutoCreateSchemaProps;启动时在:759调用,热加载时在:2183调用
- 读取默认值的机制(读取 template):
ConfigurationFileUtils.java:262
实际生效点
- 树模型写入:
ClusterSchemaFetcher.java:329
- 表模型建表或加列:
TableHeaderSchemaValidator.java:133(另见:273、:370、:502)
- 关闭后的报错文案:
AnalyzeUtils.java:377
E. 修改 default_database_level 配置项(建议实施)
此步骤不实施的风险,当你在 iotdb 中基于 root.xxxx_db 的路径下创建其他 timeseries 时可能无法创建成功的阻塞风险。
- 配置 | 方式1 docker-compose-apache-iotdb.yml 中配置/新增 datanode 的 environment 变量
配置 compose 文件
...
services:
iotdb-datanode:
image: apache/iotdb:2.0.11-datanode
environment:
# 树模式下,自动创建 Time Series Schema 时,基于 Storage Path识别Database的Level
- default_database_level=2
...
然后重启:
docker compose -f docker-compose-apache-iotdb.yml up -d --force-recreate
# 或 docker compose -f docker-compose-apache-iotdb.yml up -d --force-recreate iotdb-datanode
验证:
# docker exec iotdb-datanode sh -c "grep -n 'default_database_level' /iotdb/conf/iotdb-system.properties"
74:default_database_level=2
- 方式2 走 SQL 热加载,建议带上节点号,避免广播到 ConfigNode 被当作不可改项:
SHOW CLUSTER DETAILS; -- 取 DataNode 的 NodeID
SET CONFIGURATION 'default_database_level' = '2' ON <DataNodeId>;
Y 推荐文献
- Apache IotDB
- [时序数据/IoTDB/SeaTunnel] 基于 Apache SeaTunnel 实现MySQL时序数据同步并写入 Apache IotDB 数据库(加列方式) - 博客园/千千寰宇
- [TSDB/Docker] Apache loTDB之安装部署篇(Docker Compose版) - 博客园/千千寰宇
X 参考文献
本文链接: https://www.cnblogs.com/johnnyzen
关于博文:评论和私信会在第一时间回复,或直接私信我。
版权声明:本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!
日常交流:大数据与软件开发-QQ交流群: 774386015 【入群二维码】参见左下角。您的支持、鼓励是博主技术写作的重要动力!

浙公网安备 33010602011771号