xzj7019 commented on code in PR #1561:
URL: https://github.com/apache/doris-website/pull/1561#discussion_r1896448657
##########
i18n/zh-CN/docusaurus-plugin-content-docs/current/query-acceleration/colocation-join.md:
##########
@@ -0,0 +1,445 @@
+---
+{
+ "title": "Colocation Join",
+ "language": "zh-CN"
+}
+---
+
+<!--
+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.
+-->
+
+
+
+Colocation Join 旨在为某些 Join 查询提供本地性优化，来减少数据在节点间的传输耗时，加速查询。本文档主要介绍 Colocation
Join 的原理、实现、使用方式和注意事项。
+
+注意：这个属性不会被 CCR 同步，如果这个表是被 CCR 复制而来的，即 PROPERTIES 中包含`is_being_synced =
true`时，这个属性将会在这个表中被擦除。
+
+## 名词解释
+
+- Colocation Group（CG）：一个 CG 中会包含一张及以上的 Table。在同一个 Group 内的 Table 有着相同的
Colocation Group Schema，并且有着相同的数据分片分布。
+
+- Colocation Group Schema（CGS）：用于描述一个 CG 中的 Table，和 Colocation 相关的通用 Schema
信息。包括分桶列类型，分桶数以及副本数等。
+
+## 原理
+
+Colocation Join 功能，是将一组拥有相同 CGS 的 Table 组成一个 CG。并保证这些 Table 对应的数据分片会落在同一个 BE
节点上。使得当 CG 内的表进行分桶列上的 Join 操作时，可以通过直接进行本地数据 Join，减少数据在节点间的传输耗时。
+
+一个表的数据，最终会根据分桶列值 Hash、对桶数取模的后落在某一个分桶内。假设一个 Table 的分桶数为 8，则共有 `[0, 1, 2, 3, 4,
5, 6, 7]` 8 个分桶（Bucket），我们称这样一个序列为一个 `BucketsSequence`。每个 Bucket
内会有一个或多个数据分片（Tablet）。当表为单分区表时，一个 Bucket 内仅有一个 Tablet。如果是多分区表，则会有多个。
+
+为了使得 Table 能够有相同的数据分布，同一 CG 内的 Table 必须保证以下属性相同：
+
+1. 分桶列和分桶数
+
+ 分桶列，即在建表语句中 `DISTRIBUTED BY HASH(col1, col2, ...)`
中指定的列。分桶列决定了一张表的数据通过哪些列的值进行 Hash 划分到不同的 Tablet 中。同一 CG 内的 Table
必须保证分桶列的类型和数量完全一致，并且桶数一致，才能保证多张表的数据分片能够一一对应的进行分布控制。
+
+2. 副本数
+
+ 同一个 CG 内所有表的所有分区（Partition）的副本数必须一致。如果不一致，可能出现某一个 Tablet 的某一个副本，在同一个 BE
上没有其他的表分片的副本对应。
+
+同一个 CG 内的表，分区的个数、范围以及分区列的类型不要求一致。
+
+在固定了分桶列和分桶数后，同一个 CG 内的表会拥有相同的 BucketsSequence。而副本数决定了每个分桶内的 Tablet 的多个副本，存放在哪些
BE 上。假设 BucketsSequence 为 `[0, 1, 2, 3, 4, 5, 6, 7]`，BE 节点有 `[A, B, C, D]` 4
个。则一个可能的数据分布如下：
+
+```text
++---+ +---+ +---+ +---+ +---+ +---+ +---+ +---+
+| 0 | | 1 | | 2 | | 3 | | 4 | | 5 | | 6 | | 7 |
++---+ +---+ +---+ +---+ +---+ +---+ +---+ +---+
+| A | | B | | C | | D | | A | | B | | C | | D |
+| | | | | | | | | | | | | | | |
+| B | | C | | D | | A | | B | | C | | D | | A |
+| | | | | | | | | | | | | | | |
+| C | | D | | A | | B | | C | | D | | A | | B |
++---+ +---+ +---+ +---+ +---+ +---+ +---+ +---+
+```
+
+CG 内所有表的数据都会按照上面的规则进行统一分布，这样就保证了，分桶列值相同的数据都在同一个 BE 节点上，可以进行本地数据 Join。
+
+## 使用方式
+
+### 建表
+
+建表时，可以在 `PROPERTIES` 中指定属性 `"colocate_with" = "group_name"`，表示这个表是一个
Colocation Join 表，并且归属于一个指定的 Colocation Group。
+
+示例：
+
+```sql
+CREATE TABLE tbl (k1 int, v1 int sum)
+DISTRIBUTED BY HASH(k1)
+BUCKETS 8
+PROPERTIES(
+ "colocate_with" = "group1"
+);
+```
+
+如果指定的 Group 不存在，则 Doris 会自动创建一个只包含当前这张表的 Group。如果 Group 已存在，则 Doris 会检查当前表是否满足
Colocation Group Schema。如果满足，则会创建该表，并将该表加入 Group。同时，表会根据已存在的 Group
中的数据分布规则创建分片和副本。Group 归属于一个 Database，Group 的名字在一个 Database 内唯一。在内部存储是 Group
的全名为 `dbId_groupName`，但用户只感知 groupName。
+
+
+
+:::tip
+2.0 版本中，Doris 支持了跨 Database 的 Group。
+:::
+
+在建表时，需使用关键词 `__global__` 作为 Group 名称的前缀。如：
+
+```
Review Comment:
done
##########
i18n/zh-CN/docusaurus-plugin-content-docs/current/query-acceleration/colocation-join.md:
##########
@@ -0,0 +1,445 @@
+---
+{
+ "title": "Colocation Join",
+ "language": "zh-CN"
+}
+---
+
+<!--
+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.
+-->
+
+
+
+Colocation Join 旨在为某些 Join 查询提供本地性优化，来减少数据在节点间的传输耗时，加速查询。本文档主要介绍 Colocation
Join 的原理、实现、使用方式和注意事项。
+
+注意：这个属性不会被 CCR 同步，如果这个表是被 CCR 复制而来的，即 PROPERTIES 中包含`is_being_synced =
true`时，这个属性将会在这个表中被擦除。
+
+## 名词解释
+
+- Colocation Group（CG）：一个 CG 中会包含一张及以上的 Table。在同一个 Group 内的 Table 有着相同的
Colocation Group Schema，并且有着相同的数据分片分布。
+
+- Colocation Group Schema（CGS）：用于描述一个 CG 中的 Table，和 Colocation 相关的通用 Schema
信息。包括分桶列类型，分桶数以及副本数等。
+
+## 原理
+
+Colocation Join 功能，是将一组拥有相同 CGS 的 Table 组成一个 CG。并保证这些 Table 对应的数据分片会落在同一个 BE
节点上。使得当 CG 内的表进行分桶列上的 Join 操作时，可以通过直接进行本地数据 Join，减少数据在节点间的传输耗时。
+
+一个表的数据，最终会根据分桶列值 Hash、对桶数取模的后落在某一个分桶内。假设一个 Table 的分桶数为 8，则共有 `[0, 1, 2, 3, 4,
5, 6, 7]` 8 个分桶（Bucket），我们称这样一个序列为一个 `BucketsSequence`。每个 Bucket
内会有一个或多个数据分片（Tablet）。当表为单分区表时，一个 Bucket 内仅有一个 Tablet。如果是多分区表，则会有多个。
+
+为了使得 Table 能够有相同的数据分布，同一 CG 内的 Table 必须保证以下属性相同：
+
+1. 分桶列和分桶数
+
+ 分桶列，即在建表语句中 `DISTRIBUTED BY HASH(col1, col2, ...)`
中指定的列。分桶列决定了一张表的数据通过哪些列的值进行 Hash 划分到不同的 Tablet 中。同一 CG 内的 Table
必须保证分桶列的类型和数量完全一致，并且桶数一致，才能保证多张表的数据分片能够一一对应的进行分布控制。
+
+2. 副本数
+
+ 同一个 CG 内所有表的所有分区（Partition）的副本数必须一致。如果不一致，可能出现某一个 Tablet 的某一个副本，在同一个 BE
上没有其他的表分片的副本对应。
+
+同一个 CG 内的表，分区的个数、范围以及分区列的类型不要求一致。
+
+在固定了分桶列和分桶数后，同一个 CG 内的表会拥有相同的 BucketsSequence。而副本数决定了每个分桶内的 Tablet 的多个副本，存放在哪些
BE 上。假设 BucketsSequence 为 `[0, 1, 2, 3, 4, 5, 6, 7]`，BE 节点有 `[A, B, C, D]` 4
个。则一个可能的数据分布如下：
+
+```text
++---+ +---+ +---+ +---+ +---+ +---+ +---+ +---+
+| 0 | | 1 | | 2 | | 3 | | 4 | | 5 | | 6 | | 7 |
++---+ +---+ +---+ +---+ +---+ +---+ +---+ +---+
+| A | | B | | C | | D | | A | | B | | C | | D |
+| | | | | | | | | | | | | | | |
+| B | | C | | D | | A | | B | | C | | D | | A |
+| | | | | | | | | | | | | | | |
+| C | | D | | A | | B | | C | | D | | A | | B |
++---+ +---+ +---+ +---+ +---+ +---+ +---+ +---+
+```
+
+CG 内所有表的数据都会按照上面的规则进行统一分布，这样就保证了，分桶列值相同的数据都在同一个 BE 节点上，可以进行本地数据 Join。
+
+## 使用方式
+
+### 建表
+
+建表时，可以在 `PROPERTIES` 中指定属性 `"colocate_with" = "group_name"`，表示这个表是一个
Colocation Join 表，并且归属于一个指定的 Colocation Group。
+
+示例：
+
+```sql
+CREATE TABLE tbl (k1 int, v1 int sum)
+DISTRIBUTED BY HASH(k1)
+BUCKETS 8
+PROPERTIES(
+ "colocate_with" = "group1"
+);
+```
+
+如果指定的 Group 不存在，则 Doris 会自动创建一个只包含当前这张表的 Group。如果 Group 已存在，则 Doris 会检查当前表是否满足
Colocation Group Schema。如果满足，则会创建该表，并将该表加入 Group。同时，表会根据已存在的 Group
中的数据分布规则创建分片和副本。Group 归属于一个 Database，Group 的名字在一个 Database 内唯一。在内部存储是 Group
的全名为 `dbId_groupName`，但用户只感知 groupName。
+
+
+
+:::tip
+2.0 版本中，Doris 支持了跨 Database 的 Group。
+:::
+
+在建表时，需使用关键词 `__global__` 作为 Group 名称的前缀。如：
+
+```
+CREATE TABLE tbl (k1 int, v1 int sum)
+DISTRIBUTED BY HASH(k1)
+BUCKETS 8
+PROPERTIES(
+ "colocate_with" = "__global__group1"
+);
+```
+
+`__global__` 前缀的 Group 不再归属于一个 Database，其名称也是全局唯一的。
+
+通过创建 Global Group，可以实现跨 Database 的 Colocate Join。
+
+
+
+### 删表
+
+当 Group 中最后一张表彻底删除后（彻底删除是指从回收站中删除。通常，一张表通过 `DROP TABLE`
命令删除后，会在回收站默认停留一天的时间后，再删除），该 Group 也会被自动删除。
+
+### 查看 Group
+
+以下命令可以查看集群内已存在的 Group 信息。
+
+```sql
+SHOW PROC '/colocation_group';
+
++-------------+--------------+--------------+------------+----------------+----------+----------+
+| GroupId | GroupName | TableIds | BucketsNum | ReplicationNum |
DistCols | IsStable |
++-------------+--------------+--------------+------------+----------------+----------+----------+
+| 10005.10008 | 10005_group1 | 10007, 10040 | 10 | 3 |
int(11) | true |
++-------------+--------------+--------------+------------+----------------+----------+----------+
+```
+
+- GroupId：一个 Group 的全集群唯一标识，前半部分为 db id，后半部分为 group id。
+
+- GroupName：Group 的全名。
+
+- TabletIds：该 Group 包含的 Table 的 id 列表。
+
+- BucketsNum：分桶数。
+
+- ReplicationNum：副本数。
+
+- DistCols：Distribution columns，即分桶列类型。
+
+- IsStable：该 Group 是否稳定（稳定的定义，见 `Colocation 副本均衡和修复` 一节）。
+
+通过以下命令可以进一步查看一个 Group 的数据分布情况：
+
+```sql
+SHOW PROC '/colocation_group/10005.10008';
+
++-------------+---------------------+
+| BucketIndex | BackendIds |
++-------------+---------------------+
+| 0 | 10004, 10002, 10001 |
+| 1 | 10003, 10002, 10004 |
+| 2 | 10002, 10004, 10001 |
+| 3 | 10003, 10002, 10004 |
+| 4 | 10002, 10004, 10003 |
+| 5 | 10003, 10002, 10001 |
+| 6 | 10003, 10004, 10001 |
+| 7 | 10003, 10004, 10002 |
++-------------+---------------------+
+```
+
+- BucketIndex：分桶序列的下标。
+
+- BackendIds：分桶中数据分片所在的 BE 节点 id 列表。
+
+:::note
Review Comment:
done
--
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: commits-unsubscr...@doris.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@doris.apache.org
For additional commands, e-mail: commits-h...@doris.apache.org
