Colocate Join

一个 CG 中会包含一张及以上的 Table。一个CG内的 Table 有相同的分桶方式和副本放置方式，使用 Colocation Group Schema 描述。

Colocation Group（CG）

包含 CG 的分桶键，分桶数以及副本数等信息。

Colocation Group Schema（CGS）

名词解释

是将一组拥有相同 CGS 的 Table 组成一个 CG。并保证这些 Table 对应的分桶副本会落在相同一组BE 节点上。使得当 CG 内的表进行分桶列上的 Join 操作时，可以直接进行本地数据 Join，减少数据在节点间的传输耗时。

原理

CG中所有 Table 的 Bucket Seq 和 BE 节点的映射关系和 Parent Table 一致

Parent Table 中所有 Partition 的 Bucket Seq 和 BE 节点的映射关系和第一个 Partition 一致。

Parent Table 第一个 Partition 的 Bucket Seq 和 BE 节点的映射关系利用原生的 Round Robin 算法决定。

特性

在 PROPERTIES 中指定属性 \"colocate_with\" = \"group_name\"

同一 CG 内的 Table 的分桶键的类型、数量和顺序完全一致，并且桶数一致，这样才能保证多张表的数据分片能够一一对应地进行分布控制。

同一个 CG 内所有表的所有分区（Partition）的副本数必须一致。

同一个 CG 内所有表的分区键，分区数量可以不同。

建表

GroupId：一个 Group 的全集群唯一标识，前半部分为 db id，后半部分为 group id。GroupName：Group 的全名。TabletIds：该 Group 包含的 Table 的 id 列表。BucketsNum：分桶数。ReplicationNum：副本数。DistCols：Distribution columns，即分桶列类型。IsStable：该 Group 是否稳定

SHOW PROC '/colocation_group';

子主题

BucketIndex：分桶序列的下标。BackendIds：分桶中数据分片所在的 BE 节点 id 列表。

查看一个 Group 的数据分布情况

注意：以上命令需要 ADMIN 权限。暂不支持普通用户查看。

查看 Group 信息

修改：ALTER TABLE tbName SET (\"colocate_with\" = \"groupName\");

当 Group 中最后一张表彻底删除后（彻底删除是指从回收站中删除。通常，一张表通过 DROP TABLE 命令删除后，会在回收站默认停留一天的时间后，再删除），该 Group 也会被自动删除。

删除：ALTER TABLE tbName SET (\"colocate_with\" = \"\");

修改、删除Group信息

对 Colocation 表的查询方式和普通表一样，用户无需感知 Colocation 属性。如果 Colocation 表所在的 Group 处于 Unstable 状态，将自动退化为普通 Join。

如果 Colocation Join 生效，则 Hash Join 节点会显示 colocate: true。

查看查询计划：DESC SELECT * FROM tbl1 INNER JOIN tbl2 ON (tbl1.k2 = tbl2.k2);

Colocate Join查询

Group 自身有一个 Stable 属性，当 Stable 为 true 时，表示当前 Group 内的表的所有分片没有正在进行变动，Colocation 特性可以正常使用。当 Stable 为 false 时（Unstable），表示当前 Group 内有部分表的分片正在做修复或迁移，此时，相关表的 Colocation Join 将退化为普通 Join。

副本只能存储在指定的 BE 节点上。所以当某个 BE 不可用时（宕机、Decommission 等），需要寻找一个新的 BE 进行替换。StarRocks 会优先寻找负载最低的 BE 进行替换。替换后，该 Bucket 内的所有在旧 BE 上的数据分片都要做修复。迁移过程中，Group 被标记为 Unstable。

副本修复

StarRocks 会尽力将 Colocation 表的分片均匀分布在所有 BE 节点上。对于普通表的副本均衡，是以单副本为粒度的，即单独为每一个副本寻找负载较低的 BE 节点即可。而 Colocation 表的均衡是 Bucket 级别的，即一个 Bucket 内的所有副本都会一起迁移。我们采用一个简单的均衡算法，即在不考虑副本实际大小，而只根据副本数量，将 BucketsSequnce 均匀的分布在所有 BE 上。具体算法可以参阅 ColocateTableBalancer.java 中的代码注释。

副本均衡

注1：当前的 Colocation 副本均衡和修复算法，对于异构部署的 StarRocks 集群效果可能不佳。所谓异构部署，即 BE 节点的磁盘容量、数量、磁盘类型（SSD 和 HDD）不一致。在异构部署情况下，可能出现小容量的 BE 节点和大容量的 BE 节点存储了相同的副本数量。

注2：当一个 Group 处于 Unstable 状态时，其中的表的 Join 将退化为普通 Join。此时可能会极大降低集群的查询性能。如果不希望系统自动均衡，可以设置 FE 的配置项 disable_colocate_balance 来禁止自动均衡。然后在合适的时间打开即可。

注意

Colocation 副本均衡和修复

使用

当对一个具有 Colocation 属性的表进行增加分区（ADD PARTITION）、修改副本数时，StarRocks 会检查修改是否会违反 Colocation Group Schema，如果违反则会拒绝。

Colocation Group Schema规范：分桶键，分桶数，副本数等数据，若不一致则禁止修改

若table建表时没指定分区键，则建表后不能添加分区

建表后，添加分区时可修改分桶数量

修改分区支持修改下列属性：storage_mediumstorage_cooldown_timereplication_numin_memory

注意：

其他相关操作

关闭语法：ADMIN SET FRONTEND CONFIG (\"disable_colocate_balance\" = \"true\");

关闭 StarRocks 的自动 Colocation 副本均衡，默认开启（false）

关闭语法：set disable_colocate_join = true

session 粒度关闭 colocate join 功能，默认开启（false）

相关配置

GET /api/colocate

查看集群的全部 Colocation 信息

POST /api/colocate/group_stable?db_id=10005&group_id=10008

POST /api/colocate/group_unstable?db_id=10005&group_id=10008

将 Group 标记为 Stable 或 Unstable

说明：其中 Body 是以嵌套数组表示的 BucketsSequence 以及每个 Bucket 中分片所在 BE 的 id。

注意，使用该命令，可能需要将 FE 的配置 disable_colocate_balance 设为 true。即关闭系统自动的 Colocation 副本修复和均衡。否则可能在修改后，会被系统自动重置。

设置 Group 的数据分布

HTTP Restful API

Colocate Join