From fca156a1dff82b966c1760577c49658e0b3d35d4 Mon Sep 17 00:00:00 2001 From: WenyXu Date: Tue, 16 Jun 2026 17:50:11 +0800 Subject: [PATCH 1/3] docs: improve table sharding repartition flow Signed-off-by: WenyXu --- .../manage-data/table-sharding.md | 52 ++++++++++++++++--- .../manage-data/table-sharding.md | 52 ++++++++++++++++--- 2 files changed, 92 insertions(+), 12 deletions(-) diff --git a/docs/user-guide/deployments-administration/manage-data/table-sharding.md b/docs/user-guide/deployments-administration/manage-data/table-sharding.md index d764eb778..a160f166f 100644 --- a/docs/user-guide/deployments-administration/manage-data/table-sharding.md +++ b/docs/user-guide/deployments-administration/manage-data/table-sharding.md @@ -1,6 +1,6 @@ --- keywords: [table sharding, GreptimeDB, partitioning methods, distributed tables, data management, SQL, query performance] -description: Explains table sharding in GreptimeDB, including when to shard a table, partitioning methods, creating distributed tables, inserting data, querying data, and inspecting sharded tables. +description: Explains table sharding in GreptimeDB, including when to shard a table, partitioning methods, creating and partitioning distributed tables, inserting data, querying data, and inspecting sharded tables. --- # Table Sharding @@ -69,9 +69,7 @@ We recommend partitioning on Tag columns (the primary key columns). This matters The parentheses in `PARTITION ON COLUMNS (...)` only accept column names (e.g., `device_id`, `area`), not expressions like `device_id + 1`. GreptimeDB does not support MySQL's `PARTITION BY RANGE` syntax. ::: -### Example - -## Create a distributed table +## Create a partitioned table You can use the MySQL CLI to [connect to GreptimeDB](/user-guide/protocols/mysql.md) and create a distributed table. The following example creates a table and partitions it based on the `device_id` column. @@ -112,9 +110,51 @@ PARTITION ON COLUMNS (device_id, area) ( The following content uses the `sensor_readings` table with two partition columns as an example. -## Repartition a sharded table +## Add partitions to an existing table + +You can also partition an existing unpartitioned table with `ALTER TABLE ... PARTITION ON COLUMNS`. +The syntax is similar to creating a partitioned table, except that the partition rule is added to an existing table: + +```sql +ALTER TABLE sensor_readings PARTITION ON COLUMNS (device_id, area) ( + device_id < 100 AND area < 'South', + device_id < 100 AND area >= 'South', + device_id >= 100 AND area <= 'East', + device_id >= 100 AND area > 'East' +); +``` + +This is useful when a table starts as a single-partition table and later needs to be distributed across multiple regions. + +:::warning Warning +Partitioning an existing table is a repartitioning operation. It is only supported in distributed clusters and requires shared object storage and GC. For the full prerequisites, see [Repartition](/user-guide/deployments-administration/manage-data/repartition.md#prerequisites). +::: + +## Adjust partition rules + +After a table is partitioned, you can keep tuning its partition layout by splitting hot partitions or merging small cold partitions. + +Use `SPLIT PARTITION` to split an existing partition into multiple partitions: + +```sql +ALTER TABLE sensor_readings SPLIT PARTITION ( + device_id < 100 AND area < 'South' +) INTO ( + device_id < 50 AND area < 'South', + device_id >= 50 AND device_id < 100 AND area < 'South' +); +``` + +Use `MERGE PARTITION` to merge multiple partitions into one: + +```sql +ALTER TABLE sensor_readings MERGE PARTITION ( + device_id < 100 AND area < 'South', + device_id < 100 AND area >= 'South' +); +``` -If you need to modify partition rules for an existing table, refer to the separate [Repartition](/user-guide/deployments-administration/manage-data/repartition.md) page. +For prerequisites, hotspot diagnosis, and more step-by-step examples, see [Repartition](/user-guide/deployments-administration/manage-data/repartition.md). ## Insert data into the table diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments-administration/manage-data/table-sharding.md b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments-administration/manage-data/table-sharding.md index 39b2c6e37..9ffd524c7 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments-administration/manage-data/table-sharding.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments-administration/manage-data/table-sharding.md @@ -1,6 +1,6 @@ --- keywords: [表分片, 分区规则, 分布式表, 插入数据, 分布式查询] -description: 介绍表分片技术及其在 GreptimeDB 中的应用，包括分片时机、分区规则、创建分布式表、插入数据和分布式查询等内容。 +description: 介绍表分片技术及其在 GreptimeDB 中的应用，包括分片时机、分区规则、创建和调整分布式表、插入数据和分布式查询等内容。 --- # 表分片 @@ -69,9 +69,7 @@ PARTITION ON COLUMNS () ( `PARTITION ON COLUMNS` 括号里只能写列名（如 `device_id`、`area`），不支持表达式。GreptimeDB 不支持 MySQL 的 `PARTITION BY RANGE` 语法。 ::: -### 示例 - -## 创建分布式表 +## 创建分区表 你可以使用 MySQL CLI [连接到 GreptimeDB](/user-guide/protocols/mysql.md) 并创建一个分布式表。 下方的示例创建了一个表并基于 `device_id` 列进行分区。 @@ -112,9 +110,51 @@ PARTITION ON COLUMNS (device_id, area) ( 以下内容以具有两个分区列的 `sensor_readings` 表为例。 -## 重分区 +## 为已有表添加分区 + +你也可以使用 `ALTER TABLE ... PARTITION ON COLUMNS` 为已有的未分区表创建分区。 +它的语法和创建分区表类似，只是把分区规则添加到已有表上： + +```sql +ALTER TABLE sensor_readings PARTITION ON COLUMNS (device_id, area) ( + device_id < 100 AND area < 'South', + device_id < 100 AND area >= 'South', + device_id >= 100 AND area <= 'East', + device_id >= 100 AND area > 'East' +); +``` + +当一张表最初是单分区表，后续需要分布到多个 region 上时，可以使用这种方式。 + +:::warning 警告 +为已有表创建分区属于重分区操作，仅支持分布式集群，并且需要共享对象存储和 GC。完整前置条件请参考[重分区](/user-guide/deployments-administration/manage-data/repartition.md#前置条件)。 +::: + +## 调整分区规则 + +表分区后，你可以继续通过拆分热点分区或合并较小的冷分区来调整分区布局。 + +使用 `SPLIT PARTITION` 将已有分区拆分为多个分区： + +```sql +ALTER TABLE sensor_readings SPLIT PARTITION ( + device_id < 100 AND area < 'South' +) INTO ( + device_id < 50 AND area < 'South', + device_id >= 50 AND device_id < 100 AND area < 'South' +); +``` + +使用 `MERGE PARTITION` 将多个分区合并为一个分区： + +```sql +ALTER TABLE sensor_readings MERGE PARTITION ( + device_id < 100 AND area < 'South', + device_id < 100 AND area >= 'South' +); +``` -如果你需要修改已创建表的分区规则，请参考单独的 [重分区](/user-guide/deployments-administration/manage-data/repartition.md) 页面。 +如需了解前置条件、热点分区判断方法和更多分步示例，请参考[重分区](/user-guide/deployments-administration/manage-data/repartition.md)。 ## 向表中插入数据 From 2ff0ca7cc319eb2fa87b9a963dcf4134a79eb38f Mon Sep 17 00:00:00 2001 From: WenyXu Date: Tue, 16 Jun 2026 19:41:04 +0800 Subject: [PATCH 2/3] docs: refine existing table partition wording Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus Signed-off-by: WenyXu --- .../manage-data/table-sharding.md | 2 +- .../manage-data/table-sharding.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/deployments-administration/manage-data/table-sharding.md b/docs/user-guide/deployments-administration/manage-data/table-sharding.md index a160f166f..a6c9438ca 100644 --- a/docs/user-guide/deployments-administration/manage-data/table-sharding.md +++ b/docs/user-guide/deployments-administration/manage-data/table-sharding.md @@ -110,7 +110,7 @@ PARTITION ON COLUMNS (device_id, area) ( The following content uses the `sensor_readings` table with two partition columns as an example. -## Add partitions to an existing table +## Partition an existing table You can also partition an existing unpartitioned table with `ALTER TABLE ... PARTITION ON COLUMNS`. The syntax is similar to creating a partitioned table, except that the partition rule is added to an existing table: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments-administration/manage-data/table-sharding.md b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments-administration/manage-data/table-sharding.md index 9ffd524c7..9c6f130f0 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments-administration/manage-data/table-sharding.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments-administration/manage-data/table-sharding.md @@ -110,9 +110,9 @@ PARTITION ON COLUMNS (device_id, area) ( 以下内容以具有两个分区列的 `sensor_readings` 表为例。 -## 为已有表添加分区 +## 为已有表分区 -你也可以使用 `ALTER TABLE ... PARTITION ON COLUMNS` 为已有的未分区表创建分区。 +你也可以使用 `ALTER TABLE ... PARTITION ON COLUMNS` 为已有的未分区表分区。 它的语法和创建分区表类似，只是把分区规则添加到已有表上： ```sql @@ -127,7 +127,7 @@ ALTER TABLE sensor_readings PARTITION ON COLUMNS (device_id, area) ( 当一张表最初是单分区表，后续需要分布到多个 region 上时，可以使用这种方式。 :::warning 警告 -为已有表创建分区属于重分区操作，仅支持分布式集群，并且需要共享对象存储和 GC。完整前置条件请参考[重分区](/user-guide/deployments-administration/manage-data/repartition.md#前置条件)。 +为已有表分区属于重分区操作，仅支持分布式集群，并且需要共享对象存储和 GC。完整前置条件请参考[重分区](/user-guide/deployments-administration/manage-data/repartition.md#前置条件)。 ::: ## 调整分区规则 From f78a555716f4c9399eb075b37ae290fa5908afa9 Mon Sep 17 00:00:00 2001 From: WenyXu Date: Tue, 16 Jun 2026 19:43:53 +0800 Subject: [PATCH 3/3] docs: sync table sharding changes to v1.1 Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus Signed-off-by: WenyXu --- .../manage-data/table-sharding.md | 52 ++++++++++++++++--- .../manage-data/table-sharding.md | 52 ++++++++++++++++--- 2 files changed, 92 insertions(+), 12 deletions(-) diff --git a/i18n/zh/docusaurus-plugin-content-docs/version-1.1/user-guide/deployments-administration/manage-data/table-sharding.md b/i18n/zh/docusaurus-plugin-content-docs/version-1.1/user-guide/deployments-administration/manage-data/table-sharding.md index 39b2c6e37..9c6f130f0 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/version-1.1/user-guide/deployments-administration/manage-data/table-sharding.md +++ b/i18n/zh/docusaurus-plugin-content-docs/version-1.1/user-guide/deployments-administration/manage-data/table-sharding.md @@ -1,6 +1,6 @@ --- keywords: [表分片, 分区规则, 分布式表, 插入数据, 分布式查询] -description: 介绍表分片技术及其在 GreptimeDB 中的应用，包括分片时机、分区规则、创建分布式表、插入数据和分布式查询等内容。 +description: 介绍表分片技术及其在 GreptimeDB 中的应用，包括分片时机、分区规则、创建和调整分布式表、插入数据和分布式查询等内容。 --- # 表分片 @@ -69,9 +69,7 @@ PARTITION ON COLUMNS () ( `PARTITION ON COLUMNS` 括号里只能写列名（如 `device_id`、`area`），不支持表达式。GreptimeDB 不支持 MySQL 的 `PARTITION BY RANGE` 语法。 ::: -### 示例 - -## 创建分布式表 +## 创建分区表 你可以使用 MySQL CLI [连接到 GreptimeDB](/user-guide/protocols/mysql.md) 并创建一个分布式表。 下方的示例创建了一个表并基于 `device_id` 列进行分区。 @@ -112,9 +110,51 @@ PARTITION ON COLUMNS (device_id, area) ( 以下内容以具有两个分区列的 `sensor_readings` 表为例。 -## 重分区 +## 为已有表分区 + +你也可以使用 `ALTER TABLE ... PARTITION ON COLUMNS` 为已有的未分区表分区。 +它的语法和创建分区表类似，只是把分区规则添加到已有表上： + +```sql +ALTER TABLE sensor_readings PARTITION ON COLUMNS (device_id, area) ( + device_id < 100 AND area < 'South', + device_id < 100 AND area >= 'South', + device_id >= 100 AND area <= 'East', + device_id >= 100 AND area > 'East' +); +``` + +当一张表最初是单分区表，后续需要分布到多个 region 上时，可以使用这种方式。 + +:::warning 警告 +为已有表分区属于重分区操作，仅支持分布式集群，并且需要共享对象存储和 GC。完整前置条件请参考[重分区](/user-guide/deployments-administration/manage-data/repartition.md#前置条件)。 +::: + +## 调整分区规则 + +表分区后，你可以继续通过拆分热点分区或合并较小的冷分区来调整分区布局。 + +使用 `SPLIT PARTITION` 将已有分区拆分为多个分区： + +```sql +ALTER TABLE sensor_readings SPLIT PARTITION ( + device_id < 100 AND area < 'South' +) INTO ( + device_id < 50 AND area < 'South', + device_id >= 50 AND device_id < 100 AND area < 'South' +); +``` + +使用 `MERGE PARTITION` 将多个分区合并为一个分区： + +```sql +ALTER TABLE sensor_readings MERGE PARTITION ( + device_id < 100 AND area < 'South', + device_id < 100 AND area >= 'South' +); +``` -如果你需要修改已创建表的分区规则，请参考单独的 [重分区](/user-guide/deployments-administration/manage-data/repartition.md) 页面。 +如需了解前置条件、热点分区判断方法和更多分步示例，请参考[重分区](/user-guide/deployments-administration/manage-data/repartition.md)。 ## 向表中插入数据 diff --git a/versioned_docs/version-1.1/user-guide/deployments-administration/manage-data/table-sharding.md b/versioned_docs/version-1.1/user-guide/deployments-administration/manage-data/table-sharding.md index d764eb778..a6c9438ca 100644 --- a/versioned_docs/version-1.1/user-guide/deployments-administration/manage-data/table-sharding.md +++ b/versioned_docs/version-1.1/user-guide/deployments-administration/manage-data/table-sharding.md @@ -1,6 +1,6 @@ --- keywords: [table sharding, GreptimeDB, partitioning methods, distributed tables, data management, SQL, query performance] -description: Explains table sharding in GreptimeDB, including when to shard a table, partitioning methods, creating distributed tables, inserting data, querying data, and inspecting sharded tables. +description: Explains table sharding in GreptimeDB, including when to shard a table, partitioning methods, creating and partitioning distributed tables, inserting data, querying data, and inspecting sharded tables. --- # Table Sharding @@ -69,9 +69,7 @@ We recommend partitioning on Tag columns (the primary key columns). This matters The parentheses in `PARTITION ON COLUMNS (...)` only accept column names (e.g., `device_id`, `area`), not expressions like `device_id + 1`. GreptimeDB does not support MySQL's `PARTITION BY RANGE` syntax. ::: -### Example - -## Create a distributed table +## Create a partitioned table You can use the MySQL CLI to [connect to GreptimeDB](/user-guide/protocols/mysql.md) and create a distributed table. The following example creates a table and partitions it based on the `device_id` column. @@ -112,9 +110,51 @@ PARTITION ON COLUMNS (device_id, area) ( The following content uses the `sensor_readings` table with two partition columns as an example. -## Repartition a sharded table +## Partition an existing table + +You can also partition an existing unpartitioned table with `ALTER TABLE ... PARTITION ON COLUMNS`. +The syntax is similar to creating a partitioned table, except that the partition rule is added to an existing table: + +```sql +ALTER TABLE sensor_readings PARTITION ON COLUMNS (device_id, area) ( + device_id < 100 AND area < 'South', + device_id < 100 AND area >= 'South', + device_id >= 100 AND area <= 'East', + device_id >= 100 AND area > 'East' +); +``` + +This is useful when a table starts as a single-partition table and later needs to be distributed across multiple regions. + +:::warning Warning +Partitioning an existing table is a repartitioning operation. It is only supported in distributed clusters and requires shared object storage and GC. For the full prerequisites, see [Repartition](/user-guide/deployments-administration/manage-data/repartition.md#prerequisites). +::: + +## Adjust partition rules + +After a table is partitioned, you can keep tuning its partition layout by splitting hot partitions or merging small cold partitions. + +Use `SPLIT PARTITION` to split an existing partition into multiple partitions: + +```sql +ALTER TABLE sensor_readings SPLIT PARTITION ( + device_id < 100 AND area < 'South' +) INTO ( + device_id < 50 AND area < 'South', + device_id >= 50 AND device_id < 100 AND area < 'South' +); +``` + +Use `MERGE PARTITION` to merge multiple partitions into one: + +```sql +ALTER TABLE sensor_readings MERGE PARTITION ( + device_id < 100 AND area < 'South', + device_id < 100 AND area >= 'South' +); +``` -If you need to modify partition rules for an existing table, refer to the separate [Repartition](/user-guide/deployments-administration/manage-data/repartition.md) page. +For prerequisites, hotspot diagnosis, and more step-by-step examples, see [Repartition](/user-guide/deployments-administration/manage-data/repartition.md). ## Insert data into the table