diff --git a/db-administration/db-mgmt/db-mgmt-ts.md b/db-administration/db-mgmt/db-mgmt-ts.md index 6523990a4d558c510bc98b3672ed8bf791b0c77c..b29b81b5bf727fa0117f409f73c2623daa998acd 100644 --- a/db-administration/db-mgmt/db-mgmt-ts.md +++ b/db-administration/db-mgmt/db-mgmt-ts.md @@ -206,7 +206,7 @@ USE ts_db; ## 修改数据库 -KWDB 支持修改数据库的名称和生命周期。 +KWDB 支持修改数据库的名称、生命周期和区域配置。 ### 前提条件 @@ -215,6 +215,9 @@ KWDB 支持修改数据库的名称和生命周期。 - 目标数据库不是当前数据库。 - 修改数据库生命周期 - 用户为 Admin 用户或者 Admin 角色成员。 +- 修改数据库区域设置 + - 修改系统数据库区域配置：用户为 Admin 用户或 Admin 角色成员。 + - 修改其他数据库区域配置：用户拥有目标数据库的 CREATE 或 ZONECONFIG 权限。 ### 语法格式 @@ -230,6 +233,13 @@ KWDB 支持修改数据库的名称和生命周期。 ALTER TS DATABASE SET RETENTIONS = ; ``` +- 修改数据库区域配置 + + ```sql + ALTER DATABASE CONFIGURE ZONE + [USING = [COPY FROM PARENT | ], = [ | COPY FROM PARENT], ... | USING REBALANCE | DISCARD]; + ``` + ### 参数说明 | 参数 | 说明 | @@ -238,6 +248,11 @@ KWDB 支持修改数据库的名称和生命周期。 | `new_name` | 拟修改的数据库名称，新数据库名称必须唯一，并且[遵循数据库标识符规则](../../sql-reference/sql-identifiers.md)。目前，数据库名称不支持中文字符，最大长度不能超过 63 个字节。| | `db_name` | 待修改的数据库名称。| | `keep_duration` | 可选参数，设置数据库的数据生命周期。数据超过此时长后将被系统自动清除。
默认值： `0s`（永久保留）
时间单位：
- 秒：`s` 或 `second`
- 分钟：`m` 或 `minute`
- 小时：`h` 或 `hour`
- 天：`d` 或 `day`
- 周：`w` 或 `week`
- 月：`mon` 或 `month`
- 年：`y` 或 `year`
取值范围:正整数，上限为 1000 年
**说明：**
- 表级设置优先于库级设置。
- 保留时长越长，存储空间占用越大，请根据业务需求合理配置。
- 如果待写入的数据已超过生命周期限制，系统会直接丢弃该数据，不予写入。| +| `variable` | 要修改的变量名，时序库支持修改以下变量：
- `range_min_bytes`：数据分片的最小大小，单位为字节。数据分片小于该值时，KaiwuDB 会将其与相邻数据分片合并。默认值：256 MiB，设置值应大于 1 MiB（1048576 字节），小于数据分片的最大大小。
- `range_max_bytes`：数据分片的最大大小，单位为字节。数据分片大于该值时，KaiwuDB 会将其切分到两个数据分片。默认值： 512 MiB。设置值不得小于 5 MiB（5242880 字节）。
- `gc.ttlseconds`：数据在垃圾回收前保留的时间，单位为秒。默认值为 `90000`（25 小时）。设置值建议不小于 600 秒（10 分钟），以免影响长时间运行的查询。设置值较小时可以节省磁盘空间，设置值较大时会增加 `AS OF SYSTEM TIME` 查询的时间范围。另外，由于每行的所有版本都存储在一个永不拆分的单一数据分片内，不建议将该值设置得太大，以免单行的所有更改累计超过 64 MiB，导致内存不足或其他问题。
- `num_replicas`：副本数量。默认值为 3。`system` 数据库、`meta`、`liveness` 和 `system` 数据分片的默认副本数为 5。 **注意**：集群中存在不可用节点时，副本数量不可缩减。
- `ts_merge.days`：时序数据分片合并时间。同一个时序表同哈希点按照时间戳分裂后，超过该时间的数据分片将自动合并，且合并后不会再自动拆分。默认值：10（10天）。设置值必须大于等于 0，设置值为 0 时表示时序数据分片按照时间戳分裂后便立刻自动合并。系统数据分片数量过多导致出现网络等故障时可以将该值适当调小，以缓解数据过大的问题。**提示：** KaiwuDB 默认只根据哈希点拆分数据分片，因此数据分片按时间合并功能默认关闭，如需支持按时间合并数据分片，需将 `kv.kvserver.ts_split_interval` 实时参数设置为 `1`, 将 `kv.kvserver.ts_split_by_timestamp.enabled` 实时参数设置为 `true` 以支持按照哈希点和时间戳拆分数据分片。 | +| `value` | 变量值。 | +|`COPY FROM PARENT`| 使用父区域的设置值。| +|`USING REBALANCE` | 手动触发数据分片的区域重新分配和负载均衡。

