Merge pull request #23228 from vitlibar/improve-row-policy-docs-2

Improve documentation for CREATE ROW POLICY command #2.

docs/en/sql-reference/statements/create/row-policy.md

@@ -17,8 +17,6 @@ CREATE [ROW] POLICY [IF NOT EXISTS | OR REPLACE] policy_name1 [ON CLUSTER cluste
     [TO {role1 [, role2 ...] | ALL | ALL EXCEPT role1 [, role2 ...]}]
 ```
 
-`ON CLUSTER` clause allows creating row policies on a cluster, see [Distributed DDL](../../../sql-reference/distributed-ddl.md).
-
 ## USING Clause {#create-row-policy-using}
 
 Allows to specify a condition to filter rows. An user will see a row if the condition is calculated to non-zero for the row.
@@ -30,20 +28,20 @@ In the section `TO` you can provide a list of users and roles this policy should
 Keyword `ALL` means all the ClickHouse users including current user. Keyword `ALL EXCEPT` allow to exclude some users from the all users list, for example, `CREATE ROW POLICY ... TO ALL EXCEPT accountant, john@localhost`
 
 !!! note "Note"
-    If there are no row policies defined for a table then any user can `SELECT` all the row from the table.
-    Defining one or more row policies for the table makes the access to the table depending on the row policies no matter if
-    those row policies are defined for the current user or not. For example, the following row policy
-
+    If there are no row policies defined for a table then any user can `SELECT` all the row from the table. Defining one or more row policies for the table makes the access to the table depending on the row policies no matter if those row policies are defined for the current user or not. For example, the following policy
+    
     `CREATE ROW POLICY pol1 ON mydb.table1 USING b=1 TO mira, peter`
 
-    forbids the users `mira` and `peter` to see the rows with `b != 1`, and any non-mentioned user (e.g., the user `paul`) will see no rows from `mydb.table1` at all! If that isn't desirable you can fix it by adding one more row policy, for example:
+    forbids the users `mira` and `peter` to see the rows with `b != 1`, and any non-mentioned user (e.g., the user `paul`) will see no rows from `mydb.table1` at all.
+    
+    If that's not desirable it can't be fixed by adding one more row policy, like the following:
 
     `CREATE ROW POLICY pol2 ON mydb.table1 USING 1 TO ALL EXCEPT mira, peter`
 
 ## AS Clause {#create-row-policy-as}
 
-It's allowed to have more than one policy enabled on the same table for the same user at the one time.
-So we need a way to combine the conditions from multiple policies.
+It's allowed to have more than one policy enabled on the same table for the same user at the one time. So we need a way to combine the conditions from multiple policies.
+
 By default policies are combined using the boolean `OR` operator. For example, the following policies
 
 ``` sql
@@ -53,14 +51,15 @@ CREATE ROW POLICY pol2 ON mydb.table1 USING c=2 TO peter, antonio
 
 enables the user `peter` to see rows with either `b=1` or `c=2`.
 
-The `AS` clause specifies how policies should be combined with other policies. Policies can be either permissive or restrictive.
-By default policies are permissive, which means they are combined using the boolean `OR` operator.
+The `AS` clause specifies how policies should be combined with other policies. Policies can be either permissive or restrictive. By default policies are permissive, which means they are combined using the boolean `OR` operator.
 
 A policy can be defined as restrictive as an alternative. Restrictive policies are combined using the boolean `AND` operator.
-Here is the formula:
+
+Here is the general formula:
 
 ```
-row_is_visible = (one or more of the permissive policies' conditions are non-zero) AND (all of the restrictive policies's conditions are non-zero)`
+row_is_visible = (one or more of the permissive policies' conditions are non-zero) AND
+                 (all of the restrictive policies's conditions are non-zero)
 ```
 
 For example, the following policies
@@ -72,6 +71,10 @@ CREATE ROW POLICY pol2 ON mydb.table1 USING c=2 AS RESTRICTIVE TO peter, antonio
 
 enables the user `peter` to see rows only if both `b=1` AND `c=2`.
 
+## ON CLUSTER Clause {#create-row-policy-on-cluster}
+
+Allows creating row policies on a cluster, see [Distributed DDL](../../../sql-reference/distributed-ddl.md).
+
 
 ## Examples
 

docs/ru/sql-reference/statements/create/row-policy.md

@@ -17,9 +17,7 @@ CREATE [ROW] POLICY [IF NOT EXISTS | OR REPLACE] policy_name1 [ON CLUSTER cluste
     [TO {role [,...] | ALL | ALL EXCEPT role [,...]}]
 ```
 
-Секция `ON CLUSTER` позволяет создавать политики на кластере, см. [Распределенные DDL запросы](../../../sql-reference/distributed-ddl.md).
-
-## USING Clause {#create-row-policy-using}
+## Секция USING {#create-row-policy-using}
 
 Секция `USING` указывает условие для фильтрации строк. Пользователь может видеть строку, если это условие, вычисленное для строки, дает ненулевой результат.
 
@@ -30,22 +28,21 @@ CREATE [ROW] POLICY [IF NOT EXISTS | OR REPLACE] policy_name1 [ON CLUSTER cluste
 Ключевым словом `ALL` обозначаются все пользователи, включая текущего. Ключевые слова `ALL EXCEPT` позволяют исключить пользователей из списка всех пользователей. Например, `CREATE ROW POLICY ... TO ALL EXCEPT accountant, john@localhost`
 
 !!! note "Note"
-    Если для таблицы не задано ни одной политики доступа к строкам, то любой пользователь может выполнить `SELECT` и получить все строки таблицы.
-    Если определить хотя бы одну политику для таблицы, до доступ к строкам будет управляться этими политиками, причем для всех пользователей
-    (даже для тех, для кого политики не определялись). Например, следующая политика
+    Если для таблицы не задано ни одной политики доступа к строкам, то любой пользователь может выполнить команду SELECT и получить все строки таблицы. Если определить хотя бы одну политику для таблицы, до доступ к строкам будет управляться этими политиками, причем для всех пользователей (даже для тех, для кого политики не определялись). Например, следующая политика
 
     `CREATE ROW POLICY pol1 ON mydb.table1 USING b=1 TO mira, peter`
 
-    запретит пользователям `mira` и `peter` видеть строки с `b != 1`, и еще запретит всем остальным пользователям (например, пользователю `paul`)
-    видеть какие-либо строки вообще из таблицы `mydb.table1`! Если это нежелательно, такое поведение можно исправить, определив дополнительную политику:
+    запретит пользователям `mira` и `peter` видеть строки с `b != 1`, и еще запретит всем остальным пользователям (например, пользователю `paul`) видеть какие-либо строки вообще из таблицы `mydb.table1`.
+    
+    Если это нежелательно, такое поведение можно исправить, определив дополнительную политику:
 
     `CREATE ROW POLICY pol2 ON mydb.table1 USING 1 TO ALL EXCEPT mira, peter`
 
 ## Секция AS {#create-row-policy-as}
 
-Может быть одновременно активно более одной политики для одной и той же таблицы и одного и того же пользователя.
-Поэтому нам нужен способ комбинировать политики. По умолчанию политики комбинируются с использованием логического оператора `OR`.
-Например, политики:
+Может быть одновременно активно более одной политики для одной и той же таблицы и одного и того же пользователя. Поэтому нам нужен способ комбинировать политики.
+
+По умолчанию политики комбинируются с использованием логического оператора `OR`. Например, политики:
 
 ``` sql
 CREATE ROW POLICY pol1 ON mydb.table1 USING b=1 TO mira, peter
@@ -55,10 +52,15 @@ CREATE ROW POLICY pol2 ON mydb.table1 USING c=2 TO peter, antonio
 разрешат пользователю с именем `peter` видеть строки, для которых будет верно `b=1` или `c=2`.
 
 Секция `AS` указывает, как политики должны комбинироваться с другими политиками. Политики могут быть или разрешительными (`PERMISSIVE`), или ограничительными (`RESTRICTIVE`). По умолчанию политики создаются разрешительными (`PERMISSIVE`); такие политики комбинируются с использованием логического оператора `OR`.
-Ограничительные (`RESTRICTIVE`) политики комбинируются с использованием логического оператора `AND`.
-Используется следующая формула:
 
-`строка_видима = (одна или больше permissive-политик дала ненулевой результат проверки условия) И (все restrictive-политики дали ненулевой результат проверки условия)`
+Ограничительные (`RESTRICTIVE`) политики комбинируются с использованием логического оператора `AND`.
+
+Общая формула выглядит так:
+
+```
+строка_видима = (одна или больше permissive-политик дала ненулевой результат проверки условия) И
+                (все restrictive-политики дали ненулевой результат проверки условия)
+```
 
 Например, политики
 
@@ -69,6 +71,10 @@ CREATE ROW POLICY pol2 ON mydb.table1 USING c=2 AS RESTRICTIVE TO peter, antonio
 
 разрешат пользователю с именем `peter` видеть только те строки, для которых будет одновременно `b=1` и `c=2`.
 
+## Секция ON CLUSTER {#create-row-policy-on-cluster}
+
+Секция `ON CLUSTER` позволяет создавать политики на кластере, см. [Распределенные DDL запросы](../../../sql-reference/distributed-ddl.md).
+
 ## Примеры
 
 `CREATE ROW POLICY filter1 ON mydb.mytable USING a<1000 TO accountant, john@localhost`