Skip to content

Commit ea80ed8

Browse files
authored
rename lightweight mutation to on-the-fly mutation and update page with lightweight updates
1 parent 6d508f7 commit ea80ed8

File tree

1 file changed

+19
-8
lines changed

1 file changed

+19
-8
lines changed

docs/managing-data/updating-data/overview.md

Lines changed: 19 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -18,14 +18,13 @@ There are several ways to update data in ClickHouse, each with its own advantage
1818
For both operations, if the number of submitted mutations constantly exceeds the number of mutations that are processed in the background over some time interval, the queue of non-materialized mutations that have to be applied will continue to grow. This will result in the eventual degradation of `SELECT` query performance.
1919

2020
In summary, update operations should be issued carefully, and the mutations queue should be tracked closely using the `system.mutations` table. Do not issue updates frequently as you would in OLTP databases. If you have a requirement for frequent updates, see [ReplacingMergeTree](/engines/table-engines/mergetree-family/replacingmergetree).
21-
2221
| Method | Syntax | When to use |
2322
|---------------------------------------------------------------------------------------|--------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
2423
| [Update mutation](/sql-reference/statements/alter/update) | `ALTER TABLE [table] UPDATE` | Use when data must be updated to disk immediately (e.g. for compliance). Negatively affects `SELECT` performance. |
25-
| [Lightweight update](/guides/developer/lightweight-update) | `ALTER TABLE [table] UPDATE` | Enable using `SET apply_mutations_on_fly = 1;`. Use when updating small amounts of data. Rows are immediately returned with updated data in all subsequent `SELECT` queries but are initially only internally marked as updated on disk. |
24+
| [Lightweight updates](/sql-reference/statements/update) | `UPDATE [table] SET ... WHERE` | Use for updating small amounts of data (up to ~10% of table). Creates patch parts for immediate visibility without rewriting entire columns. Adds overhead to `SELECT` queries but has predictable latency. Currently experimental. |
25+
| [On-the-fly updates](/guides/developer/lightweight-update) | `ALTER TABLE [table] UPDATE` | Enable using `SET apply_mutations_on_fly = 1;`. Use when updating small amounts of data. Rows are immediately returned with updated data in all subsequent `SELECT` queries but are initially only internally marked as updated on disk. |
2626
| [ReplacingMergeTree](/engines/table-engines/mergetree-family/replacingmergetree) | `ENGINE = ReplacingMergeTree` | Use when updating large amounts of data. This table engine is optimized for data deduplication on merges. |
2727
| [CollapsingMergeTree](/engines/table-engines/mergetree-family/collapsingmergetree) | `ENGINE = CollapsingMergeTree(Sign)` | Use when updating individual rows frequently, or for scenarios where you need to maintain the latest state of objects that change over time. For example, tracking user activity or article stats. |
28-
2928
Here is a summary of the different ways to update data in ClickHouse:
3029

3130
## Update Mutations {#update-mutations}
@@ -40,9 +39,21 @@ These are extremely IO-heavy, rewriting all the parts that match the `WHERE` exp
4039

4140
Read more about [update mutations](/sql-reference/statements/alter/update).
4241

43-
## Lightweight Updates {#lightweight-updates}
42+
## Lightweight updates {#lightweight-updates}
43+
44+
Lightweight updates are a ClickHouse feature that updates rows using "patch parts" - special data parts containing only the updated columns and rows, rather than rewriting entire columns like traditional mutations. The Lightweight UPDATE
45+
Key characteristics:
46+
47+
- Uses the standard `UPDATE` syntax and creates patch parts immediately without waiting for merges
48+
- Updated values are immediately visible in `SELECT` queries through patch application, but physically materialized only during subsequent merges
49+
- Designed for small updates (up to ~10% of table) with predictable latency
50+
- Adds overhead to `SELECT` queries that need to apply patches, but avoids rewriting entire columns
51+
52+
For more details see ["The Lightweight UPDATE Statement"](/sql-reference/statements/update)
53+
54+
## On-the-fly Updates {#on-the-fly-updates}
4455

45-
Lightweight updates provide a mechanism to update rows such that they are updated immediately, and subsequent `SELECT` queries will automatically return with the changed values (this incurs an overhead and will slow queries). This effectively addresses the atomicity limitation of normal mutations. We show an example below:
56+
On-the-fly updates provide a mechanism to update rows such that they are updated immediately, and subsequent `SELECT` queries will automatically return with the changed values (this incurs an overhead and will slow queries). This effectively addresses the atomicity limitation of normal mutations. We show an example below:
4657

4758
```sql
4859
SET apply_mutations_on_fly = 1;
@@ -52,7 +63,7 @@ FROM posts
5263
WHERE Id = 404346
5364

5465
┌─ViewCount─┐
55-
26762
66+
26762
5667
└───────────┘
5768

5869
1 row in set. Elapsed: 0.115 sec. Processed 59.55 million rows, 238.25 MB (517.83 million rows/s., 2.07 GB/s.)
@@ -73,9 +84,9 @@ WHERE Id = 404346
7384
1 row in set. Elapsed: 0.149 sec. Processed 59.55 million rows, 259.91 MB (399.99 million rows/s., 1.75 GB/s.)
7485
```
7586

76-
Note that for lightweight updates, a mutation is still used to update the data; it is just not materialized immediately and applied during `SELECT` queries. It will still be applied in the background as an asynchronous process and incurs the same heavy overhead as a mutation and thus is an I/O intense operation that should be used sparingly. The expressions that can be used with this operation are also limited (see here for [details](/guides/developer/lightweight-update#support-for-subqueries-and-non-deterministic-functions)).
87+
Note that for on-the-fly updates, a mutation is still used to update the data; it is just not materialized immediately and applied during `SELECT` queries. It will still be applied in the background as an asynchronous process and incurs the same heavy overhead as a mutation and thus is an I/O intense operation that should be used sparingly. The expressions that can be used with this operation are also limited (see here for [details](/guides/developer/lightweight-update#support-for-subqueries-and-non-deterministic-functions)).
7788

78-
Read more about [lightweight updates](/guides/developer/lightweight-update).
89+
Read more about [on-the-fly updates](/guides/developer/lightweight-update).
7990

8091
## Collapsing Merge Tree {#collapsing-merge-tree}
8192

0 commit comments

Comments
 (0)