You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@tsfile.apache.org by "ColinLeeo (via GitHub)" <gi...@apache.org> on 2026/06/18 03:30:26 UTC

[PR] Tsfile doc [tsfile]

ColinLeeo opened a new pull request, #846:
URL: https://github.com/apache/tsfile/pull/846

   (no comment)


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@tsfile.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Tsfile doc [tsfile]

Posted by "leto-bbq (via GitHub)" <gi...@apache.org>.
leto-bbq commented on code in PR #846:
URL: https://github.com/apache/tsfile/pull/846#discussion_r3464465073


##########
src/zh/UserGuide/latest/Tools/Tsfile-CLI.md:
##########
@@ -0,0 +1,174 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+# tsfile-cli

Review Comment:
   文档标题建议首字母大写



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@tsfile.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Tsfile doc [tsfile]

Posted by "jt2594838 (via GitHub)" <gi...@apache.org>.
jt2594838 merged PR #846:
URL: https://github.com/apache/tsfile/pull/846


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@tsfile.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Tsfile doc [tsfile]

Posted by "jt2594838 (via GitHub)" <gi...@apache.org>.
jt2594838 commented on code in PR #846:
URL: https://github.com/apache/tsfile/pull/846#discussion_r3434333184


##########
src/UserGuide/develop/DataFrame/TsFileDataFrame.md:
##########
@@ -0,0 +1,287 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+# TsFileDataFrame
+
+`TsFileDataFrame` lets you read the time series inside one or more TsFiles the
+same way you would work with a pandas DataFrame — without having to care about
+the underlying file format or data-loading details. It is part of the Python
+package (`pip install tsfile`).
+
+## Quick start
+
+```python
+from tsfile import TsFileDataFrame
+
+df = TsFileDataFrame("table_data/")           # load every .tsfile under the directory
+print(df)                                     # browse all series (metadata only)
+
+ts = df["weather.Beijing.humidity"]           # pick one series (lazy handle)
+window = ts[20:100]                           # slice by row index -> np.ndarray
+
+data = df.loc[start:end, [                     # align multiple series on timestamps
+    "weather.Beijing.temperature",
+    "weather.Beijing.humidity",
+]]
+data.values                                   # -> np.ndarray, shape = (N, 2)
+```
+
+## Core types
+
+`TsFileDataFrame` is built around three types:
+
+- **`TsFileDataFrame`** — the entry point. It loads one or more TsFiles and
+  exposes a unified view. Construction only scans metadata; **no values are read**.
+- **`Timeseries`** — a lazy handle to a single series, obtained from `df[...]`.
+  It carries the series' metadata but reads nothing until you index it by row.
+- **`AlignedTimeseries`** — the result of aligning several series on a common
+  time axis, obtained from `df.loc[...]`. It reads the requested range of the
+  requested series into memory at once.
+
+### TsFileDataFrame
+
+In the table below, `df` is a `TsFileDataFrame` instance, created with
+`df = TsFileDataFrame(paths)`.
+
+| Example | Operation | Returns |
+|---|---|---|
+| `TsFileDataFrame(paths)` | Load a file / list of files / directory | `TsFileDataFrame` |
+| `len(df)` | Number of time series | `int` |
+| `df.list_timeseries("weather")` | Series names, optionally filtered by prefix | `List[str]` |
+| `df["weather.Beijing.humidity"]`, `df[0]`, `df[-1]` | One series | `Timeseries` |
+| `df["city"]` | A metadata column (a tag / `field` / `start_time` / `end_time` / `count`) | `pandas.Series` |
+| `df[0:3]`, `df[[0, 2, 5]]` | A subset view | `TsFileDataFrame` |

Review Comment:
   What does the index indicate/ what is the order of it.



##########
src/UserGuide/develop/DataFrame/TsFileDataFrame.md:
##########
@@ -0,0 +1,287 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+# TsFileDataFrame
+
+`TsFileDataFrame` lets you read the time series inside one or more TsFiles the
+same way you would work with a pandas DataFrame — without having to care about
+the underlying file format or data-loading details. It is part of the Python
+package (`pip install tsfile`).
+
+## Quick start
+
+```python
+from tsfile import TsFileDataFrame
+
+df = TsFileDataFrame("table_data/")           # load every .tsfile under the directory
+print(df)                                     # browse all series (metadata only)
+
+ts = df["weather.Beijing.humidity"]           # pick one series (lazy handle)
+window = ts[20:100]                           # slice by row index -> np.ndarray
+
+data = df.loc[start:end, [                     # align multiple series on timestamps
+    "weather.Beijing.temperature",
+    "weather.Beijing.humidity",
+]]
+data.values                                   # -> np.ndarray, shape = (N, 2)
+```
+
+## Core types
+
+`TsFileDataFrame` is built around three types:
+
+- **`TsFileDataFrame`** — the entry point. It loads one or more TsFiles and
+  exposes a unified view. Construction only scans metadata; **no values are read**.
+- **`Timeseries`** — a lazy handle to a single series, obtained from `df[...]`.
+  It carries the series' metadata but reads nothing until you index it by row.
+- **`AlignedTimeseries`** — the result of aligning several series on a common
+  time axis, obtained from `df.loc[...]`. It reads the requested range of the
+  requested series into memory at once.
+
+### TsFileDataFrame
+
+In the table below, `df` is a `TsFileDataFrame` instance, created with
+`df = TsFileDataFrame(paths)`.
+
+| Example | Operation | Returns |
+|---|---|---|
+| `TsFileDataFrame(paths)` | Load a file / list of files / directory | `TsFileDataFrame` |
+| `len(df)` | Number of time series | `int` |
+| `df.list_timeseries("weather")` | Series names, optionally filtered by prefix | `List[str]` |
+| `df["weather.Beijing.humidity"]`, `df[0]`, `df[-1]` | One series | `Timeseries` |
+| `df["city"]` | A metadata column (a tag / `field` / `start_time` / `end_time` / `count`) | `pandas.Series` |
+| `df[0:3]`, `df[[0, 2, 5]]` | A subset view | `TsFileDataFrame` |
+| `df[df["city"] == "Beijing"]` | Filter by a metadata column | `TsFileDataFrame` |
+| `df.loc[start:end, series_list]` | Timestamp-aligned query | `AlignedTimeseries` |
+| `df.show(max_rows=20)` / `print(df)` | Formatted metadata table | — |
+| `df.close()` | Release file handles | — |
+
+### Timeseries
+
+In the table below, `ts` is a `Timeseries`, obtained from `ts = df[...]`.
+
+| Example | Operation | Returns |
+|---|---|---|
+| `ts.name` | Series name | `str` |
+| `len(ts)` | Number of points | `int` |
+| `ts.stats` | Series statistics | `dict` (`start_time`, `end_time`, `count`) |
+| `ts[20]` | Single value | `float` (or `None` if null) |

Review Comment:
   It should be highlighted that only numeric values are supported.
   How are non-numeric series processed? Silently skipped during construction or thrown an exception when visited?



