From daabd4be3cbb79ae98acd5211f5e179b0ef655ee Mon Sep 17 00:00:00 2001 From: Shengliang Guan Date: Tue, 18 Feb 2025 14:53:39 +0800 Subject: [PATCH] docs: minor changes --- docs/zh/06-advanced/01-subscription.md | 18 +++++++++--------- docs/zh/06-advanced/02-cache.md | 18 +++++++++--------- docs/zh/06-advanced/03-stream.md | 8 ++++---- docs/zh/07-develop/01-connect/index.md | 4 ++-- docs/zh/07-develop/index.md | 8 ++++---- 5 files changed, 28 insertions(+), 28 deletions(-) diff --git a/docs/zh/06-advanced/01-subscription.md b/docs/zh/06-advanced/01-subscription.md index 5d458b186c..0760f44446 100644 --- a/docs/zh/06-advanced/01-subscription.md +++ b/docs/zh/06-advanced/01-subscription.md @@ -12,7 +12,7 @@ toc_max_heading_level: 4 为实现上述功能，TDengine 会为预写数据日志（Write-Ahead Logging，WAL）文件自动创建索引，以支持快速随机访问，并提供了灵活可配置的文件切换与保留机制。用户可以根据需求指定 WAL 文件的保留时间和大小。通过这些方法，WAL 被改造成一个保留事件到达顺序的、可持久化的存储引擎。对于以主题形式创建的查询，TDengine 将从 WAL 读取数据。在消费过程中，TDengine 根据当前消费进度从 WAL 直接读取数据，并使用统一的查询引擎实现过滤、变换等操作，然后将数据推送给消费者。 -从 3.2.0.0 版本开始，数据订阅支持 vnode 迁移和分裂。 由于数据订阅依赖 wal文件，而在 vnode 迁移和分裂的过程中，wal 并不会同步过去，所以迁移或分裂后，之前没消费完的 wal数据后消费不到。所以请保证之前把数据全部消费完后，再进行 vnode 迁移或分裂，否则，消费会丢失数据。 +从 3.2.0.0 版本开始，数据订阅支持 vnode 迁移和分裂。由于数据订阅依赖 wal 文件，而在 vnode 迁移和分裂的过程中，wal 文件并不会进行同步。因此，在迁移或分裂操作完成后，您将无法继续消费之前尚未消费完 wal 数据。请务必在执行 vnode 迁移或分裂之前，将所有 wal 数据消费完毕。 ## 主题类型 @@ -31,7 +31,7 @@ CREATE TOPIC [IF NOT EXISTS] topic_name as subquery 3. 若发生表结构变更，新增的列不出现在结果中。 4. 对于 select *，则订阅展开为创建时所有的列（子表、普通表为数据列，超级表为数据列加标签列） -假设需要订阅所有智能电表中电压值大于 200 的数据，而且仅仅返回时间戳、电流、电压 3 个采集量（不返回相位），那么可以通过下面的 SQL 创建 power_topic 这个主题。 +假设需要订阅所有智能电表中电压值大于 200 的数据，且仅仅返回时间戳、电流、电压 3 个采集量（不返回相位），那么可以通过下面的 SQL 创建 power_topic 这个主题。 ```sql CREATE TOPIC power_topic AS SELECT ts, current, voltage FROM power.meters WHERE voltage > 200; ``` @@ -45,21 +45,21 @@ CREATE TOPIC [IF NOT EXISTS] topic_name [with meta] AS STABLE stb_name [where_co 与使用 `SELECT * from stbName` 订阅的区别是： -1. 不会限制用户的表结构变更，即表结构变更以及变更后的新数据都能够订阅到 +1. 不会限制用户的表结构变更，即表结构变更以及变更后的新数据都能够订阅到。 2. 返回的是非结构化的数据，返回数据的结构会随着超级表的表结构变化而变化。 -3. with meta 参数可选，选择时将返回创建超级表，子表等语句，主要用于 taosx 做超级表迁移。 -4. where_condition 参数可选，选择时将用来过滤符合条件的子表，订阅这些子表。where 条件里不能有普通列，只能是 tag 或 tbname，where 条件里可以用函数，用来过滤 tag，但是不能是聚合函数，因为子表 tag 值无法做聚合。也可以是常量表达式，比如 2 > 1（订阅全部子表），或者 false（订阅 0 个子表）。 +3. with meta 参数可选，选择时将返回创建超级表，子表等语句，主要用于 taosX 做超级表迁移。 +4. where_condition 参数可选，选择时将用来过滤符合条件的子表，订阅这些子表。where 条件里不能有普通列，只能是 tag 或 tbname，where 条件里可以用函数，用来过滤 tag，但是不能是聚合函数，因为子表 tag 值无法做聚合。可以是常量表达式，比如 2 > 1（订阅全部子表），或者 false（订阅 0 个子表）。 5. 返回数据不包含标签。 ### 数据库主题 -订阅一个数据库里所有数据，其语法如下 +订阅一个数据库里所有数据，其语法如下： ```sql CREATE TOPIC [IF NOT EXISTS] topic_name [with meta] AS DATABASE db_name; ``` -通过该语句可创建一个包含数据库所有表数据的订阅 -1. with meta 参数可选，选择时将返回数据库里所有超级表，子表、普通表的元数据创建、删除、修改语句，主要用于 taosx 做数据库迁移。 +通过该语句可创建一个包含数据库所有表数据的订阅： +1. with meta 参数可选，选择时将返回数据库里所有超级表，子表、普通表的元数据创建、删除、修改语句，主要用于 taosX 做数据库迁移。 2. 超级表订阅和库订阅属于高级订阅模式，容易出错，如确实要使用，请咨询技术支持人员。 ## 删除主题 @@ -128,7 +128,7 @@ TDengine 的数据订阅功能支持回放（replay）功能，允许用户按 2023/09/22 00:00:08.000 ``` -使用数据订阅的回放功能时需要注意如下几项。 +使用数据订阅的回放功能时需要注意如下几项： - 数据订阅的回放功能仅查询订阅支持数据回放，超级表和库订阅不支持回放。 - 回放不支持进度保存。 - 因为数据回放本身需要处理时间，所以回放的精度存在几十毫秒的误差。 diff --git a/docs/zh/06-advanced/02-cache.md b/docs/zh/06-advanced/02-cache.md index 875452205b..5054bd6acd 100644 --- a/docs/zh/06-advanced/02-cache.md +++ b/docs/zh/06-advanced/02-cache.md @@ -29,14 +29,14 @@ TDengine 采用时间驱动的缓存管理策略，将最新数据优先存储 ## TDengine 的读缓存配置 -在创建数据库时，用户可以选择是否启用缓存机制以存储该数据库中每张子表的最新数据。这一缓存机制由数据库创建参数 cachemodel 进行控制。参数 cachemodel 具有如 下 4 种情况： +在创建数据库时，用户可以选择是否启用缓存机制以存储该数据库中每张子表的最新数据。这一缓存机制由数据库创建参数 cachemodel 进行控制。参数 cachemodel 具有如下 4 种情况： - none：不缓存 - last_row：缓存子表最近一行数据，这将显著改善 last_row 函数的性能 -- last_value：缓存子表每一列最近的非 NULL 值，这将显著改善无特殊影响（比如 WHERE,ORDER BY,GROUP BY, INTERVAL）时的 last 函数的性能 +- last_value：缓存子表每一列最近的非 NULL 值，这将显著改善无特殊影响（比如 WHERE、ORDER BY、GROUP BY、INTERVAL）时的 last 函数的性能 - both：同时缓存最近的行和列，即等同于上述 cachemodel 值为 last_row 和 last_value 的行为同时生效 当使用数据库读缓存时，可以使用参数 cachesize 来配置每个 vnode 的内存大小。 -- cachesize：表示每个 vnode 中用于缓存子表最近数据的内存大小。默认为 1 ，范围是[1，65536]，单位是 MB。需要根据机器内存合理配置。 +- cachesize：表示每个 vnode 中用于缓存子表最近数据的内存大小。默认为 1，范围是 [1，65536]，单位是 MB。需要根据机器内存合理配置。 关于数据库的具体创建，相关参数和操作说明请参考[创建数据库](../../reference/taos-sql/database/) @@ -48,25 +48,25 @@ TDengine 采用时间驱动的缓存管理策略，将最新数据优先存储 # taosBenchmark -d power -Q --start-timestamp=1600000000000 --tables=10000 --records=10000 --time-step=10000 -y ``` -上面的命令，taosBenchmark 工具在 TDengine 中生成了一个用于测试的 电表数据库 power，产生共 10 亿条时序数据。时序数据的时间戳从 `1600000000000（2020-09-13T20:26:40+08:00）`开始，超级表为 `meter`s，包含 10000 个设备（子表），每个设备有 10000 条数据，时序数据的采集频率是 10 秒/ 条。 +上面的命令，taosBenchmark 工具在 TDengine 中生成了一个用于测试的 电表数据库 power，产生共 10 亿条时序数据。时序数据的时间戳从 `1600000000000（2020-09-13T20:26:40+08:00）` 开始，超级表为 `meters`，包含 10000 个设备（子表），每个设备有 10000 条数据，时序数据的采集频率是 10 秒/条。 查询任意一个电表的最新的电流和时间戳数据，执行如下 SQL ```sql -taos> select last(ts,current) from meters; +taos> select last(ts, current) from meters; last(ts) | last(current) | ================================================= 2020-09-15 00:13:10.000 | 1.1294620 | Query OK, 1 row(s) in set (0.353815s) -taos> select last_row(ts,current) from meters; +taos> select last_row(ts, current) from meters; last_row(ts) | last_row(current) | ================================================= 2020-09-15 00:13:10.000 | 1.1294620 | Query OK, 1 row(s) in set (0.344070s) ``` -希望使用缓存来查询任意一个电表的最新时间戳数据，执行如下 SQL ，并检查数据库的缓存生效。 +希望使用缓存来查询任意一个电表的最新时间戳数据，执行如下 SQL，并检查数据库的缓存生效。 ```sql taos> alter database power cachemodel 'both' ; @@ -82,13 +82,13 @@ Query OK, 1 row(s) in set (0.000282s) 再次查询电表的最新的实时数据，第一次查询会做缓存计算，后续的查询时延就大大缩减。 ```sql -taos> select last(ts,current) from meters; +taos> select last(ts, current) from meters; last(ts) | last(current) | ================================================= 2020-09-15 00:13:10.000 | 1.1294620 | Query OK, 1 row(s) in set (0.044021s) -taos> select last_row(ts,current) from meters; +taos> select last_row(ts, current) from meters; last_row(ts) | last_row(current) | ================================================= 2020-09-15 00:13:10.000 | 1.1294620 | diff --git a/docs/zh/06-advanced/03-stream.md b/docs/zh/06-advanced/03-stream.md index 8692afad45..74e7e81675 100644 --- a/docs/zh/06-advanced/03-stream.md +++ b/docs/zh/06-advanced/03-stream.md @@ -60,20 +60,20 @@ subquery 支持会话窗口、状态窗口、时间窗口、事件窗口与计 3. INTERVAL 是时间窗口，又可分为滑动时间窗口和翻转时间窗口。INTERVAL 子句用于指定窗口相等时间周期，SLIDING 字句用于指定窗口向前滑动的时间。当 interval_val 与 sliding_val 相等的时候，时间窗口即为翻转时间窗口，否则为滑动时间窗口，注意：sliding_val 必须小于等于 interval_val。 -4. EVENT_WINDOW 是事件窗口，根据开始条件和结束条件来划定窗口。当 start_trigger_condition 满足时则窗口开始，直到 end_trigger_condition 满足时窗口关闭。 start_trigger_condition 和 end_trigger_condition 可以是任意 TDengine 支持的条件表达式，且可以包含不同的列。 +4. EVENT_WINDOW 是事件窗口，根据开始条件和结束条件来划定窗口。当 start_trigger_condition 满足时则窗口开始，直到 end_trigger_condition 满足时窗口关闭。start_trigger_condition 和 end_trigger_condition 可以是任意 TDengine 支持的条件表达式，且可以包含不同的列。 -5. COUNT_WINDOW 是计数窗口，按固定的数据行数来划分窗口。 count_val 是常量，是正整数，必须大于等于 2，小于 2147483648。 count_val 表示每个 COUNT_WINDOW 包含的最大数据行数，总数据行数不能整除 count_val 时，最后一个窗口的行数会小于 count_val 。 sliding_val 是常量，表示窗口滑动的数量，类似于 INTERVAL 的 SLIDING 。 +5. COUNT_WINDOW 是计数窗口，按固定的数据行数来划分窗口。count_val 是常量，是正整数，必须大于等于 2，小于 2147483648。count_val 表示每个 COUNT_WINDOW 包含的最大数据行数，总数据行数不能整除 count_val 时，最后一个窗口的行数会小于 count_val。sliding_val 是常量，表示窗口滑动的数量，类似于 INTERVAL 的 SLIDING 。 窗口的定义与时序数据窗口查询中的定义完全相同，具体可参考 TDengine 窗口函数部分。 -如下 SQL 将创建一个流计算，执行后 TDengine 会自动创建名为avg_vol 的超级表，此流计算以 1min 为时间窗口、30s 为前向增量统计这些智能电表的平均电压，并将来自 meters 的数据的计算结果写入 avg_vol，不同分区的数据会分别创建子表并写入不同子表。 +如下 SQL 将创建一个流计算，执行后 TDengine 会自动创建名为 avg_vol 的超级表，此流计算以 1min 为时间窗口、30s 为前向增量统计这些智能电表的平均电压，并将来自 meters 的数据的计算结果写入 avg_vol，不同分区的数据会分别创建子表并写入不同子表。 ```sql CREATE STREAM avg_vol_s INTO avg_vol AS SELECT _wstart, count(*), avg(voltage) FROM power.meters PARTITION BY tbname INTERVAL(1m) SLIDING(30s); ``` 本节涉及的相关参数的说明如下。 -- stb_name 是保存计算结果的超级表的表名，如果该超级表不存在，则会自动创建；如果已存在，则检查列的 schema 信息。详见 6.3.8 节。 +- stb_name 是保存计算结果的超级表的表名，如果该超级表不存在，则会自动创建；如果已存在，则检查列的 schema 信息。 - tags 子句定义了流计算中创建标签的规则。通过 tags 字段可以为每个分区对应的子表生成自定义的标签值。 ## 流式计算的规则和策略 diff --git a/docs/zh/07-develop/01-connect/index.md b/docs/zh/07-develop/01-connect/index.md index 494e93f6ef..234a6b9792 100644 --- a/docs/zh/07-develop/01-connect/index.md +++ b/docs/zh/07-develop/01-connect/index.md @@ -20,7 +20,7 @@ import VerifyLinux from "../../14-reference/05-connector/_verify_linux.mdx"; import VerifyMacOS from "../../14-reference/05-connector/_verify_macos.mdx"; import VerifyWindows from "../../14-reference/05-connector/_verify_windows.mdx"; -TDengine 提供了丰富的应用程序开发接口，为了便于用户快速开发自己的应用，TDengine 支持了多种编程语言的连接器，其中官方连接器包括支持 C/C++、Java、Python、Go、Node.js、C#、Rust、Lua（社区贡献）和 PHP （社区贡献）的连接器。这些连接器支持使用原生接口（taosc）和 REST 接口（部分语言暂不支持）连接 TDengine 集群。社区开发者也贡献了多个非官方连接器，例如 ADO.NET 连接器、Lua 连接器和 PHP 连接器。另外 TDengine 还可以直接调用 taosadapter 提供的 REST API 接口，进行数据写入和查询操作。 +TDengine 提供了丰富的应用程序开发接口，为了便于用户快速开发自己的应用，TDengine 支持了多种编程语言的连接器，其中官方连接器包括支持 C/C++、Java、Python、Go、Node.js、C#、Rust、Lua（社区贡献）和 PHP （社区贡献）的连接器。这些连接器支持使用原生接口（taosc）和 REST 接口（部分语言暂不支持）连接 TDengine 集群。社区开发者也贡献了多个非官方连接器，例如 ADO.NET 连接器、Lua 连接器和 PHP 连接器。另外 TDengine 还可以直接调用 taosAdapter 提供的 REST API 接口，进行数据写入和查询操作。 ## 连接方式 @@ -33,7 +33,7 @@ TDengine 提供了丰富的应用程序开发接口，为了便于用户快速 ![TDengine connection type](connection-type-zh.webp) 无论使用何种方式建立连接，连接器都提供了相同或相似的 API 操作数据库，都可以执行 SQL 语句，只是初始化连接的方式稍有不同，用户在使用上不会感到什么差别。 -各种连接方式和各语言连接器支持情况请参考：[连接器功能特性](../../reference/connector/#功能特性) +各种连接方式和各语言连接器支持情况请参考 [连接器功能特性](../../reference/connector/#功能特性) 关键不同点在于： diff --git a/docs/zh/07-develop/index.md b/docs/zh/07-develop/index.md index 4759027344..c870c09f42 100644 --- a/docs/zh/07-develop/index.md +++ b/docs/zh/07-develop/index.md @@ -5,19 +5,19 @@ description: 让开发者能够快速上手的指南 开发一个应用，如果你准备采用 TDengine 作为时序数据处理的工具，那么有如下几个事情要做： -1. 确定应用到 TDengine 的连接方式。无论你使用何种编程语言，你总是可以使用 REST 接口, 但也可以使用每种编程语言独有的连接器进行方便的连接。 +1. 确定应用到 TDengine 的连接方式。无论你使用何种编程语言，你总是可以使用 REST 接口，但也可以使用每种编程语言独有的连接器进行方便的连接。 2. 根据自己的应用场景，确定数据模型。根据数据特征，决定建立一个还是多个库；分清静态标签、采集量，建立正确的超级表，建立子表。 3. 决定插入数据的方式。TDengine 支持使用标准的 SQL 写入，但同时也支持 Schemaless 模式写入，这样不用手工建表，可以将数据直接写入。 4. 根据业务要求，看需要撰写哪些 SQL 查询语句。 -5. 如果你要基于时序数据做轻量级的实时统计分析，包括各种监测看板，那么建议你采用 TDengine 3.0 的流式计算功能，而不用额外部署 Spark, Flink 等复杂的流式计算系统。 +5. 如果你要基于时序数据做轻量级的实时统计分析，包括各种监测看板，那么建议你采用 TDengine 3.0 的流式计算功能，而不用额外部署 Spark、Flink 等复杂的流式计算系统。 6. 如果你的应用有模块需要消费插入的数据，希望有新的数据插入时，就能获取通知，那么建议你采用 TDengine 提供的数据订阅功能，而无需专门部署 Kafka 或其他消息队列软件。 7. 在很多场景下（如车辆管理），应用需要获取每个数据采集点的最新状态，那么建议你采用 TDengine 的 Cache 功能，而不用单独部署 Redis 等缓存软件。 8. 如果你发现 TDengine 的函数无法满足你的要求，那么你可以使用用户自定义函数（UDF）来解决问题。 本部分内容就是按照上述顺序组织的。为便于理解，TDengine 为每个功能和每个支持的编程语言都提供了示例代码，位于 [示例代码](https://github.com/taosdata/TDengine/tree/main/docs/examples)。所有示例代码都会有 CI 保证正确性，脚本位于 [示例代码 CI](https://github.com/taosdata/TDengine/tree/main/tests/docs-examples-test)。 -如果你希望深入了解 SQL 的使用，需要查看[SQL 手册](../reference/taos-sql/)。如果想更深入地了解各连接器的使用，请阅读[连接器参考指南](../reference/connector/)。如果还希望想将 TDengine 与第三方系统集成起来，比如 Grafana, 请参考[第三方工具](../third-party/)。 +如果你希望深入了解 SQL 的使用，需要查看 [SQL 手册](../reference/taos-sql/)。如果想更深入地了解各连接器的使用，请阅读 [连接器参考指南](../reference/connector/)。如果还希望想将 TDengine 与第三方系统集成起来，比如 Grafana，请参考 [第三方工具](../third-party/)。 -如果在开发过程中遇到任何问题，请点击每个页面下方的["反馈问题"](https://github.com/taosdata/TDengine/issues/new/choose), 在 GitHub 上直接递交 Issue。 +如果在开发过程中遇到任何问题，请点击每个页面下方的 [反馈问题](https://github.com/taosdata/TDengine/issues/new/choose)，在 GitHub 上直接递交 Issue。 ```mdx-code-block import DocCardList from '@theme/DocCardList';