docs improvements based on comments [#CLICKHOUSE-3859]

docs/en/operations/table_engines/mergetree.md

@@ -51,18 +51,23 @@ For a description of request parameters, see [request description](../../query_l
 
 - `ENGINE` - Name and parameters of the engine. `ENGINE = MergeTree()`. `MergeTree` engine does not have parameters.
 
-- `ORDER BY` — Primary key (or sorting key if the separate `PRIMARY KEY` clause is present).
-
-    A tuple of columns or arbitrary expressions. Example: `ORDER BY (CounterID, EventDate)`.
-If a sampling expression is used, the primary key must contain it. Example: `ORDER BY (CounterID, EventDate, intHash32(UserID))`.
-
-- `PRIMARY KEY` - Primary key if it differs from the [sorting key](mergetree.md#table_engines-mergetree-sorting_key) (the sorting key in this case is specified by the `ORDER BY` clause).
-
 - `PARTITION BY` — The [partitioning key](custom_partitioning_key.md#table_engines-custom_partitioning_key).
 
     For partitioning by month, use the `toYYYYMM(date_column)` expression, where `date_column` is a column with a date of the type [Date](../../data_types/date.md#data_type-date). The partition names here have the `"YYYYMM"` format.
 
-- `SAMPLE BY` — An  expression for sampling. Example: `intHash32(UserID))`.
+- `ORDER BY` — The sorting key.
+
+    A tuple of columns or arbitrary expressions. Example: `ORDER BY (CounterID, EventDate)`.
+
+- `PRIMARY KEY` - The primary key if it [differs from the sorting key](mergetree.md#table_engines-mergetree-sorting_key).
+
+    By default the primary key is the same as the sorting key (which is specified by the `ORDER BY` clause).
+    Thus in most cases it is unnecessary to specify a separate `PRIMARY KEY` clause.
+
+- `SAMPLE BY` — An  expression for sampling.
+
+    If a sampling expression is used, the primary key must contain it. Example:  
+    `SAMPLE BY intHash32(UserID) ORDER BY (CounterID, EventDate, intHash32(UserID))`.
 
 - `SETTINGS` — Additional parameters that control the behavior of the `MergeTree`:
     - `index_granularity` — The granularity of an index. The number of data rows between the "marks" of an index. By default, 8192.
@@ -164,17 +169,17 @@ The number of columns in the primary key is not explicitly limited. Depending on
 
 - Provide additional logic when data parts merging in the [CollapsingMergeTree](collapsingmergetree.md#table_engine-collapsingmergetree) and [SummingMergeTree](summingmergetree.md#table_engine-summingmergetree) engines.
 
-    If you need this, it makes sense to specify the *sorting key* that is distinct from the primary key.
+    In this case it makes sense to specify the *sorting key* that is different from the primary key.
 
 A long primary key will negatively affect the insert performance and memory consumption, but extra columns in the primary key do not affect ClickHouse performance during `SELECT` queries.
 
 <a name="table_engines-mergetree-sorting_key"></a>
 
-### Choosing the Sorting Key that is distinct from the Primary Key
+### Choosing the Primary Key that differs from the Sorting Key
 
-It is possible to specify the sorting key (the expression for sorting the rows in data parts) that is distinct
-from the primary key (the expression, values of which are written into the index file for each mark). In this
-case primary key expression tuple must be a prefix of the sorting key expression tuple.
+It is possible to specify the primary key (the expression, values of which are written into the index file
+for each mark) that is different from the sorting key (the expression for sorting the rows in data parts).
+In this case the primary key expression tuple must be a prefix of the sorting key expression tuple.
 
 This feature is helpful when using the [SummingMergeTree](summingmergetree.md) and
 [AggregatingMergeTree](aggregatingmergetree.md) table engines. In a common case when using these engines the

docs/en/query_language/alter.md

@@ -78,17 +78,19 @@ The following command is supported:
 MODIFY ORDER BY new_expression
 ```
 
-It only works for tables in the `MergeTree` family (including replicated tables). The command changes the
+It only works for tables in the [`MergeTree`](../operations/table_engines/mergetree.md) family (including
+[replicated](../operations/table_engines/replication.md) tables). The command changes the
 [sorting key](../operations/table_engines/mergetree.md#table_engines-mergetree-sorting_key) of the table
 to `new_expression` (an expression or a tuple of expressions). Primary key remains the same.
 
 The command is lightweight in a sense that it only changes metadata. To keep the property that data part
-rows are sorted by the sorting key expression you cannot add expressions containing existing columns
+rows are ordered by the sorting key expression you cannot add expressions containing existing columns
 to the sorting key (only columns added by the `ADD COLUMN` command in the same `ALTER` query).
 
 ### Manipulations With Partitions and Parts
 
-It only works for tables in the `MergeTree` family (including replicated tables). The following operations
+It only works for tables in the [`MergeTree`](../operations/table_engines/mergetree.md) family (including
+[replicated](../operations/table_engines/replication.md) tables). The following operations
 are available:
 
 - `DETACH PARTITION` – Move a partition to the 'detached' directory and forget it.

docs/ru/operations/table_engines/mergetree.md

@@ -49,18 +49,23 @@ CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster]
 
 - `ENGINE` — Имя и параметры движка. `ENGINE = MergeTree()`. Движок `MergeTree` не имеет параметров.
 
-- `ORDER BY` — первичный ключ (если не указана отдельная секция `PRIMARY KEY`).
-
-    Кортеж столбцов или произвольных выражений. Пример: `ORDER BY (CounerID, EventDate)`.  
-    Если используется выражение для сэмплирования, то первичный ключ должен содержать его. Пример: `ORDER BY (CounerID, EventDate, intHash32(UserID))`.
-
-- `PRIMARY KEY` - первичный ключ, если он отличается от [ключа сортировки](mergetree.md#table_engines-mergetree-sorting_key) (который в этом случае задаёт секция `ORDER BY`).
-
 - `PARTITION BY` — [ключ партиционирования](custom_partitioning_key.md#table_engines-custom_partitioning_key).
 
     Для партиционирования по месяцам используйте выражение `toYYYYMM(date_column)`, где `date_column` — столбец с датой типа [Date](../../data_types/date.md#data_type-date). В этом случае имена партиций имеют формат `"YYYYMM"`.
 
-- `SAMPLE BY` — выражение для сэмплирования. Пример: `intHash32(UserID))`.
+- `ORDER BY` — ключ сортировки.
+
+    Кортеж столбцов или произвольных выражений. Пример: `ORDER BY (CounerID, EventDate)`.  
+
+- `PRIMARY KEY` - первичный ключ, если он [отличается от ключа сортировки](mergetree.md#table_engines-mergetree-sorting_key).
+
+    По умолчанию первичный ключ совпадает с ключом сортировки (который задаётся секцией `ORDER BY`). Поэтому
+    в большинстве случаев секцию `PRIMARY KEY` отдельно указывать не нужно.
+
+- `SAMPLE BY` — выражение для сэмплирования.
+
+    Если используется выражение для сэмплирования, то первичный ключ должен содержать его. Пример:  
+    `SAMPLE BY intHash32(UserID) ORDER BY (CounerID, EventDate, intHash32(UserID))`.
 
 - `SETTINGS` — дополнительные параметры, регулирующие поведение `MergeTree`:
 
@@ -164,17 +169,17 @@ ClickHouse не требует уникального первичного кл
 
 - Обеспечить дополнительную логику при слиянии кусков данных в движках [CollapsingMergeTree](collapsingmergetree.md#table_engine-collapsingmergetree) и [SummingMergeTree](summingmergetree.md#table_engine-summingmergetree).
 
-    Для этого имеет смысл задать отдельный *ключ сортировки*, отличающийся от первичного ключа.
+    В этом случае имеет смысл задать отдельный *ключ сортировки*, отличающийся от первичного ключа.
 
 Длинный первичный ключ будет негативно влиять на производительность вставки и потребление памяти, однако на производительность ClickHouse при запросах `SELECT` лишние столбцы в первичном ключе не влияют.
 
 <a name="table_engines-mergetree-sorting_key"></a>
 
-### Ключ сортировки, отличный от первичного ключа
+### Первичный ключ, отличный от ключа сортировки
 
-Существует возможность задать ключ сортировки (выражение, по которому будут упорядочены строки в кусках
-данных), отличающийся от первичного ключа (выражения, значения которого будут записаны в индексный файл для
-каждой засечки). Кортеж выражения первичного ключа при этом должен быть префиксом кортежа выражения ключа
+Существует возможность задать первичный ключ (выражение, значения которого будут записаны в индексный файл для
+каждой засечки), отличный от ключа сортировки (выражения, по которому будут упорядочены строки в кусках
+данных). Кортеж выражения первичного ключа при этом должен быть префиксом кортежа выражения ключа
 сортировки.
 
 Данная возможность особенно полезна при использовании движков [SummingMergeTree](summingmergetree.md)

docs/ru/query_language/alter.md

@@ -76,7 +76,7 @@ MODIFY COLUMN name [type] [default_expr]
 MODIFY ORDER BY new_expression
 ```
 
-Работает только для таблиц семейства `MergeTree` (в том числе реплицированных). После выполнения запроса
+Работает только для таблиц семейства [`MergeTree`](../operations/table_engines/mergetree.md) (в том числе [реплицированных](../operations/table_engines/replication.md)). После выполнения запроса
 [ключ сортировки](../operations/table_engines/mergetree.md#table_engines-mergetree-sorting_key) таблицы
 заменяется на `new_expression` (выражение или кортеж выражений). Первичный ключ при этом остаётся прежним.
 
@@ -86,7 +86,7 @@ MODIFY ORDER BY new_expression
 
 ### Манипуляции с партициями и кусками
 
-Работает только для таблиц семейства `MergeTree` (в том числе реплицированных). Существуют следующие виды
+Работает только для таблиц семейства [`MergeTree`](../operations/table_engines/mergetree.md) (в том числе [реплицированных](../operations/table_engines/replication.md)). Существуют следующие виды
 операций:
 
 -   `DETACH PARTITION` - перенести партицию в директорию detached и забыть про неё.