--- title: "Runtime Filter - OceanBase 数据库 V4.3.0 | OceanBase 文档中心" description: Runtime Filter OceanBase 数据库支持 Hash Join 联接算法，可以将两个表基于某些字段进行等值匹配连接。然而，当参与连接的表尤其是参与 Probe Table 的数据量较大时，Hash Join 的性能会受到很大的影响，在这种情况下，Hash Join 可以使用 Runtime Filt… --- 切换语言 - 中文站 - 简体中文 - International - English - 日本站 - 日本語 文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库分布式版 - V 4.3.0 # Runtime Filter 更新时间：2026-04-10 11:58:35 [编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.3.0/zh-CN/700.reference/1000.performance-tuning-guide/500.sql-optimization/400.sql-optimization/600.query-optimization/200.join-algorithm/300.runtime-filter.md) OceanBase 数据库支持 Hash Join 联接算法，可以将两个表基于某些字段进行等值匹配连接。然而，当参与连接的表尤其是参与 Probe Table 的数据量较大时，Hash Join 的性能会受到很大的影响，在这种情况下，Hash Join 可以使用 Runtime Filter（RF）来提高效率。 ## 原理介绍 Runtime Filter 是一种用于优化 Hash Join 性能的技术，它可以通过减少使用 Hash Join 时所需 Probe 的数据量来提高查询的效率。例如，在星形连接的多张维度表和实施表 Join 的场景中，Runtime Filter 是一个非常有效的优化手段。 Runtime Filter 实际上是一个过滤器，它可以利用 Hash Join 的 Build 过程构建一个轻量的 Filter，然后将 Filter 广播发送给参与 Probe 的大表，Probe Table 可以使用多个 Runtime Filter 来提前在存储层过滤数据，减少真正参与 Hash Join 以及网络传输的数据，从而提高查询的效率。 Runtime Filter 可以基于三个层面进行分类：基于是否需要跨机传输层面，Runtime Filter 可以分为 Local 和 Global 两类；基于 Runtime Filter 的数据结构层面，Runtime Filter 可以分为 Bloom Filter、In Filter 和 Range Filter 三类。无论是 Local Runtime Filter 还是 Global Runtime Filter，都可以使用这三种数据结构的 Runtime Filter；基于 Runtime Filter 过滤的实体层面，Runtime Filter 可以分为过滤连接键和过滤分区两类，第一类为普通 Runtime Filter，第二类为 Part Join Filter。基于过滤的实体层面的分类和和基于需要跨机传输层面分类是正交的。普通 Runtime Filter 支持三种数据结构的 Runtime Filter，而 Part Join Filter 当前仅支持 Bloom Filter。 本文将通过具体示例详细介绍 Local Runtime Filter、Global Runtime Filter 和 Part Join Filter。 ### Local Runtime Filter Local Runtime Filter 的 Runtime Filter 无需经历网络传输，其所构建的 Filter 只需要在本地节点计算过滤条件。Local Runtime Filter 通常适用于 Hash Join Probe 侧没有 Shuffle 的场景。 如下为 Local Runtime Filter 执行计划的示例。 ```shell obclient> CREATE TABLE tt1(v1 INT, v2 INT) PARTITION BY HASH(v1) PARTITIONS 5; Query OK, 0 rows affected obclient> CREATE TABLE tt2(v1 INT, v2 INT) PARTITION BY HASH(v1) PARTITIONS 5; Query OK, 0 rows affected obclient> EXPLAIN SELECT /*+ PX_JOIN_FILTER(tt2) PARALLEL(4) */ * FROM tt1 JOIN tt2 ON tt1.v1=tt2.v1; +------------------------------------------------------------------------------------------------------------------------------------+ | Query Plan | +------------------------------------------------------------------------------------------------------------------------------------+ | ============================================================== | | |ID|OPERATOR |NAME |EST.ROWS|EST.TIME(us)| | | -------------------------------------------------------------- | | |0 |PX COORDINATOR | |1 |7 | | | |1 |└─EXCHANGE OUT DISTR |:EX10000|1 |6 | | | |2 | └─PX PARTITION ITERATOR | |1 |6 | | | |3 | └─HASH JOIN | |1 |6 | | | |4 | ├─JOIN FILTER CREATE|:RF0000 |1 |3 | | | |5 | │ └─TABLE FULL SCAN |tt2 |1 |3 | | | |6 | └─JOIN FILTER USE |:RF0000 |1 |4 | | | |7 | └─TABLE FULL SCAN |tt1 |1 |4 | | | ============================================================== | | Outputs & filters: | | ------------------------------------- | | 0 - output([INTERNAL_FUNCTION(tt1.v1, tt1.v2, tt2.v1, tt2.v2)]), filter(nil), rowset=256 | | 1 - output([INTERNAL_FUNCTION(tt1.v1, tt1.v2, tt2.v1, tt2.v2)]), filter(nil), rowset=256 | | dop=4 | | 2 - output([tt1.v1], [tt2.v1], [tt2.v2], [tt1.v2]), filter(nil), rowset=256 | | partition wise, force partition granule | | 3 - output([tt1.v1], [tt2.v1], [tt2.v2], [tt1.v2]), filter(nil), rowset=256 | | equal_conds ([tt1.v1 = tt2.v1]), other_conds(nil) | | 4 - output([tt2.v1], [tt2.v2]), filter(nil), rowset=256 | | RF_TYPE(in, range, bloom), RF_EXPR[tt2.v1] | | 5 - output([tt2.v1], [tt2.v2]), filter(nil), rowset=256 | | access([tt2.v1], [tt2.v2]), partitions(p[0-4]) | | is_index_back=false, is_global_index=false, | | range_key([tt2.__pk_increment]), range(MIN ; MAX)always true | | 6 - output([tt1.v1], [tt1.v2]), filter(nil), rowset=256 | | 7 - output([tt1.v1], [tt1.v2]), filter([RF_IN_FILTER(tt1.v1)], [RF_RANGE_FILTER(tt1.v1)], [RF_BLOOM_FILTER(tt1.v1)]), rowset=256 | | access([tt1.v1], [tt1.v2]), partitions(p[0-4]) | | is_index_back=false, is_global_index=false, filter_before_indexback[false,false,false], | | range_key([tt1.__pk_increment]), range(MIN ; MAX)always true | +------------------------------------------------------------------------------------------------------------------------------------+ 32 rows in set ``` 上述示例中，`NAME` 字段值为 `RF0000` 的 4 号 `JOIN FILTER CREATE` 和 6 号 `JOIN FILTER USE` 算子就是普通 Runtime Filter，它们在该计划中构建了一个 Local Runtime Filter，该 Filter 无需网络传播，仅在本机使用。 ### Global Runtime Filter Global Runtime Filter 的 Runtime Filter 需要广播传输给多个执行节点，并且在计划形态中可以按需将 RF 嵌套下压至计划中的任意位置完成过滤。相比 Local Runtime Filter，Global Runtime Filter 的节省代价不仅包括 SQL 层投影及计算开销，还包括了网络传输，因此往往性能获得不错的执行性能提升。 如下为 Global Runtime Filter 执行计划的示例。 ```shell obclient> CREATE TABLE tt1 (c1_rand INT, c2_rand INT, c3_rand INT, c4_rand INT, c5_rand INT) PARTITION BY HASH(c5_rand) PARTITIONS 5; Query OK, 0 rows affected obclient> CREATE TABLE tt2 (c1_rand INT, c2_rand INT, c3_rand INT, c4_rand INT, c5_rand INT) PARTITION BY HASH(c5_rand) PARTITIONS 5; Query OK, 0 rows affected obclient> CREATE TABLE tt3 (c1_rand INT, c2_rand INT, c3_rand INT, c4_rand INT, c5_rand INT) PARTITION BY HASH(c5_rand) PARTITIONS 5; Query OK, 0 rows affected obclient> EXPLAIN BASIC SELECT /*+ LEADING(a (b c)) PARALLEL(3) USE_HASH(b) USE_HASH(c) PQ_DISTRIBUTE(c HASH HASH) PX_JOIN_FILTER(c a) PX_JOIN_FILTER(c b) */ COUNT(*) FROM tt1 a, tt2 b, tt3 c WHERE a.c1_rand=b.c1_rand AND a.c2_rand = c.c2_rand AND b.c3_rand = c.c3_rand; +------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Query Plan | +------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | ======================================================== | | |ID|OPERATOR |NAME | | | -------------------------------------------------------- | | |0 |SCALAR GROUP BY | | | | |1 |└─PX COORDINATOR | | | | |2 | └─EXCHANGE OUT DISTR |:EX10003| | | |3 | └─MERGE GROUP BY | | | | |4 | └─SHARED HASH JOIN | | | | |5 | ├─JOIN FILTER CREATE |:RF0001 | | | |6 | │ └─EXCHANGE IN DISTR | | | | |7 | │ └─EXCHANGE OUT DISTR (BC2HOST)|:EX10000| | | |8 | │ └─PX BLOCK ITERATOR | | | | |9 | │ └─TABLE FULL SCAN |a | | | |10| └─HASH JOIN | | | | |11| ├─JOIN FILTER CREATE |:RF0000 | | | |12| │ └─EXCHANGE IN DISTR | | | | |13| │ └─EXCHANGE OUT DISTR (HASH) |:EX10001| | | |14| │ └─PX BLOCK ITERATOR | | | | |15| │ └─TABLE FULL SCAN |b | | | |16| └─EXCHANGE IN DISTR | | | | |17| └─EXCHANGE OUT DISTR (HASH) |:EX10002| | | |18| └─JOIN FILTER USE |:RF0000 | | | |19| └─JOIN FILTER USE |:RF0001 | | | |20| └─PX BLOCK ITERATOR | | | | |21| └─TABLE FULL SCAN |c | | | ======================================================== | | Outputs & filters: | | ------------------------------------- | | 0 - output([T_FUN_COUNT_SUM(T_FUN_COUNT(*))]), filter(nil), rowset=256 | | group(nil), agg_func([T_FUN_COUNT_SUM(T_FUN_COUNT(*))]) | | 1 - output([T_FUN_COUNT(*)]), filter(nil), rowset=256 | | 2 - output([T_FUN_COUNT(*)]), filter(nil), rowset=256 | | dop=3 | | 3 - output([T_FUN_COUNT(*)]), filter(nil), rowset=256 | | group(nil), agg_func([T_FUN_COUNT(*)]) | | 4 - output(nil), filter(nil), rowset=256 | | equal_conds([a.c1_rand = b.c1_rand], [a.c2_rand = c.c2_rand]), other_conds(nil) | | 5 - output([a.c2_rand], [a.c1_rand]), filter(nil), rowset=256 | | RF_TYPE(in, range, bloom), RF_EXPR[a.c2_rand] | | 6 - output([a.c2_rand], [a.c1_rand]), filter(nil), rowset=256 | | 7 - output([a.c2_rand], [a.c1_rand]), filter(nil), rowset=256 | | dop=3 | | 8 - output([a.c1_rand], [a.c2_rand]), filter(nil), rowset=256 | | 9 - output([a.c1_rand], [a.c2_rand]), filter(nil), rowset=256 | | access([a.c1_rand], [a.c2_rand]), partitions(p[0-4]) | | is_index_back=false, is_global_index=false, | | range_key([a.__pk_increment]), range(MIN ; MAX)always true | | 10 - output([b.c1_rand], [c.c2_rand]), filter(nil), rowset=256 | | equal_conds([b.c3_rand = c.c3_rand]), other_conds(nil) | | 11 - output([b.c3_rand], [b.c1_rand]), filter(nil), rowset=256 | | RF_TYPE(in, range, bloom), RF_EXPR[b.c3_rand] | | 12 - output([b.c3_rand], [b.c1_rand]), filter(nil), rowset=256 | | 13 - output([b.c3_rand], [b.c1_rand]), filter(nil), rowset=256 | | (#keys=1, [b.c3_rand]), dop=3 | | 14 - output([b.c1_rand], [b.c3_rand]), filter(nil), rowset=256 | | 15 - output([b.c1_rand], [b.c3_rand]), filter(nil), rowset=256 | | access([b.c1_rand], [b.c3_rand]), partitions(p[0-4]) | | is_index_back=false, is_global_index=false, | | range_key([b.__pk_increment]), range(MIN ; MAX)always true | | 16 - output([c.c3_rand], [c.c2_rand]), filter(nil), rowset=256 | | 17 - output([c.c3_rand], [c.c2_rand), filter(nil), rowset=256 | | (#keys=1, [c.c3_rand]), dop=3 | | 18 - output([c.c3_rand], [c.c2_rand]), filter(nil), rowset=256 | | 19 - output([c.c3_rand], [c.c2_rand]), filter(nil), rowset=256 | | 20 - output([c.c3_rand], [c.c2_rand]), filter(nil), rowset=256 | | 21 - output([c.c3_rand], [c.c2_rand]), filter([RF_IN_FILTER(c.c3_rand)], [RF_RANGE_FILTER(c.c3_rand)], [RF_BLOOM_FILTER(c.c3_rand)], [RF_IN_FILTER(c.c2_rand)], | | [RF_RANGE_FILTER(c.c2_rand)], [RF_BLOOM_FILTER(c.c2_rand)]), rowset=256 | | access([c.c2_rand], [c.c3_rand]), partitions(p[0-4]) | | is_index_back=false, is_global_index=false, filter_before_indexback[false,false,false,false,false,false], | | range_key([c.__pk_increment]), range(MIN ; MAX)always true | +------------------------------------------------------------------------------------------------------------------------------------------------------------------+ 70 rows in set ``` 上述示例中，5 号算子的 `NAME` 字段值对应 `RF0001`，11 号算子对应 `RF000`，而被 Push Down 到 21 号的 `TABLE FULL SCAN` 算子横跨了多个 DFO 进行过滤，符合 Global Runtime Filter 的特征。 ### Part Join Filter 由于 Hash Join 的执行流程是在左侧数据阻塞建哈希表，右侧逐行匹配数据，左侧建哈希表会获取左侧所有数据，在这个过程中，如果可以获取左侧所有数据关于右侧某表的分区分布特征，那么在右侧扫描该表数据时，可以根据已统计的分区分布特征提前过滤掉不必要的分区，从而提升性能，Part Join Filter 的引入正是为了优化这一场景。为了使 Hash Join 左侧计算出右侧某表具体分区，Join 的连接键必须包含右侧该表的分区键，这是生成 Part Join Filter 的前提。 如下为 Part Join Filter 执行计划的示例。 ```shell obclient> CREATE TABLE tt1(v1 INT); Query OK, 0 rows affected obclient> CREATE TABLE tt2(v1 INT) PARTITION BY HASH(v1) PARTITIONS 5; Query OK, 0 rows affected obclient> EXPLAIN SELECT /*+ PARALLEL(3) LEADING(tt1 tt2) PX_PART_JOIN_FILTER(tt2)*/ * FROM tt1 JOIN tt2 ON tt1.v1=tt2.v1; +-------------------------------------------------------------------------------+ | Query Plan | +-------------------------------------------------------------------------------+ | ======================================================================= | | |ID|OPERATOR |NAME |EST.ROWS|EST.TIME(us)| | | ----------------------------------------------------------------------- | | |0 |PX COORDINATOR | |1 |5 | | | |1 |└─EXCHANGE OUT DISTR |:EX10001|1 |4 | | | |2 | └─HASH JOIN | |1 |4 | | | |3 | ├─PART JOIN FILTER CREATE |:RF0000 |1 |1 | | | |4 | │ └─EXCHANGE IN DISTR | |1 |1 | | | |5 | │ └─EXCHANGE OUT DISTR (PKEY)|:EX10000|1 |1 | | | |6 | │ └─PX BLOCK ITERATOR | |1 |1 | | | |7 | │ └─TABLE FULL SCAN |tt1 |1 |1 | | | |8 | └─PX PARTITION HASH JOIN-FILTER|:RF0000 |1 |3 | | | |9 | └─TABLE FULL SCAN |tt2 |1 |3 | | | ======================================================================= | | Outputs & filters: | | ------------------------------------- | | 0 - output([INTERNAL_FUNCTION(tt1.v1, tt2.v1)]), filter(nil), rowset=256 | | 1 - output([INTERNAL_FUNCTION(tt1.v1, tt2.v1)]), filter(nil), rowset=256 | | dop=3 | | 2 - output([tt1.v1], [tt2.v1]), filter(nil), rowset=256 | | equal_conds([tt1.v1 = tt2.v1]), other_conds(nil) | | 3 - output([tt1.v1]), filter(nil), rowset=256 | | RF_TYPE(bloom), RF_EXPR[t1.v1] | | 4 - output([tt1.v1]), filter(nil), rowset=256 | | 5 - output([tt1.v1]), filter(nil), rowset=256 | | (#keys=1, [t1.v1]), dop=3 | | 6 - output([tt1.v1]), filter(nil), rowset=256 | | 7 - output([tt1.v1]), filter(nil), rowset=256 | | access([tt1.v1]), partitions(p0) | | is_index_back=false, is_global_index=false, | | range_key([tt1.__pk_increment]), range(MIN ; MAX)always true | | 8 - output([tt2.v1]), filter(nil), rowset=256 | | affinitize | | 9 - output([tt2.v1]), filter(nil), rowset=256 | | access([tt2.v1]), partitions(p[0-4]) | | is_index_back=false, is_global_index=false, | | range_key([tt2.__pk_increment]), range(MIN ; MAX)always true | +-------------------------------------------------------------------------------+ ``` 上述示例中，在计划中 3 号 `PART JOIN FILTER CREATE` 算子和 8 号 `PX PARTITION HASH JOIN-FILTER` 算子就是 Part Join Filter。3 号算子对应 Part Join Filter，它会被应用到 8 号算子中对 `tt2` 表进行分区级别的过滤。 ## 手动开启和关闭 Runtime Filter Runtime Filter 的使用场景仅限于 Hash Join，当连接类型不为 Hash Join 时，优化器将不会分配 Runtime Filter。一般情况下，在进行 Hash Join 时优化器会自动分配 Runtime Filter，如果优化器并未分配 Runtime Filter，用户也可以手动通过 Hint 来分配。 `PX_JOIN_FILTER` Hint 和 `PX_PART_JOIN_FILTER` Hint 用于手动开启 Runtime Filter。SQL 语法格式如下： ```shell /*+ PX_JOIN_FILTER(join_right_table_name)*/ /*+ PX_PART_JOIN_FILTER(join_right_table_name)*/ ``` 示例如下： ```shell EXPLAIN SELECT /*+ PX_JOIN_FILTER(tt2) PARALLEL(4) */ * FROM tt1 JOIN tt2 ON tt1.v1=tt2.v1; EXPLAIN SELECT /*+ PARALLEL(3) LEADING(tt1 tt2) PX_PART_JOIN_FILTER(tt2)*/ * FROM tt1 JOIN tt2 ON tt1.v1=tt2.v1; ``` 在并行度为 1 的场景下，不会分配 Runtime Filter，此种情况下用户需要指定并行度至少为 2，可以使用 `PARALLEL` Hint 进行设置，示例如下： ```shell /*+ PARALLEL(2) */ ``` 需要注意的是，当 Hash Join 的过滤性不足时，使用 Runtime Filter 并不能解决问题，反而可能会导致轻微性能下降。因此，在选择手动开启 Runtime Filter 的时候，需要对查询场景进行仔细评估，以确定 Runtime Filter 是否适用。 `NO_PX_JOIN_FILTER` Hint 和 `NO_PX_PART_JOIN_FILTER` Hint 用于手动关闭 Runtime Filter。SQL 语法格式如下： ```shell /*+ NO_PX_JOIN_FILTER(join_right_table_name)*/ /*+ NO_PX_PART_JOIN_FILTER(join_right_table_name)*/ ``` ## 调整 Runtime Filter 的执行策略 Runtime Filter 具有自适应能力。在默认配置下，当 Join 基于连接键的选择率满足条件会默认创建三种数据结构的 Runtime Filter，即 In、Range 和 Bloom Filter。In Filter 内部使用 Hash 表进行过滤判定，Range Filter 内部使用最大或最小值进行过滤判定。 在过滤优先级上，由于 In Filter 具有最准的过滤性，当 In Filter 在执行期被启用时，其他两种 Filter 会被自适应关闭，在执行期间，执行器会根据实际 NDV 值确定是否使用 In Filter。此外，每种 Filter 在实际计算中会根据实时过滤性自适应 Disable Filter 以及重新 Enable Filter。 OceanBase 数据库提供了系统变量用于调整 Runtime Filter 执行的相关策略，包括 `runtime_filter_type`、`runtime_filter_max_in_num`、`runtime_filter_wait_time_ms` 和 `runtime_bloom_filter_max_size`。 `runtime_filter_type` 变量用于指定所启用的 Runtime Filter 类型。`runtime_filter_type` 的默认值为 `'BLOOM_FILTER,RANGE,IN'`，表示同时启用三种类型的 Runtime Filter，当 `runtime_filter_type=''` 时，表示不启用任何类型的 Runtime Filter。示例如下： ```shell ALTER SYSTEM SET runtime_filter_type = 'BLOOM_FILTER,RANGE,IN' ``` 一般情况下，使用默认值指定的 Runtime Filter 类型即可，不需要使用 `runtime_filter_type` 变量特别指定。OceanBase 数据库会在优化和执行阶段选择最优的 Runtime Filter 类型进行过滤。 `runtime_filter_max_in_num` 变量用于指定 In Filter 所使用的 NDV，默认值为 1024。优化器会估算 Build 表的 NDV，如果 `NDV > runtime_filter_max_in_num`，则不会分配 In Filter。由于优化器估算 NDV 不一定准确，可能存在实际 NDV 很大但是估算较小导致误分配 In Filter 的情况，在这种情况下，执行器会在执行过程中会根据实际的 NDV 自适应关闭 In Filter。一般情况下，不建议用户将该值设置过大，因为在 Build 表 NDV 很大的情况下，In Filter 的优化效果不如 Bloom Filter。 `runtime_filter_wait_time_ms` 变量用于设置 Probe 端等待 Runtime Filter 到达的最长等待时间，默认值为 10 ms。Probe 端会等待 Runtime Filter 到达之后再吐数据，如果超过 `runtime_filter_wait_time_ms` 所设时间 Runtime Filter 还未到达，则会进入 By Pass 阶段，此时不经过 Runtime Filter 过滤直接开始吐数据，当之后的某个时刻 Runtime Filter 达到后，Runtime Filter 仍然会被启用并执行过滤。一般情况下，该值不需要调整，当实际使用的 Bloom Filter 数据很大时，并且过滤性比较好的情况下，可以适当调大该值。 `runtime_bloom_filter_max_size` 变量用于限制 Bloom Filter 的最大长度, 默认值为 2048 MB。在用户实际使用中 Build 表的数据过多时，如果 Bloom Filter 默认的最大长度不能容纳数据，此时需要调大 `runtime_bloom_filter_max_size` 的值。 ## 相关文档 [联接算法](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000643242) 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线