##########
src/UserGuide/develop/DataFrame/TsFileDataFrame.md:
##########
@@ -0,0 +1,287 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+# TsFileDataFrame
+
+`TsFileDataFrame` lets you read the time series inside one or more TsFiles the
+same way you would work with a pandas DataFrame — without having to care about
+the underlying file format or data-loading details. It is part of the Python
+package (`pip install tsfile`).
+
+## Quick start
+
+```python
+from tsfile import TsFileDataFrame
+
+df = TsFileDataFrame("table_data/")           # load every .tsfile under the directory
+print(df)                                     # browse all series (metadata only)
+
+ts = df["weather.Beijing.humidity"]           # pick one series (lazy handle)
+window = ts[20:100]                           # slice by row index -> np.ndarray
+
+data = df.loc[start:end, [                     # align multiple series on timestamps
+    "weather.Beijing.temperature",
+    "weather.Beijing.humidity",
+]]
+data.values                                   # -> np.ndarray, shape = (N, 2)

Review Comment:
   What is the N and the 2.



##########
src/UserGuide/develop/DataFrame/TsFileDataFrame.md:
##########
@@ -0,0 +1,287 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+# TsFileDataFrame
+
+`TsFileDataFrame` lets you read the time series inside one or more TsFiles the
+same way you would work with a pandas DataFrame — without having to care about
+the underlying file format or data-loading details. It is part of the Python
+package (`pip install tsfile`).
+
+## Quick start
+
+```python
+from tsfile import TsFileDataFrame
+
+df = TsFileDataFrame("table_data/")           # load every .tsfile under the directory
+print(df)                                     # browse all series (metadata only)
+
+ts = df["weather.Beijing.humidity"]           # pick one series (lazy handle)
+window = ts[20:100]                           # slice by row index -> np.ndarray
+
+data = df.loc[start:end, [                     # align multiple series on timestamps
+    "weather.Beijing.temperature",
+    "weather.Beijing.humidity",
+]]
+data.values                                   # -> np.ndarray, shape = (N, 2)
+```
+
+## Core types
+
+`TsFileDataFrame` is built around three types:
+
+- **`TsFileDataFrame`** — the entry point. It loads one or more TsFiles and
+  exposes a unified view. Construction only scans metadata; **no values are read**.
+- **`Timeseries`** — a lazy handle to a single series, obtained from `df[...]`.
+  It carries the series' metadata but reads nothing until you index it by row.
+- **`AlignedTimeseries`** — the result of aligning several series on a common
+  time axis, obtained from `df.loc[...]`. It reads the requested range of the
+  requested series into memory at once.
+
+### TsFileDataFrame
+
+In the table below, `df` is a `TsFileDataFrame` instance, created with
+`df = TsFileDataFrame(paths)`.
+
+| Example | Operation | Returns |
+|---|---|---|
+| `TsFileDataFrame(paths)` | Load a file / list of files / directory | `TsFileDataFrame` |
+| `len(df)` | Number of time series | `int` |
+| `df.list_timeseries("weather")` | Series names, optionally filtered by prefix | `List[str]` |
+| `df["weather.Beijing.humidity"]`, `df[0]`, `df[-1]` | One series | `Timeseries` |
+| `df["city"]` | A metadata column (a tag / `field` / `start_time` / `end_time` / `count`) | `pandas.Series` |
+| `df[0:3]`, `df[[0, 2, 5]]` | A subset view | `TsFileDataFrame` |
+| `df[df["city"] == "Beijing"]` | Filter by a metadata column | `TsFileDataFrame` |
+| `df.loc[start:end, series_list]` | Timestamp-aligned query | `AlignedTimeseries` |
+| `df.show(max_rows=20)` / `print(df)` | Formatted metadata table | — |
+| `df.close()` | Release file handles | — |
+
+### Timeseries
+
+In the table below, `ts` is a `Timeseries`, obtained from `ts = df[...]`.
+
+| Example | Operation | Returns |
+|---|---|---|
+| `ts.name` | Series name | `str` |
+| `len(ts)` | Number of points | `int` |
+| `ts.stats` | Series statistics | `dict` (`start_time`, `end_time`, `count`) |
+| `ts[20]` | Single value | `float` (or `None` if null) |
+| `ts[20:100]` | Row-range slice | `np.ndarray` |
+| `ts.timestamps` | Timestamp array | `np.ndarray` |
+
+### AlignedTimeseries
+
+In the table below, `data` is an `AlignedTimeseries`, obtained from
+`data = df.loc[...]`.
+
+| Example | Operation | Returns |
+|---|---|---|
+| `data.timestamps` | Timestamp array | `np.ndarray` |
+| `data.values` | Value matrix | `np.ndarray`, shape `(N, M)` |
+| `data.series_names` | Series names | `List[str]` |
+| `data.shape` | Shape `(N, M)` — N timestamps, M series | `tuple` |
+| `len(data)` | Number of rows | `int` |
+| `data[0]`, `data[0:10]`, `data[0, 1]` | Row / element indexing | `np.ndarray` / scalar |
+| `data.show(50)` / `print(data)` | Formatted output (auto-truncated) | — |
+
+## Series names
+
+A series is uniquely identified by its **series name**, a string formed by
+joining the **table name**, the **tag-column values**, and the **field name**
+with `.`, in that order:

Review Comment:
   Highlight what will happen if `.` is contained in either of them.



##########
src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md:
##########
@@ -88,7 +124,7 @@ void free_write_file(WriteFile* write_file);
 ### TsFile Writer Create/Close
 
 When creating a TsFile Writer, you need to specify WriteFile and TableSchema. You can use the memory_threshold parameter in
-tsfile_writer_new_with_memory_threshold to limit the memory usage of the Writer during data writing, but in the current version, this parameter does not take effect.
+tsfile_writer_new_with_memory_threshold to set a memory threshold.

Review Comment:
   Explain how the threshold works.



##########
src/UserGuide/develop/Tools/Tsfile-CLI.md:
##########
@@ -0,0 +1,183 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+# tsfile-cli
+
+`tsfile-cli` is a single, pipe-friendly C++ command-line tool for inspecting
+**and** importing Apache TsFile (`.tsfile`) files from the shell. Read commands print data to **stdout** and
+diagnostics to **stderr**, so they compose with `awk`, `jq`, `sort`, and friends;
+the `write` command imports CSV/TSV into a new `.tsfile`. It is built on the
+public `TsFileReader` and `TsFileTableWriter` APIs.
+
+## Building from source
+
+The CLI is part of the C++ module. Build it with the Maven wrapper, which
+downloads a pinned CMake and compiles the whole C++ module (the `libtsfile`
+shared library + the `tsfile-cli` executable) for you.

Review Comment:
   Add CMake-only compilation steps.



##########
src/zh/UserGuide/develop/DataFrame/TsFileDataFrame.md:
##########
@@ -0,0 +1,270 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+# TsFileDataFrame
+
+`TsFileDataFrame` 让你像操作 pandas DataFrame 一样读取一个或多个 TsFile 中的时序数据,
+无需关心底层文件格式与数据加载细节。它是 Python 包的一部分(`pip install tsfile`)。

Review Comment:
   Python 包 -> TsFile Python 包



##########
src/zh/UserGuide/develop/Tools/Tsfile-Viewer.md:
##########


Review Comment:
   这个文档太简略了,截止到启动后面就没有了,然而后面的怎么用才是最重要的。



##########
src/zh/UserGuide/develop/DataFrame/TsFileDataFrame.md:
##########
@@ -0,0 +1,270 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+# TsFileDataFrame
+
+`TsFileDataFrame` 让你像操作 pandas DataFrame 一样读取一个或多个 TsFile 中的时序数据,
+无需关心底层文件格式与数据加载细节。它是 Python 包的一部分(`pip install tsfile`)。
+
+## 快速上手
+
+```python
+from tsfile import TsFileDataFrame
+
+df = TsFileDataFrame("table_data/")           # 加载目录下所有 .tsfile
+print(df)                                     # 浏览所有序列(仅元数据)
+
+ts = df["weather.Beijing.humidity"]           # 取一条序列(懒加载句柄)
+window = ts[20:100]                           # 按行号切片 -> np.ndarray
+
+data = df.loc[start:end, [                     # 按时间戳对齐多条序列
+    "weather.Beijing.temperature",
+    "weather.Beijing.humidity",
+]]
+data.values                                   # -> np.ndarray, shape = (N, 2)
+```
+
+## 核心类型
+
+`TsFileDataFrame` 围绕三个核心类型:
+
+- **`TsFileDataFrame`**:入口对象,加载一至多个 TsFile 并提供统一视图。初始化时只扫描元数据,
+  **不读取实际数值**。
+- **`Timeseries`**:单条序列的懒加载句柄,通过 `df[...]` 获得。它携带序列元信息,但在按行号索引前
+  不读取任何数据。
+- **`AlignedTimeseries`**:多条序列在同一时间轴上的对齐结果,通过 `df.loc[...]` 获得,会一次性将
+  指定时间范围内的多条序列读入内存。
+
+### TsFileDataFrame
+
+下表中 `df` 是一个 `TsFileDataFrame` 实例,由 `df = TsFileDataFrame(paths)` 创建。
+
+| 示例 | 操作 | 返回类型 |
+|---|---|---|
+| `TsFileDataFrame(paths)` | 加载文件 / 文件列表 / 目录 | `TsFileDataFrame` |
+| `len(df)` | 时间序列总数 | `int` |
+| `df.list_timeseries("weather")` | 获取序列名,可按前缀筛选 | `List[str]` |
+| `df["weather.Beijing.humidity"]`、`df[0]`、`df[-1]` | 获取单条序列 | `Timeseries` |
+| `df["city"]` | 获取某元数据列(标签 / `field` / `start_time` / `end_time` / `count`) | `pandas.Series` |
+| `df[0:3]`、`df[[0, 2, 5]]` | 获取子集视图 | `TsFileDataFrame` |
+| `df[df["city"] == "Beijing"]` | 按元数据列过滤 | `TsFileDataFrame` |
+| `df.loc[start:end, series_list]` | 按时间戳对齐查询 | `AlignedTimeseries` |
+| `df.show(max_rows=20)` / `print(df)` | 格式化元数据表格 | — |
+| `df.close()` | 释放文件句柄 | — |
+
+### Timeseries
+
+下表中 `ts` 是一条 `Timeseries`,由 `ts = df[...]` 获得。
+
+| 示例 | 操作 | 返回类型 |
+|---|---|---|
+| `ts.name` | 序列名 | `str` |
+| `len(ts)` | 序列点数 | `int` |
+| `ts.stats` | 序列统计信息 | `dict`(`start_time`、`end_time`、`count`) |
+| `ts[20]` | 单值读取 | `float`(空值为 `None`) |
+| `ts[20:100]` | 行范围切片 | `np.ndarray` |
+| `ts.timestamps` | 时间戳数组 | `np.ndarray` |
+
+### AlignedTimeseries
+
+下表中 `data` 是一个 `AlignedTimeseries`,由 `data = df.loc[...]` 获得。
+
+| 示例 | 操作 | 返回类型 |
+|---|---|---|
+| `data.timestamps` | 时间戳数组 | `np.ndarray` |
+| `data.values` | 值矩阵 | `np.ndarray`,shape `(N, M)` |
+| `data.series_names` | 序列名列表 | `List[str]` |
+| `data.shape` | 形状 `(N, M)`——N 为时间戳数,M 为序列数 | `tuple` |
+| `len(data)` | 行数 | `int` |
+| `data[0]`、`data[0:10]`、`data[0, 1]` | 行 / 元素索引 | `np.ndarray` / 标量 |
+| `data.show(50)` / `print(data)` | 格式化输出(自动截断) | — |
+
+## 序列名
+
+TsFileDataFrame 以**序列名**(一个字符串)作为序列的唯一标识。序列名由 **表名**、**各标签列的取值**、
+**字段名** 三部分按此顺序经 `.` 连接构成:
+
+```text
+{表名}.{标签值1}.{标签值2}...{字段名}
+```
+
+`list_timeseries()` 返回的即为序列名;按名称索引(`df[...]`)与 `df.loc[...]` 中的序列选择均以序列名为参数。
+
+示例:
+
+- `weather.Beijing.humidity` — 表 `weather`,标签 `Beijing`,字段 `humidity`
+- `sensor.s1.pressure` — 表 `sensor`,标签 `s1`,字段 `pressure`
+
+> 序列名可由 `list_timeseries()` 获取,无需手工构造;亦可改用整数索引(`df[0]`)或元数据过滤
+> (`df[df["city"] == "Beijing"]`)选择序列。
+
+## 加载
+
+路径可以是单个文件、文件列表或目录:

Review Comment:
   可以是目录列表吗?



##########
src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md:
##########
@@ -260,6 +296,41 @@ ERRNO tsfile_writer_write(TsFileWriter writer, Tablet tablet);
 
 
 
+## Configuration (encoding & compression)
+
+Columns are stored with the **global default** encoding and compression for their
+data type (a `ColumnSchema` does not carry codec settings). Change those
+defaults *before* creating a writer with the functions below.
+
+Each setter returns `RET_OK` (0) on success, or `RET_NOT_SUPPORT` (40) for an
+unsupported data-type/encoding or compression combination.
+
+```C
+/* Default value encoding per data type, and default compression. */
+int     set_datatype_encoding(uint8_t data_type, uint8_t encoding);
+int     set_global_compression(uint8_t compression);
+uint8_t get_datatype_encoding(uint8_t data_type);
+uint8_t get_global_compression();
+
+/* Time column (the time data type is fixed to INT64). */
+int     set_global_time_encoding(uint8_t encoding);
+int     set_global_time_compression(uint8_t compression);
+uint8_t get_global_time_encoding();
+uint8_t get_global_time_compression();
+```
+
+Allowed values: encoding accepts `PLAIN` for `BOOLEAN`; `PLAIN`/`TS_2DIFF`/
+`GORILLA`/`ZIGZAG`/`RLE`/`SPRINTZ` for `INT32`/`INT64`/`DATE`;
+`PLAIN`/`TS_2DIFF`/`GORILLA`/`SPRINTZ` for `FLOAT`/`DOUBLE`;
+`PLAIN`/`DICTIONARY` for `STRING`/`TEXT`. Compression accepts `UNCOMPRESSED`,
+`SNAPPY`, `GZIP`, `LZO`, or `LZ4`.
+

Review Comment:
   Better to list a table.



##########
src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-C.md:
##########
@@ -32,13 +32,46 @@ typedef enum {
     TS_DATATYPE_FLOAT = 3,
     TS_DATATYPE_DOUBLE = 4,
     TS_DATATYPE_TEXT = 5,
-    TS_DATATYPE_STRING = 11
+    TS_DATATYPE_TIMESTAMP = 8,
+    TS_DATATYPE_DATE = 9,
+    TS_DATATYPE_BLOB = 10,
+    TS_DATATYPE_STRING = 11,
+    TS_DATATYPE_INVALID = 255
 } TSDataType;
 
-typedef enum column_category { TAG = 0, FIELD = 1 } ColumnCategory;
-
-// ColumnSchema: Represents the schema of a single column, 
+// Value encoding.
+typedef enum {
+    TS_ENCODING_PLAIN = 0,
+    TS_ENCODING_DICTIONARY = 1,
+    TS_ENCODING_RLE = 2,
+    TS_ENCODING_TS_2DIFF = 4,
+    TS_ENCODING_GORILLA = 8,
+    TS_ENCODING_ZIGZAG = 9,
+    TS_ENCODING_SPRINTZ = 12,
+    TS_ENCODING_INVALID = 255
+} TSEncoding;
+
+// Compression type. LZ4 is the default.
+typedef enum {
+    TS_COMPRESSION_UNCOMPRESSED = 0,
+    TS_COMPRESSION_SNAPPY = 1,
+    TS_COMPRESSION_GZIP = 2,
+    TS_COMPRESSION_LZO = 3,
+    TS_COMPRESSION_LZ4 = 7,
+    TS_COMPRESSION_INVALID = 255
+} CompressionType;
+
+typedef enum column_category {
+    TAG = 0,
+    FIELD = 1,
+    ATTRIBUTE = 2,
+    TIME = 3
+} ColumnCategory;
+
+// ColumnSchema: Represents the schema of a single column,
 // including its name, data type, and category.
+// Encoding/compression for columns follow the global defaults
+// (see "Configuration" below).

Review Comment:
   This is valid for write, but invalid for read.
   TsFiles written by different programs may have different configurations.



##########
src/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-Python.md:
##########
@@ -140,148 +185,121 @@ class Tablet(object)
     
 ```
 
