Doc fix: Update info about system.columns + system.tables (en) (#4838)

docs/en/operations/system_tables.md

@@ -30,17 +30,26 @@ user String — The name of the user for connecting to the server.
 
 ## system.columns
 
-Contains information about the columns in all tables.
-You can use this table to get information similar to `DESCRIBE TABLE`, but for multiple tables at once.
+Contains information about the columns in all the tables.
 
-```
-database String — The name of the database the table is in.
-table String – Table name.
-name String — Column name.
-type String — Column type.
-default_type String — Expression type (DEFAULT, MATERIALIZED, ALIAS) for the default value, or an empty string if it is not defined.
-default_expression String — Expression for the default value, or an empty string if it is not defined.
-```
+You can use this table to get information similar to the [DESCRIBE TABLE](../query_language/misc.md#misc-describe-table) query, but for multiple tables at once.
+
+The `system.columns` table contains the following columns (the type of the corresponding column is shown in brackets):
+
+- `database` (String) — Database name.
+- `table` (String) — Table name.
+- `name` (String) — Column name.
+- `type` (String) — Column type.
+- `default_kind` (String) — Expression type (`DEFAULT`, `MATERIALIZED`, `ALIAS`) for the default value, or an empty string if it is not defined.
+- `default_expression` (String) — Expression for the default value, or an empty string if it is not defined.
+- `data_compressed_bytes` (UInt64) — The size of compressed data, in bytes.
+- `data_uncompressed_bytes` (UInt64) — The size of decompressed data, in bytes.
+- `marks_bytes` (UInt64) — The size of marks, in bytes.
+- `comment` (String) — The comment about column, or an empty string if it is not defined.
+- `is_in_partition_key` (UInt8) — Flag that indicates whether the column is in partition expression.
+- `is_in_sorting_key` (UInt8) — Flag that indicates whether the column is in sorting key expression.
+- `is_in_primary_key` (UInt8) — Flag that indicates whether the column is in primary key expression.
+- `is_in_sampling_key` (UInt8) — Flag that indicates whether the column is in sampling key expression.
 
 ## system.databases
 
@@ -374,10 +383,27 @@ WHERE changed
 
 ## system.tables
 
-This table contains the String columns 'database', 'name', and 'engine'.
-The table also contains three virtual columns: metadata_modification_time (DateTime type), create_table_query, and engine_full (String type).
-Each table that the server knows about is entered in the 'system.tables' table.
-This system table is used for implementing SHOW TABLES queries.
+Contains metadata of each table that the server knows about. Detached tables are not shown in `system.tables`.
+
+This table contains the following columns (the type of the corresponding column is shown in brackets):
+
+- `database` (String) — The name of database the table is in.
+- `name` (String) — Table name.
+- `engine` (String) — Table engine name (without parameters).
+- `is_temporary` (UInt8) - Flag that indicates whether the table is temporary.
+- `data_path` (String) - Path to the table data in the file system.
+- `metadata_path` (String) - Path to the table metadata in the file system. 
+- `metadata_modification_time` (DateTime) - Time of latest modification of the table metadata.
+- `dependencies_database` (Array(String)) - Database dependencies.
+- `dependencies_table` (Array(String)) - Table dependencies ([MaterializedView](table_engines/materializedview.md) tables based on the current table).
+- `create_table_query` (String) - The query that was used to create the table.
+- `engine_full` (String) - Parameters of the table engine.
+- `partition_key` (String) - The partition key expression specified in the table. 
+- `sorting_key` (String) - The sorting key expression specified in the table.
+- `primary_key` (String) - The primary key expression specified in the table.
+- `sampling_key` (String) - The sampling key expression specified in the table.
+
+The `system.tables` is used in `SHOW TABLES` query implementation.
 
 ## system.zookeeper
 

docs/en/query_language/misc.md

@@ -51,7 +51,7 @@ If the table is corrupted, you can copy the non-corrupted data to another table.
 3. Execute the query `INSERT INTO <new_table_name> SELECT * FROM <damaged_table_name>`. This request copies the non-corrupted data from the damaged table to another table. Only the data before the corrupted part will be copied.
 4. Restart the `clickhouse-client` to reset the `max_threads` value.
 
-## DESCRIBE TABLE
+## DESCRIBE TABLE {#misc-describe-table}
 
 ``` sql
 DESC|DESCRIBE TABLE [db.]table [INTO OUTFILE filename] [FORMAT format]

docs/en/query_language/select.md

@@ -51,18 +51,18 @@ The `SAMPLE` clause allows for approximated query processing. Approximated query
 The features of data sampling are listed below:
 
 - Data sampling is a deterministic mechanism. The result of the same `SELECT .. SAMPLE` query is always the same.
-- Sampling works consistently for different tables. For tables with a single sampling key, a sample with the same coefficient always selects the same subset of possible data. For example, a sample of user IDs takes rows with the same subset of all the possible user IDs from different tables. This allows using the sample in subqueries in the `IN` clause, as well as for manually correlating results of different queries with samples.
-- Sampling allows reading less data from a disk. Note that for this you must specify the sampling key correctly. For more details see [Creating a MergeTree Table](../operations/table_engines/mergetree.md#table_engine-mergetree-creating-a-table).
+- Sampling works consistently for different tables. For tables with a single sampling key, a sample with the same coefficient always selects the same subset of possible data. For example, a sample of user IDs takes rows with the same subset of all the possible user IDs from different tables. This means that you can use the sample in subqueries in the `IN` clause, as well as manually correlate results of different queries with samples.
+- Sampling allows reading less data from a disk. Note that you must specify the sampling key correctly. For more information, see [Creating a MergeTree Table](../operations/table_engines/mergetree.md#table_engine-mergetree-creating-a-table).
 
-The `SAMPLE` clause can be specified in several ways:
+For the `SAMPLE` clause the following syntax is supported:
 
-- `SAMPLE k`, where `k` is a decimal number from 0 to 1. The query is executed on `k` percent of data. For example, `SAMPLE 0.1` runs the query on 10% of data. [Read more](#select-sample-k)
+- `SAMPLE k`, where `k` is a decimal number from 0 to 1. The query is executed on `k` fraction of data. For example, `SAMPLE 0.1` runs the query on 10% of data. [Read more](#select-sample-k)
 - `SAMPLE n`, where `n` is a sufficiently large integer. The query is executed on a sample of at least `n` rows (but not significantly more than this). For example, `SAMPLE 10000000` runs the query on a minimum of 10,000,000 rows. [Read more](#select-sample-n)
 - `SAMPLE k OFFSET m` where `k` and `m` are numbers from 0 to 1. The query is executed on a sample of `k` percent of the data. The data used for the sample is offset by `m` percent. [Read more](#select-sample-offset)
 
 #### SAMPLE k {#select-sample-k}
 
-In a `SAMPLE k` clause, `k` is a percent amount of data that the sample is taken from. The example is shown below:
+In a `SAMPLE k` clause, the sample is taken from the `k` fraction of data. The example is shown below:
 
 ``` sql
 SELECT
@@ -84,9 +84,9 @@ In this case, the query is executed on a sample of at least `n` rows, where `n`
 
 Since the minimum unit for data reading is one granule (its size is set by the `index_granularity` setting), it makes sense to set a sample that is much larger than the size of the granule.
 
-When using the `SAMPLE n` clause, the relative coefficient is calculated dynamically. Since you do not know which relative percent of data was processed, you do not know the coefficient the aggregate functions should be multiplied by (for example, you do not know if the `SAMPLE 1000000` was taken from a set of 10,000,000 rows or from a set of 1,000,000,000 rows). In this case, use the `_sample_factor` column to get the approximate result.
+When using the `SAMPLE n` clause, the relative coefficient is calculated dynamically. Since you do not know which relative percent of data was processed, you do not know the coefficient the aggregate functions should be multiplied by (for example, you do not know if `SAMPLE 1000000` was taken from a set of 10,000,000 rows or from a set of 1,000,000,000 rows). In this case, use the `_sample_factor` virtual column to get the approximate result.
 
-The `_sample_factor` is a virtual column that ClickHouse stores relative coefficients in. This column is created automatically when you create a table with the specified sampling key. The usage example is shown below:
+The `_sample_factor` column is where ClickHouse stores relative coefficients. This column is created automatically when you create a table with the specified sampling key. The usage example is shown below:
 
 ``` sql
 SELECT sum(Duration * _sample_factor)
@@ -94,7 +94,7 @@ FROM visits
 SAMPLE 10000000
 ```   
 
-If you need to get the approximate count of rows in a `SELECT .. SAMPLE n` query, get the sum() of `_sample_factor` column instead of counting `count(column * _sample_factor)` value. For example:
+If you need to get the approximate count of rows in a `SELECT .. SAMPLE n` query, get the sum() of the `_sample_factor` column instead of counting the `count(*) * _sample_factor` value. For example:
 
 ``` sql
 SELECT sum(_sample_factor)
@@ -102,7 +102,7 @@ FROM visits
 SAMPLE 10000000
 ```  
 
-Note that to calculate the average in a `SELECT .. SAMPLE n` query, you do not need to use `_sample_factor` column:
+Note that to calculate the average in a `SELECT .. SAMPLE n` query, you do not need to use the `_sample_factor` column:
 
 ``` sql
 SELECT avg(Duration)
@@ -120,7 +120,7 @@ Example 1.
 SAMPLE 1/10
 ```
 
-In this example, the sample is the 1/10th of all data:
+In this example, the sample is 1/10th of all data:
 
 `[++------------------]`
 
@@ -130,7 +130,7 @@ Example 2.
 SAMPLE 1/10 OFFSET 1/2
 ```
 
-Here, the sample of 10% is taken from the second half of data.
+Here, a sample of 10% is taken from the second half of data.
 
 `[----------++--------]`