This is an automated email from the ASF dual-hosted git repository.
HTHou pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iotdb-docs.git
The following commit(s) were added to refs/heads/main by this push:
new b9fa3777 add debug sql in maintenance from 2091 (#1087)
b9fa3777 is described below
commit b9fa377709fbb11026d1ba8ada26108410fc6be6
Author: leto-b <[email protected]>
AuthorDate: Wed Apr 22 12:08:21 2026 +0800
add debug sql in maintenance from 2091 (#1087)
---
.../User-Manual/Maintenance-commands_apache.md | 44 ++++++++++++++++++-
.../User-Manual/Maintenance-commands_timecho.md | 44 ++++++++++++++++++-
.../User-Manual/Maintenance-commands_apache.md | 40 ++++++++++++++++-
.../User-Manual/Maintenance-commands_timecho.md | 40 ++++++++++++++++-
.../User-Manual/Maintenance-commands_apache.md | 44 ++++++++++++++++++-
.../User-Manual/Maintenance-commands_timecho.md | 44 ++++++++++++++++++-
.../User-Manual/Maintenance-commands_apache.md | 40 ++++++++++++++++-
.../User-Manual/Maintenance-commands_timecho.md | 40 ++++++++++++++++-
.../User-Manual/Maintenance-statement_apache.md | 50 +++++++++++++++++++++-
.../User-Manual/Maintenance-statement_timecho.md | 50 +++++++++++++++++++++-
.../User-Manual/Maintenance-statement_apache.md | 46 +++++++++++++++++++-
.../User-Manual/Maintenance-statement_timecho.md | 45 +++++++++++++++++++
.../User-Manual/Maintenance-statement_apache.md | 50 +++++++++++++++++++++-
.../User-Manual/Maintenance-statement_timecho.md | 50 +++++++++++++++++++++-
.../User-Manual/Maintenance-statement_apache.md | 46 +++++++++++++++++++-
.../User-Manual/Maintenance-statement_timecho.md | 45 +++++++++++++++++++
16 files changed, 704 insertions(+), 14 deletions(-)
diff --git
a/src/UserGuide/Master/Table/User-Manual/Maintenance-commands_apache.md
b/src/UserGuide/Master/Table/User-Manual/Maintenance-commands_apache.md
index 481665f4..b6094310 100644
--- a/src/UserGuide/Master/Table/User-Manual/Maintenance-commands_apache.md
+++ b/src/UserGuide/Master/Table/User-Manual/Maintenance-commands_apache.md
@@ -853,4 +853,46 @@ Terminate all queries:
```SQL
IoTDB> KILL ALL QUERIES;
-```
\ No newline at end of file
+```
+
+## 6. Query Debugging
+### 6.1 DEBUG SQL
+
+**Definition**: Add the `DEBUG` keyword at the beginning of an SQL query
statement. During execution, debug logs will be output, including the
underlying file scan information involved in the query.
+
+> Supported since V2.0.9-beta
+
+#### Syntax:
+```sql
+debugSQLStatement
+ : DEBUG ? query
+ ;
+```
+
+**Description**:
+* Log output path: `logs/log_datanode_query_debug.log`
+
+#### Example:
+1. Execute the following SQL for DEBUG query
+```sql
+DEBUG SELECT * FROM table3;
+```
+
+2. Check the log content in `log_datanode_query_debug.log` to view the file
scan information involved in the query.
+
+```bash
+2026-03-24 10:10:41,515 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.t.TsFileResource:1098 - Path: table3.d1 file
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2864/1769139940009-1-0-0.tsfile
is not satisfied because of no device!
+2026-03-24 10:10:41,515 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.t.TsFileResource:1098 - Path: table3.d1 file
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2865/1769139940010-1-0-0.tsfile
is not satisfied because of no device!
+2026-03-24 10:10:41,516 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:159 - Cache miss: table3.d1. in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,516 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:160 - Device: table3.d1, all sensors:
[, temperature]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.BloomFilterCache:110 - get bloomFilter from cache where
filePath is:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries: table3.d1.
metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=-128,
chunkMetaDataListDataSize=8, measurementId='', dataType=VECTOR,
statistics=startTime: 1747065600001 endTime: 1747065601002 count: 2,
modified=false, isSeq=true, chun [...]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries:
table3.d1.temperature metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=64,
chunkMetaDataListDataSize=8, measurementId='temperature', dataType=FLOAT,
statistics=startTime: 1747065600001 endTime: 1747065601002 count: 2
[minValue:85.0 [...]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:110 - Modifications
size is 1 for file Path:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:114 - []
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:125 - After
modification Chunk meta data list is:
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:126 -
org.apache.tsfile.file.metadata.TableDeviceChunkMetadata@2e11291f
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile',
regionId=4, timePartitionId=2888, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=19}
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile',
regionId=4, timePartitionId=2888, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=46}
+2026-03-24 10:10:41,519
[pool-69-IoTDB-ClientRPC-Processor-1$20260324_021041_00068_1] INFO
o.a.i.d.q.p.Coordinator:902 - debug select * from table3
+```
diff --git
a/src/UserGuide/Master/Table/User-Manual/Maintenance-commands_timecho.md
b/src/UserGuide/Master/Table/User-Manual/Maintenance-commands_timecho.md
index 30d26acc..e82d0885 100644
--- a/src/UserGuide/Master/Table/User-Manual/Maintenance-commands_timecho.md
+++ b/src/UserGuide/Master/Table/User-Manual/Maintenance-commands_timecho.md
@@ -854,4 +854,46 @@ Terminate all queries:
```SQL
IoTDB> KILL ALL QUERIES;
-```
\ No newline at end of file
+```
+
+## 6. Query Debugging
+### 6.1 DEBUG SQL
+
+**Definition**: Add the `DEBUG` keyword at the beginning of an SQL query
statement. During execution, debug logs will be output, including the
underlying file scan information involved in the query.
+
+> Supported since V2.0.9
+
+#### Syntax:
+```sql
+debugSQLStatement
+ : DEBUG ? query
+ ;
+```
+
+**Description**:
+* Log output path: `logs/log_datanode_query_debug.log`
+
+#### Example:
+1. Execute the following SQL for DEBUG query
+```sql
+DEBUG SELECT * FROM table3;
+```
+
+2. Check the log content in `log_datanode_query_debug.log` to view the file
scan information involved in the query.
+
+```bash
+2026-03-24 10:10:41,515 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.t.TsFileResource:1098 - Path: table3.d1 file
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2864/1769139940009-1-0-0.tsfile
is not satisfied because of no device!
+2026-03-24 10:10:41,515 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.t.TsFileResource:1098 - Path: table3.d1 file
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2865/1769139940010-1-0-0.tsfile
is not satisfied because of no device!
+2026-03-24 10:10:41,516 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:159 - Cache miss: table3.d1. in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,516 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:160 - Device: table3.d1, all sensors:
[, temperature]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.BloomFilterCache:110 - get bloomFilter from cache where
filePath is:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries: table3.d1.
metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=-128,
chunkMetaDataListDataSize=8, measurementId='', dataType=VECTOR,
statistics=startTime: 1747065600001 endTime: 1747065601002 count: 2,
modified=false, isSeq=true, chun [...]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries:
table3.d1.temperature metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=64,
chunkMetaDataListDataSize=8, measurementId='temperature', dataType=FLOAT,
statistics=startTime: 1747065600001 endTime: 1747065601002 count: 2
[minValue:85.0 [...]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:110 - Modifications
size is 1 for file Path:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:114 - []
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:125 - After
modification Chunk meta data list is:
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:126 -
org.apache.tsfile.file.metadata.TableDeviceChunkMetadata@2e11291f
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile',
regionId=4, timePartitionId=2888, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=19}
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile',
regionId=4, timePartitionId=2888, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=46}
+2026-03-24 10:10:41,519
[pool-69-IoTDB-ClientRPC-Processor-1$20260324_021041_00068_1] INFO
o.a.i.d.q.p.Coordinator:902 - debug select * from table3
+```
diff --git
a/src/UserGuide/Master/Tree/User-Manual/Maintenance-commands_apache.md
b/src/UserGuide/Master/Tree/User-Manual/Maintenance-commands_apache.md
index 55f14c68..c3ba550b 100644
--- a/src/UserGuide/Master/Tree/User-Manual/Maintenance-commands_apache.md
+++ b/src/UserGuide/Master/Tree/User-Manual/Maintenance-commands_apache.md
@@ -619,4 +619,42 @@ Terminate all queries:
```SQL
IoTDB> KILL ALL QUERIES;
-```
\ No newline at end of file
+```
+
+## 6. Query Debugging
+
+### 6.1 DEBUG SQL
+
+**Definition**: Add the `DEBUG` keyword at the beginning of an SQL query
statement. During execution, debug logs will be output, including underlying
file scan information involved in the query.
+
+> Supported since V2.0.9-beta
+
+#### Syntax:
+```sql
+debugSQLStatement
+ : DEBUG ? query
+ ;
+```
+
+**Description**:
+* Log output directory: `logs/log_datanode_query_debug.log`
+
+#### Example:
+1. Execute the following SQL for a DEBUG query
+```sql
+DEBUG SELECT * FROM root.ln.**;
+```
+
+2. Check the log content in `log_datanode_query_debug.log` to view the file
scan information involved in the query.
+
+```bash
+2026-03-24 10:06:18,755 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:159 - Cache miss:
root.ln.wf01.wt01.temperature in file:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,757 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:160 - Device: root.ln.wf01.wt01, all
sensors: [temperature]
+2026-03-24 10:06:18,758 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.BloomFilterCache:110 - get bloomFilter from cache where
filePath is:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries:
root.ln.wf01.wt01.temperature metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=0,
chunkMetaDataListDataSize=8, measurementId='temperature', dataType=DOUBLE,
statistics=startTime: 1773824951259 endTime: 1773824951259 count: 1 [minValue
[...]
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:97 - Modifications size is 0
for file Path:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:109 - After modification
Chunk meta data list is:
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:110 - measurementId:
temperature, datatype: DOUBLE, version: 0, Statistics: startTime: 1773824951259
endTime: 1773824951259 count: 1
[minValue:12.9,maxValue:12.9,firstValue:12.9,lastValue:12.9,sumValue:12.9],
deleteIntervalList: null
+2026-03-24 10:06:18,760 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile',
regionId=13, timePartitionId=2932, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=27}
+2026-03-24 10:06:18,761
[pool-69-IoTDB-ClientRPC-Processor-1$20260324_020618_00052_1] INFO
o.a.i.d.q.p.Coordinator:902 - debug select * from root.ln.**
+```
diff --git
a/src/UserGuide/Master/Tree/User-Manual/Maintenance-commands_timecho.md
b/src/UserGuide/Master/Tree/User-Manual/Maintenance-commands_timecho.md
index b19c029d..268ff96c 100644
--- a/src/UserGuide/Master/Tree/User-Manual/Maintenance-commands_timecho.md
+++ b/src/UserGuide/Master/Tree/User-Manual/Maintenance-commands_timecho.md
@@ -618,4 +618,42 @@ Terminate all queries:
```SQL
IoTDB> KILL ALL QUERIES;
-```
\ No newline at end of file
+```
+
+## 6. Query Debugging
+
+### 6.1 DEBUG SQL
+
+**Definition**: Add the `DEBUG` keyword at the beginning of an SQL query
statement. During execution, debug logs will be output, including underlying
file scan information involved in the query.
+
+> Supported since V2.0.9
+
+#### Syntax:
+```sql
+debugSQLStatement
+ : DEBUG ? query
+ ;
+```
+
+**Description**:
+* Log output directory: `logs/log_datanode_query_debug.log`
+
+#### Example:
+1. Execute the following SQL for a DEBUG query
+```sql
+DEBUG SELECT * FROM root.ln.**;
+```
+
+2. Check the log content in `log_datanode_query_debug.log` to view the file
scan information involved in the query.
+
+```bash
+2026-03-24 10:06:18,755 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:159 - Cache miss:
root.ln.wf01.wt01.temperature in file:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,757 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:160 - Device: root.ln.wf01.wt01, all
sensors: [temperature]
+2026-03-24 10:06:18,758 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.BloomFilterCache:110 - get bloomFilter from cache where
filePath is:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries:
root.ln.wf01.wt01.temperature metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=0,
chunkMetaDataListDataSize=8, measurementId='temperature', dataType=DOUBLE,
statistics=startTime: 1773824951259 endTime: 1773824951259 count: 1 [minValue
[...]
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:97 - Modifications size is 0
for file Path:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:109 - After modification
Chunk meta data list is:
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:110 - measurementId:
temperature, datatype: DOUBLE, version: 0, Statistics: startTime: 1773824951259
endTime: 1773824951259 count: 1
[minValue:12.9,maxValue:12.9,firstValue:12.9,lastValue:12.9,sumValue:12.9],
deleteIntervalList: null
+2026-03-24 10:06:18,760 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile',
regionId=13, timePartitionId=2932, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=27}
+2026-03-24 10:06:18,761
[pool-69-IoTDB-ClientRPC-Processor-1$20260324_020618_00052_1] INFO
o.a.i.d.q.p.Coordinator:902 - debug select * from root.ln.**
+```
diff --git
a/src/UserGuide/latest-Table/User-Manual/Maintenance-commands_apache.md
b/src/UserGuide/latest-Table/User-Manual/Maintenance-commands_apache.md
index 481665f4..b6094310 100644
--- a/src/UserGuide/latest-Table/User-Manual/Maintenance-commands_apache.md
+++ b/src/UserGuide/latest-Table/User-Manual/Maintenance-commands_apache.md
@@ -853,4 +853,46 @@ Terminate all queries:
```SQL
IoTDB> KILL ALL QUERIES;
-```
\ No newline at end of file
+```
+
+## 6. Query Debugging
+### 6.1 DEBUG SQL
+
+**Definition**: Add the `DEBUG` keyword at the beginning of an SQL query
statement. During execution, debug logs will be output, including the
underlying file scan information involved in the query.
+
+> Supported since V2.0.9-beta
+
+#### Syntax:
+```sql
+debugSQLStatement
+ : DEBUG ? query
+ ;
+```
+
+**Description**:
+* Log output path: `logs/log_datanode_query_debug.log`
+
+#### Example:
+1. Execute the following SQL for DEBUG query
+```sql
+DEBUG SELECT * FROM table3;
+```
+
+2. Check the log content in `log_datanode_query_debug.log` to view the file
scan information involved in the query.
+
+```bash
+2026-03-24 10:10:41,515 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.t.TsFileResource:1098 - Path: table3.d1 file
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2864/1769139940009-1-0-0.tsfile
is not satisfied because of no device!
+2026-03-24 10:10:41,515 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.t.TsFileResource:1098 - Path: table3.d1 file
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2865/1769139940010-1-0-0.tsfile
is not satisfied because of no device!
+2026-03-24 10:10:41,516 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:159 - Cache miss: table3.d1. in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,516 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:160 - Device: table3.d1, all sensors:
[, temperature]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.BloomFilterCache:110 - get bloomFilter from cache where
filePath is:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries: table3.d1.
metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=-128,
chunkMetaDataListDataSize=8, measurementId='', dataType=VECTOR,
statistics=startTime: 1747065600001 endTime: 1747065601002 count: 2,
modified=false, isSeq=true, chun [...]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries:
table3.d1.temperature metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=64,
chunkMetaDataListDataSize=8, measurementId='temperature', dataType=FLOAT,
statistics=startTime: 1747065600001 endTime: 1747065601002 count: 2
[minValue:85.0 [...]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:110 - Modifications
size is 1 for file Path:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:114 - []
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:125 - After
modification Chunk meta data list is:
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:126 -
org.apache.tsfile.file.metadata.TableDeviceChunkMetadata@2e11291f
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile',
regionId=4, timePartitionId=2888, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=19}
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile',
regionId=4, timePartitionId=2888, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=46}
+2026-03-24 10:10:41,519
[pool-69-IoTDB-ClientRPC-Processor-1$20260324_021041_00068_1] INFO
o.a.i.d.q.p.Coordinator:902 - debug select * from table3
+```
diff --git
a/src/UserGuide/latest-Table/User-Manual/Maintenance-commands_timecho.md
b/src/UserGuide/latest-Table/User-Manual/Maintenance-commands_timecho.md
index 30d26acc..e82d0885 100644
--- a/src/UserGuide/latest-Table/User-Manual/Maintenance-commands_timecho.md
+++ b/src/UserGuide/latest-Table/User-Manual/Maintenance-commands_timecho.md
@@ -854,4 +854,46 @@ Terminate all queries:
```SQL
IoTDB> KILL ALL QUERIES;
-```
\ No newline at end of file
+```
+
+## 6. Query Debugging
+### 6.1 DEBUG SQL
+
+**Definition**: Add the `DEBUG` keyword at the beginning of an SQL query
statement. During execution, debug logs will be output, including the
underlying file scan information involved in the query.
+
+> Supported since V2.0.9
+
+#### Syntax:
+```sql
+debugSQLStatement
+ : DEBUG ? query
+ ;
+```
+
+**Description**:
+* Log output path: `logs/log_datanode_query_debug.log`
+
+#### Example:
+1. Execute the following SQL for DEBUG query
+```sql
+DEBUG SELECT * FROM table3;
+```
+
+2. Check the log content in `log_datanode_query_debug.log` to view the file
scan information involved in the query.
+
+```bash
+2026-03-24 10:10:41,515 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.t.TsFileResource:1098 - Path: table3.d1 file
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2864/1769139940009-1-0-0.tsfile
is not satisfied because of no device!
+2026-03-24 10:10:41,515 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.t.TsFileResource:1098 - Path: table3.d1 file
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2865/1769139940010-1-0-0.tsfile
is not satisfied because of no device!
+2026-03-24 10:10:41,516 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:159 - Cache miss: table3.d1. in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,516 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:160 - Device: table3.d1, all sensors:
[, temperature]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.BloomFilterCache:110 - get bloomFilter from cache where
filePath is:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries: table3.d1.
metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=-128,
chunkMetaDataListDataSize=8, measurementId='', dataType=VECTOR,
statistics=startTime: 1747065600001 endTime: 1747065601002 count: 2,
modified=false, isSeq=true, chun [...]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries:
table3.d1.temperature metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=64,
chunkMetaDataListDataSize=8, measurementId='temperature', dataType=FLOAT,
statistics=startTime: 1747065600001 endTime: 1747065601002 count: 2
[minValue:85.0 [...]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:110 - Modifications
size is 1 for file Path:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:114 - []
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:125 - After
modification Chunk meta data list is:
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:126 -
org.apache.tsfile.file.metadata.TableDeviceChunkMetadata@2e11291f
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile',
regionId=4, timePartitionId=2888, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=19}
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile',
regionId=4, timePartitionId=2888, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=46}
+2026-03-24 10:10:41,519
[pool-69-IoTDB-ClientRPC-Processor-1$20260324_021041_00068_1] INFO
o.a.i.d.q.p.Coordinator:902 - debug select * from table3
+```
diff --git a/src/UserGuide/latest/User-Manual/Maintenance-commands_apache.md
b/src/UserGuide/latest/User-Manual/Maintenance-commands_apache.md
index 55f14c68..c3ba550b 100644
--- a/src/UserGuide/latest/User-Manual/Maintenance-commands_apache.md
+++ b/src/UserGuide/latest/User-Manual/Maintenance-commands_apache.md
@@ -619,4 +619,42 @@ Terminate all queries:
```SQL
IoTDB> KILL ALL QUERIES;
-```
\ No newline at end of file
+```
+
+## 6. Query Debugging
+
+### 6.1 DEBUG SQL
+
+**Definition**: Add the `DEBUG` keyword at the beginning of an SQL query
statement. During execution, debug logs will be output, including underlying
file scan information involved in the query.
+
+> Supported since V2.0.9-beta
+
+#### Syntax:
+```sql
+debugSQLStatement
+ : DEBUG ? query
+ ;
+```
+
+**Description**:
+* Log output directory: `logs/log_datanode_query_debug.log`
+
+#### Example:
+1. Execute the following SQL for a DEBUG query
+```sql
+DEBUG SELECT * FROM root.ln.**;
+```
+
+2. Check the log content in `log_datanode_query_debug.log` to view the file
scan information involved in the query.
+
+```bash
+2026-03-24 10:06:18,755 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:159 - Cache miss:
root.ln.wf01.wt01.temperature in file:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,757 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:160 - Device: root.ln.wf01.wt01, all
sensors: [temperature]
+2026-03-24 10:06:18,758 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.BloomFilterCache:110 - get bloomFilter from cache where
filePath is:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries:
root.ln.wf01.wt01.temperature metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=0,
chunkMetaDataListDataSize=8, measurementId='temperature', dataType=DOUBLE,
statistics=startTime: 1773824951259 endTime: 1773824951259 count: 1 [minValue
[...]
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:97 - Modifications size is 0
for file Path:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:109 - After modification
Chunk meta data list is:
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:110 - measurementId:
temperature, datatype: DOUBLE, version: 0, Statistics: startTime: 1773824951259
endTime: 1773824951259 count: 1
[minValue:12.9,maxValue:12.9,firstValue:12.9,lastValue:12.9,sumValue:12.9],
deleteIntervalList: null
+2026-03-24 10:06:18,760 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile',
regionId=13, timePartitionId=2932, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=27}
+2026-03-24 10:06:18,761
[pool-69-IoTDB-ClientRPC-Processor-1$20260324_020618_00052_1] INFO
o.a.i.d.q.p.Coordinator:902 - debug select * from root.ln.**
+```
diff --git a/src/UserGuide/latest/User-Manual/Maintenance-commands_timecho.md
b/src/UserGuide/latest/User-Manual/Maintenance-commands_timecho.md
index b19c029d..268ff96c 100644
--- a/src/UserGuide/latest/User-Manual/Maintenance-commands_timecho.md
+++ b/src/UserGuide/latest/User-Manual/Maintenance-commands_timecho.md
@@ -618,4 +618,42 @@ Terminate all queries:
```SQL
IoTDB> KILL ALL QUERIES;
-```
\ No newline at end of file
+```
+
+## 6. Query Debugging
+
+### 6.1 DEBUG SQL
+
+**Definition**: Add the `DEBUG` keyword at the beginning of an SQL query
statement. During execution, debug logs will be output, including underlying
file scan information involved in the query.
+
+> Supported since V2.0.9
+
+#### Syntax:
+```sql
+debugSQLStatement
+ : DEBUG ? query
+ ;
+```
+
+**Description**:
+* Log output directory: `logs/log_datanode_query_debug.log`
+
+#### Example:
+1. Execute the following SQL for a DEBUG query
+```sql
+DEBUG SELECT * FROM root.ln.**;
+```
+
+2. Check the log content in `log_datanode_query_debug.log` to view the file
scan information involved in the query.
+
+```bash
+2026-03-24 10:06:18,755 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:159 - Cache miss:
root.ln.wf01.wt01.temperature in file:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,757 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:160 - Device: root.ln.wf01.wt01, all
sensors: [temperature]
+2026-03-24 10:06:18,758 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.BloomFilterCache:110 - get bloomFilter from cache where
filePath is:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries:
root.ln.wf01.wt01.temperature metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=0,
chunkMetaDataListDataSize=8, measurementId='temperature', dataType=DOUBLE,
statistics=startTime: 1773824951259 endTime: 1773824951259 count: 1 [minValue
[...]
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:97 - Modifications size is 0
for file Path:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:109 - After modification
Chunk meta data list is:
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:110 - measurementId:
temperature, datatype: DOUBLE, version: 0, Statistics: startTime: 1773824951259
endTime: 1773824951259 count: 1
[minValue:12.9,maxValue:12.9,firstValue:12.9,lastValue:12.9,sumValue:12.9],
deleteIntervalList: null
+2026-03-24 10:06:18,760 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile',
regionId=13, timePartitionId=2932, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=27}
+2026-03-24 10:06:18,761
[pool-69-IoTDB-ClientRPC-Processor-1$20260324_020618_00052_1] INFO
o.a.i.d.q.p.Coordinator:902 - debug select * from root.ln.**
+```
diff --git
a/src/zh/UserGuide/Master/Table/User-Manual/Maintenance-statement_apache.md
b/src/zh/UserGuide/Master/Table/User-Manual/Maintenance-statement_apache.md
index cd23608d..3ac95b3a 100644
--- a/src/zh/UserGuide/Master/Table/User-Manual/Maintenance-statement_apache.md
+++ b/src/zh/UserGuide/Master/Table/User-Manual/Maintenance-statement_apache.md
@@ -873,4 +873,52 @@ killQueryStatement
```SQL
IoTDB> KILL QUERY 20250108_101015_00000_1; -- 终止指定query
IoTDB> KILL ALL QUERIES; -- 终止所有query
-```
\ No newline at end of file
+```
+
+## 6. 调试查询
+
+### 6.1 DEBUG SQL
+
+
+**含义：**在 SQL 查询语句开头添加 debug 关键字，执行时将输出 debug 日志，包括涉及到的底层文件 scan 信息。
+
+> V2.0.9-beta 起支持该功能
+
+#### 语法：
+
+```SQL
+debugSQLStatement
+ : DEBUG ? query
+ ;
+```
+
+**说明：**
+
+* 日志输出目录为： `logs/log_datanode_query_debug.log`
+
+#### 示例：
+
+1. 执行以下 SQL 进行 DEBUG 查询
+
+```SQL
+debug select * from table3;
+```
+
+2. 观察`log_datanode_query_debug.log` 的日志内容，查看查询涉及到的文件 scan 信息。
+
+```Bash
+2026-03-24 10:10:41,515 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.t.TsFileResource:1098 - Path: table3.d1 file
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2864/1769139940009-1-0-0.tsfile
is not satisfied because of no device!
+2026-03-24 10:10:41,515 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.t.TsFileResource:1098 - Path: table3.d1 file
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2865/1769139940010-1-0-0.tsfile
is not satisfied because of no device!
+2026-03-24 10:10:41,516 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:159 - Cache miss: table3.d1. in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,516 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:160 - Device: table3.d1, all sensors:
[, temperature]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.BloomFilterCache:110 - get bloomFilter from cache where
filePath is:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries: table3.d1.
metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=-128,
chunkMetaDataListDataSize=8, measurementId='', dataType=VECTOR,
statistics=startTime: 1747065600001 endTime: 1747065601002 count: 2,
modified=false, isSeq=true, chun [...]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries:
table3.d1.temperature metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=64,
chunkMetaDataListDataSize=8, measurementId='temperature', dataType=FLOAT,
statistics=startTime: 1747065600001 endTime: 1747065601002 count: 2
[minValue:85.0 [...]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:110 - Modifications
size is 1 for file Path:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:114 - []
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:125 - After
modification Chunk meta data list is:
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:126 -
org.apache.tsfile.file.metadata.TableDeviceChunkMetadata@2e11291f
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile',
regionId=4, timePartitionId=2888, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=19}
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile',
regionId=4, timePartitionId=2888, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=46}
+2026-03-24 10:10:41,519
[pool-69-IoTDB-ClientRPC-Processor-1$20260324_021041_00068_1] INFO
o.a.i.d.q.p.Coordinator:902 - debug select * from table3
+```
diff --git
a/src/zh/UserGuide/Master/Table/User-Manual/Maintenance-statement_timecho.md
b/src/zh/UserGuide/Master/Table/User-Manual/Maintenance-statement_timecho.md
index 69764c6c..2535ca94 100644
--- a/src/zh/UserGuide/Master/Table/User-Manual/Maintenance-statement_timecho.md
+++ b/src/zh/UserGuide/Master/Table/User-Manual/Maintenance-statement_timecho.md
@@ -872,4 +872,52 @@ killQueryStatement
```SQL
IoTDB> KILL QUERY 20250108_101015_00000_1; -- 终止指定query
IoTDB> KILL ALL QUERIES; -- 终止所有query
-```
\ No newline at end of file
+```
+
+## 6. 调试查询
+
+### 6.1 DEBUG SQL
+
+
+**含义：**在 SQL 查询语句开头添加 debug 关键字，执行时将输出 debug 日志，包括涉及到的底层文件 scan 信息。
+
+> V2.0.9 起支持该功能
+
+#### 语法：
+
+```SQL
+debugSQLStatement
+ : DEBUG ? query
+ ;
+```
+
+**说明：**
+
+* 日志输出目录为： `logs/log_datanode_query_debug.log`
+
+#### 示例：
+
+1. 执行以下 SQL 进行 DEBUG 查询
+
+```SQL
+debug select * from table3;
+```
+
+2. 观察`log_datanode_query_debug.log` 的日志内容，查看查询涉及到的文件 scan 信息。
+
+```Bash
+2026-03-24 10:10:41,515 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.t.TsFileResource:1098 - Path: table3.d1 file
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2864/1769139940009-1-0-0.tsfile
is not satisfied because of no device!
+2026-03-24 10:10:41,515 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.t.TsFileResource:1098 - Path: table3.d1 file
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2865/1769139940010-1-0-0.tsfile
is not satisfied because of no device!
+2026-03-24 10:10:41,516 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:159 - Cache miss: table3.d1. in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,516 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:160 - Device: table3.d1, all sensors:
[, temperature]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.BloomFilterCache:110 - get bloomFilter from cache where
filePath is:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries: table3.d1.
metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=-128,
chunkMetaDataListDataSize=8, measurementId='', dataType=VECTOR,
statistics=startTime: 1747065600001 endTime: 1747065601002 count: 2,
modified=false, isSeq=true, chun [...]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries:
table3.d1.temperature metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=64,
chunkMetaDataListDataSize=8, measurementId='temperature', dataType=FLOAT,
statistics=startTime: 1747065600001 endTime: 1747065601002 count: 2
[minValue:85.0 [...]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:110 - Modifications
size is 1 for file Path:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:114 - []
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:125 - After
modification Chunk meta data list is:
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:126 -
org.apache.tsfile.file.metadata.TableDeviceChunkMetadata@2e11291f
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile',
regionId=4, timePartitionId=2888, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=19}
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile',
regionId=4, timePartitionId=2888, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=46}
+2026-03-24 10:10:41,519
[pool-69-IoTDB-ClientRPC-Processor-1$20260324_021041_00068_1] INFO
o.a.i.d.q.p.Coordinator:902 - debug select * from table3
+```
diff --git
a/src/zh/UserGuide/Master/Tree/User-Manual/Maintenance-statement_apache.md
b/src/zh/UserGuide/Master/Tree/User-Manual/Maintenance-statement_apache.md
index 10f7aea2..b73a3691 100644
--- a/src/zh/UserGuide/Master/Tree/User-Manual/Maintenance-statement_apache.md
+++ b/src/zh/UserGuide/Master/Tree/User-Manual/Maintenance-statement_apache.md
@@ -637,4 +637,48 @@ killQueryStatement
```SQL
IoTDB> KILL QUERY 20250108_101015_00000_1; -- 终止指定query
IoTDB> KILL ALL QUERIES; -- 终止所有query
-```
\ No newline at end of file
+```
+
+
+## 6. 调试查询
+
+### 6.1 DEBUG SQL
+
+
+**含义：**在 SQL 查询语句开头添加 debug 关键字，执行时将输出 debug 日志，包括涉及到的底层文件 scan 信息。
+
+> V2.0.9-beta 起支持该功能
+
+#### 语法：
+
+```SQL
+debugSQLStatement
+ : DEBUG ? query
+ ;
+```
+
+**说明：**
+
+* 日志输出目录为： `logs/log_datanode_query_debug.log`
+
+#### 示例：
+
+1. 执行以下 SQL 进行 DEBUG 查询
+
+```SQL
+debug select * from root.ln.**;
+```
+
+2. 观察`log_datanode_query_debug.log` 的日志内容，查看查询涉及到的文件 scan 信息。
+
+```Bash
+2026-03-24 10:06:18,755 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:159 - Cache miss:
root.ln.wf01.wt01.temperature in file:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,757 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:160 - Device: root.ln.wf01.wt01, all
sensors: [temperature]
+2026-03-24 10:06:18,758 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.BloomFilterCache:110 - get bloomFilter from cache where
filePath is:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries:
root.ln.wf01.wt01.temperature metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=0,
chunkMetaDataListDataSize=8, measurementId='temperature', dataType=DOUBLE,
statistics=startTime: 1773824951259 endTime: 1773824951259 count: 1 [minVal
[...]
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:97 - Modifications size is 0
for file Path:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:109 - After modification
Chunk meta data list is:
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:110 - measurementId:
temperature, datatype: DOUBLE, version: 0, Statistics: startTime: 1773824951259
endTime: 1773824951259 count: 1
[minValue:12.9,maxValue:12.9,firstValue:12.9,lastValue:12.9,sumValue:12.9],
deleteIntervalList: null
+2026-03-24 10:06:18,760 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile',
regionId=13, timePartitionId=2932, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=27}
+2026-03-24 10:06:18,761
[pool-69-IoTDB-ClientRPC-Processor-1$20260324_020618_00052_1] INFO
o.a.i.d.q.p.Coordinator:902 - debug select * from root.ln.**
+```
diff --git
a/src/zh/UserGuide/Master/Tree/User-Manual/Maintenance-statement_timecho.md
b/src/zh/UserGuide/Master/Tree/User-Manual/Maintenance-statement_timecho.md
index dc592f16..5171b33c 100644
--- a/src/zh/UserGuide/Master/Tree/User-Manual/Maintenance-statement_timecho.md
+++ b/src/zh/UserGuide/Master/Tree/User-Manual/Maintenance-statement_timecho.md
@@ -639,4 +639,49 @@ killQueryStatement
```SQL
IoTDB> KILL QUERY 20250108_101015_00000_1; -- 终止指定query
IoTDB> KILL ALL QUERIES; -- 终止所有query
+```
+
+
+
+## 6. 调试查询
+
+### 6.1 DEBUG SQL
+
+
+**含义：**在 SQL 查询语句开头添加 debug 关键字，执行时将输出 debug 日志，包括涉及到的底层文件 scan 信息。
+
+> V2.0.9 起支持该功能
+
+#### 语法：
+
+```SQL
+debugSQLStatement
+ : DEBUG ? query
+ ;
+```
+
+**说明：**
+
+* 日志输出目录为： `logs/log_datanode_query_debug.log`
+
+#### 示例：
+
+1. 执行以下 SQL 进行 DEBUG 查询
+
+```SQL
+debug select * from root.ln.**;
+```
+
+2. 观察`log_datanode_query_debug.log` 的日志内容，查看查询涉及到的文件 scan 信息。
+
+```Bash
+2026-03-24 10:06:18,755 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:159 - Cache miss:
root.ln.wf01.wt01.temperature in file:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,757 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:160 - Device: root.ln.wf01.wt01, all
sensors: [temperature]
+2026-03-24 10:06:18,758 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.BloomFilterCache:110 - get bloomFilter from cache where
filePath is:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries:
root.ln.wf01.wt01.temperature metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=0,
chunkMetaDataListDataSize=8, measurementId='temperature', dataType=DOUBLE,
statistics=startTime: 1773824951259 endTime: 1773824951259 count: 1 [minVal
[...]
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:97 - Modifications size is 0
for file Path:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:109 - After modification
Chunk meta data list is:
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:110 - measurementId:
temperature, datatype: DOUBLE, version: 0, Statistics: startTime: 1773824951259
endTime: 1773824951259 count: 1
[minValue:12.9,maxValue:12.9,firstValue:12.9,lastValue:12.9,sumValue:12.9],
deleteIntervalList: null
+2026-03-24 10:06:18,760 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile',
regionId=13, timePartitionId=2932, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=27}
+2026-03-24 10:06:18,761
[pool-69-IoTDB-ClientRPC-Processor-1$20260324_020618_00052_1] INFO
o.a.i.d.q.p.Coordinator:902 - debug select * from root.ln.**
```
\ No newline at end of file
diff --git
a/src/zh/UserGuide/latest-Table/User-Manual/Maintenance-statement_apache.md
b/src/zh/UserGuide/latest-Table/User-Manual/Maintenance-statement_apache.md
index cd23608d..3ac95b3a 100644
--- a/src/zh/UserGuide/latest-Table/User-Manual/Maintenance-statement_apache.md
+++ b/src/zh/UserGuide/latest-Table/User-Manual/Maintenance-statement_apache.md
@@ -873,4 +873,52 @@ killQueryStatement
```SQL
IoTDB> KILL QUERY 20250108_101015_00000_1; -- 终止指定query
IoTDB> KILL ALL QUERIES; -- 终止所有query
-```
\ No newline at end of file
+```
+
+## 6. 调试查询
+
+### 6.1 DEBUG SQL
+
+
+**含义：**在 SQL 查询语句开头添加 debug 关键字，执行时将输出 debug 日志，包括涉及到的底层文件 scan 信息。
+
+> V2.0.9-beta 起支持该功能
+
+#### 语法：
+
+```SQL
+debugSQLStatement
+ : DEBUG ? query
+ ;
+```
+
+**说明：**
+
+* 日志输出目录为： `logs/log_datanode_query_debug.log`
+
+#### 示例：
+
+1. 执行以下 SQL 进行 DEBUG 查询
+
+```SQL
+debug select * from table3;
+```
+
+2. 观察`log_datanode_query_debug.log` 的日志内容，查看查询涉及到的文件 scan 信息。
+
+```Bash
+2026-03-24 10:10:41,515 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.t.TsFileResource:1098 - Path: table3.d1 file
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2864/1769139940009-1-0-0.tsfile
is not satisfied because of no device!
+2026-03-24 10:10:41,515 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.t.TsFileResource:1098 - Path: table3.d1 file
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2865/1769139940010-1-0-0.tsfile
is not satisfied because of no device!
+2026-03-24 10:10:41,516 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:159 - Cache miss: table3.d1. in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,516 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:160 - Device: table3.d1, all sensors:
[, temperature]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.BloomFilterCache:110 - get bloomFilter from cache where
filePath is:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries: table3.d1.
metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=-128,
chunkMetaDataListDataSize=8, measurementId='', dataType=VECTOR,
statistics=startTime: 1747065600001 endTime: 1747065601002 count: 2,
modified=false, isSeq=true, chun [...]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries:
table3.d1.temperature metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=64,
chunkMetaDataListDataSize=8, measurementId='temperature', dataType=FLOAT,
statistics=startTime: 1747065600001 endTime: 1747065601002 count: 2
[minValue:85.0 [...]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:110 - Modifications
size is 1 for file Path:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:114 - []
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:125 - After
modification Chunk meta data list is:
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:126 -
org.apache.tsfile.file.metadata.TableDeviceChunkMetadata@2e11291f
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile',
regionId=4, timePartitionId=2888, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=19}
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile',
regionId=4, timePartitionId=2888, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=46}
+2026-03-24 10:10:41,519
[pool-69-IoTDB-ClientRPC-Processor-1$20260324_021041_00068_1] INFO
o.a.i.d.q.p.Coordinator:902 - debug select * from table3
+```
diff --git
a/src/zh/UserGuide/latest-Table/User-Manual/Maintenance-statement_timecho.md
b/src/zh/UserGuide/latest-Table/User-Manual/Maintenance-statement_timecho.md
index 69764c6c..2535ca94 100644
--- a/src/zh/UserGuide/latest-Table/User-Manual/Maintenance-statement_timecho.md
+++ b/src/zh/UserGuide/latest-Table/User-Manual/Maintenance-statement_timecho.md
@@ -872,4 +872,52 @@ killQueryStatement
```SQL
IoTDB> KILL QUERY 20250108_101015_00000_1; -- 终止指定query
IoTDB> KILL ALL QUERIES; -- 终止所有query
-```
\ No newline at end of file
+```
+
+## 6. 调试查询
+
+### 6.1 DEBUG SQL
+
+
+**含义：**在 SQL 查询语句开头添加 debug 关键字，执行时将输出 debug 日志，包括涉及到的底层文件 scan 信息。
+
+> V2.0.9 起支持该功能
+
+#### 语法：
+
+```SQL
+debugSQLStatement
+ : DEBUG ? query
+ ;
+```
+
+**说明：**
+
+* 日志输出目录为： `logs/log_datanode_query_debug.log`
+
+#### 示例：
+
+1. 执行以下 SQL 进行 DEBUG 查询
+
+```SQL
+debug select * from table3;
+```
+
+2. 观察`log_datanode_query_debug.log` 的日志内容，查看查询涉及到的文件 scan 信息。
+
+```Bash
+2026-03-24 10:10:41,515 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.t.TsFileResource:1098 - Path: table3.d1 file
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2864/1769139940009-1-0-0.tsfile
is not satisfied because of no device!
+2026-03-24 10:10:41,515 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.t.TsFileResource:1098 - Path: table3.d1 file
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2865/1769139940010-1-0-0.tsfile
is not satisfied because of no device!
+2026-03-24 10:10:41,516 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:159 - Cache miss: table3.d1. in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,516 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:160 - Device: table3.d1, all sensors:
[, temperature]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.BloomFilterCache:110 - get bloomFilter from cache where
filePath is:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries: table3.d1.
metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=-128,
chunkMetaDataListDataSize=8, measurementId='', dataType=VECTOR,
statistics=startTime: 1747065600001 endTime: 1747065601002 count: 2,
modified=false, isSeq=true, chun [...]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries:
table3.d1.temperature metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=64,
chunkMetaDataListDataSize=8, measurementId='temperature', dataType=FLOAT,
statistics=startTime: 1747065600001 endTime: 1747065601002 count: 2
[minValue:85.0 [...]
+2026-03-24 10:10:41,517 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:110 - Modifications
size is 1 for file Path:
/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:114 - []
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:125 - After
modification Chunk meta data list is:
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskAlignedChunkMetadataLoader:126 -
org.apache.tsfile.file.metadata.TableDeviceChunkMetadata@2e11291f
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile',
regionId=4, timePartitionId=2888, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=19}
+2026-03-24 10:10:41,518 [Query-Worker-Thread-0$20260324_021041_00068_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/database1/4/2888/1774247880109-1-0-0.tsfile',
regionId=4, timePartitionId=2888, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=46}
+2026-03-24 10:10:41,519
[pool-69-IoTDB-ClientRPC-Processor-1$20260324_021041_00068_1] INFO
o.a.i.d.q.p.Coordinator:902 - debug select * from table3
+```
diff --git
a/src/zh/UserGuide/latest/User-Manual/Maintenance-statement_apache.md
b/src/zh/UserGuide/latest/User-Manual/Maintenance-statement_apache.md
index 10f7aea2..b73a3691 100644
--- a/src/zh/UserGuide/latest/User-Manual/Maintenance-statement_apache.md
+++ b/src/zh/UserGuide/latest/User-Manual/Maintenance-statement_apache.md
@@ -637,4 +637,48 @@ killQueryStatement
```SQL
IoTDB> KILL QUERY 20250108_101015_00000_1; -- 终止指定query
IoTDB> KILL ALL QUERIES; -- 终止所有query
-```
\ No newline at end of file
+```
+
+
+## 6. 调试查询
+
+### 6.1 DEBUG SQL
+
+
+**含义：**在 SQL 查询语句开头添加 debug 关键字，执行时将输出 debug 日志，包括涉及到的底层文件 scan 信息。
+
+> V2.0.9-beta 起支持该功能
+
+#### 语法：
+
+```SQL
+debugSQLStatement
+ : DEBUG ? query
+ ;
+```
+
+**说明：**
+
+* 日志输出目录为： `logs/log_datanode_query_debug.log`
+
+#### 示例：
+
+1. 执行以下 SQL 进行 DEBUG 查询
+
+```SQL
+debug select * from root.ln.**;
+```
+
+2. 观察`log_datanode_query_debug.log` 的日志内容，查看查询涉及到的文件 scan 信息。
+
+```Bash
+2026-03-24 10:06:18,755 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:159 - Cache miss:
root.ln.wf01.wt01.temperature in file:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,757 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:160 - Device: root.ln.wf01.wt01, all
sensors: [temperature]
+2026-03-24 10:06:18,758 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.BloomFilterCache:110 - get bloomFilter from cache where
filePath is:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries:
root.ln.wf01.wt01.temperature metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=0,
chunkMetaDataListDataSize=8, measurementId='temperature', dataType=DOUBLE,
statistics=startTime: 1773824951259 endTime: 1773824951259 count: 1 [minVal
[...]
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:97 - Modifications size is 0
for file Path:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:109 - After modification
Chunk meta data list is:
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:110 - measurementId:
temperature, datatype: DOUBLE, version: 0, Statistics: startTime: 1773824951259
endTime: 1773824951259 count: 1
[minValue:12.9,maxValue:12.9,firstValue:12.9,lastValue:12.9,sumValue:12.9],
deleteIntervalList: null
+2026-03-24 10:06:18,760 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile',
regionId=13, timePartitionId=2932, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=27}
+2026-03-24 10:06:18,761
[pool-69-IoTDB-ClientRPC-Processor-1$20260324_020618_00052_1] INFO
o.a.i.d.q.p.Coordinator:902 - debug select * from root.ln.**
+```
diff --git
a/src/zh/UserGuide/latest/User-Manual/Maintenance-statement_timecho.md
b/src/zh/UserGuide/latest/User-Manual/Maintenance-statement_timecho.md
index dc592f16..5171b33c 100644
--- a/src/zh/UserGuide/latest/User-Manual/Maintenance-statement_timecho.md
+++ b/src/zh/UserGuide/latest/User-Manual/Maintenance-statement_timecho.md
@@ -639,4 +639,49 @@ killQueryStatement
```SQL
IoTDB> KILL QUERY 20250108_101015_00000_1; -- 终止指定query
IoTDB> KILL ALL QUERIES; -- 终止所有query
+```
+
+
+
+## 6. 调试查询
+
+### 6.1 DEBUG SQL
+
+
+**含义：**在 SQL 查询语句开头添加 debug 关键字，执行时将输出 debug 日志，包括涉及到的底层文件 scan 信息。
+
+> V2.0.9 起支持该功能
+
+#### 语法：
+
+```SQL
+debugSQLStatement
+ : DEBUG ? query
+ ;
+```
+
+**说明：**
+
+* 日志输出目录为： `logs/log_datanode_query_debug.log`
+
+#### 示例：
+
+1. 执行以下 SQL 进行 DEBUG 查询
+
+```SQL
+debug select * from root.ln.**;
+```
+
+2. 观察`log_datanode_query_debug.log` 的日志内容，查看查询涉及到的文件 scan 信息。
+
+```Bash
+2026-03-24 10:06:18,755 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:159 - Cache miss:
root.ln.wf01.wt01.temperature in file:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,757 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:160 - Device: root.ln.wf01.wt01, all
sensors: [temperature]
+2026-03-24 10:06:18,758 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.BloomFilterCache:110 - get bloomFilter from cache where
filePath is:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.TimeSeriesMetadataCache:227 - Get timeseries:
root.ln.wf01.wt01.temperature metadata in file:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
from cache: TimeseriesMetadata{timeSeriesMetadataType=0,
chunkMetaDataListDataSize=8, measurementId='temperature', dataType=DOUBLE,
statistics=startTime: 1773824951259 endTime: 1773824951259 count: 1 [minVal
[...]
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:97 - Modifications size is 0
for file Path:
/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:109 - After modification
Chunk meta data list is:
+2026-03-24 10:06:18,759 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.d.r.r.c.m.DiskChunkMetadataLoader:110 - measurementId:
temperature, datatype: DOUBLE, version: 0, Statistics: startTime: 1773824951259
endTime: 1773824951259 count: 1
[minValue:12.9,maxValue:12.9,firstValue:12.9,lastValue:12.9,sumValue:12.9],
deleteIntervalList: null
+2026-03-24 10:06:18,760 [Query-Worker-Thread-3$20260324_020618_00052_1.1.0.0]
INFO o.a.i.d.s.b.ChunkCache:167 - get chunk from cache whose key is:
ChunkCacheKey{filePath='/home/iotdb/timechodb/data/datanode/data/sequence/root.ln/13/2932/1773824951611-1-0-0.tsfile',
regionId=13, timePartitionId=2932, tsFileVersion=1, compactionVersion=0,
offsetOfChunkHeader=27}
+2026-03-24 10:06:18,761
[pool-69-IoTDB-ClientRPC-Processor-1$20260324_020618_00052_1] INFO
o.a.i.d.q.p.Coordinator:902 - debug select * from root.ln.**
```
\ No newline at end of file