+### dataframe_to_tsfile
+
+```python
+def dataframe_to_tsfile(dataframe: pd.DataFrame,
+                        file_path: str,
+                        table_name: Optional[str] = None,
+                        time_column: Optional[str] = None,
+                        tag_column: Optional[list[str]] = None)
+    """
+    Write a pandas DataFrame to a TsFile.
+
+    :param dataframe:   the data to write.
+    :param file_path:   destination .tsfile path.
+    :param table_name:  output table name.
+    :param time_column: name of the column to use as the timestamp column.
+    :param tag_column:  names of the columns to treat as TAG columns.
+    """
+```
+
+## Configuration
+
+Global write defaults — the default per-type encodings, the default compression,
+and the time-column encoding/compression — are exposed as a single dictionary.
+Change them **before** creating a writer.
+
+```python
+from tsfile import get_tsfile_config, set_tsfile_config
+from tsfile import TSEncoding, Compressor
+
+cfg = get_tsfile_config()          # -> dict of all config values
+# e.g. cfg["default_compression_type_"], cfg["int64_encoding_type_"],
+#      cfg["time_encoding_type_"], cfg["time_compress_type_"], ...
+
+set_tsfile_config({
+    "default_compression_type_": Compressor.LZ4,
+    "int64_encoding_type_": TSEncoding.TS_2DIFF,
+})
+```
+
+`set_tsfile_config` validates each value and only updates the keys you pass.
+Encoding/compression values are `TSEncoding` / `Compressor` members; the same
+type-vs-encoding restrictions as the C++ API apply.
+