适用于以下场景：
- 关闭自动均衡后的主动调优
- 负载不均时的人工干预

KaiwuDB 默认自动执行后台数据分片均衡，用户通过 `SET CLUSTER SETTING kv.allocator.ts_consider_rebalance.enabled = false;` 关闭自动均衡功能后，可在系统低负载时段进行手动均衡。

注意：
- 该功能仅适用于用户数据分片，不适用于系统数据分片
- 建议在业务低峰期执行，避免影响正常业务性能。 | +|`DISCARD` | 移除区域配置，采用默认值。| ### 语法示例 @@ -257,6 +272,29 @@ KWDB 支持修改数据库的名称和生命周期。 ALTER TS DATABASE tsdb SET RETENTIONS = 10 day; ``` +- 修改数据库的区域配置。 + + 以下示例将 `tsdb` 数据库的副本数改为5个，将数据在垃圾回收前保留的时间改为100000秒。 + + ```SQL + -- 1. 修改区域配置 + > ALTER DATABASE tsdb CONFIGURE ZONE USING num_replicas = 5, gc.ttlseconds = 100000; + CONFIGURE ZONE 1 + + -- 2. 查看修改是否成功 + > SHOW ZONE CONFIGURATION FOR DATABASE tsdb; + zone_name | config_sql + +-----------+-----------------------------------------+ + tsdb | ALTER DATABASE tsdb CONFIGURE ZONE USING + | range_min_bytes = 268435456, + | range_max_bytes = 536870912, + | gc.ttlseconds = 100000, + | num_replicas = 5, + | constraints = '[]', + | lease_preferences = '[]' + (6 rows) + ``` + ## 删除数据库 `DROP DATABASE` 语句用于删除目标数据库。删除成功后，所有用户针对目标数据库和其对象的所有权限均被删除。 diff --git a/db-administration/db-object-mgmt/ts-db/table-mgmt-ts.md b/db-administration/db-object-mgmt/ts-db/table-mgmt-ts.md index 7d89fd8e71af09c824dc4e5b9780b63038278775..0d58c7c636a456e0ee77786ec989e15fdb56d61e 100644 --- a/db-administration/db-object-mgmt/ts-db/table-mgmt-ts.md +++ b/db-administration/db-object-mgmt/ts-db/table-mgmt-ts.md @@ -21,7 +21,8 @@ CREATE TABLE () PRIMARY [TAGS|ATTRIBUTES] () [RETENTIONS ] [DICT ENCODING] -[COMMENT [=] <'comment_text'>]; +[COMMENT [=] <'comment_text'>] +[WITH HASH()]; ``` ### 参数说明 @@ -40,6 +41,7 @@ PRIMARY [TAGS|ATTRIBUTES] () | `keep_duration` | 可选参数，设置表的数据生命周期。数据超过此时长后将被系统自动清除。
默认值： `0s`（永久保留）
时间单位：
- 秒：`s` 或 `second`
- 分钟：`m` 或 `minute`
- 小时：`h` 或 `hour`
- 天：`d` 或 `day`
- 周：`w` 或 `week`
- 月：`mon` 或 `month`
- 年：`y` 或 `year`
取值范围:正整数，上限为 1000 年
**说明：**
- 表级设置优先于库级设置。
- 保留时长越长，存储空间占用越大，请根据业务需求合理配置。
- 如果待写入的数据已超过生命周期限制，系统会直接丢弃该数据，不予写入。| | `DICT ENCODING`| 可选参数，启用字符串的字典编码功能，提升字符串数据的压缩能力。表中存储的字符串数据重复率越高，压缩优化效果越明显。该功能只适用于 CHAR 和 VARCHAR 长度小于等于 `1023` 的字符串，且只能在建表时开启。开启后不支持禁用。 | | `[COMMENT [=] <'comment_text'>` | 可选项，定义表的注释信息。 | +| `hash_value`| 可选参数，用于定义分布式集群中 HASH 环的大小，决定最大 Range 分片数量。例如 HASH(100) 表示最多可产生 100 个不同的 Range 分片。

