[技术调研/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 的预建成本不可接受;
  • 因此需要依赖「首次写入即自动创建序列」。

需要闭环回答的问题:

  1. enable_auto_create_schema 参数是否存在、默认值是什么?
  2. 该参数在 2.0.11 中当前是否真的生效(而非仅停留在配置文件)?
  3. 除 timeseries 外,database 是否也会自动创建、按哪一层切分?
  4. 自动创建出来的 timeseries,数据类型/编码/压缩由什么决定?
  5. 若被关闭,写入行为是"失败"还是"静默丢弃"?
  6. Docker Compose 部署下如何查询、如何配置、如何保证不随容器重建丢失?

3. 机制说明

3.1 写入时的判定顺序

flowchart TD A["INSERT INTO root.db.dev.s(...)"] --> B{"序列已存在?"} B -- 是 --> H["直接写入成功"] B -- 否 --> C{"enable_auto_create_schema = true?"} C -- false --> G["写入失败: 序列/库不存在"] C -- true --> D{"database 已存在?"} D -- 否 --> E["按 default_storage_group_level 自动建库"] --> F D -- 是 --> F["按首写值推断类型, 自动建序列"] --> I["写入成功"] linkStyle default stroke:#4a4a4a,stroke-width:1.2px

要点:关闭自动创建时,写入是直接报错,不是丢弃数据。这也是关闭该参数后 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)。

语义要点:

  1. 不带 ALL 时,只返回「配置文件中已配置的项」——这正是 enable_auto_create_schema 默认查不到的原因;
  2. 带 ALL 时返回所有配置项,未配置项的 value 为 null;
  3. 带 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、立即可见)。

实测结论

实测结论:

  1. enable_auto_create_schema 在 2.0.11 默认环境确实生效,行为侧无疑义;
  2. default_storage_group_level=1 生效,root.zz_probe_db 被作为 database 自动创建;
  3. 类型推断符合默认配置:浮点 → DOUBLE、整型 → DOUBLE、文本 → TEXT;
  4. 自动创建序列的编码/压缩为 GORILLA / PLAIN + LZ4(实测值,可能与预建序列的显式声明不同);
  5. 实测环境中 SHOW CONFIGURATION 结果中未出现该项,与"默认只列显式配置项"的语义一致。

6. 未启用时如何配置启用

6.1 修改配置文件(单机 / 无 SQL 通道)

  1. 打开 conf/iotdb-system.properties;
  2. 已有则改为 enable_auto_create_schema=true;没有则新增一行(可从 iotdb-system.properties.template 对应段落复制);

enable_auto_create_schema=false

  1. 每台 ConfigNode、每台 DataNode 均需修改、且保持一致(公共配置不一致会出现"部分写入成功、部分报错");
  2. 重启(顺序:先 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 修改后复验(四步闭环)

  1. SHOW ALL CONFIGURATION ON <nodeId> WITH DESC → 确认 value 为期望值;(表模式下)

SHOW CLUSTER DETAILS; 可知悉 nodeId (表模式 or 树模式下)

  1. 重启相应服务;
  2. 再次 SHOW ALL CONFIGURATION → 确认未回退; (表模式下)
  3. 行为探针 → 确认写入行为符合预期。

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)。因此"不预建序列"方案成立,但首写类型即最终类型,关键测点仍需预建以保证类型与编码可控。

上线检查清单:

  1. SHOW ALL CONFIGURATION ON <DataNodeId> 确认 enable_auto_create_schema 非 false;
  2. 重启后以 Session 首写探针确认实际生效(不用 SQL INSERT 测表模型);
  3. 关键测点清单化预建,覆盖需要 INT32/INT64 或指定编码的场景;
  4. SeaTunnel 任务首跑使用影子库,确认自动建序列无报错;
  5. 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 段)

https://github.com/apache/iotdb/blob/v2.0.11/iotdb-core/node-commons/src/assembly/resources/conf/iotdb-system.properties.template#L1017

  • 发行版随附的精简配置文件(只有 72 行,不含这一项)

https://github.com/apache/iotdb/blob/v2.0.11/iotdb-core/node-commons/src/assembly/resources/conf/iotdb-system.properties

核心源码

  • 配置字段与普通操作:IoTDBConfig.java:644(字段)、:2415、:2419(isAutoCreateSchemaEnabled、setAutoCreateSchemaEnabled)

https://github.com/apache/iotdb/blob/v2.0.11/iotdb-core/datanode/src/main/java/org/apache/iotdb/db/conf/IoTDBConfig.java#L644

  • 配置加载与热加载:IoTDBDescriptor.java:1873 中的 loadAutoCreateSchemaProps;启动时在 :759 调用,热加载时在 :2183 调用

https://github.com/apache/iotdb/blob/v2.0.11/iotdb-core/datanode/src/main/java/org/apache/iotdb/db/conf/IoTDBDescriptor.java#L1873

  • 读取默认值的机制(读取 template):ConfigurationFileUtils.java:262

https://github.com/apache/iotdb/blob/v2.0.11/iotdb-core/node-commons/src/main/java/org/apache/iotdb/commons/conf/ConfigurationFileUtils.java#L262

实际生效点

  • 树模型写入:ClusterSchemaFetcher.java:329

https://github.com/apache/iotdb/blob/v2.0.11/iotdb-core/datanode/src/main/java/org/apache/iotdb/db/queryengine/plan/analyze/schema/ClusterSchemaFetcher.java#L329

  • 表模型建表或加列:TableHeaderSchemaValidator.java:133(另见 :273、:370、:502)

https://github.com/apache/iotdb/blob/v2.0.11/iotdb-core/datanode/src/main/java/org/apache/iotdb/db/queryengine/plan/relational/metadata/fetcher/TableHeaderSchemaValidator.java#L133

  • 关闭后的报错文案:AnalyzeUtils.java:377

https://github.com/apache/iotdb/blob/v2.0.11/iotdb-core/datanode/src/main/java/org/apache/iotdb/db/queryengine/plan/analyze/AnalyzeUtils.java#L377

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

X 参考文献

posted @ 2026-11-20 14:43  千千寰宇  阅读(4)  评论(0)    收藏  举报