Review Comment:
   Also list the table here.
   The Python guys may not want to read another doc unnecessarily.



##########
src/UserGuide/develop/DataFrame/TsFileDataFrame.md:
##########
@@ -0,0 +1,287 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+# TsFileDataFrame
+
+`TsFileDataFrame` lets you read the time series inside one or more TsFiles the
+same way you would work with a pandas DataFrame — without having to care about
+the underlying file format or data-loading details. It is part of the Python
+package (`pip install tsfile`).
+
+## Quick start
+
+```python
+from tsfile import TsFileDataFrame
+
+df = TsFileDataFrame("table_data/")           # load every .tsfile under the directory
+print(df)                                     # browse all series (metadata only)
+
+ts = df["weather.Beijing.humidity"]           # pick one series (lazy handle)
+window = ts[20:100]                           # slice by row index -> np.ndarray
+
+data = df.loc[start:end, [                     # align multiple series on timestamps
+    "weather.Beijing.temperature",
+    "weather.Beijing.humidity",
+]]
+data.values                                   # -> np.ndarray, shape = (N, 2)
+```
+
+## Core types
+
+`TsFileDataFrame` is built around three types:
+
+- **`TsFileDataFrame`** — the entry point. It loads one or more TsFiles and
+  exposes a unified view. Construction only scans metadata; **no values are read**.
+- **`Timeseries`** — a lazy handle to a single series, obtained from `df[...]`.
+  It carries the series' metadata but reads nothing until you index it by row.
+- **`AlignedTimeseries`** — the result of aligning several series on a common
+  time axis, obtained from `df.loc[...]`. It reads the requested range of the
+  requested series into memory at once.
+
+### TsFileDataFrame
+
+In the table below, `df` is a `TsFileDataFrame` instance, created with
+`df = TsFileDataFrame(paths)`.
+
+| Example | Operation | Returns |
+|---|---|---|
+| `TsFileDataFrame(paths)` | Load a file / list of files / directory | `TsFileDataFrame` |
+| `len(df)` | Number of time series | `int` |
+| `df.list_timeseries("weather")` | Series names, optionally filtered by prefix | `List[str]` |
+| `df["weather.Beijing.humidity"]`, `df[0]`, `df[-1]` | One series | `Timeseries` |
+| `df["city"]` | A metadata column (a tag / `field` / `start_time` / `end_time` / `count`) | `pandas.Series` |
+| `df[0:3]`, `df[[0, 2, 5]]` | A subset view | `TsFileDataFrame` |
+| `df[df["city"] == "Beijing"]` | Filter by a metadata column | `TsFileDataFrame` |
+| `df.loc[start:end, series_list]` | Timestamp-aligned query | `AlignedTimeseries` |
+| `df.show(max_rows=20)` / `print(df)` | Formatted metadata table | — |
+| `df.close()` | Release file handles | — |
+
+### Timeseries
+
+In the table below, `ts` is a `Timeseries`, obtained from `ts = df[...]`.
+
+| Example | Operation | Returns |
+|---|---|---|
+| `ts.name` | Series name | `str` |
+| `len(ts)` | Number of points | `int` |
+| `ts.stats` | Series statistics | `dict` (`start_time`, `end_time`, `count`) |
+| `ts[20]` | Single value | `float` (or `None` if null) |
+| `ts[20:100]` | Row-range slice | `np.ndarray` |
+| `ts.timestamps` | Timestamp array | `np.ndarray` |
+
+### AlignedTimeseries
+
+In the table below, `data` is an `AlignedTimeseries`, obtained from
+`data = df.loc[...]`.
+
+| Example | Operation | Returns |
+|---|---|---|
+| `data.timestamps` | Timestamp array | `np.ndarray` |
+| `data.values` | Value matrix | `np.ndarray`, shape `(N, M)` |
+| `data.series_names` | Series names | `List[str]` |
+| `data.shape` | Shape `(N, M)` — N timestamps, M series | `tuple` |
+| `len(data)` | Number of rows | `int` |
+| `data[0]`, `data[0:10]`, `data[0, 1]` | Row / element indexing | `np.ndarray` / scalar |
+| `data.show(50)` / `print(data)` | Formatted output (auto-truncated) | — |
+
+## Series names
+
+A series is uniquely identified by its **series name**, a string formed by
+joining the **table name**, the **tag-column values**, and the **field name**
+with `.`, in that order:
+
+```text
+{table_name}.{tag_value_1}.{tag_value_2}...{field_name}
+```
+
+`list_timeseries()` returns series names; name-based indexing (`df[...]`) and
+series selection in `df.loc[...]` both take a series name.
+
+Examples:
+
+- `weather.Beijing.humidity` — table `weather`, tag `Beijing`, field `humidity`
+- `sensor.s1.pressure` — table `sensor`, tag `s1`, field `pressure`
+
+> A series name can be obtained from `list_timeseries()` and need not be
+> constructed by hand; a series may also be selected by integer index (`df[0]`)
+> or metadata filter (`df[df["city"] == "Beijing"]`).
+
+## Loading
+
+A path may be a single file, a list of files, or a directory:
+
+```python
+from tsfile import TsFileDataFrame
+
+df = TsFileDataFrame(["data/weather.tsfile", "data/sensor.tsfile"])
+df = TsFileDataFrame("data/")     # recursively find every .tsfile under the directory
+print(df)
+```
+
+Construction only scans metadata; actual values are not read. When several files
+are loaded, metadata is scanned in parallel.

Review Comment:
   Is it possible to control the concurrency and how?



