Merge branch 'master' into add-test-toast

kssenii · Oct 13, 2023 · 4555f2d · 4555f2d
2 parents b13147c + ab4a065
commit 4555f2d
Show file tree

Hide file tree

Showing 75 changed files with 2,625 additions and 1,039 deletions.
diff --git a/docs/en/interfaces/mysql.md b/docs/en/interfaces/mysql.md
@@ -10,10 +10,6 @@ ClickHouse supports the MySQL wire protocol. This allow tools that are MySQL-com
 
 ## Enabling the MySQL Interface On ClickHouse Cloud
 
-:::note
-The MySQL interface for ClickHouse Cloud is currently in private preview. Please contact support@clickhouse.com to enable this feature for your ClickHouse Cloud service.
-:::
-
 1. After creating your ClickHouse Cloud Service, on the credentials screen, select the MySQL tab
 
 ![Credentials screen - Prompt](./images/mysql1.png)

diff --git a/docs/en/operations/query-cache.md b/docs/en/operations/query-cache.md
@@ -61,17 +61,17 @@ FROM table
 SETTINGS use_query_cache = true, enable_writes_to_query_cache = false;
 ```
 
-For maximum control, it is generally recommended to provide settings "use_query_cache", "enable_writes_to_query_cache" and
-"enable_reads_from_query_cache" only with specific queries. It is also possible to enable caching at user or profile level (e.g. via `SET
+For maximum control, it is generally recommended to provide settings `use_query_cache`, `enable_writes_to_query_cache` and
+`enable_reads_from_query_cache` only with specific queries. It is also possible to enable caching at user or profile level (e.g. via `SET
 use_query_cache = true`) but one should keep in mind that all `SELECT` queries including monitoring or debugging queries to system tables
 may return cached results then.
 
 The query cache can be cleared using statement `SYSTEM DROP QUERY CACHE`. The content of the query cache is displayed in system table
-`system.query_cache`. The number of query cache hits and misses since database start are shown as events "QueryCacheHits" and
-"QueryCacheMisses" in system table [system.events](system-tables/events.md). Both counters are only updated for `SELECT` queries which run
-with setting `use_query_cache = true`, other queries do not affect "QueryCacheMisses". Field `query_cache_usage` in system table
-[system.query_log](system-tables/query_log.md) shows for each executed query whether the query result was written into or read from the
-query cache. Asynchronous metrics "QueryCacheEntries" and "QueryCacheBytes" in system table
+[system.query_cache](system-tables/query_cache.md). The number of query cache hits and misses since database start are shown as events
+"QueryCacheHits" and "QueryCacheMisses" in system table [system.events](system-tables/events.md). Both counters are only updated for
+`SELECT` queries which run with setting `use_query_cache = true`, other queries do not affect "QueryCacheMisses". Field `query_cache_usage`
+in system table [system.query_log](system-tables/query_log.md) shows for each executed query whether the query result was written into or
+read from the query cache. Asynchronous metrics "QueryCacheEntries" and "QueryCacheBytes" in system table
 [system.asynchronous_metrics](system-tables/asynchronous_metrics.md) show how many entries / bytes the query cache currently contains.
 
 The query cache exists once per ClickHouse server process. However, cache results are by default not shared between users. This can be