默认值为 2000，表示最多可产生 2000 个 Range 分片。支持设置范围为 [1,50000]。

性能影响：HASH 值过小时将导致多个设备的数据集中在少数 Range 中，形成写入热点，HASH 值过大时则会导致 Range 数量过多，增加管理开销。

推荐配置：建议根据预期设备数量选择合适的 HASH 值：
- 设备数 ≤ 1,000：HASH 值 < 20
- 设备数 ≤ 50,000：HASH 值 < 2,000
- 设备数 ≤ 1,000,000：HASH 值 < 10,000

最佳实践：建议配合集群参数 `SET CLUSTER SETTING sql.ts_create.leaseholder_auto_relocated.enabled = true;`使用，可在建表时自动将 Range 分片和 Leaseholder 均匀分布到各节点，从源头避免热点问题。 | ### 语法示例 @@ -112,6 +114,14 @@ PRIMARY [TAGS|ATTRIBUTES] () CREATE ``` +- 创建时序表并设置 HASH 环大小。 + + 以下示例创建一个名为 `sensors` 的时序表并将 HASH 环大小设置为 20。 + + ```sql + CREATE TABLE sensors (ts TIMESTAMP NOT NULL, value FLOAT) TAGS (sensor_id INT NOT NULL) PRIMARY TAGS (sensor_id) WITH HASH(20); + ``` + ## 查看表 ### 前提条件 diff --git a/db-operation/cluster-ha.md b/db-operation/cluster-ha.md index ea0f8fcbe961f3b7e229c1d0e6abbbbf05ddbace..1bbb24a7db4de7556f248f114ab6e0f129239fb3 100644 --- a/db-operation/cluster-ha.md +++ b/db-operation/cluster-ha.md @@ -60,7 +60,7 @@ KWDB 集群启动后，分片副本均匀分布在所有节点上，确保数据 ##### 依次故障 -如果两个节点依次发生故障，当第二个节点发生故障前系统已完成副本补足，则第二个节点发生故障后，系统仍支持正常运行。 +如果两个节点依次发生故障，当第二个节点故障前系统已完成副本补足，则第二个节点故障后，系统仍可正常运行。注意：在 5 节点三副本集群中禁用副本自动补足功能后，将无法承受连续的节点故障。 img @@ -92,6 +92,16 @@ SET CLUSTER SETTING server.time_until_store_dead = ; 设置时间建议不小于 75s。注意：延长节点判定时间，可以减少节点故障对集群性能的长时间影响，但可能会影响集群的高可用性功能和 DDL 相关操作。 +### 控制节点死亡后是否自动迁移补齐副本 + +系统将离线节点标记为不可用节点后，如果剩余节点数量仍大于副本数，系统将自动补足缺失的副本，确保数据的高可用性。用户也可以通过以下 SQL 命令关闭自动补足副本功能： + +```SQL +SET CLUSTER SETTING kv.allocator.ts_store_dead_rebalance.enabled = false; +``` + +注意：在 5 节点三副本集群中禁用该功能后，将无法承受连续节点故障。 + #### 查看节点状态 使用 `kwbase` 命令查询节点状态: @@ -110,4 +120,8 @@ SET CLUSTER SETTING server.time_until_store_dead = ; SELECT sum((metrics->>'ranges.unavailable')::DECIMAL)::INT AS ranges_unavailable, sum((metrics->>'ranges.underreplicated')::DECIMAL)::INT As ranges_underreplicated FROM kwdb_internal.kv_store_status; - ``` \ No newline at end of file + ``` + +### 查看副本同步状态 + + 通过导入[分布式面板](https://gitee.com/kwdb/kwdb/blob/master/kwbase/monitoring/grafana-dashboards/6.KaiwuDB_Console_Replication.json)查看副本同步情况。 \ No newline at end of file diff --git a/db-operation/cluster-settings-config.md b/db-operation/cluster-settings-config.md index e5eaa8e0c5e4cf3a63c524a4d22bbd5ff098419e..37416f8f6dcba2e55a901cd8ea6344d0a22f886a 100644 --- a/db-operation/cluster-settings-config.md +++ b/db-operation/cluster-settings-config.md @@ -177,6 +177,8 @@ KWDB 支持通过 `SET CLUSTER SETTING` 语句修改集群设置，设置后立 | `kv.allocator.load_based_rebalancing` | 是否基于存储之间的 QPS 分布重新平衡。
- `0`：表示不启动。
- `1`：表示重新平衡租约。
- `2`：表示平衡租约和副本。 | `2` | enum | | `kv.allocator.qps_rebalance_threshold` | 存储节点的 QPS 与平均值之间的最小分数，用于判断存储节点负载是否过高或过低。 | `0.25` | float | | `kv.allocator.range_rebalance_threshold` | 存储的 Range 数与平均值的最小分数，用于判断存储节点负载是否过高或过低。 | `0.05` | float | +| `kv.allocator.ts_consider_rebalance.enabled` | 控制后台时序数据分片的自动均衡行为。启用时，集群扩缩容后系统会自动进行数据重分布；禁用时，扩缩容后不会自动触发数据重分布。如需进行扩缩容均衡，可临时启用该参数等待数据均衡完成后再关闭，或执行 `ALTER ... CONFIGURE ZONE` 命令对指定表、库或数据分片进行手动均衡。 | `true` | bool | +| `kv.allocator.ts_store_dead_rebalance.enabled` | 控制节点死亡后的副本自动迁移行为。启用时，副本队列会根据节点状态自动进行副本迁移、替换和补足；禁用时，即使节点死亡也不会进行副本补足。注意：在 5 节点三副本集群中禁用该功能后，将无法承受连续节点故障。 | `true` | bool | | `kv.bulk_io_write.max_rate` | 批量输入/输出（IO）操作向磁盘写入数据时的速率限制。 | `1.0 TiB` | byte size | | `kv.closed_timestamp.follower_reads_enabled` | 所有副本基于封闭时间戳的信息提供一致的历史读取。 | `TRUE` | bool | | `kv.protectedts.reconciliation.interval` | 通过受保护的时间戳记录协调作业的频率。 | `5m0s` | duration | @@ -239,6 +241,7 @@ KWDB 支持通过 `SET CLUSTER SETTING` 语句修改集群设置，设置后立 | `sql.trace.log_statement_execute` | 设置为 `TRUE` 时，启用执行语句的日志记录。 | `FALSE` | bool | | `sql.trace.session_eventlog.enabled` | 设置为 `TRUE` 时，启用会话跟踪。这可能会明显影响性能。 | `FALSE` | bool | | `sql.trace.txn.enable_threshold` | 事务的执行时间超过指定的持续时间时，系统将对该事务进行追踪。设置为 `0` 时，表示禁用该功能。 | `0s` | duration | +| `sql.ts_create.leaseholder_auto_relocated.enabled` | 控制时序表建表时的预均衡行为，设置为 `true` 时，系统在创建时序表的预分裂阶段完成后，会自动执行一次该表的 leaseholder（主副本）均衡。 建议启用此参数前，先执行 `SET CLUSTER SETTING kv.allocator.ts_consider_rebalance.enabled = false;` 以关闭防止后台自动均衡机制，避免不必要的数据重分布。 | `false` | bool | | `sql.ts_insert_select.block_memory` | 时序数据 `INSERT INTO SELECT` 语句单次写入的数据块内存限制。 | `200` | int | | `sql.ts_insert_select_limit.enabled` | 允许时序数据写入关系表。 | `FALSE` | bool | | `sql.ts_stats.enabled` | 启动时序数据统计信息收集。 | `TRUE` | bool | diff --git a/sql-reference/ddl/ts-db/ts-database.md b/sql-reference/ddl/ts-db/ts-database.md index ec23e64c55a7b109f9b43ccb35dd1c8a42a4a1c6..a62481eabab1c286f559e119e6d81f57d7f21174 100644 --- a/sql-reference/ddl/ts-db/ts-database.md +++ b/sql-reference/ddl/ts-db/ts-database.md @@ -7,7 +7,6 @@ id: ts-database 作为一款多模数据库系统，KWDB 支持用户在一个 KWDB 实例中创建一个或多个数据库对象（Database）用来管理时序和关系数据。其中专门用于存储和管理时间数据的数据库对象为时序数据库（Time Series Database）。时序数据库中包括 public 模式和用户自定义的时序表。 - ## 创建数据库 `CREATE TS DATABASE` 语句用于创建时序数据库，每条语句只支持创建一个时序数据库。 @@ -207,11 +206,15 @@ USE ts_db; ## 修改数据库 -`ALTER DATABASE` 语句用于修改数据库的名称和生命周期。 +`ALTER DATABASE` 语句用于修改数据库的名称、生命周期和区域配置。 ### 所需权限 -用户为 Admin 用户或者 Admin 角色成员。 +- 修改数据库的名称：用户为 Admin 用户或者 Admin 角色成员。 +- 修改数据库生命周期：用户为 Admin 用户或者 Admin 角色成员。 +- 修改数据库区域设置 + - 修改系统数据库区域配置：用户为 Admin 用户或 Admin 角色成员。 + - 修改其他数据库区域配置：用户拥有目标数据库的 CREATE 或 ZONECONFIG 权限。 ### 语法格式 @@ -223,6 +226,10 @@ USE ts_db; ![](../../../static/sql-reference/Ab69bP86UozqWDxtCLMc3vxznwh.png) +- 修改数据库的区域配置 + + ![](../../../static/sql-reference/alter-db-zone-ts.png) + ### 参数说明 | 参数 | 说明 | @@ -231,6 +238,11 @@ USE ts_db; | `new_name` | 拟修改的数据库名称，新数据库名称必须唯一，并且遵循[数据库标识符规则](../../sql-identifiers.md)。目前，数据库名称不支持中文字符，最大长度不能超过 63 个字节。| | `database_name` | 待修改的数据库名称。| | `keep_duration` | 可选参数，设置数据库的数据生命周期。数据超过此时长后将被系统自动清除。
默认值： `0s`（永久保留）
时间单位：
- 秒：`s` 或 `second`
- 分钟：`m` 或 `minute`
- 小时：`h` 或 `hour`
- 天：`d` 或 `day`
- 周：`w` 或 `week`
- 月：`mon` 或 `month`
- 年：`y` 或 `year`
取值范围:正整数，上限为 1000 年
**说明：**
- 表级设置优先于库级设置。
- 保留时长越长，存储空间占用越大，请根据业务需求合理配置。
- 如果待写入的数据已超过生命周期限制，系统会直接丢弃该数据，不予写入。| +| `variable` | 要修改的变量名，时序库支持修改以下变量：
- `range_min_bytes`：分区的最小大小，单位为字节。分区小于该值时，KaiwuDB 会将其与相邻分区合并。默认值：256 MiB，设置值应大于 1 MiB（1048576 字节），小于分区的最大大小。
- `range_max_bytes`：分区的最大大小，单位为字节。分区大于该值时，KaiwuDB 会将其切分到两个分区。默认值： 512 MiB。设置值不得小于 5 MiB（5242880 字节）。
- `gc.ttlseconds`：数据在垃圾回收前保留的时间，单位为秒。默认值为 `90000`（25 小时）。设置值建议不小于 600 秒（10 分钟），以免影响长时间运行的查询。设置值较小时可以节省磁盘空间，设置值较大时会增加 `AS OF SYSTEM TIME` 查询的时间范围。另外，由于每行的所有版本都存储在一个永不拆分的单一分区内，不建议将该值设置得太大，以免单行的所有更改累计超过 64 MiB，导致内存不足或其他问题。
- `num_replicas`：副本数量。默认值为 3。`system` 数据库、`meta`、`liveness` 和 `system` 分区的默认副本数为 5。 **注意**：集群中存在不可用节点时，副本数量不可缩减。
- `ts_merge.days`：时序分区合并时间。同一个时序表同哈希点按照时间戳分裂后，超过该时间的分区将自动合并，且合并后不会再自动拆分。默认值：10（10天）。设置值必须大于等于 0，设置值为 0 时表示时序分区按照时间戳分裂后便立刻自动合并。系统分区数量过多导致出现网络等故障时可以将该值适当调小，以缓解数据过大的问题。**提示：** KaiwuDB 默认只根据哈希点拆分分区，因此分区按时间合并功能默认关闭，如需支持按时间合并分区，需将 `kv.kvserver.ts_split_interval` 实时参数设置为 `1`, 将 `kv.kvserver.ts_split_by_timestamp.enabled` 实时参数设置为 `true` 以支持按照哈希点和时间戳拆分分区。 | +| `value` | 变量值。 | +|`COPY FROM PARENT`| 使用父区域的设置值。| +|`USING REBALANCE` | 手动触发数据分片的区域重新分配和负载均衡。