##########
src/UserGuide/develop/DataFrame/TsFileDataFrame.md:
##########
@@ -0,0 +1,287 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+# TsFileDataFrame
+
+`TsFileDataFrame` lets you read the time series inside one or more TsFiles the
+same way you would work with a pandas DataFrame — without having to care about
+the underlying file format or data-loading details. It is part of the Python
+package (`pip install tsfile`).
+
+## Quick start
+
+```python
+from tsfile import TsFileDataFrame
+
+df = TsFileDataFrame("table_data/")           # load every .tsfile under the directory
+print(df)                                     # browse all series (metadata only)
+
+ts = df["weather.Beijing.humidity"]           # pick one series (lazy handle)
+window = ts[20:100]                           # slice by row index -> np.ndarray
+
+data = df.loc[start:end, [                     # align multiple series on timestamps
+    "weather.Beijing.temperature",
+    "weather.Beijing.humidity",
+]]
+data.values                                   # -> np.ndarray, shape = (N, 2)
+```
+
+## Core types
+
+`TsFileDataFrame` is built around three types:
+
+- **`TsFileDataFrame`** — the entry point. It loads one or more TsFiles and
+  exposes a unified view. Construction only scans metadata; **no values are read**.
+- **`Timeseries`** — a lazy handle to a single series, obtained from `df[...]`.
+  It carries the series' metadata but reads nothing until you index it by row.
+- **`AlignedTimeseries`** — the result of aligning several series on a common
+  time axis, obtained from `df.loc[...]`. It reads the requested range of the
+  requested series into memory at once.
+
+### TsFileDataFrame
+
+In the table below, `df` is a `TsFileDataFrame` instance, created with
+`df = TsFileDataFrame(paths)`.
+
+| Example | Operation | Returns |
+|---|---|---|
+| `TsFileDataFrame(paths)` | Load a file / list of files / directory | `TsFileDataFrame` |
+| `len(df)` | Number of time series | `int` |
+| `df.list_timeseries("weather")` | Series names, optionally filtered by prefix | `List[str]` |
+| `df["weather.Beijing.humidity"]`, `df[0]`, `df[-1]` | One series | `Timeseries` |
+| `df["city"]` | A metadata column (a tag / `field` / `start_time` / `end_time` / `count`) | `pandas.Series` |
+| `df[0:3]`, `df[[0, 2, 5]]` | A subset view | `TsFileDataFrame` |
+| `df[df["city"] == "Beijing"]` | Filter by a metadata column | `TsFileDataFrame` |
+| `df.loc[start:end, series_list]` | Timestamp-aligned query | `AlignedTimeseries` |
+| `df.show(max_rows=20)` / `print(df)` | Formatted metadata table | — |
+| `df.close()` | Release file handles | — |
+
+### Timeseries
+
+In the table below, `ts` is a `Timeseries`, obtained from `ts = df[...]`.
+
+| Example | Operation | Returns |
+|---|---|---|
+| `ts.name` | Series name | `str` |
+| `len(ts)` | Number of points | `int` |
+| `ts.stats` | Series statistics | `dict` (`start_time`, `end_time`, `count`) |
+| `ts[20]` | Single value | `float` (or `None` if null) |
+| `ts[20:100]` | Row-range slice | `np.ndarray` |
+| `ts.timestamps` | Timestamp array | `np.ndarray` |
+
+### AlignedTimeseries
+
+In the table below, `data` is an `AlignedTimeseries`, obtained from
+`data = df.loc[...]`.
+
+| Example | Operation | Returns |
+|---|---|---|
+| `data.timestamps` | Timestamp array | `np.ndarray` |
+| `data.values` | Value matrix | `np.ndarray`, shape `(N, M)` |
+| `data.series_names` | Series names | `List[str]` |
+| `data.shape` | Shape `(N, M)` — N timestamps, M series | `tuple` |
+| `len(data)` | Number of rows | `int` |
+| `data[0]`, `data[0:10]`, `data[0, 1]` | Row / element indexing | `np.ndarray` / scalar |
+| `data.show(50)` / `print(data)` | Formatted output (auto-truncated) | — |
+
+## Series names
+
+A series is uniquely identified by its **series name**, a string formed by
+joining the **table name**, the **tag-column values**, and the **field name**
+with `.`, in that order:
+
+```text
+{table_name}.{tag_value_1}.{tag_value_2}...{field_name}
+```
+
+`list_timeseries()` returns series names; name-based indexing (`df[...]`) and
+series selection in `df.loc[...]` both take a series name.
+
+Examples:
+
+- `weather.Beijing.humidity` — table `weather`, tag `Beijing`, field `humidity`
+- `sensor.s1.pressure` — table `sensor`, tag `s1`, field `pressure`
+
+> A series name can be obtained from `list_timeseries()` and need not be
+> constructed by hand; a series may also be selected by integer index (`df[0]`)
+> or metadata filter (`df[df["city"] == "Beijing"]`).
+
+## Loading
+
+A path may be a single file, a list of files, or a directory:
+
+```python
+from tsfile import TsFileDataFrame
+
+df = TsFileDataFrame(["data/weather.tsfile", "data/sensor.tsfile"])
+df = TsFileDataFrame("data/")     # recursively find every .tsfile under the directory
+print(df)
+```
+
+Construction only scans metadata; actual values are not read. When several files
+are loaded, metadata is scanned in parallel.
+
+If several files contain the **same series** (e.g. daily shards of
+`weather.Beijing.humidity`), they are merged into one continuous series. For
+duplicate timestamps only the first is kept — this is not an expected situation,

Review Comment:
   This should be highlighted since usually we expect the last one to be kept.



##########
src/UserGuide/develop/DataFrame/TsFileDataFrame.md:
##########
@@ -0,0 +1,287 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+# TsFileDataFrame
+
+`TsFileDataFrame` lets you read the time series inside one or more TsFiles the
+same way you would work with a pandas DataFrame — without having to care about
+the underlying file format or data-loading details. It is part of the Python
+package (`pip install tsfile`).
+
+## Quick start
+
+```python
+from tsfile import TsFileDataFrame
+
+df = TsFileDataFrame("table_data/")           # load every .tsfile under the directory
+print(df)                                     # browse all series (metadata only)
+
+ts = df["weather.Beijing.humidity"]           # pick one series (lazy handle)
+window = ts[20:100]                           # slice by row index -> np.ndarray
+
+data = df.loc[start:end, [                     # align multiple series on timestamps
+    "weather.Beijing.temperature",
+    "weather.Beijing.humidity",
+]]
+data.values                                   # -> np.ndarray, shape = (N, 2)
+```
+
+## Core types
+
+`TsFileDataFrame` is built around three types:
+
+- **`TsFileDataFrame`** — the entry point. It loads one or more TsFiles and
+  exposes a unified view. Construction only scans metadata; **no values are read**.
+- **`Timeseries`** — a lazy handle to a single series, obtained from `df[...]`.
+  It carries the series' metadata but reads nothing until you index it by row.
+- **`AlignedTimeseries`** — the result of aligning several series on a common
+  time axis, obtained from `df.loc[...]`. It reads the requested range of the
+  requested series into memory at once.
+
+### TsFileDataFrame
+
+In the table below, `df` is a `TsFileDataFrame` instance, created with
+`df = TsFileDataFrame(paths)`.
+
+| Example | Operation | Returns |
+|---|---|---|
+| `TsFileDataFrame(paths)` | Load a file / list of files / directory | `TsFileDataFrame` |
+| `len(df)` | Number of time series | `int` |
+| `df.list_timeseries("weather")` | Series names, optionally filtered by prefix | `List[str]` |
+| `df["weather.Beijing.humidity"]`, `df[0]`, `df[-1]` | One series | `Timeseries` |
+| `df["city"]` | A metadata column (a tag / `field` / `start_time` / `end_time` / `count`) | `pandas.Series` |
+| `df[0:3]`, `df[[0, 2, 5]]` | A subset view | `TsFileDataFrame` |
+| `df[df["city"] == "Beijing"]` | Filter by a metadata column | `TsFileDataFrame` |
+| `df.loc[start:end, series_list]` | Timestamp-aligned query | `AlignedTimeseries` |
+| `df.show(max_rows=20)` / `print(df)` | Formatted metadata table | — |
+| `df.close()` | Release file handles | — |
+
+### Timeseries
+
+In the table below, `ts` is a `Timeseries`, obtained from `ts = df[...]`.
+
+| Example | Operation | Returns |
+|---|---|---|
+| `ts.name` | Series name | `str` |
+| `len(ts)` | Number of points | `int` |
+| `ts.stats` | Series statistics | `dict` (`start_time`, `end_time`, `count`) |
+| `ts[20]` | Single value | `float` (or `None` if null) |
+| `ts[20:100]` | Row-range slice | `np.ndarray` |
+| `ts.timestamps` | Timestamp array | `np.ndarray` |
+
+### AlignedTimeseries
+
+In the table below, `data` is an `AlignedTimeseries`, obtained from
+`data = df.loc[...]`.
+
+| Example | Operation | Returns |
+|---|---|---|
+| `data.timestamps` | Timestamp array | `np.ndarray` |
+| `data.values` | Value matrix | `np.ndarray`, shape `(N, M)` |
+| `data.series_names` | Series names | `List[str]` |
+| `data.shape` | Shape `(N, M)` — N timestamps, M series | `tuple` |

Review Comment:
   May put `shape` first since it explains what `N` and `M` are.



