From b668fccd9fc09e64879db33d712e97bf48001ab3 Mon Sep 17 00:00:00 2001 From: ColinLee Date: Thu, 25 Jun 2026 18:36:34 +0800 Subject: [PATCH 1/2] update dataframe series schema. --- .../develop/DataFrame/TsFileDataFrame.md | 25 +++++++++++-------- .../latest/DataFrame/TsFileDataFrame.md | 25 +++++++++++-------- .../develop/DataFrame/TsFileDataFrame.md | 7 +++--- .../latest/DataFrame/TsFileDataFrame.md | 7 +++--- 4 files changed, 36 insertions(+), 28 deletions(-) diff --git a/src/UserGuide/develop/DataFrame/TsFileDataFrame.md b/src/UserGuide/develop/DataFrame/TsFileDataFrame.md index db290bbd6..91a32ee8e 100644 --- a/src/UserGuide/develop/DataFrame/TsFileDataFrame.md +++ b/src/UserGuide/develop/DataFrame/TsFileDataFrame.md @@ -113,25 +113,28 @@ with `.`, in that order: {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. +`list_timeseries()` returns `SeriesPath` objects — a `str` subclass whose value +is the escaped path above, so each works directly as a key in `df[...]` and +`df.loc[...]`. A `SeriesPath` also exposes its parts as `.table`, `.tags` (a +tuple, with `None` for a null tag), and `.field`. Examples: - `weather.Beijing.humidity` — table `weather`, tag `Beijing`, field `humidity` - `sensor.s1.pressure` — table `sensor`, tag `s1`, field `pressure` -**Dots inside a name.** Because `.` separates the parts, a `.` that belongs to a -table, tag, or field name is escaped with a backslash. `list_timeseries()` -returns the escaped form — e.g. a `weather` table with tag value `Bei.jing` and -field `humidity` is rendered as `weather.Bei\.jing.humidity` (a literal `\` -becomes `\\`). Selecting it needs the same escaped form: the unescaped -`weather.Bei.jing.humidity` would be read as two tags `Bei` and `jing`. Reuse the -string `list_timeseries()` returns, or type it as a raw string so Python keeps -the backslash: +**Escaping in a name.** `.` separates the parts, so a `.` inside a table, tag, or +field name is escaped with a backslash, and a null tag value is written as `\N` +(distinct from the literal string `"null"`). `list_timeseries()` returns this +escaped form — e.g. tag value `Bei.jing` in table `weather` renders as +`weather.Bei\.jing.humidity` (a literal `\` becomes `\\`). Selecting needs the +same escaped form, so reuse the `SeriesPath` from `list_timeseries()` (or read +its `.table` / `.tags` / `.field` parts) rather than hand-building it; if you do +type one, use a raw string so Python keeps the backslash: ```python -df[r"weather.Bei\.jing.humidity"] # selects the device whose tag is "Bei.jing" +df[r"weather.Bei\.jing.humidity"] # tag "Bei.jing" (the dot is part of the value) +df[r"weather.\N.Beijing.humidity"] # tags (null, "Beijing") ``` > A series name can be obtained from `list_timeseries()` and need not be diff --git a/src/UserGuide/latest/DataFrame/TsFileDataFrame.md b/src/UserGuide/latest/DataFrame/TsFileDataFrame.md index db290bbd6..91a32ee8e 100644 --- a/src/UserGuide/latest/DataFrame/TsFileDataFrame.md +++ b/src/UserGuide/latest/DataFrame/TsFileDataFrame.md @@ -113,25 +113,28 @@ with `.`, in that order: {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. +`list_timeseries()` returns `SeriesPath` objects — a `str` subclass whose value +is the escaped path above, so each works directly as a key in `df[...]` and +`df.loc[...]`. A `SeriesPath` also exposes its parts as `.table`, `.tags` (a +tuple, with `None` for a null tag), and `.field`. Examples: - `weather.Beijing.humidity` — table `weather`, tag `Beijing`, field `humidity` - `sensor.s1.pressure` — table `sensor`, tag `s1`, field `pressure` -**Dots inside a name.** Because `.` separates the parts, a `.` that belongs to a -table, tag, or field name is escaped with a backslash. `list_timeseries()` -returns the escaped form — e.g. a `weather` table with tag value `Bei.jing` and -field `humidity` is rendered as `weather.Bei\.jing.humidity` (a literal `\` -becomes `\\`). Selecting it needs the same escaped form: the unescaped -`weather.Bei.jing.humidity` would be read as two tags `Bei` and `jing`. Reuse the -string `list_timeseries()` returns, or type it as a raw string so Python keeps -the backslash: +**Escaping in a name.** `.` separates the parts, so a `.` inside a table, tag, or +field name is escaped with a backslash, and a null tag value is written as `\N` +(distinct from the literal string `"null"`). `list_timeseries()` returns this +escaped form — e.g. tag value `Bei.jing` in table `weather` renders as +`weather.Bei\.jing.humidity` (a literal `\` becomes `\\`). Selecting needs the +same escaped form, so reuse the `SeriesPath` from `list_timeseries()` (or read +its `.table` / `.tags` / `.field` parts) rather than hand-building it; if you do +type one, use a raw string so Python keeps the backslash: ```python -df[r"weather.Bei\.jing.humidity"] # selects the device whose tag is "Bei.jing" +df[r"weather.Bei\.jing.humidity"] # tag "Bei.jing" (the dot is part of the value) +df[r"weather.\N.Beijing.humidity"] # tags (null, "Beijing") ``` > A series name can be obtained from `list_timeseries()` and need not be diff --git a/src/zh/UserGuide/develop/DataFrame/TsFileDataFrame.md b/src/zh/UserGuide/develop/DataFrame/TsFileDataFrame.md index 0a8876c9b..816a8cca6 100644 --- a/src/zh/UserGuide/develop/DataFrame/TsFileDataFrame.md +++ b/src/zh/UserGuide/develop/DataFrame/TsFileDataFrame.md @@ -106,17 +106,18 @@ TsFileDataFrame 以**序列名**（一个字符串）作为序列的唯一标识 {表名}.{标签值1}.{标签值2}...{字段名} ``` -`list_timeseries()` 返回的即为序列名；按名称索引（`df[...]`）与 `df.loc[...]` 中的序列选择均以序列名为参数。 +`list_timeseries()` 返回 `SeriesPath` 对象——`str` 的子类，其字符串值即上面的转义路径，可直接用作 `df[...]`、`df.loc[...]` 的键；它还以 `.table`、`.tags`（元组，`None` 表示空标签）、`.field` 暴露各组成部分。 示例： - `weather.Beijing.humidity` — 表 `weather`，标签 `Beijing`，字段 `humidity` - `sensor.s1.pressure` — 表 `sensor`，标签 `s1`，字段 `pressure` -**名称中含点号时。** 由于 `.` 用作分隔符，属于表名/标签/字段名本身的 `.` 会用反斜杠转义。`list_timeseries()` 返回的是转义后的形式——例如表 `weather`、标签值 `Bei.jing`、字段 `humidity`，渲染为 `weather.Bei\.jing.humidity`（字面 `\` 转义为 `\\`）。选取时也要用这种转义形式：若传未转义的 `weather.Bei.jing.humidity`，会被当成 `Bei`、`jing` 两个标签。直接复用 `list_timeseries()` 的返回值，或用 raw string 让 Python 保留反斜杠： +**名称中的转义。** `.` 用作分隔符，因此属于表名/标签/字段名本身的 `.` 会用反斜杠转义；空标签值写作 `\N`（与字面字符串 `"null"` 区分）。`list_timeseries()` 返回的就是这种转义形式——例如表 `weather` 中标签值 `Bei.jing`、字段 `humidity` 渲染为 `weather.Bei\.jing.humidity`（字面 `\` 转义为 `\\`）。选取时也要用这种转义形式，因此请直接复用 `list_timeseries()` 返回的 `SeriesPath`（或读取它的 `.table`/`.tags`/`.field`），不要手拼；若确需手写，请用 raw string 让 Python 保留反斜杠： ```python -df[r"weather.Bei\.jing.humidity"] # 选中标签为 "Bei.jing" 的设备 +df[r"weather.Bei\.jing.humidity"] # 标签 "Bei.jing"（点号是值的一部分） +df[r"weather.\N.Beijing.humidity"] # 标签 (null, "Beijing") ``` > 序列名可由 `list_timeseries()` 获取，无需手工构造；亦可改用整数索引（`df[0]`）或元数据过滤 diff --git a/src/zh/UserGuide/latest/DataFrame/TsFileDataFrame.md b/src/zh/UserGuide/latest/DataFrame/TsFileDataFrame.md index 0a8876c9b..816a8cca6 100644 --- a/src/zh/UserGuide/latest/DataFrame/TsFileDataFrame.md +++ b/src/zh/UserGuide/latest/DataFrame/TsFileDataFrame.md @@ -106,17 +106,18 @@ TsFileDataFrame 以**序列名**（一个字符串）作为序列的唯一标识 {表名}.{标签值1}.{标签值2}...{字段名} ``` -`list_timeseries()` 返回的即为序列名；按名称索引（`df[...]`）与 `df.loc[...]` 中的序列选择均以序列名为参数。 +`list_timeseries()` 返回 `SeriesPath` 对象——`str` 的子类，其字符串值即上面的转义路径，可直接用作 `df[...]`、`df.loc[...]` 的键；它还以 `.table`、`.tags`（元组，`None` 表示空标签）、`.field` 暴露各组成部分。 示例： - `weather.Beijing.humidity` — 表 `weather`，标签 `Beijing`，字段 `humidity` - `sensor.s1.pressure` — 表 `sensor`，标签 `s1`，字段 `pressure` -**名称中含点号时。** 由于 `.` 用作分隔符，属于表名/标签/字段名本身的 `.` 会用反斜杠转义。`list_timeseries()` 返回的是转义后的形式——例如表 `weather`、标签值 `Bei.jing`、字段 `humidity`，渲染为 `weather.Bei\.jing.humidity`（字面 `\` 转义为 `\\`）。选取时也要用这种转义形式：若传未转义的 `weather.Bei.jing.humidity`，会被当成 `Bei`、`jing` 两个标签。直接复用 `list_timeseries()` 的返回值，或用 raw string 让 Python 保留反斜杠： +**名称中的转义。** `.` 用作分隔符，因此属于表名/标签/字段名本身的 `.` 会用反斜杠转义；空标签值写作 `\N`（与字面字符串 `"null"` 区分）。`list_timeseries()` 返回的就是这种转义形式——例如表 `weather` 中标签值 `Bei.jing`、字段 `humidity` 渲染为 `weather.Bei\.jing.humidity`（字面 `\` 转义为 `\\`）。选取时也要用这种转义形式，因此请直接复用 `list_timeseries()` 返回的 `SeriesPath`（或读取它的 `.table`/`.tags`/`.field`），不要手拼；若确需手写，请用 raw string 让 Python 保留反斜杠： ```python -df[r"weather.Bei\.jing.humidity"] # 选中标签为 "Bei.jing" 的设备 +df[r"weather.Bei\.jing.humidity"] # 标签 "Bei.jing"（点号是值的一部分） +df[r"weather.\N.Beijing.humidity"] # 标签 (null, "Beijing") ``` > 序列名可由 `list_timeseries()` 获取，无需手工构造；亦可改用整数索引（`df[0]`）或元数据过滤 From b6488690ca4d544f341d0c4aeafeb74483200775 Mon Sep 17 00:00:00 2001 From: ColinLee Date: Thu, 25 Jun 2026 19:06:06 +0800 Subject: [PATCH 2/2] docs: reword raw-string note in TsFileDataFrame series names Co-Authored-By: Claude Opus 4.8 (1M context) --- src/UserGuide/develop/DataFrame/TsFileDataFrame.md | 6 +++--- src/UserGuide/latest/DataFrame/TsFileDataFrame.md | 6 +++--- src/zh/UserGuide/develop/DataFrame/TsFileDataFrame.md | 2 +- src/zh/UserGuide/latest/DataFrame/TsFileDataFrame.md | 2 +- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/UserGuide/develop/DataFrame/TsFileDataFrame.md b/src/UserGuide/develop/DataFrame/TsFileDataFrame.md index 91a32ee8e..1b90dcd3e 100644 --- a/src/UserGuide/develop/DataFrame/TsFileDataFrame.md +++ b/src/UserGuide/develop/DataFrame/TsFileDataFrame.md @@ -128,9 +128,9 @@ field name is escaped with a backslash, and a null tag value is written as `\N` (distinct from the literal string `"null"`). `list_timeseries()` returns this escaped form — e.g. tag value `Bei.jing` in table `weather` renders as `weather.Bei\.jing.humidity` (a literal `\` becomes `\\`). Selecting needs the -same escaped form, so reuse the `SeriesPath` from `list_timeseries()` (or read -its `.table` / `.tags` / `.field` parts) rather than hand-building it; if you do -type one, use a raw string so Python keeps the backslash: +same escaped form: reuse the `SeriesPath` from `list_timeseries()` (or read its +`.table` / `.tags` / `.field` parts), or write one as a raw string to keep the +backslash: ```python df[r"weather.Bei\.jing.humidity"] # tag "Bei.jing" (the dot is part of the value) diff --git a/src/UserGuide/latest/DataFrame/TsFileDataFrame.md b/src/UserGuide/latest/DataFrame/TsFileDataFrame.md index 91a32ee8e..1b90dcd3e 100644 --- a/src/UserGuide/latest/DataFrame/TsFileDataFrame.md +++ b/src/UserGuide/latest/DataFrame/TsFileDataFrame.md @@ -128,9 +128,9 @@ field name is escaped with a backslash, and a null tag value is written as `\N` (distinct from the literal string `"null"`). `list_timeseries()` returns this escaped form — e.g. tag value `Bei.jing` in table `weather` renders as `weather.Bei\.jing.humidity` (a literal `\` becomes `\\`). Selecting needs the -same escaped form, so reuse the `SeriesPath` from `list_timeseries()` (or read -its `.table` / `.tags` / `.field` parts) rather than hand-building it; if you do -type one, use a raw string so Python keeps the backslash: +same escaped form: reuse the `SeriesPath` from `list_timeseries()` (or read its +`.table` / `.tags` / `.field` parts), or write one as a raw string to keep the +backslash: ```python df[r"weather.Bei\.jing.humidity"] # tag "Bei.jing" (the dot is part of the value) diff --git a/src/zh/UserGuide/develop/DataFrame/TsFileDataFrame.md b/src/zh/UserGuide/develop/DataFrame/TsFileDataFrame.md index 816a8cca6..9fec27c88 100644 --- a/src/zh/UserGuide/develop/DataFrame/TsFileDataFrame.md +++ b/src/zh/UserGuide/develop/DataFrame/TsFileDataFrame.md @@ -113,7 +113,7 @@ TsFileDataFrame 以**序列名**（一个字符串）作为序列的唯一标识 - `weather.Beijing.humidity` — 表 `weather`，标签 `Beijing`，字段 `humidity` - `sensor.s1.pressure` — 表 `sensor`，标签 `s1`，字段 `pressure` -**名称中的转义。** `.` 用作分隔符，因此属于表名/标签/字段名本身的 `.` 会用反斜杠转义；空标签值写作 `\N`（与字面字符串 `"null"` 区分）。`list_timeseries()` 返回的就是这种转义形式——例如表 `weather` 中标签值 `Bei.jing`、字段 `humidity` 渲染为 `weather.Bei\.jing.humidity`（字面 `\` 转义为 `\\`）。选取时也要用这种转义形式，因此请直接复用 `list_timeseries()` 返回的 `SeriesPath`（或读取它的 `.table`/`.tags`/`.field`），不要手拼；若确需手写，请用 raw string 让 Python 保留反斜杠： +**名称中的转义。** `.` 用作分隔符，因此属于表名/标签/字段名本身的 `.` 会用反斜杠转义；空标签值写作 `\N`（与字面字符串 `"null"` 区分）。`list_timeseries()` 返回的就是这种转义形式——例如表 `weather` 中标签值 `Bei.jing`、字段 `humidity` 渲染为 `weather.Bei\.jing.humidity`（字面 `\` 转义为 `\\`）。选取时也要用这种转义形式：可直接复用 `list_timeseries()` 返回的 `SeriesPath`（或读取它的 `.table`/`.tags`/`.field`），或用 raw string 保留反斜杠： ```python df[r"weather.Bei\.jing.humidity"] # 标签 "Bei.jing"（点号是值的一部分） diff --git a/src/zh/UserGuide/latest/DataFrame/TsFileDataFrame.md b/src/zh/UserGuide/latest/DataFrame/TsFileDataFrame.md index 816a8cca6..9fec27c88 100644 --- a/src/zh/UserGuide/latest/DataFrame/TsFileDataFrame.md +++ b/src/zh/UserGuide/latest/DataFrame/TsFileDataFrame.md @@ -113,7 +113,7 @@ TsFileDataFrame 以**序列名**（一个字符串）作为序列的唯一标识 - `weather.Beijing.humidity` — 表 `weather`，标签 `Beijing`，字段 `humidity` - `sensor.s1.pressure` — 表 `sensor`，标签 `s1`，字段 `pressure` -**名称中的转义。** `.` 用作分隔符，因此属于表名/标签/字段名本身的 `.` 会用反斜杠转义；空标签值写作 `\N`（与字面字符串 `"null"` 区分）。`list_timeseries()` 返回的就是这种转义形式——例如表 `weather` 中标签值 `Bei.jing`、字段 `humidity` 渲染为 `weather.Bei\.jing.humidity`（字面 `\` 转义为 `\\`）。选取时也要用这种转义形式，因此请直接复用 `list_timeseries()` 返回的 `SeriesPath`（或读取它的 `.table`/`.tags`/`.field`），不要手拼；若确需手写，请用 raw string 让 Python 保留反斜杠： +**名称中的转义。** `.` 用作分隔符，因此属于表名/标签/字段名本身的 `.` 会用反斜杠转义；空标签值写作 `\N`（与字面字符串 `"null"` 区分）。`list_timeseries()` 返回的就是这种转义形式——例如表 `weather` 中标签值 `Bei.jing`、字段 `humidity` 渲染为 `weather.Bei\.jing.humidity`（字面 `\` 转义为 `\\`）。选取时也要用这种转义形式：可直接复用 `list_timeseries()` 返回的 `SeriesPath`（或读取它的 `.table`/`.tags`/`.field`），或用 raw string 保留反斜杠： ```python df[r"weather.Bei\.jing.humidity"] # 标签 "Bei.jing"（点号是值的一部分）