适用于以下场景：
- 关闭自动均衡后的主动调优
- 负载不均时的人工干预

KaiwuDB 默认自动执行后台数据分片均衡，用户通过 `SET CLUSTER SETTING kv.allocator.ts_consider_rebalance.enabled = false;` 关闭自动均衡功能后，可在系统低负载时段进行手动均衡。

注意：
- 该功能仅适用于用户数据分片，不适用于系统数据分片
- 建议在业务低峰期执行，避免影响正常业务性能。 | +|`DISCARD` | 移除区域配置，采用默认值。| ### 语法示例 @@ -250,6 +262,29 @@ USE ts_db; ALTER TS DATABASE tsdb SET RETENTIONS = 10 day; ``` +- 修改数据库的区域配置。 + + 以下示例将 `tsdb` 数据库的副本数改为5个，将数据在垃圾回收前保留的时间改为100000秒。 + + ```SQL + -- 1. 修改区域配置 + > ALTER DATABASE tsdb CONFIGURE ZONE USING num_replicas = 5, gc.ttlseconds = 100000; + CONFIGURE ZONE 1 + + -- 2. 查看修改是否成功 + > SHOW ZONE CONFIGURATION FOR DATABASE tsdb; + zone_name | config_sql + +-----------+-----------------------------------------+ + tsdb | ALTER DATABASE tsdb CONFIGURE ZONE USING + | range_min_bytes = 268435456, + | range_max_bytes = 536870912, + | gc.ttlseconds = 100000, + | num_replicas = 5, + | constraints = '[]', + | lease_preferences = '[]' + (6 rows) + ``` + ## 删除数据库 `DROP DATABASE` 语句用于删除数据库及其所有对象。目标数据库不能是当前数据库。如需删除当前数据库，使用 `USE ` 语句将当前数据库切换成其他数据库，再进行删除。 diff --git a/sql-reference/ddl/ts-db/ts-table.md b/sql-reference/ddl/ts-db/ts-table.md index 7c243673d496cd6617af05641131e24b54c1ca33..93198be0041d5ce7bdde229579c71eb5f3666286 100644 --- a/sql-reference/ddl/ts-db/ts-table.md +++ b/sql-reference/ddl/ts-db/ts-table.md @@ -34,6 +34,8 @@ id: ts-table | `primary_tag_list`| 主标签列表，支持添加一个或多个主标签名称，最多可指定 `4` 个。主标签必须包含在标签列表内且指定为 NOT NULL，不支持浮点类型和除 VARCHAR 之外的变长数据类型。VARCHAR 类型长度默认 `64` 字节，最大长度为 `128` 字节。| | `keep_duration` | 可选参数，设置表的数据生命周期。数据超过此时长后将被系统自动清除。
默认值： `0s`（永久保留）
时间单位：
- 秒：`s` 或 `second`
- 分钟：`m` 或 `minute`
- 小时：`h` 或 `hour`
- 天：`d` 或 `day`
- 周：`w` 或 `week`
- 月：`mon` 或 `month`
- 年：`y` 或 `year`
取值范围:正整数，上限为 1000 年
**说明：**
- 表级设置优先于库级设置。
- 保留时长越长，存储空间占用越大，请根据业务需求合理配置。
- 如果待写入的数据已超过生命周期限制，系统会直接丢弃该数据，不予写入。| | `DICT ENCODING`| 可选参数，启用字符串的字典编码功能，提升字符串数据的压缩能力。表中存储的字符串数据重复率越高，压缩优化效果越明显。该功能只适用于 CHAR 和 VARCHAR 长度小于等于 `1023` 的字符串，且只能在建表时开启。开启后不支持禁用。 | +| `[COMMENT [=] <'comment_text'>` | 可选参数，定义表的注释信息。 | +| `hash_value`| 可选参数，用于定义分布式集群中 HASH 环的大小，决定最大 Range 分片数量。例如 HASH(100) 表示最多可产生 100 个不同的 Range 分片。