##########
src/UserGuide/develop/DataFrame/TsFileDataFrame.md:
##########
@@ -0,0 +1,287 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+# TsFileDataFrame
+
+`TsFileDataFrame` lets you read the time series inside one or more TsFiles the
+same way you would work with a pandas DataFrame — without having to care about
+the underlying file format or data-loading details. It is part of the Python
+package (`pip install tsfile`).
+
+## Quick start
+
+```python
+from tsfile import TsFileDataFrame
+
+df = TsFileDataFrame("table_data/")           # load every .tsfile under the directory
+print(df)                                     # browse all series (metadata only)
+
+ts = df["weather.Beijing.humidity"]           # pick one series (lazy handle)
+window = ts[20:100]                           # slice by row index -> np.ndarray
+
+data = df.loc[start:end, [                     # align multiple series on timestamps
+    "weather.Beijing.temperature",
+    "weather.Beijing.humidity",
+]]
+data.values                                   # -> np.ndarray, shape = (N, 2)
+```
+
+## Core types
+
+`TsFileDataFrame` is built around three types:
+
+- **`TsFileDataFrame`** — the entry point. It loads one or more TsFiles and
+  exposes a unified view. Construction only scans metadata; **no values are read**.
+- **`Timeseries`** — a lazy handle to a single series, obtained from `df[...]`.
+  It carries the series' metadata but reads nothing until you index it by row.
+- **`AlignedTimeseries`** — the result of aligning several series on a common
+  time axis, obtained from `df.loc[...]`. It reads the requested range of the
+  requested series into memory at once.
+
+### TsFileDataFrame
+
+In the table below, `df` is a `TsFileDataFrame` instance, created with
+`df = TsFileDataFrame(paths)`.
+
+| Example | Operation | Returns |
+|---|---|---|
+| `TsFileDataFrame(paths)` | Load a file / list of files / directory | `TsFileDataFrame` |
+| `len(df)` | Number of time series | `int` |
+| `df.list_timeseries("weather")` | Series names, optionally filtered by prefix | `List[str]` |
+| `df["weather.Beijing.humidity"]`, `df[0]`, `df[-1]` | One series | `Timeseries` |
+| `df["city"]` | A metadata column (a tag / `field` / `start_time` / `end_time` / `count`) | `pandas.Series` |
+| `df[0:3]`, `df[[0, 2, 5]]` | A subset view | `TsFileDataFrame` |
+| `df[df["city"] == "Beijing"]` | Filter by a metadata column | `TsFileDataFrame` |
+| `df.loc[start:end, series_list]` | Timestamp-aligned query | `AlignedTimeseries` |
+| `df.show(max_rows=20)` / `print(df)` | Formatted metadata table | — |
+| `df.close()` | Release file handles | — |
+
+### Timeseries
+
+In the table below, `ts` is a `Timeseries`, obtained from `ts = df[...]`.
+
+| Example | Operation | Returns |
+|---|---|---|
+| `ts.name` | Series name | `str` |
+| `len(ts)` | Number of points | `int` |
+| `ts.stats` | Series statistics | `dict` (`start_time`, `end_time`, `count`) |
+| `ts[20]` | Single value | `float` (or `None` if null) |
+| `ts[20:100]` | Row-range slice | `np.ndarray` |
+| `ts.timestamps` | Timestamp array | `np.ndarray` |
+
+### AlignedTimeseries
+
+In the table below, `data` is an `AlignedTimeseries`, obtained from
+`data = df.loc[...]`.
+
+| Example | Operation | Returns |
+|---|---|---|
+| `data.timestamps` | Timestamp array | `np.ndarray` |
+| `data.values` | Value matrix | `np.ndarray`, shape `(N, M)` |
+| `data.series_names` | Series names | `List[str]` |
+| `data.shape` | Shape `(N, M)` — N timestamps, M series | `tuple` |
+| `len(data)` | Number of rows | `int` |
+| `data[0]`, `data[0:10]`, `data[0, 1]` | Row / element indexing | `np.ndarray` / scalar |
+| `data.show(50)` / `print(data)` | Formatted output (auto-truncated) | — |
+
+## Series names
+
+A series is uniquely identified by its **series name**, a string formed by
+joining the **table name**, the **tag-column values**, and the **field name**
+with `.`, in that order:
+
+```text
+{table_name}.{tag_value_1}.{tag_value_2}...{field_name}
+```
+
+`list_timeseries()` returns series names; name-based indexing (`df[...]`) and
+series selection in `df.loc[...]` both take a series name.
+
+Examples:
+
+- `weather.Beijing.humidity` — table `weather`, tag `Beijing`, field `humidity`
+- `sensor.s1.pressure` — table `sensor`, tag `s1`, field `pressure`
+
+> A series name can be obtained from `list_timeseries()` and need not be
+> constructed by hand; a series may also be selected by integer index (`df[0]`)
+> or metadata filter (`df[df["city"] == "Beijing"]`).
+
+## Loading
+
+A path may be a single file, a list of files, or a directory:
+
+```python
+from tsfile import TsFileDataFrame
+
+df = TsFileDataFrame(["data/weather.tsfile", "data/sensor.tsfile"])
+df = TsFileDataFrame("data/")     # recursively find every .tsfile under the directory
+print(df)
+```
+
+Construction only scans metadata; actual values are not read. When several files
+are loaded, metadata is scanned in parallel.
+
+If several files contain the **same series** (e.g. daily shards of
+`weather.Beijing.humidity`), they are merged into one continuous series. For
+duplicate timestamps only the first is kept — this is not an expected situation,
+so deduplicate during preprocessing to avoid metadata distortion.
+
+### Displaying a DataFrame
+
+`print(df)` (and `df.show(max_rows=...)`) prints series metadata, head/tail
+truncated when large. The header is:
+
+```text
+index │ table │ <tag1> │ <tag2> │ ... │ field │ start_time │ end_time │ count
+```
+
+For devices with different numbers of tags the tag values are left-aligned and
+shorter ones are padded with `None` at the end.
+
+```text
+TsFileDataFrame(table model, 972 time series, 5 files)
+     table  ps_id                    sn  frac                 field           start_time             end_time  count
+  0    pvf     10  30100194A00234H00572     1                   pac  2024-04-02 00:00:00  2024-10-28 23:45:00  20160
+  1    pvf     10  30100194A00234H00572     1    tenmeterswindspeed  2024-04-02 00:00:00  2024-10-28 23:45:00  20160
+...
+```
+
+### Closing
+
+A `with` block closes file handles automatically; you can also close manually:
+
+```python
+with TsFileDataFrame("data/") as df:
+    ...                       # handles released on exit
+
+tsdf = TsFileDataFrame("data/")
+tsdf.close()                  # or close it yourself
+```

Review Comment:
   This should be the last section?



##########
src/UserGuide/develop/Tools/Tsfile-CLI.md:
##########
@@ -0,0 +1,183 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+# tsfile-cli
+
+`tsfile-cli` is a single, pipe-friendly C++ command-line tool for inspecting
+**and** importing Apache TsFile (`.tsfile`) files from the shell. Read commands print data to **stdout** and
+diagnostics to **stderr**, so they compose with `awk`, `jq`, `sort`, and friends;
+the `write` command imports CSV/TSV into a new `.tsfile`. It is built on the
+public `TsFileReader` and `TsFileTableWriter` APIs.
+
+## Building from source
+
+The CLI is part of the C++ module. Build it with the Maven wrapper, which
+downloads a pinned CMake and compiles the whole C++ module (the `libtsfile`
+shared library + the `tsfile-cli` executable) for you.
+
+**Prerequisites:** a JDK (8+) to run Maven, and a C++11 compiler (GCC / Clang).
+The third-party C++ dependencies (Snappy, LZ4, LZOKAY, Zlib, …) are bundled under
+`cpp/third_party/` and built automatically.

Review Comment:
   Unnecessary to mention this.



##########
src/UserGuide/develop/Tools/Tsfile-CLI.md:
##########
@@ -0,0 +1,183 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+# tsfile-cli
+
+`tsfile-cli` is a single, pipe-friendly C++ command-line tool for inspecting
+**and** importing Apache TsFile (`.tsfile`) files from the shell. Read commands print data to **stdout** and
+diagnostics to **stderr**, so they compose with `awk`, `jq`, `sort`, and friends;
+the `write` command imports CSV/TSV into a new `.tsfile`. It is built on the
+public `TsFileReader` and `TsFileTableWriter` APIs.

