This is an automated email from the ASF dual-hosted git repository.
morningman pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new cdf2447223b [feat] add skew hint doc (#3488)
cdf2447223b is described below
commit cdf2447223b3d799a73c7fd38ba45168fc3b4bff
Author: feiniaofeiafei <[email protected]>
AuthorDate: Sat Oct 17 05:40:32 2026 +0800
[feat] add skew hint doc (#3488)
## Summary
Document join, DISTINCT aggregation and window skew hints in the current
Execution Tuning navigation for dev and 4.x, English and Chinese.
Rebased the old draft without reviving removed hints-overview routes.
The rewritten guide uses Doris DDL and complete query/result examples,
identifies available 4.1.0 behavior, explains required hot-key sides and
ASOF applicability, aggregation/window rewrite constraints, and session
variable ranges/defaults. It corrects the original confusion between
table buckets and join salt replication.
## Validation
Compared master and 4.x rewrite implementations, session variables, the
4.1.0 source tag and existing skew regression suites. `git diff --check`
and sidebar JSON parsing pass. Examples were checked statically; no
cluster execution or full site build was performed.
---
.../tuning/tuning-execution/skew-hint.md | 134 +++++++++++++++++++++
.../tuning/tuning-execution/skew-hint.md | 134 +++++++++++++++++++++
.../tuning/tuning-execution/skew-hint.md | 134 +++++++++++++++++++++
sidebars.ts | 1 +
.../tuning/tuning-execution/skew-hint.md | 134 +++++++++++++++++++++
versioned_sidebars/version-4.x-sidebars.json | 1 +
6 files changed, 538 insertions(+)
diff --git a/docs/query-acceleration/tuning/tuning-execution/skew-hint.md
b/docs/query-acceleration/tuning/tuning-execution/skew-hint.md
new file mode 100644
index 00000000000..2da72520c56
--- /dev/null
+++ b/docs/query-acceleration/tuning/tuning-execution/skew-hint.md
@@ -0,0 +1,134 @@
+---
+{
+ "title": "Skew Hints",
+ "language": "en",
+ "description": "Use join, DISTINCT aggregation and window skew hints to
mitigate uneven work, with runnable examples and plan/profile verification.",
+ "keywords": [
+ "Doris skew hint",
+ "SaltJoin",
+ "DISTINCT skew",
+ "window skew"
+ ]
+}
+---
+
+Skew hints mitigate long-running instances caused by a few hot keys. Doris
supports join salting, DISTINCT aggregation bucketing and window sorting
strategies while preserving SQL results. Use them when Profiles show skew;
replication and extra shuffles also add cost.
+
+:::note
+The three hint forms on this page are available in Doris 4.1.0. Check the
execution plan for the deployed release to confirm whether a rewrite applies.
+:::
+
+## Prepare Data
+
+The examples require CREATE, INSERT and SELECT privileges in the current
database. These small tables verify syntax and results, rather than
demonstrating a performance benefit:
+
+```sql
+CREATE TABLE skew_left (id INT, k INT, v INT)
+DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 1
+PROPERTIES ("replication_num"="1");
+CREATE TABLE skew_right (id INT, k INT, v INT)
+DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 1
+PROPERTIES ("replication_num"="1");
+INSERT INTO skew_left VALUES (1,1,10),(2,1,20),(3,2,30),(4,3,40);
+INSERT INTO skew_right VALUES (1,1,100),(2,2,200);
+```
+
+## Join Skew Hint
+
+For known hot join keys, use `shuffle[skew(<column>(<literal>, ...))]`. Doris
randomly salts hot rows on one side, replicates matching rows on the other side
across salt values, and shuffles on the original key plus the salt.
+
+- For ordinary INNER and LEFT joins, the hot column must come from the left
side. For RIGHT joins, it must come from the right. ASOF INNER/LEFT/RIGHT
variants follow the corresponding side rule and still require their
MATCH_CONDITION and equality keys.
+- The column must be a direct column reference in a join equality key.
Expressions, casts and columns outside the equality keys do not trigger
rewriting. The hint requires shuffle; Mark, FULL, SEMI and ANTI joins are
excluded.
+- One specified hot column is handled per rewrite. Skew on both sides can
still leave replication costs and very large join results.
+
+Write the hint on the join:
+
+```sql
+SELECT l.id AS left_id, r.id AS right_id
+FROM skew_left l
+JOIN[shuffle[skew(l.k(1))]] skew_right r ON l.k = r.k
+ORDER BY left_id, right_id;
+```
+
+```text
+left_id right_id
+1 1
+2 1
+3 2
+```
+
+The same distribution and hot key can be specified in LEADING:
+
+```sql
+SELECT /*+ leading(l shuffle[skew(l.k(1))] r) */
+ l.id AS left_id, r.id AS right_id
+FROM skew_left l JOIN skew_right r ON l.k = r.k
+ORDER BY left_id, right_id;
+```
+
+```text
+left_id right_id
+1 1
+2 1
+3 2
+```
+
+Here `l.k` is the hot column and `1` is its known hot value. Use literals
compatible with the column type. If join order changes, check that the hot
column remains on the required side.
+
+## DISTINCT Aggregation Skew Hint
+
+Place `[skew]` before the argument of a single-argument DISTINCT aggregate:
+
+```sql
+SELECT k, COUNT(DISTINCT [skew] id) AS distinct_ids
+FROM skew_left
+GROUP BY k
+ORDER BY k;
+```
+
+```text
+k distinct_ids
+1 2
+2 1
+3 1
+```
+
+Supported functions are COUNT, SUM, SUM0 and single-argument GROUP_CONCAT.
Rewriting requires GROUP BY, exactly one aggregate function and one DISTINCT
argument at that level, a direct column argument, and that argument not already
included in GROUP BY. Otherwise Doris keeps the regular aggregation. The
rewrite distributes deduplication by group keys and hash buckets before merging
by the original group keys, reducing high-NDV hot-group pressure.
+
+## Window Skew Hint
+
+Place `[skew]` after PARTITION BY in the window specification:
+
+```sql
+SELECT id, SUM(v) OVER (
+ PARTITION BY [skew] k ORDER BY id
+ ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
+) AS running_sum
+FROM skew_left
+ORDER BY id;
+```
+
+```text
+id running_sum
+1 10
+2 30
+3 30
+4 40
+```
+
+This strategy locally sorts before shuffling by partition keys and merging
sorted streams. Within a partition-key group, only the bottom window node
requiring shuffle uses it; upper nodes reuse distribution and ordering. A
global window without PARTITION BY does not gain partition-level parallelism,
and a very large single partition can still be slow.
+
+## Parameters
+
+| Parameter | Type | Default | Range and effect |
+|---|---|---|---|
+| `skew_rewrite_join_salt_explode_factor` | Session integer | `0` | `0`
chooses automatically from BEs/CPU; `1` to `65535` sets the salt/replication
multiplier. This is independent of table bucket count |
+| `skew_rewrite_agg_bucket_num` | Session integer | `1024` | `1` to `65535`,
controls hash buckets for the DISTINCT rewrite |
+
+## Verification and Guidance
+
+Prefix the example SELECT with EXPLAIN and inspect accepted hints and the
added salt, aggregation or sorting nodes. Enable `enable_profile=true` and
compare per-instance rows, time, memory and shuffle bytes for the same SQL. A
hint can be inapplicable; the final plan determines whether rewriting occurred.
+
+Choose hot values from actual data. Start with automatic join salting: larger
multipliers replicate more rows on the other side and may increase
network/memory usage or cause OOM. Excessive aggregate buckets add shuffle and
merge costs. Window skew handling optimizes sorting rather than reducing
required rows. Measure again when data distribution changes.
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/query-acceleration/tuning/tuning-execution/skew-hint.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/query-acceleration/tuning/tuning-execution/skew-hint.md
new file mode 100644
index 00000000000..e0e0522821b
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/query-acceleration/tuning/tuning-execution/skew-hint.md
@@ -0,0 +1,134 @@
+---
+{
+ "title": "Skew Hint 数据倾斜优化",
+ "language": "zh-CN",
+ "description": "使用 Join、DISTINCT 聚合和窗口 Skew Hint 缓解数据倾斜，并通过执行计划和 Profile
验证效果。",
+ "keywords": [
+ "Doris skew hint",
+ "SaltJoin",
+ "DISTINCT skew",
+ "window skew"
+ ]
+}
+---
+
+Skew Hint 用于缓解少数热点键导致的单实例长尾。Doris 支持 Join 加盐、DISTINCT
聚合分桶和窗口排序三种策略，查询结果语义不变。仅在 Profile 证明数据倾斜时使用，额外复制和 Shuffle 也会增加成本。
+
+:::note
+本页三种 Hint 在 Doris 4.1.0 中已支持。请使用与部署版本对应的文档和执行计划核对实际生效情况。
+:::
+
+## 准备数据
+
+示例需要当前数据库的建表、写入和查询权限。以下小表用于验证语法和结果，不用于展示性能收益：
+
+```sql
+CREATE TABLE skew_left (id INT, k INT, v INT)
+DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 1
+PROPERTIES ("replication_num"="1");
+CREATE TABLE skew_right (id INT, k INT, v INT)
+DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 1
+PROPERTIES ("replication_num"="1");
+INSERT INTO skew_left VALUES (1,1,10),(2,1,20),(3,2,30),(4,3,40);
+INSERT INTO skew_right VALUES (1,1,100),(2,2,200);
+```
+
+## Join Skew Hint
+
+对已知热点 Join 键，使用 `shuffle[skew(<column>(<literal>,
...))]`。热点侧随机加盐，另一侧的相应行被复制到多个盐值，再按原键和盐值进行 Shuffle Join。
+
+- 普通 `INNER JOIN`、`LEFT JOIN` 的热点列必须来自左侧；`RIGHT JOIN` 的热点列必须来自右侧。ASOF 的
INNER/LEFT/RIGHT 变体遵循对应侧的规则，并仍需满足 ASOF 的 MATCH_CONDITION 和等值键要求。
+- 列必须是 Join 等值键中的直接列引用；表达式、CAST 和不在等值条件中的列不能触发重写。只适用于 Shuffle；Mark
Join、FULL/SEMI/ANTI Join 不适用。
+- 一次优化处理一个指定热点列。两侧同时高度倾斜时，复制侧的热点和结果行数膨胀仍存在。
+
+可直接写在 Join 上：
+
+```sql
+SELECT l.id AS left_id, r.id AS right_id
+FROM skew_left l
+JOIN[shuffle[skew(l.k(1))]] skew_right r ON l.k = r.k
+ORDER BY left_id, right_id;
+```
+
+```text
+left_id right_id
+1 1
+2 1
+3 2
+```
+
+也可以在 `LEADING` 中指定相同分布和热点：
+
+```sql
+SELECT /*+ leading(l shuffle[skew(l.k(1))] r) */
+ l.id AS left_id, r.id AS right_id
+FROM skew_left l JOIN skew_right r ON l.k = r.k
+ORDER BY left_id, right_id;
+```
+
+```text
+left_id right_id
+1 1
+2 1
+3 2
+```
+
+`l.k` 是热点列，`1` 是已知热点值。热点值列表必须使用与列类型兼容的字面量。实际 Join 顺序若变化，需重新确认热点列位于正确侧。
+
+## DISTINCT 聚合 Skew Hint
+
+将 `[skew]` 写在单参数 DISTINCT 聚合的参数前：
+
+```sql
+SELECT k, COUNT(DISTINCT [skew] id) AS distinct_ids
+FROM skew_left
+GROUP BY k
+ORDER BY k;
+```
+
+```text
+k distinct_ids
+1 2
+2 1
+3 1
+```
+
+支持 `COUNT`、`SUM`、`SUM0` 和单参数 `GROUP_CONCAT`。生效条件是存在 GROUP BY、同一层只有一个聚合函数和一个
DISTINCT 列参数、参数为直接列引用，且该参数不已包含在 GROUP BY
中。未满足时回退普通聚合。重写将去重工作按分组键和哈希桶分散，再按原分组键合并；它主要缓解热点组的高 NDV 内存和长尾。
+
+## 窗口 Skew Hint
+
+将 `[skew]` 写在窗口 PARTITION BY 关键字之后：
+
+```sql
+SELECT id, SUM(v) OVER (
+ PARTITION BY [skew] k ORDER BY id
+ ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
+) AS running_sum
+FROM skew_left
+ORDER BY id;
+```
+
+```text
+id running_sum
+1 10
+2 30
+3 30
+4 40
+```
+
+该策略先局部排序，再按分区键 Shuffle 并归并排序，减少热点分区的重新排序成本。同一组分区键下，仅需要 Shuffle
的最底层窗口节点使用该策略，上层复用分布和顺序。没有 PARTITION BY 的全局窗口不能因此获得分区级并行；极大的单分区仍可能形成长尾。
+
+## 参数
+
+| 参数 | 类型 | 默认值 | 范围及作用 |
+|---|---|---|---|
+| `skew_rewrite_join_salt_explode_factor` | Session integer | `0` | `0` 按
BE/CPU 自动决定；`1` 到 `65535` 手动指定加盐/复制倍数。它不是表的 bucket 数 |
+| `skew_rewrite_agg_bucket_num` | Session integer | `1024` | `1` 到 `65535`，控制
DISTINCT 重写的哈希桶数 |
+
+## 验证与建议
+
+在示例 SELECT 前加 `EXPLAIN` 检查 Hint 和新增加盐/多阶段聚合/排序节点；启用 `enable_profile=true` 比较同一
SQL 的各实例行数、时间、内存和 Shuffle 字节。Hint 不保证必然触发重写，最终计划才是依据。
+
+热点值列表应来自实际数据。先尝试自动 Join 加盐倍数，增大倍数会复制另一侧更多行，可能增加网络和内存甚至 OOM。聚合桶数过大也会增加 Shuffle
与合并成本。窗口策略优化排序，不减少窗口必须处理的行数。不同数据分布下需重新测量。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/query-acceleration/tuning/tuning-execution/skew-hint.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/query-acceleration/tuning/tuning-execution/skew-hint.md
new file mode 100644
index 00000000000..e0e0522821b
--- /dev/null
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/query-acceleration/tuning/tuning-execution/skew-hint.md
@@ -0,0 +1,134 @@
+---
+{
+ "title": "Skew Hint 数据倾斜优化",
+ "language": "zh-CN",
+ "description": "使用 Join、DISTINCT 聚合和窗口 Skew Hint 缓解数据倾斜，并通过执行计划和 Profile
验证效果。",
+ "keywords": [
+ "Doris skew hint",
+ "SaltJoin",
+ "DISTINCT skew",
+ "window skew"
+ ]
+}
+---
+
+Skew Hint 用于缓解少数热点键导致的单实例长尾。Doris 支持 Join 加盐、DISTINCT
聚合分桶和窗口排序三种策略，查询结果语义不变。仅在 Profile 证明数据倾斜时使用，额外复制和 Shuffle 也会增加成本。
+
+:::note
+本页三种 Hint 在 Doris 4.1.0 中已支持。请使用与部署版本对应的文档和执行计划核对实际生效情况。
+:::
+
+## 准备数据
+
+示例需要当前数据库的建表、写入和查询权限。以下小表用于验证语法和结果，不用于展示性能收益：
+
+```sql
+CREATE TABLE skew_left (id INT, k INT, v INT)
+DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 1
+PROPERTIES ("replication_num"="1");
+CREATE TABLE skew_right (id INT, k INT, v INT)
+DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 1
+PROPERTIES ("replication_num"="1");
+INSERT INTO skew_left VALUES (1,1,10),(2,1,20),(3,2,30),(4,3,40);
+INSERT INTO skew_right VALUES (1,1,100),(2,2,200);
+```
+
+## Join Skew Hint
+
+对已知热点 Join 键，使用 `shuffle[skew(<column>(<literal>,
...))]`。热点侧随机加盐，另一侧的相应行被复制到多个盐值，再按原键和盐值进行 Shuffle Join。
+
+- 普通 `INNER JOIN`、`LEFT JOIN` 的热点列必须来自左侧；`RIGHT JOIN` 的热点列必须来自右侧。ASOF 的
INNER/LEFT/RIGHT 变体遵循对应侧的规则，并仍需满足 ASOF 的 MATCH_CONDITION 和等值键要求。
+- 列必须是 Join 等值键中的直接列引用；表达式、CAST 和不在等值条件中的列不能触发重写。只适用于 Shuffle；Mark
Join、FULL/SEMI/ANTI Join 不适用。
+- 一次优化处理一个指定热点列。两侧同时高度倾斜时，复制侧的热点和结果行数膨胀仍存在。
+
+可直接写在 Join 上：
+
+```sql
+SELECT l.id AS left_id, r.id AS right_id
+FROM skew_left l
+JOIN[shuffle[skew(l.k(1))]] skew_right r ON l.k = r.k
+ORDER BY left_id, right_id;
+```
+
+```text
+left_id right_id
+1 1
+2 1
+3 2
+```
+
+也可以在 `LEADING` 中指定相同分布和热点：
+
+```sql
+SELECT /*+ leading(l shuffle[skew(l.k(1))] r) */
+ l.id AS left_id, r.id AS right_id
+FROM skew_left l JOIN skew_right r ON l.k = r.k
+ORDER BY left_id, right_id;
+```
+
+```text
+left_id right_id
+1 1
+2 1
+3 2
+```
+
+`l.k` 是热点列，`1` 是已知热点值。热点值列表必须使用与列类型兼容的字面量。实际 Join 顺序若变化，需重新确认热点列位于正确侧。
+
+## DISTINCT 聚合 Skew Hint
+
+将 `[skew]` 写在单参数 DISTINCT 聚合的参数前：
+
+```sql
+SELECT k, COUNT(DISTINCT [skew] id) AS distinct_ids
+FROM skew_left
+GROUP BY k
+ORDER BY k;
+```
+
+```text
+k distinct_ids
+1 2
+2 1
+3 1
+```
+
+支持 `COUNT`、`SUM`、`SUM0` 和单参数 `GROUP_CONCAT`。生效条件是存在 GROUP BY、同一层只有一个聚合函数和一个
DISTINCT 列参数、参数为直接列引用，且该参数不已包含在 GROUP BY
中。未满足时回退普通聚合。重写将去重工作按分组键和哈希桶分散，再按原分组键合并；它主要缓解热点组的高 NDV 内存和长尾。
+
+## 窗口 Skew Hint
+
+将 `[skew]` 写在窗口 PARTITION BY 关键字之后：
+
+```sql
+SELECT id, SUM(v) OVER (
+ PARTITION BY [skew] k ORDER BY id
+ ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
+) AS running_sum
+FROM skew_left
+ORDER BY id;
+```
+
+```text
+id running_sum
+1 10
+2 30
+3 30
+4 40
+```
+
+该策略先局部排序，再按分区键 Shuffle 并归并排序，减少热点分区的重新排序成本。同一组分区键下，仅需要 Shuffle
的最底层窗口节点使用该策略，上层复用分布和顺序。没有 PARTITION BY 的全局窗口不能因此获得分区级并行；极大的单分区仍可能形成长尾。
+
+## 参数
+
+| 参数 | 类型 | 默认值 | 范围及作用 |
+|---|---|---|---|
+| `skew_rewrite_join_salt_explode_factor` | Session integer | `0` | `0` 按
BE/CPU 自动决定；`1` 到 `65535` 手动指定加盐/复制倍数。它不是表的 bucket 数 |
+| `skew_rewrite_agg_bucket_num` | Session integer | `1024` | `1` 到 `65535`，控制
DISTINCT 重写的哈希桶数 |
+
+## 验证与建议
+
+在示例 SELECT 前加 `EXPLAIN` 检查 Hint 和新增加盐/多阶段聚合/排序节点；启用 `enable_profile=true` 比较同一
SQL 的各实例行数、时间、内存和 Shuffle 字节。Hint 不保证必然触发重写，最终计划才是依据。
+
+热点值列表应来自实际数据。先尝试自动 Join 加盐倍数，增大倍数会复制另一侧更多行，可能增加网络和内存甚至 OOM。聚合桶数过大也会增加 Shuffle
与合并成本。窗口策略优化排序，不减少窗口必须处理的行数。不同数据分布下需重新测量。
diff --git a/sidebars.ts b/sidebars.ts
index 79f280b247f..b8b827a525d 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -637,6 +637,7 @@ const sidebars: SidebarsConfig = {
'query-acceleration/tuning/tuning-execution/parallelism-tuning',
'query-acceleration/tuning/tuning-execution/adjustment-of-runtimefilter-wait-time',
'query-acceleration/tuning/tuning-execution/data-skew-handling',
+
'query-acceleration/tuning/tuning-execution/skew-hint',
'query-acceleration/tuning/tuning-plan/controlling-hints-with-cbo-rule',
],
},
diff --git
a/versioned_docs/version-4.x/query-acceleration/tuning/tuning-execution/skew-hint.md
b/versioned_docs/version-4.x/query-acceleration/tuning/tuning-execution/skew-hint.md
new file mode 100644
index 00000000000..2da72520c56
--- /dev/null
+++
b/versioned_docs/version-4.x/query-acceleration/tuning/tuning-execution/skew-hint.md
@@ -0,0 +1,134 @@
+---
+{
+ "title": "Skew Hints",
+ "language": "en",
+ "description": "Use join, DISTINCT aggregation and window skew hints to
mitigate uneven work, with runnable examples and plan/profile verification.",
+ "keywords": [
+ "Doris skew hint",
+ "SaltJoin",
+ "DISTINCT skew",
+ "window skew"
+ ]
+}
+---
+
+Skew hints mitigate long-running instances caused by a few hot keys. Doris
supports join salting, DISTINCT aggregation bucketing and window sorting
strategies while preserving SQL results. Use them when Profiles show skew;
replication and extra shuffles also add cost.
+
+:::note
+The three hint forms on this page are available in Doris 4.1.0. Check the
execution plan for the deployed release to confirm whether a rewrite applies.
+:::
+
+## Prepare Data
+
+The examples require CREATE, INSERT and SELECT privileges in the current
database. These small tables verify syntax and results, rather than
demonstrating a performance benefit:
+
+```sql
+CREATE TABLE skew_left (id INT, k INT, v INT)
+DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 1
+PROPERTIES ("replication_num"="1");
+CREATE TABLE skew_right (id INT, k INT, v INT)
+DUPLICATE KEY(id)
+DISTRIBUTED BY HASH(id) BUCKETS 1
+PROPERTIES ("replication_num"="1");
+INSERT INTO skew_left VALUES (1,1,10),(2,1,20),(3,2,30),(4,3,40);
+INSERT INTO skew_right VALUES (1,1,100),(2,2,200);
+```
+
+## Join Skew Hint
+
+For known hot join keys, use `shuffle[skew(<column>(<literal>, ...))]`. Doris
randomly salts hot rows on one side, replicates matching rows on the other side
across salt values, and shuffles on the original key plus the salt.
+
+- For ordinary INNER and LEFT joins, the hot column must come from the left
side. For RIGHT joins, it must come from the right. ASOF INNER/LEFT/RIGHT
variants follow the corresponding side rule and still require their
MATCH_CONDITION and equality keys.
+- The column must be a direct column reference in a join equality key.
Expressions, casts and columns outside the equality keys do not trigger
rewriting. The hint requires shuffle; Mark, FULL, SEMI and ANTI joins are
excluded.
+- One specified hot column is handled per rewrite. Skew on both sides can
still leave replication costs and very large join results.
+
+Write the hint on the join:
+
+```sql
+SELECT l.id AS left_id, r.id AS right_id
+FROM skew_left l
+JOIN[shuffle[skew(l.k(1))]] skew_right r ON l.k = r.k
+ORDER BY left_id, right_id;
+```
+
+```text
+left_id right_id
+1 1
+2 1
+3 2
+```
+
+The same distribution and hot key can be specified in LEADING:
+
+```sql
+SELECT /*+ leading(l shuffle[skew(l.k(1))] r) */
+ l.id AS left_id, r.id AS right_id
+FROM skew_left l JOIN skew_right r ON l.k = r.k
+ORDER BY left_id, right_id;
+```
+
+```text
+left_id right_id
+1 1
+2 1
+3 2
+```
+
+Here `l.k` is the hot column and `1` is its known hot value. Use literals
compatible with the column type. If join order changes, check that the hot
column remains on the required side.
+
+## DISTINCT Aggregation Skew Hint
+
+Place `[skew]` before the argument of a single-argument DISTINCT aggregate:
+
+```sql
+SELECT k, COUNT(DISTINCT [skew] id) AS distinct_ids
+FROM skew_left
+GROUP BY k
+ORDER BY k;
+```
+
+```text
+k distinct_ids
+1 2
+2 1
+3 1
+```
+
+Supported functions are COUNT, SUM, SUM0 and single-argument GROUP_CONCAT.
Rewriting requires GROUP BY, exactly one aggregate function and one DISTINCT
argument at that level, a direct column argument, and that argument not already
included in GROUP BY. Otherwise Doris keeps the regular aggregation. The
rewrite distributes deduplication by group keys and hash buckets before merging
by the original group keys, reducing high-NDV hot-group pressure.
+
+## Window Skew Hint
+
+Place `[skew]` after PARTITION BY in the window specification:
+
+```sql
+SELECT id, SUM(v) OVER (
+ PARTITION BY [skew] k ORDER BY id
+ ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
+) AS running_sum
+FROM skew_left
+ORDER BY id;
+```
+
+```text
+id running_sum
+1 10
+2 30
+3 30
+4 40
+```
+
+This strategy locally sorts before shuffling by partition keys and merging
sorted streams. Within a partition-key group, only the bottom window node
requiring shuffle uses it; upper nodes reuse distribution and ordering. A
global window without PARTITION BY does not gain partition-level parallelism,
and a very large single partition can still be slow.
+
+## Parameters
+
+| Parameter | Type | Default | Range and effect |
+|---|---|---|---|
+| `skew_rewrite_join_salt_explode_factor` | Session integer | `0` | `0`
chooses automatically from BEs/CPU; `1` to `65535` sets the salt/replication
multiplier. This is independent of table bucket count |
+| `skew_rewrite_agg_bucket_num` | Session integer | `1024` | `1` to `65535`,
controls hash buckets for the DISTINCT rewrite |
+
+## Verification and Guidance
+
+Prefix the example SELECT with EXPLAIN and inspect accepted hints and the
added salt, aggregation or sorting nodes. Enable `enable_profile=true` and
compare per-instance rows, time, memory and shuffle bytes for the same SQL. A
hint can be inapplicable; the final plan determines whether rewriting occurred.
+
+Choose hot values from actual data. Start with automatic join salting: larger
multipliers replicate more rows on the other side and may increase
network/memory usage or cause OOM. Excessive aggregate buckets add shuffle and
merge costs. Window skew handling optimizes sorting rather than reducing
required rows. Measure again when data distribution changes.
diff --git a/versioned_sidebars/version-4.x-sidebars.json
b/versioned_sidebars/version-4.x-sidebars.json
index ec833bdf53f..8458650e2d8 100644
--- a/versioned_sidebars/version-4.x-sidebars.json
+++ b/versioned_sidebars/version-4.x-sidebars.json
@@ -709,6 +709,7 @@
"query-acceleration/tuning/tuning-execution/parallelism-tuning",
"query-acceleration/tuning/tuning-execution/adjustment-of-runtimefilter-wait-time",
"query-acceleration/tuning/tuning-execution/data-skew-handling",
+ "query-acceleration/tuning/tuning-execution/skew-hint",
"query-acceleration/tuning/tuning-plan/controlling-hints-with-cbo-rule"
]
},
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