默认值为 2000，表示最多可产生 2000 个 Range 分片。支持设置范围为 [1,50000]。

性能影响：HASH 值过小时将导致多个设备的数据集中在少数 Range 中，形成写入热点，HASH 值过大时则会导致 Range 数量过多，增加管理开销。

推荐配置：建议根据预期设备数量选择合适的 HASH 值：
- 设备数 ≤ 1,000：HASH 值 < 20
- 设备数 ≤ 50,000：HASH 值 < 2,000
- 设备数 ≤ 1,000,000：HASH 值 < 10,000

最佳实践：建议配合集群参数 `SET CLUSTER SETTING sql.ts_create.leaseholder_auto_relocated.enabled = true;`使用，可在建表时自动将 Range 分片和 Leaseholder 均匀分布到各节点，从源头避免热点问题。 | ### 语法示例 @@ -106,6 +108,14 @@ id: ts-table CREATE TABLE ``` +- 创建时序表并设置 HASH 环大小。 + + 以下示例创建一个名为 `sensors` 的时序表并将 HASH 环大小设置为 20。 + + ```sql + CREATE TABLE sensors (ts TIMESTAMP NOT NULL, value FLOAT) TAGS (sensor_id INT NOT NULL) PRIMARY TAGS (sensor_id) WITH HASH(20); + ``` + ## 查看表 `SHOW TABLES` 语句用于查看当前或指定数据库下的所有表，如未指定数据库则默认为当前数据库。 diff --git a/sql-reference/ddl/ts-db/ts-zone.md b/sql-reference/ddl/ts-db/ts-zone.md index 029233550ed7611ba61e02387c2e57d73f7ac570..9a52afd87307f7d9005a99ea3c135d5042d659ff 100644 --- a/sql-reference/ddl/ts-db/ts-zone.md +++ b/sql-reference/ddl/ts-db/ts-zone.md @@ -145,8 +145,8 @@ id: ts-zone | `variable` | 要修改的变量名，时序库支持修改以下变量：
- `range_min_bytes`：数据分片的最小大小，单位为字节。数据分片小于该值时，KWDB 会将其与相邻数据分片合并。默认值：256 MiB，设置值应大于 1 MiB（1048576 字节），小于数据分片的最大大小。
- `range_max_bytes`：数据分片的最大大小，单位为字节。数据分片大于该值时，KWDB 会将其切分到两个数据分片。默认值： 512 MiB。设置值不得小于 5 MiB（5242880 字节）。
- `gc.ttlseconds`：数据在垃圾回收前保留的时间，单位为秒。默认值为 `90000`（25 小时）。设置值建议不小于 600 秒（10 分钟），以免影响长时间运行的查询。设置值较小时可以节省磁盘空间，设置值较大时会增加 `AS OF SYSTEM TIME` 查询的时间范围。另外，由于每行的所有版本都存储在一个永不拆分的单一数据分片内，不建议将该值设置得太大，以免单行的所有更改累计超过 64 MiB，导致内存不足或其他问题。
- `num_replicas`：副本数量。默认值为 3。`system` 数据库、`meta`、`liveness` 和 `system` 数据分片的默认副本数为 5。 **注意**：集群中存在不可用节点时，副本数量不可缩减。
- `constraints`：副本位置的必需（+）和/或禁止（-）约束。例如 `constraints = '{+region=node1: 1, +region=node2: 1, +region=node3: 1}'` 表示在 `node1`、`node2`、`node3` 上必须各放置 1 个副本。目前只支持 `region=nodex` 格式。
- `lease_preferences`：主副本位置的必需（+）和/或禁止（-）约束的有序列表。例如 `lease_preferences = '[[+region=node1]]'` 表示倾向将主副本放置在 `node1`。如果不能满足首选项，KWDB 将尝试下一个优先级。如果所有首选项都无法满足，KWDB 将使用默认的租约分布算法，基于每个节点已持有的租约数量来决定租约位置，尝试平衡租约分布。列表中的每个值可以包含多个约束。
- `ts_merge.days`：时序数据分片合并时间。同一个时序表同哈希点按照时间戳分裂后，超过该时间的数据分片将自动合并，且合并后不会再自动拆分。默认值：10（10天）。设置值必须大于等于 0，设置值为 0 时表示时序数据分片按照时间戳分裂后便立刻自动合并。系统数据分片数量过多导致出现网络等故障时可以将该值适当调小，以缓解数据过大的问题。