Review Comment:
   May remove the last sentence, the user does not concern it.



##########
src/UserGuide/develop/Tools/Tsfile-CLI.md:
##########
@@ -0,0 +1,183 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+# tsfile-cli
+
+`tsfile-cli` is a single, pipe-friendly C++ command-line tool for inspecting
+**and** importing Apache TsFile (`.tsfile`) files from the shell. Read commands print data to **stdout** and
+diagnostics to **stderr**, so they compose with `awk`, `jq`, `sort`, and friends;
+the `write` command imports CSV/TSV into a new `.tsfile`. It is built on the
+public `TsFileReader` and `TsFileTableWriter` APIs.
+
+## Building from source
+
+The CLI is part of the C++ module. Build it with the Maven wrapper, which
+downloads a pinned CMake and compiles the whole C++ module (the `libtsfile`
+shared library + the `tsfile-cli` executable) for you.
+
+**Prerequisites:** a JDK (8+) to run Maven, and a C++11 compiler (GCC / Clang).
+The third-party C++ dependencies (Snappy, LZ4, LZOKAY, Zlib, …) are bundled under
+`cpp/third_party/` and built automatically.
+
+From the repository root:
+
+```bash
+./mvnw clean package -P with-cpp
+```
+
+This produces, under `cpp/target/build/`:
+
+| Artifact | Path |
+|---|---|
+| CLI executable | `cpp/target/build/bin/tsfile-cli` |
+| Shared library | `cpp/target/build/lib/libtsfile.so` (Linux) — `libtsfile.dylib` on macOS |
+
+`tsfile-cli` is dynamically linked against `libtsfile`. Run it **in place** by its
+full path and it finds the library automatically:
+
+```bash
+cpp/target/build/bin/tsfile-cli --version    # -> tsfile-cli (Apache TsFile C++) <version>
+cpp/target/build/bin/tsfile-cli --help
+```
+
+To run the binary from **somewhere else** (e.g. after copying it out of the build
+tree), the dynamic loader must be able to find `libtsfile.so`. Either point the
+loader at the build's `lib/` directory, or copy the library to a standard
+location:
+
+```bash
+# point the loader at the build's lib directory (Linux; macOS uses DYLD_LIBRARY_PATH)
+export LD_LIBRARY_PATH=/path/to/cpp/target/build/lib:$LD_LIBRARY_PATH
+
+# — or — copy the library to a system library path
+sudo cp cpp/target/build/lib/libtsfile.so /usr/local/lib/ && sudo ldconfig
+```
+
+## Usage
+
+```text
+tsfile-cli <command> [options] <file.tsfile>
+tsfile-cli --help | --version | help
+```
+
+Exit codes: `0` success, `1` usage/argument error, `2` file open/corrupt,
+`3` query/runtime error.
+
+### Reading
+
+| Command | Description |
+|---|---|
+| `ls` | List devices (tree model) or tables (table model), one name per line |
+| `schema` | Per-series `target, measurement, datatype, encoding, compression` |
+| `meta` | File summary: model, device/table/series counts, time range, file size |
+| `stats` | Per-series `count, start_time, end_time, min, max, first, last, sum` |
+| `count` | Per-series row counts plus a `total` row (from statistics, no page scan) |
+| `head` | First N rows (default 10; use `-n`) |
+| `cat` | All matching rows, streamed (`table` format buffers to align columns) |
+| `sample` | Reproducible reservoir sample (default 10; `-n`, `--seed`) |
+
+The metadata commands (`ls` / `schema` / `meta` / `stats` / `count`) answer most
+questions **without decoding data pages**.
+
+Shared options:
+
+| Option | Meaning |
+|---|---|
+| `-f, --format csv\|tsv\|json\|table` | Output format; defaults to `table` on a TTY, `tsv` when piped |
+| `-d, --device <id>` / `-t, --table <name>` | Scope to one device / table (mutually exclusive) |
+| `-m, --measurements a,b,c` | Column projection (`schema`, `stats`, `count`, `head`, `cat`, `sample`) |
+| `-n, --limit N` / `--offset N` | Max rows / rows to skip (`head`, `cat`; `--offset` not valid for `sample`) |
+| `--start <ms>` / `--end <ms>` | Inclusive epoch-millisecond time range (`head`, `cat`, `sample`) |
+| `--seed N` | Reproducible sampling seed (`sample` only) |
+| `--tag-filter C OP V` / `--tag-between C L U` / `--tag-not-between C L U` | Table TAG predicate for `head`, `cat`, `sample`; `OP` is `eq`, `neq`, `lt`, `lteq`, `gt`, `gteq`, `regexp`, or `not-regexp` |
+| `--no-header` | Omit the header row |
+| `--model tree\|table` | Force the model (otherwise auto-detected) |
+
+`json` output is NDJSON (one object per line; numbers/booleans bare, other values

Review Comment:
   What is an object here?



##########
src/zh/UserGuide/develop/DataFrame/TsFileDataFrame.md:
##########
@@ -0,0 +1,270 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+# TsFileDataFrame
+
+`TsFileDataFrame` 让你像操作 pandas DataFrame 一样读取一个或多个 TsFile 中的时序数据,
+无需关心底层文件格式与数据加载细节。它是 Python 包的一部分(`pip install tsfile`)。
+
+## 快速上手
+
+```python
+from tsfile import TsFileDataFrame
+
+df = TsFileDataFrame("table_data/")           # 加载目录下所有 .tsfile
+print(df)                                     # 浏览所有序列(仅元数据)
+
+ts = df["weather.Beijing.humidity"]           # 取一条序列(懒加载句柄)
+window = ts[20:100]                           # 按行号切片 -> np.ndarray
+
+data = df.loc[start:end, [                     # 按时间戳对齐多条序列
+    "weather.Beijing.temperature",
+    "weather.Beijing.humidity",
+]]
+data.values                                   # -> np.ndarray, shape = (N, 2)
+```
+
+## 核心类型
+
+`TsFileDataFrame` 围绕三个核心类型:
+
+- **`TsFileDataFrame`**:入口对象,加载一至多个 TsFile 并提供统一视图。初始化时只扫描元数据,
+  **不读取实际数值**。
+- **`Timeseries`**:单条序列的懒加载句柄,通过 `df[...]` 获得。它携带序列元信息,但在按行号索引前
+  不读取任何数据。
+- **`AlignedTimeseries`**:多条序列在同一时间轴上的对齐结果,通过 `df.loc[...]` 获得,会一次性将
+  指定时间范围内的多条序列读入内存。
+
+### TsFileDataFrame
+
+下表中 `df` 是一个 `TsFileDataFrame` 实例,由 `df = TsFileDataFrame(paths)` 创建。
+
+| 示例 | 操作 | 返回类型 |
+|---|---|---|
+| `TsFileDataFrame(paths)` | 加载文件 / 文件列表 / 目录 | `TsFileDataFrame` |
+| `len(df)` | 时间序列总数 | `int` |
+| `df.list_timeseries("weather")` | 获取序列名,可按前缀筛选 | `List[str]` |
+| `df["weather.Beijing.humidity"]`、`df[0]`、`df[-1]` | 获取单条序列 | `Timeseries` |
+| `df["city"]` | 获取某元数据列(标签 / `field` / `start_time` / `end_time` / `count`) | `pandas.Series` |
+| `df[0:3]`、`df[[0, 2, 5]]` | 获取子集视图 | `TsFileDataFrame` |
+| `df[df["city"] == "Beijing"]` | 按元数据列过滤 | `TsFileDataFrame` |
+| `df.loc[start:end, series_list]` | 按时间戳对齐查询 | `AlignedTimeseries` |
+| `df.show(max_rows=20)` / `print(df)` | 格式化元数据表格 | — |
+| `df.close()` | 释放文件句柄 | — |
+
+### Timeseries
+
+下表中 `ts` 是一条 `Timeseries`,由 `ts = df[...]` 获得。
+
+| 示例 | 操作 | 返回类型 |
+|---|---|---|
+| `ts.name` | 序列名 | `str` |
+| `len(ts)` | 序列点数 | `int` |
+| `ts.stats` | 序列统计信息 | `dict`(`start_time`、`end_time`、`count`) |
+| `ts[20]` | 单值读取 | `float`(空值为 `None`) |
+| `ts[20:100]` | 行范围切片 | `np.ndarray` |
+| `ts.timestamps` | 时间戳数组 | `np.ndarray` |
+
+### AlignedTimeseries
+
+下表中 `data` 是一个 `AlignedTimeseries`,由 `data = df.loc[...]` 获得。
+
+| 示例 | 操作 | 返回类型 |
+|---|---|---|
+| `data.timestamps` | 时间戳数组 | `np.ndarray` |
+| `data.values` | 值矩阵 | `np.ndarray`,shape `(N, M)` |
+| `data.series_names` | 序列名列表 | `List[str]` |
+| `data.shape` | 形状 `(N, M)`——N 为时间戳数,M 为序列数 | `tuple` |
+| `len(data)` | 行数 | `int` |
+| `data[0]`、`data[0:10]`、`data[0, 1]` | 行 / 元素索引 | `np.ndarray` / 标量 |
+| `data.show(50)` / `print(data)` | 格式化输出(自动截断) | — |
+
+## 序列名
+
+TsFileDataFrame 以**序列名**(一个字符串)作为序列的唯一标识。序列名由 **表名**、**各标签列的取值**、
+**字段名** 三部分按此顺序经 `.` 连接构成:
+
+```text
+{表名}.{标签值1}.{标签值2}...{字段名}
+```
+
+`list_timeseries()` 返回的即为序列名;按名称索引(`df[...]`)与 `df.loc[...]` 中的序列选择均以序列名为参数。
+
+示例:
+
+- `weather.Beijing.humidity` — 表 `weather`,标签 `Beijing`,字段 `humidity`
+- `sensor.s1.pressure` — 表 `sensor`,标签 `s1`,字段 `pressure`
+
+> 序列名可由 `list_timeseries()` 获取,无需手工构造;亦可改用整数索引(`df[0]`)或元数据过滤
+> (`df[df["city"] == "Beijing"]`)选择序列。
+
+## 加载
+
+路径可以是单个文件、文件列表或目录:
+
+```python
+from tsfile import TsFileDataFrame
+
+df = TsFileDataFrame(["data/weather.tsfile", "data/sensor.tsfile"])
+df = TsFileDataFrame("data/")     # 递归查找目录下所有 .tsfile
+print(df)
+```
+
+初始化时只扫描元数据,不读取实际数值。加载多个文件时会并行扫描元数据。
+
+如果多个文件包含 **同名序列**(如按日分片的 `weather.Beijing.humidity`),会自动合并为一条连续序列。
+对于重复时间戳仅保留第一条——这并非预期情况,请在预处理阶段去重,以免造成元数据失真。
+
+### DataFrame 的展示
+
+`print(df)`(以及 `df.show(max_rows=...)`)打印序列元信息,数据量大时头尾截断。表头为:
+
+```text
+index │ table │ <tag1> │ <tag2> │ ... │ field │ start_time │ end_time │ count
+```
+
+对于标签数量不同的设备:标签值按左对齐,较短的在末尾补 `None`。
+
+```text
+TsFileDataFrame(table model, 972 time series, 5 files)
+     table  ps_id                    sn  frac                 field           start_time             end_time  count
+  0    pvf     10  30100194A00234H00572     1                   pac  2024-04-02 00:00:00  2024-10-28 23:45:00  20160
+  1    pvf     10  30100194A00234H00572     1    tenmeterswindspeed  2024-04-02 00:00:00  2024-10-28 23:45:00  20160
+...
+```

Review Comment:
   什么是左对齐?
   简单说缺失部分补 None 就行。
   需要说明多个表的 tag 顺序不同时,如何处理等。



##########
src/zh/UserGuide/develop/DataFrame/TsFileDataFrame.md:
##########
@@ -0,0 +1,270 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+# TsFileDataFrame
+
+`TsFileDataFrame` 让你像操作 pandas DataFrame 一样读取一个或多个 TsFile 中的时序数据,
+无需关心底层文件格式与数据加载细节。它是 Python 包的一部分(`pip install tsfile`)。
+
+## 快速上手
+
+```python
+from tsfile import TsFileDataFrame
+
+df = TsFileDataFrame("table_data/")           # 加载目录下所有 .tsfile
+print(df)                                     # 浏览所有序列(仅元数据)
+
+ts = df["weather.Beijing.humidity"]           # 取一条序列(懒加载句柄)
+window = ts[20:100]                           # 按行号切片 -> np.ndarray
+
+data = df.loc[start:end, [                     # 按时间戳对齐多条序列
+    "weather.Beijing.temperature",
+    "weather.Beijing.humidity",
+]]
+data.values                                   # -> np.ndarray, shape = (N, 2)
+```
+
+## 核心类型
+
+`TsFileDataFrame` 围绕三个核心类型:
+
+- **`TsFileDataFrame`**:入口对象,加载一至多个 TsFile 并提供统一视图。初始化时只扫描元数据,
+  **不读取实际数值**。
+- **`Timeseries`**:单条序列的懒加载句柄,通过 `df[...]` 获得。它携带序列元信息,但在按行号索引前
+  不读取任何数据。
+- **`AlignedTimeseries`**:多条序列在同一时间轴上的对齐结果,通过 `df.loc[...]` 获得,会一次性将
+  指定时间范围内的多条序列读入内存。
+
+### TsFileDataFrame
+
+下表中 `df` 是一个 `TsFileDataFrame` 实例,由 `df = TsFileDataFrame(paths)` 创建。
+
+| 示例 | 操作 | 返回类型 |
+|---|---|---|
+| `TsFileDataFrame(paths)` | 加载文件 / 文件列表 / 目录 | `TsFileDataFrame` |
+| `len(df)` | 时间序列总数 | `int` |
+| `df.list_timeseries("weather")` | 获取序列名,可按前缀筛选 | `List[str]` |
+| `df["weather.Beijing.humidity"]`、`df[0]`、`df[-1]` | 获取单条序列 | `Timeseries` |
+| `df["city"]` | 获取某元数据列(标签 / `field` / `start_time` / `end_time` / `count`) | `pandas.Series` |
+| `df[0:3]`、`df[[0, 2, 5]]` | 获取子集视图 | `TsFileDataFrame` |
+| `df[df["city"] == "Beijing"]` | 按元数据列过滤 | `TsFileDataFrame` |
+| `df.loc[start:end, series_list]` | 按时间戳对齐查询 | `AlignedTimeseries` |
+| `df.show(max_rows=20)` / `print(df)` | 格式化元数据表格 | — |

Review Comment:
   格式化?



##########
src/zh/UserGuide/develop/QuickStart/InterfaceDefinition/InterfaceDefinition-CPP.md:
##########
@@ -20,96 +20,121 @@
 -->
 # 接口定义 - C++
 
+## 数据类型、编码与压缩
+
+下列枚举为读写接口共用。其数值编码同时也是磁盘上存储的取值。

Review Comment:
   感觉这句话对用户没什么价值



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@tsfile.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Tsfile doc [tsfile]

Posted by "leto-bbq (via GitHub)" <gi...@apache.org>.
leto-bbq commented on code in PR #846:
URL: https://github.com/apache/tsfile/pull/846#discussion_r3464464323


##########
src/zh/UserGuide/latest/Tools/Tsfile-Viewer.md:
##########
@@ -0,0 +1,101 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+# tsfile-viewer

Review Comment:
   文档标题建议首字母大写



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@tsfile.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Tsfile doc [tsfile]

Posted by "ColinLeeo (via GitHub)" <gi...@apache.org>.
ColinLeeo commented on code in PR #846:
URL: https://github.com/apache/tsfile/pull/846#discussion_r3471639695


##########
src/zh/UserGuide/latest/Tools/Tsfile-CLI.md:
##########
@@ -0,0 +1,174 @@
+<!--
+
+    Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+-->
+# tsfile-cli

Review Comment:
   Good idea and already modified.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: notifications-unsubscribe@tsfile.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org