From 14476cd2c2afc23dedbdadf62aa65fd40368de28 Mon Sep 17 00:00:00 2001 From: Shaun Struwig <41984034+Blargian@users.noreply.github.com> Date: Sun, 16 Mar 2025 12:41:58 +0100 Subject: [PATCH 1/2] fix codeblock highlighting --- contribute/style-guide.md | 32 ++++++++++ .../bestpractices/avoidnullablecolumns.md | 4 +- .../best-practices/sparse-primary-indexes.md | 60 +++++++++---------- docs/integrations/data-ingestion/gcs/index.md | 8 +-- 4 files changed, 68 insertions(+), 36 deletions(-) diff --git a/contribute/style-guide.md b/contribute/style-guide.md index 54c32fa4649..c928a63cd5d 100644 --- a/contribute/style-guide.md +++ b/contribute/style-guide.md @@ -92,6 +92,38 @@ Code blocks: - Have a title (optional) such as 'Query' or 'Response' - Use language `response` if it is for the result of a query. +### Highlighting + +You can highlight lines in a code block using the following keywords: + +- `highlight-next-line` +- `highlight-start` +- `highlight-end` + +These keywords should be added as comments in the codeblock with the appropriate +escape symbol for the codeblock language. + +For example, if the codeblock is SQL: + +```text +SELECT UserID, count(UserID) AS Count +-- highlight-next-line +FROM mv_hits_URL_UserID +WHERE URL = 'http://public_search' +GROUP BY UserID +ORDER BY Count DESC +LIMIT 10; +``` + +If the codeblock is a response: + +```text +10 rows in set. Elapsed: 0.026 sec. +# highlight-next-line +Processed 335.87 thousand rows, +13.54 MB (12.91 million rows/s., 520.38 MB/s.) +``` + ### Associated markdown rule or CI check - [`MD040` enforces that codeblocks have a language specified](/scripts/.markdownlint-cli2.yaml) diff --git a/docs/cloud/bestpractices/avoidnullablecolumns.md b/docs/cloud/bestpractices/avoidnullablecolumns.md index 670e058bc3e..75e750ca48e 100644 --- a/docs/cloud/bestpractices/avoidnullablecolumns.md +++ b/docs/cloud/bestpractices/avoidnullablecolumns.md @@ -13,7 +13,7 @@ To avoid `Nullable` columns, consider setting a default value for that column. CREATE TABLE default.sample ( `x` Int8, - # highlight-next-line + -- highlight-next-line `y` Nullable(Int8) ) ENGINE = MergeTree @@ -25,7 +25,7 @@ use CREATE TABLE default.sample2 ( `x` Int8, - # highlight-next-line + -- highlight-next-line `y` Int8 DEFAULT 0 ) ENGINE = MergeTree diff --git a/docs/guides/best-practices/sparse-primary-indexes.md b/docs/guides/best-practices/sparse-primary-indexes.md index 9048d14d091..d990bd3334a 100644 --- a/docs/guides/best-practices/sparse-primary-indexes.md +++ b/docs/guides/best-practices/sparse-primary-indexes.md @@ -146,7 +146,7 @@ The response is: └────────────────────────────────┴───────┘ 10 rows in set. Elapsed: 0.022 sec. -// highlight-next-line +# highlight-next-line Processed 8.87 million rows, 70.45 MB (398.53 million rows/s., 3.17 GB/s.) ``` @@ -183,7 +183,7 @@ CREATE TABLE hits_UserID_URL `EventTime` DateTime ) ENGINE = MergeTree -// highlight-next-line +-- highlight-next-line PRIMARY KEY (UserID, URL) ORDER BY (UserID, URL, EventTime) SETTINGS index_granularity = 8192, index_granularity_bytes = 0, compress_primary_key = 0; @@ -532,7 +532,7 @@ The response is: └────────────────────────────────┴───────┘ 10 rows in set. Elapsed: 0.005 sec. -// highlight-next-line +# highlight-next-line Processed 8.19 thousand rows, 740.18 KB (1.53 million rows/s., 138.59 MB/s.) ``` @@ -543,13 +543,13 @@ The output for the ClickHouse client is now showing that instead of doing a full If trace logging is enabled then the ClickHouse server log file shows that ClickHouse was running a binary search over the 1083 UserID index marks, in order to identify granules that possibly can contain rows with a UserID column value of `749927693`. This requires 19 steps with an average time complexity of `O(log2 n)`: ```response ...Executor): Key condition: (column 0 in [749927693, 749927693]) -// highlight-next-line +# highlight-next-line ...Executor): Running binary search on index range for part all_1_9_2 (1083 marks) ...Executor): Found (LEFT) boundary mark: 176 ...Executor): Found (RIGHT) boundary mark: 177 ...Executor): Found continuous range in 19 steps ...Executor): Selected 1/1 parts by partition key, 1 parts by primary key, -// highlight-next-line +# highlight-next-line 1/1083 marks by primary key, 1 marks to read from 1 ranges ...Reading ...approx. 8192 rows starting from 1441792 ``` @@ -597,7 +597,7 @@ The response looks like: │ UserID │ │ Condition: (UserID in [749927693, 749927693]) │ │ Parts: 1/1 │ -// highlight-next-line +# highlight-next-line │ Granules: 1/1083 │ └───────────────────────────────────────────────────────────────────────────────────────┘ @@ -765,7 +765,7 @@ The response is: └────────────┴───────┘ 10 rows in set. Elapsed: 0.086 sec. -// highlight-next-line +# highlight-next-line Processed 8.81 million rows, 799.69 MB (102.11 million rows/s., 9.27 GB/s.) ``` @@ -776,11 +776,11 @@ If [trace_logging](/operations/server-configuration-parameters/settings#logger) ```response ...Executor): Key condition: (column 1 in ['http://public_search', 'http://public_search']) -// highlight-next-line +# highlight-next-line ...Executor): Used generic exclusion search over index for part all_1_9_2 with 1537 steps ...Executor): Selected 1/1 parts by partition key, 1 parts by primary key, -// highlight-next-line +# highlight-next-line 1076/1083 marks by primary key, 1076 marks to read from 5 ranges ...Executor): Reading approx. 8814592 rows with 10 streams ``` @@ -927,7 +927,7 @@ CREATE TABLE hits_URL_UserID `EventTime` DateTime ) ENGINE = MergeTree -// highlight-next-line +-- highlight-next-line PRIMARY KEY (URL, UserID) ORDER BY (URL, UserID, EventTime) SETTINGS index_granularity = 8192, index_granularity_bytes = 0, compress_primary_key = 0; @@ -964,7 +964,7 @@ This is the resulting primary key: That can now be used to significantly speed up the execution of our example query filtering on the URL column in order to calculate the top 10 users that most frequently clicked on the URL "http://public_search": ```sql SELECT UserID, count(UserID) AS Count -// highlight-next-line +-- highlight-next-line FROM hits_URL_UserID WHERE URL = 'http://public_search' GROUP BY UserID @@ -990,7 +990,7 @@ The response is: └────────────┴───────┘ 10 rows in set. Elapsed: 0.017 sec. -// highlight-next-line +# highlight-next-line Processed 319.49 thousand rows, 11.38 MB (18.41 million rows/s., 655.75 MB/s.) ``` @@ -1004,13 +1004,13 @@ The corresponding trace log in the ClickHouse server log file confirms that: ```response ...Executor): Key condition: (column 0 in ['http://public_search', 'http://public_search']) -// highlight-next-line +# highlight-next-line ...Executor): Running binary search on index range for part all_1_9_2 (1083 marks) ...Executor): Found (LEFT) boundary mark: 644 ...Executor): Found (RIGHT) boundary mark: 683 ...Executor): Found continuous range in 19 steps ...Executor): Selected 1/1 parts by partition key, 1 parts by primary key, -// highlight-next-line +# highlight-next-line 39/1083 marks by primary key, 39 marks to read from 1 ranges ...Executor): Reading approx. 319488 rows with 2 streams ``` @@ -1055,7 +1055,7 @@ The response is: └────────────────────────────────┴───────┘ 10 rows in set. Elapsed: 0.024 sec. -// highlight-next-line +# highlight-next-line Processed 8.02 million rows, 73.04 MB (340.26 million rows/s., 3.10 GB/s.) ``` @@ -1063,11 +1063,11 @@ Processed 8.02 million rows, Server Log: ```response ...Executor): Key condition: (column 1 in [749927693, 749927693]) -// highlight-next-line +# highlight-next-line ...Executor): Used generic exclusion search over index for part all_1_9_2 with 1453 steps ...Executor): Selected 1/1 parts by partition key, 1 parts by primary key, -// highlight-next-line +# highlight-next-line 980/1083 marks by primary key, 980 marks to read from 23 ranges ...Executor): Reading approx. 8028160 rows with 10 streams ``` @@ -1119,7 +1119,7 @@ ClickHouse is storing the [column data files](#data-is-stored-on-disk-ordered-by The implicitly created table (and its primary index) backing the materialized view can now be used to significantly speed up the execution of our example query filtering on the URL column: ```sql SELECT UserID, count(UserID) AS Count -// highlight-next-line +-- highlight-next-line FROM mv_hits_URL_UserID WHERE URL = 'http://public_search' GROUP BY UserID @@ -1144,7 +1144,7 @@ The response is: └────────────┴───────┘ 10 rows in set. Elapsed: 0.026 sec. -// highlight-next-line +# highlight-next-line Processed 335.87 thousand rows, 13.54 MB (12.91 million rows/s., 520.38 MB/s.) ``` @@ -1156,11 +1156,11 @@ The corresponding trace log in the ClickHouse server log file confirms that Clic ```response ...Executor): Key condition: (column 0 in ['http://public_search', 'http://public_search']) -// highlight-next-line +# highlight-next-line ...Executor): Running binary search on index range ... ... ...Executor): Selected 4/4 parts by partition key, 4 parts by primary key, -// highlight-next-line +# highlight-next-line 41/1083 marks by primary key, 41 marks to read from 4 ranges ...Executor): Reading approx. 335872 rows with 4 streams ``` @@ -1203,7 +1203,7 @@ ClickHouse is storing the [column data files](#data-is-stored-on-disk-ordered-by The hidden table (and its primary index) created by the projection can now be (implicitly) used to significantly speed up the execution of our example query filtering on the URL column. Note that the query is syntactically targeting the source table of the projection. ```sql SELECT UserID, count(UserID) AS Count -// highlight-next-line +-- highlight-next-line FROM hits_UserID_URL WHERE URL = 'http://public_search' GROUP BY UserID @@ -1228,7 +1228,7 @@ The response is: └────────────┴───────┘ 10 rows in set. Elapsed: 0.029 sec. -// highlight-next-line +# highlight-next-line Processed 319.49 thousand rows, 1 1.38 MB (11.05 million rows/s., 393.58 MB/s.) ``` @@ -1241,14 +1241,14 @@ The corresponding trace log in the ClickHouse server log file confirms that Clic ```response ...Executor): Key condition: (column 0 in ['http://public_search', 'http://public_search']) -// highlight-next-line +# highlight-next-line ...Executor): Running binary search on index range for part prj_url_userid (1083 marks) ...Executor): ... -// highlight-next-line +# highlight-next-line ...Executor): Choose complete Normal projection prj_url_userid ...Executor): projection required columns: URL, UserID ...Executor): Selected 1/1 parts by partition key, 1 parts by primary key, -// highlight-next-line +# highlight-next-line 39/1083 marks by primary key, 39 marks to read from 1 ranges ...Executor): Reading approx. 319488 rows with 2 streams ``` @@ -1327,7 +1327,7 @@ CREATE TABLE hits_URL_UserID_IsRobot `IsRobot` UInt8 ) ENGINE = MergeTree -// highlight-next-line +-- highlight-next-line PRIMARY KEY (URL, UserID, IsRobot); ``` @@ -1355,7 +1355,7 @@ CREATE TABLE hits_IsRobot_UserID_URL `IsRobot` UInt8 ) ENGINE = MergeTree -// highlight-next-line +-- highlight-next-line PRIMARY KEY (IsRobot, UserID, URL); ``` And populate it with the same 8.87 million rows that we used to populate the previous table: @@ -1395,7 +1395,7 @@ The response is: └─────────┘ 1 row in set. Elapsed: 0.026 sec. -// highlight-next-line +# highlight-next-line Processed 7.92 million rows, 31.67 MB (306.90 million rows/s., 1.23 GB/s.) ``` @@ -1413,7 +1413,7 @@ The response is: └─────────┘ 1 row in set. Elapsed: 0.003 sec. -// highlight-next-line +# highlight-next-line Processed 20.32 thousand rows, 81.28 KB (6.61 million rows/s., 26.44 MB/s.) ``` diff --git a/docs/integrations/data-ingestion/gcs/index.md b/docs/integrations/data-ingestion/gcs/index.md index 0639e6d2367..ce6389e7bb7 100644 --- a/docs/integrations/data-ingestion/gcs/index.md +++ b/docs/integrations/data-ingestion/gcs/index.md @@ -155,7 +155,7 @@ CREATE TABLE trips_gcs ENGINE = MergeTree PARTITION BY toYYYYMM(pickup_date) ORDER BY pickup_datetime -# highlight-next-line +-- highlight-next-line SETTINGS storage_policy='gcs_main' ``` @@ -468,10 +468,10 @@ zk_synced_followers 2 # highlight-end ``` - ### Start ClickHouse server {#start-clickhouse-server} On `chnode1` and `chnode` run: + ```bash sudo service clickhouse-server start ``` @@ -546,7 +546,7 @@ cache_path: ``` #### Verify that tables created on the cluster are created on both nodes {#verify-that-tables-created-on-the-cluster-are-created-on-both-nodes} ```sql -# highlight-next-line +-- highlight-next-line create table trips on cluster 'cluster_1S_2R' ( `trip_id` UInt32, `pickup_date` Date, @@ -564,7 +564,7 @@ create table trips on cluster 'cluster_1S_2R' ( ENGINE = ReplicatedMergeTree PARTITION BY toYYYYMM(pickup_date) ORDER BY pickup_datetime -# highlight-next-line +-- highlight-next-line SETTINGS storage_policy='gcs_main' ``` ```response From 1aa69ca5ee5537b654472d4d9d9bc3d3f8a4c3d3 Mon Sep 17 00:00:00 2001 From: Shaun Struwig <41984034+Blargian@users.noreply.github.com> Date: Sun, 16 Mar 2025 21:01:50 +0100 Subject: [PATCH 2/2] Fix code blocks --- .../incremental-materialized-view.md | 54 +++++++++---------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/materialized-view/incremental-materialized-view.md b/docs/materialized-view/incremental-materialized-view.md index a18f286ddad..2b0b1adbeb6 100644 --- a/docs/materialized-view/incremental-materialized-view.md +++ b/docs/materialized-view/incremental-materialized-view.md @@ -57,16 +57,16 @@ ORDER BY day ASC LIMIT 10 ┌─────────────────day─┬─UpVotes─┬─DownVotes─┐ -│ 2008-07-31 00:00:00 │ 6 │ 0 │ -│ 2008-08-01 00:00:00 │ 182 │ 50 │ -│ 2008-08-02 00:00:00 │ 436 │ 107 │ -│ 2008-08-03 00:00:00 │ 564 │ 100 │ -│ 2008-08-04 00:00:00 │ 1306 │ 259 │ -│ 2008-08-05 00:00:00 │ 1368 │ 269 │ -│ 2008-08-06 00:00:00 │ 1701 │ 211 │ -│ 2008-08-07 00:00:00 │ 1544 │ 211 │ -│ 2008-08-08 00:00:00 │ 1241 │ 212 │ -│ 2008-08-09 00:00:00 │ 576 │ 46 │ +│ 2008-07-31 00:00:00 │ 6 │ 0 │ +│ 2008-08-01 00:00:00 │ 182 │ 50 │ +│ 2008-08-02 00:00:00 │ 436 │ 107 │ +│ 2008-08-03 00:00:00 │ 564 │ 100 │ +│ 2008-08-04 00:00:00 │ 1306 │ 259 │ +│ 2008-08-05 00:00:00 │ 1368 │ 269 │ +│ 2008-08-06 00:00:00 │ 1701 │ 211 │ +│ 2008-08-07 00:00:00 │ 1544 │ 211 │ +│ 2008-08-08 00:00:00 │ 1241 │ 212 │ +│ 2008-08-09 00:00:00 │ 576 │ 46 │ └─────────────────────┴─────────┴───────────┘ 10 rows in set. Elapsed: 0.133 sec. Processed 238.98 million rows, 2.15 GB (1.79 billion rows/s., 16.14 GB/s.) @@ -121,7 +121,7 @@ FROM up_down_votes_per_day FINAL ┌─count()─┐ -│ 5723 │ +│ 5723 │ └─────────┘ ``` @@ -151,16 +151,16 @@ GROUP BY Day ORDER BY Day ASC LIMIT 10 ┌────────Day─┬─UpVotes─┬─DownVotes─┐ -│ 2008-07-31 │ 6 │ 0 │ -│ 2008-08-01 │ 182 │ 50 │ -│ 2008-08-02 │ 436 │ 107 │ -│ 2008-08-03 │ 564 │ 100 │ -│ 2008-08-04 │ 1306 │ 259 │ -│ 2008-08-05 │ 1368 │ 269 │ -│ 2008-08-06 │ 1701 │ 211 │ -│ 2008-08-07 │ 1544 │ 211 │ -│ 2008-08-08 │ 1241 │ 212 │ -│ 2008-08-09 │ 576 │ 46 │ +│ 2008-07-31 │ 6 │ 0 │ +│ 2008-08-01 │ 182 │ 50 │ +│ 2008-08-02 │ 436 │ 107 │ +│ 2008-08-03 │ 564 │ 100 │ +│ 2008-08-04 │ 1306 │ 259 │ +│ 2008-08-05 │ 1368 │ 269 │ +│ 2008-08-06 │ 1701 │ 211 │ +│ 2008-08-07 │ 1544 │ 211 │ +│ 2008-08-08 │ 1241 │ 212 │ +│ 2008-08-09 │ 576 │ 46 │ └────────────┴─────────┴───────────┘ 10 rows in set. Elapsed: 0.010 sec. Processed 8.97 thousand rows, 89.68 KB (907.32 thousand rows/s., 9.07 MB/s.) @@ -189,18 +189,18 @@ GROUP BY Day ORDER BY Day DESC LIMIT 10 - ┌─────────────────Day─┬────────Score_99th─┬────AvgCommentCount─┐ + ┌─────────────────Day─┬────────Score_99th─┬────AvgCommentCount─┐ 1. │ 2024-03-31 00:00:00 │ 5.23700000000008 │ 1.3429811866859624 │ - 2. │ 2024-03-30 00:00:00 │ 5 │ 1.3097158891616976 │ + 2. │ 2024-03-30 00:00:00 │ 5 │ 1.3097158891616976 │ 3. │ 2024-03-29 00:00:00 │ 5.78899999999976 │ 1.2827635327635327 │ - 4. │ 2024-03-28 00:00:00 │ 7 │ 1.277746158224246 │ + 4. │ 2024-03-28 00:00:00 │ 7 │ 1.277746158224246 │ 5. │ 2024-03-27 00:00:00 │ 5.738999999999578 │ 1.2113264918282023 │ - 6. │ 2024-03-26 00:00:00 │ 6 │ 1.3097536945812809 │ - 7. │ 2024-03-25 00:00:00 │ 6 │ 1.2836721018539201 │ + 6. │ 2024-03-26 00:00:00 │ 6 │ 1.3097536945812809 │ + 7. │ 2024-03-25 00:00:00 │ 6 │ 1.2836721018539201 │ 8. │ 2024-03-24 00:00:00 │ 5.278999999999996 │ 1.2931667891256429 │ 9. │ 2024-03-23 00:00:00 │ 6.253000000000156 │ 1.334061135371179 │ 10. │ 2024-03-22 00:00:00 │ 9.310999999999694 │ 1.2388059701492538 │ - └─────────────────────┴───────────────────┴────────────────────┘ + └─────────────────────┴───────────────────┴────────────────────┘ 10 rows in set. Elapsed: 0.113 sec. Processed 59.82 million rows, 777.65 MB (528.48 million rows/s., 6.87 GB/s.) Peak memory usage: 658.84 MiB.