**提示**：
- 租约偏好不必与 `constraints` 字段共享，用户可以单独定义 `lease_preferences`。
- 设置 `constraints` 时需要同步设置 `num_replicas`，且 `constraints` 数量需要小于等于 `num_replicas` 数量。`constraints` 中的顺序无影响。
- KWDB 默认只根据哈希点拆分数据分片，因此数据分片按时间合并功能默认关闭，如需支持按时间合并数据分片，需将 `kv.kvserver.ts_split_interval` 实时参数设置为 `1`, 将 `kv.kvserver.ts_split_by_timestamp.enabled` 实时参数设置为 `true` 以支持按照哈希点和时间戳拆分数据分片。 | | `value` | 变量值。 | |`COPY FROM PARENT`| 使用父区域的设置值。| -|`REBALANCE` | 手动触发数据分片的区域重新分配和负载均衡。

适用于以下场景：
- 关闭自动均衡后的主动调优
- 负载不均时的人工干预

KWDB 默认自动执行后台数据分片均衡，用户通过 `SET CLUSTER SETTING kv.allocator.ts_consider_rebalance.enabled = false;` 关闭自动均衡功能后，可在系统低负载时段进行手动均衡。

注意：
- 该功能仅适用于用户数据分片，不适用于系统数据分片
- 建议在业务低峰期执行，避免影响正常业务性能。 | |`DISCARD` | 移除区域配置，采用默认值。| +|`USING REBALANCE` | 手动触发数据库、表、或数据分片的区域重新分配和负载均衡。