@@ -86,9 +86,18 @@ If the query was aborted due to an exception or user cancellation, no entry is w
 The size of the query cache in bytes, the maximum number of cache entries and the maximum size of individual cache entries (in bytes and in
 records) can be configured using different [server configuration options](server-configuration-parameters/settings.md#server_configuration_parameters_query-cache).
 
+```xml
+<query_cache>
+    <max_size_in_bytes>1073741824</max_size_in_bytes>
+    <max_entries>1024</max_entries>
+    <max_entry_size_in_bytes>1048576</max_entry_size_in_bytes>
+    <max_entry_size_in_rows>30000000</max_entry_size_in_rows>
+</query_cache>
+```
+
 It is also possible to limit the cache usage of individual users using [settings profiles](settings/settings-profiles.md) and [settings
 constraints](settings/constraints-on-settings.md). More specifically, you can restrict the maximum amount of memory (in bytes) a user may
-allocate in the query cache and the the maximum number of stored query results. For that, first provide configurations
+allocate in the query cache and the maximum number of stored query results. For that, first provide configurations
 [query_cache_max_size_in_bytes](settings/settings.md#query-cache-max-size-in-bytes) and
 [query_cache_max_entries](settings/settings.md#query-cache-size-max-entries) in a user profile in `users.xml`, then make both settings
 readonly:
@@ -158,6 +167,7 @@ Also, results of queries with non-deterministic functions are not cached by defa
 - functions which depend on the environment: [`currentUser()`](../sql-reference/functions/other-functions.md#currentUser),
   [`queryID()`](../sql-reference/functions/other-functions.md#queryID),
   [`getMacro()`](../sql-reference/functions/other-functions.md#getMacro) etc.
+
 To force caching of results of queries with non-deterministic functions regardless, use setting
 [query_cache_store_results_of_queries_with_nondeterministic_functions](settings/settings.md#query-cache-store-results-of-queries-with-nondeterministic-functions).
 

diff --git a/docs/en/operations/server-configuration-parameters/settings.md b/docs/en/operations/server-configuration-parameters/settings.md
@@ -2403,7 +2403,8 @@ This section contains the following parameters:
 - zookeeper_load_balancing - Specifies the algorithm of ZooKeeper node selection.
   * random - randomly selects one of ZooKeeper nodes.
   * in_order - selects the first ZooKeeper node, if it's not available then the second, and so on.
-  * nearest_hostname - selects a ZooKeeper node with a hostname that is most similar to the server’s hostname.
+  * nearest_hostname - selects a ZooKeeper node with a hostname that is most similar to the server’s hostname, hostname is compared with name prefix.
+  * hostname_levenshtein_distance - just like nearest_hostname, but it compares hostname in a levenshtein distance manner.
   * first_or_random - selects the first ZooKeeper node, if it's not available then randomly selects one of remaining ZooKeeper nodes.
   * round_robin - selects the first ZooKeeper node, if reconnection happens selects the next.
 
@@ -2425,7 +2426,7 @@ This section contains the following parameters:
     <root>/path/to/zookeeper/node</root>
     <!-- Optional. Zookeeper digest ACL string. -->
     <identity>user:password</identity>
-    <!--<zookeeper_load_balancing>random / in_order / nearest_hostname / first_or_random / round_robin</zookeeper_load_balancing>-->
+    <!--<zookeeper_load_balancing>random / in_order / nearest_hostname / hostname_levenshtein_distance / first_or_random / round_robin</zookeeper_load_balancing>-->
     <zookeeper_load_balancing>random</zookeeper_load_balancing>
 </zookeeper>
 ```

diff --git a/docs/en/operations/settings/settings.md b/docs/en/operations/settings/settings.md
@@ -1413,6 +1413,7 @@ ClickHouse supports the following algorithms of choosing replicas:
 
 - [Random](#load_balancing-random) (by default)
 - [Nearest hostname](#load_balancing-nearest_hostname)
+- [Hostname levenshtein distance](#load_balancing-hostname_levenshtein_distance)
 - [In order](#load_balancing-in_order)
 - [First or random](#load_balancing-first_or_random)
 - [Round robin](#load_balancing-round_robin)
@@ -1444,6 +1445,25 @@ This method might seem primitive, but it does not require external data about ne
 Thus, if there are equivalent replicas, the closest one by name is preferred.
 We can also assume that when sending a query to the same server, in the absence of failures, a distributed query will also go to the same servers. So even if different data is placed on the replicas, the query will return mostly the same results.
 
+### Hostname levenshtein distance {#load_balancing-hostname_levenshtein_distance}
+
+``` sql
+load_balancing = hostname_levenshtein_distance
+```
+
+Just like `nearest_hostname`, but it compares hostname in a [levenshtein distance](https://en.wikipedia.org/wiki/Levenshtein_distance) manner. For example:
+
+``` text
+example-clickhouse-0-0 ample-clickhouse-0-0
+1
+
+example-clickhouse-0-0 example-clickhouse-1-10
+2
+
+example-clickhouse-0-0 example-clickhouse-12-0
+3
+```
+
 ### In Order {#load_balancing-in_order}
 
 ``` sql

diff --git a/docs/en/operations/system-tables/query_cache.md b/docs/en/operations/system-tables/query_cache.md
@@ -0,0 +1,36 @@
+---
+slug: /en/operations/system-tables/query_cache
+---
+# query_cache
+
+Shows the content of the [query cache](../query-cache.md).
+
+Columns:
+
+- `query` ([String](../../sql-reference/data-types/string.md)) — Query string.
+- `result_size` ([UInt64](../../sql-reference/data-types/int-uint.md#uint-ranges)) — Size of the query cache entry.
+- `stale` ([UInt8](../../sql-reference/data-types/int-uint.md)) — If the query cache entry is stale.
+- `shared` ([UInt8](../../sql-reference/data-types/int-uint.md)) — If the query cache entry is shared between multiple users.
+- `compressed` ([UInt8](../../sql-reference/data-types/int-uint.md)) — If the query cache entry is compressed.
+- `expires_at` ([DateTime](../../sql-reference/data-types/datetime.md)) — When the query cache entry becomes stale.
+- `key_hash` ([UInt64](../../sql-reference/data-types/int-uint.md#uint-ranges)) — A hash of the query string, used as a key to find query cache entries.
+
+**Example**
+
+``` sql
+SELECT * FROM system.query_cache FORMAT Vertical;
+```
+
+``` text
+Row 1:
+──────
+query:       SELECT 1 SETTINGS use_query_cache = 1
+result_size: 128
+stale:       0
+shared:      0
+compressed:  1
+expires_at:  2023-10-13 13:35:45
+key_hash:    12188185624808016954
+
+1 row in set. Elapsed: 0.004 sec.
+```
diff --git a/docs/en/sql-reference/functions/arithmetic-functions.md b/docs/en/sql-reference/functions/arithmetic-functions.md
@@ -441,3 +441,40 @@ DB::Exception: Decimal result's scale is less than argument's one: While process
 │ -12 │ 2.1 │                                                       -5.7 │                                                   -5.71428 │
 └─────┴─────┴────────────────────────────────────────────────────────────┴────────────────────────────────────────────────────────────┘
 ```
+
+## byteSwap
+
+Reverses the bytes of an integer, i.e. changes its [endianness](https://en.wikipedia.org/wiki/Endianness). Currently, integers of up to 64 bit are supported.
+
+**Syntax**
+
+```sql
+byteSwap(a)
+```
+
+**Example**
+
+```sql
+byteSwap(3351772109)
+```
+
+Result:
+
+```result
+┌─byteSwap(3351772109)─┐
+│           3455829959 │
+└──────────────────────┘
+```
+
+The above example can be worked out in the following manner:
+1. Convert the base-10 integer to its equivalent hexadecimal format in big-endian format, i.e. 3351772109 -> C7 C7 FB CD (4 bytes)
+2. Reverse the bytes, i.e. C7 C7 FB CD -> CD FB C7 C7
+3. Convert the result back to an integer assuming big-endian, i.e. CD FB C7 C7  -> 3455829959
+
+One use case of this function is reversing IPv4s:
+
+```result
+┌─toIPv4(byteSwap(toUInt32(toIPv4('205.251.199.199'))))─┐
+│ 199.199.251.205                                       │
+└───────────────────────────────────────────────────────┘
+```