Merge pull request #4046 from ClickHouse/melvynator-patch-4

Fix the documentation page to align with the new lightweight update page

Author: Blargian

docs/guides/developer/lightweight-update.md

@@ -1,16 +1,16 @@
 ---
 slug: /guides/developer/lightweight-update
-sidebar_label: 'Lightweight Update'
-title: 'Lightweight Update'
-keywords: ['lightweight update']
-description: 'Provides a description of lightweight updates'
+sidebar_label: 'On-the-fly mutation'
+title: 'On-the-fly Mutations'
+keywords: ['On-the-fly mutation']
+description: 'Provides a description of on-the-fly mutations'
 ---
 
-## Lightweight Update {#lightweight-update}
+## On-the-fly mutations {#lightweight-update}
 
-When lightweight updates are enabled, updated rows are marked as updated immediately and subsequent `SELECT` queries will automatically return with the changed values. When lightweight updates are not enabled, you may have to wait for your mutations to be applied via a background process to see the changed values.
+When on-the-fly mutations are enabled, updated rows are marked as updated immediately and subsequent `SELECT` queries will automatically return with the changed values. When on-the-fly mutations are not enabled, you may have to wait for your mutations to be applied via a background process to see the changed values.
 
-Lightweight updates can be enabled for `MergeTree`-family tables by enabling the query-level setting `apply_mutations_on_fly`.
+On-the-fly mutations can be enabled for `MergeTree`-family tables by enabling the query-level setting `apply_mutations_on_fly`.
 
 ```sql
 SET apply_mutations_on_fly = 1;
@@ -24,7 +24,7 @@ CREATE TABLE test_on_fly_mutations (id UInt64, v String)
 ENGINE = MergeTree ORDER BY id;
 
 -- Disable background materialization of mutations to showcase
--- default behavior when lightweight updates are not enabled
+-- default behavior when on-the-fly mutations are not enabled
 SYSTEM STOP MERGES test_on_fly_mutations;
 SET mutations_sync = 0;
 
@@ -39,8 +39,9 @@ ALTER TABLE test_on_fly_mutations DELETE WHERE v = 'e';
 ```
 
 Let's check the result of the updates via a `SELECT` query:
+
 ```sql
--- Explicitly disable lightweight updates
+-- Explicitly disable on-the-fly-mutations
 SET apply_mutations_on_fly = 0;
 
 SELECT id, v FROM test_on_fly_mutations ORDER BY id;
@@ -56,10 +57,10 @@ Note that the values of the rows have not yet been updated when we query the new
 └────┴───┘
 ```
 
-Let's now see what happens when we enable lightweight updates:
+Let's now see what happens when we enable on-the-fly mutations:
 
 ```sql
--- Enable lightweight updates
+-- Enable on-the-fly mutations
 SET apply_mutations_on_fly = 1;
 
 SELECT id, v FROM test_on_fly_mutations ORDER BY id;
@@ -73,17 +74,17 @@ The `SELECT` query now returns the correct result immediately, without having to
 └────┴───┘
 ```
 
-## Performance Impact {#performance-impact}
+## Performance impact {#performance-impact}
 
-When lightweight updates are enabled, mutations are not materialized immediately but will only be applied during `SELECT` queries. However, please note that mutations are still being materialized asynchronously in the background, which is a heavy process.
+When on-the-fly mutations are enabled, mutations are not materialized immediately but will only be applied during `SELECT` queries. However, please note that mutations are still being materialized asynchronously in the background, which is a heavy process.
 
 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 unmaterialized mutations that have to be applied will continue to grow. This will result in the eventual degradation of `SELECT` query performance.
 
 We suggest enabling the setting `apply_mutations_on_fly` together with other `MergeTree`-level settings such as `number_of_mutations_to_throw` and `number_of_mutations_to_delay` to restrict the infinite growth of unmaterialized mutations.
 
 ## Support for subqueries and non-deterministic functions {#support-for-subqueries-and-non-deterministic-functions}
 
-Lightweight updates have limited support with subqueries and non-deterministic functions. Only scalar subqueries with a result that have a reasonable size (controlled by the setting `mutations_max_literal_size_to_replace`) are supported. Only constant non-deterministic functions are supported (e.g. the function `now()`).
+On-the-fly mutations have limited support with subqueries and non-deterministic functions. Only scalar subqueries with a result that have a reasonable size (controlled by the setting `mutations_max_literal_size_to_replace`) are supported. Only constant non-deterministic functions are supported (e.g. the function `now()`).
 
 These behaviours are controlled by the following settings:
 

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

@@ -18,14 +18,13 @@ There are several ways to update data in ClickHouse, each with its own advantage
 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.
 
 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).
-
 | Method                                                                                | Syntax                               | When to use                                                                                                                                                                                                                              |
 |---------------------------------------------------------------------------------------|--------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | [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.                                                                                                                        |
-| [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. |
+| [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.      |
+| [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. |
 | [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.                                                                                                                                |
 | [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.                                       |
-
 Here is a summary of the different ways to update data in ClickHouse:
 
 ## Update Mutations {#update-mutations}
@@ -40,9 +39,21 @@ These are extremely IO-heavy, rewriting all the parts that match the `WHERE` exp
 
 Read more about [update mutations](/sql-reference/statements/alter/update).
 
-## Lightweight Updates {#lightweight-updates}
+## Lightweight updates {#lightweight-updates}
+
+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 
+Key characteristics:
+
+- Uses the standard `UPDATE` syntax and creates patch parts immediately without waiting for merges
+- Updated values are immediately visible in `SELECT` queries through patch application, but physically materialized only during subsequent merges
+- Designed for small updates (up to ~10% of table) with predictable latency
+- Adds overhead to `SELECT` queries that need to apply patches, but avoids rewriting entire columns
+
+For more details see ["The Lightweight UPDATE Statement"](/sql-reference/statements/update)
+
+## On-the-fly Updates {#on-the-fly-updates}
 
-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:
+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:
 
 ```sql
 SET apply_mutations_on_fly = 1;
@@ -52,7 +63,7 @@ FROM posts
 WHERE Id = 404346
 
 ┌─ViewCount─┐
-│       26762   │
+│   26762   │
 └───────────┘
 
 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
 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.)
 ```
 
-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)).
+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)).
 
-Read more about [lightweight updates](/guides/developer/lightweight-update).
+Read more about [on-the-fly updates](/guides/developer/lightweight-update).
 
 ## Collapsing Merge Tree {#collapsing-merge-tree}