适用于以下场景：
- 关闭自动均衡后的主动调优
- 负载不均时的人工干预

KWDB 默认自动执行后台数据分片均衡，用户通过 `SET CLUSTER SETTING kv.allocator.ts_consider_rebalance.enabled = false;` 关闭自动均衡功能后，可在系统低负载时段进行手动均衡。

注意：
- 该功能仅适用于用户数据分片，不适用于系统数据分片
- 建议在业务低峰期执行，避免影响正常业务性能。 | ### 语法示例 diff --git a/static/sql-reference/alter-db-zone-ts.png b/static/sql-reference/alter-db-zone-ts.png new file mode 100644 index 0000000000000000000000000000000000000000..3bdc3c7c59c6b8415af3cfe3459d3f89e45bb22e Binary files /dev/null and b/static/sql-reference/alter-db-zone-ts.png differ diff --git a/static/sql-reference/alter-ts-table.png b/static/sql-reference/alter-ts-table.png index 68e175a0c2bc8f3b70507cc4bcc15ee2374f56c0..7332b8e416be75b2ce712ec67c2579d840975c02 100644 Binary files a/static/sql-reference/alter-ts-table.png and b/static/sql-reference/alter-ts-table.png differ diff --git a/static/sql-reference/alter-zone.png b/static/sql-reference/alter-zone.png index 6f40bfbf2d9f755a32c721718a28a9c960ed1dea..cfcb377d929491b1155488674efa4a0114055cd9 100644 Binary files a/static/sql-reference/alter-zone.png and b/static/sql-reference/alter-zone.png differ diff --git a/static/sql-reference/createdb_ts.png b/static/sql-reference/createdb_ts.png index e2f9dd77b81eac3fd1b9b44dda564c63f24143dc..a995f610ef552729b553d667f9e2f1095160d76a 100644 Binary files a/static/sql-reference/createdb_ts.png and b/static/sql-reference/createdb_ts.png differ