Merge pull request #37623 from den-crane/patch-12

Doc. Notes about UInt64 key for dictionaries layout

docs/en/sql-reference/dictionaries/external-dictionaries/external-dicts-dict-layout.md

@@ -21,7 +21,7 @@ ClickHouse generates an exception for errors with dictionaries. Examples of erro
 -   The dictionary being accessed could not be loaded.
 -   Error querying a `cached` dictionary.
 
-You can view the list of external dictionaries and their statuses in the `system.dictionaries` table.
+You can view the list of external dictionaries and their statuses in the [system.dictionaries](../../../operations/system-tables/dictionaries.md) table.
 
 The configuration looks like this:
 
@@ -48,6 +48,35 @@ LAYOUT(LAYOUT_TYPE(param value)) -- layout settings
 ...
 ```
 
+Dictionaries without word `complex-key*` in a layout have a key with [UInt64](../../../sql-reference/data-types/int-uint.md) type, `complex-key*` dictionaries have a composite key (complex, with arbitrary types).
+
+[UInt64](../../../sql-reference/data-types/int-uint.md) keys in XML dictionaries are defined with `<id>` tag.
+
+Configuration example (column key_column has UInt64 type):
+```xml
+...
+<structure>
+    <id>
+        <name>key_column</name>
+    </id>
+...
+```
+
+Composite `complex` keys XML dictionaries are defined `<key>` tag.
+
+Configuration example of a composite key (key has one element with [String](../../../sql-reference/data-types/string.md) type):
+```xml
+...
+<structure>
+    <key>
+        <attribute>
+            <name>country_code</name>
+            <type>String</type>
+        </attribute>
+    </key>
+...
+```
+
 ## Ways to Store Dictionaries in Memory {#ways-to-store-dictionaries-in-memory}
 
 -   [flat](#flat)
@@ -98,6 +127,8 @@ LAYOUT(FLAT(INITIAL_ARRAY_SIZE 50000 MAX_ARRAY_SIZE 5000000))
 
 The dictionary is completely stored in memory in the form of a hash table. The dictionary can contain any number of elements with any identifiers In practice, the number of keys can reach tens of millions of items.
 
+The dictionary key has the [UInt64](../../../sql-reference/data-types/int-uint.md) type.
+
 If `preallocate` is `true` (default is `false`) the hash table will be preallocated (this will make the dictionary load faster). But note that you should use it only if:
 
 - The source support an approximate number of elements (for now it is supported only by the `ClickHouse` source).
@@ -125,6 +156,8 @@ LAYOUT(HASHED(PREALLOCATE 0))
 
 Similar to `hashed`, but uses less memory in favor more CPU usage.
 
+The dictionary key has the [UInt64](../../../sql-reference/data-types/int-uint.md) type.
+
 It will be also preallocated so as `hashed` (with `preallocate` set to `true`), and note that it is even more significant for `sparse_hashed`.
 
 Configuration example:
@@ -181,6 +214,8 @@ LAYOUT(COMPLEX_KEY_SPARSE_HASHED())
 
 The dictionary is completely stored in memory. Each attribute is stored in an array. The key attribute is stored in the form of a hashed table where value is an index in the attributes array. The dictionary can contain any number of elements with any identifiers. In practice, the number of keys can reach tens of millions of items.
 
+The dictionary key has the [UInt64](../../../sql-reference/data-types/int-uint.md) type.
+
 All types of sources are supported. When updating, data (from a file or from a table) is read in its entirety.
 
 Configuration example:
@@ -220,6 +255,7 @@ LAYOUT(COMPLEX_KEY_HASHED_ARRAY())
 
 The dictionary is stored in memory in the form of a hash table with an ordered array of ranges and their corresponding values.
 
+The dictionary key has the [UInt64](../../../sql-reference/data-types/int-uint.md) type.
 This storage method works the same way as hashed and allows using date/time (arbitrary numeric type) ranges in addition to the key.
 
 Example: The table contains discounts for each advertiser in the format:
@@ -360,6 +396,8 @@ RANGE(MIN StartDate MAX EndDate);
 
 The dictionary is stored in a cache that has a fixed number of cells. These cells contain frequently used elements.
 
+The dictionary key has the [UInt64](../../../sql-reference/data-types/int-uint.md) type.
+
 When searching for a dictionary, the cache is searched first. For each block of data, all keys that are not found in the cache or are outdated are requested from the source using `SELECT attrs... FROM db.table WHERE id IN (k1, k2, ...)`. The received data is then written to the cache.
 
 If keys are not found in dictionary, then update cache task is created and added into update queue. Update queue properties can be controlled with settings `max_update_queue_size`, `update_queue_push_timeout_milliseconds`, `query_wait_timeout_milliseconds`, `max_threads_for_updates`.
@@ -420,6 +458,8 @@ This type of storage is for use with composite [keys](../../../sql-reference/dic
 
 Similar to `cache`, but stores data on SSD and index in RAM. All cache dictionary settings related to update queue can also be applied to SSD cache dictionaries.
 
+The dictionary key has the [UInt64](../../../sql-reference/data-types/int-uint.md) type.
+
 ``` xml
 <layout>
     <ssd_cache>
@@ -452,7 +492,7 @@ This type of storage is for use with composite [keys](../../../sql-reference/dic
 
 The dictionary is not stored in memory and directly goes to the source during the processing of a request.
 
-The dictionary key has the `UInt64` type.
+The dictionary key has the [UInt64](../../../sql-reference/data-types/int-uint.md) type.
 
 All types of [sources](../../../sql-reference/dictionaries/external-dictionaries/external-dicts-dict-sources.md), except local files, are supported.
 

docs/ru/sql-reference/dictionaries/external-dictionaries/external-dicts-dict-layout.md

@@ -21,7 +21,7 @@ sidebar_label: "Хранение словарей в памяти"
 -   При обращении к словарю, который не удалось загрузить.
 -   При ошибке запроса к `cached`-словарю.
 
-Список внешних словарей и их статус можно посмотреть в таблице `system.dictionaries`.
+Список внешних словарей и их статус можно посмотреть в таблице [system.dictionaries](../../../operations/system-tables/dictionaries.md).
 
 Общий вид конфигурации:
 
@@ -48,6 +48,36 @@ LAYOUT(LAYOUT_TYPE(param value)) -- layout settings
 ...
 ```
 
+Ключ словарей не имеющих слово `complex-key*` в названии имеет тип [UInt64](../../../sql-reference/data-types/int-uint.md), `complex-key*` словари позволяют произвольный тип ключа (составной, и из разных типов).
+
+[UInt64](../../../sql-reference/data-types/int-uint.md) ключи в XML словарях задаются тегом `<id>`.
+
+Пример конфигурации (поле key_column имеет тип UInt64):
+```xml
+...
+<structure>
+    <id>
+        <name>key_column</name>
+    </id>
+...
+```
+
+Cоставные `complex` ключи в XML словарях задаются тегом `<key>`.
+
+Пример конфигурации составного ключа (ключ состоит из одного элемента с типом [String](../../../sql-reference/data-types/string.md)):
+```xml
+...
+<structure>
+    <key>
+        <attribute>
+            <name>country_code</name>
+            <type>String</type>
+        </attribute>
+    </key>
+...
+```
+
+
 ## Способы размещения словарей в памяти {#ways-to-store-dictionaries-in-memory}
 
 -   [flat](#flat)
@@ -98,6 +128,8 @@ LAYOUT(FLAT(INITIAL_ARRAY_SIZE 50000 MAX_ARRAY_SIZE 5000000))
 
 Словарь полностью хранится в оперативной памяти в виде хэш-таблиц. Словарь может содержать произвольное количество элементов с произвольными идентификаторами. На практике количество ключей может достигать десятков миллионов элементов.
 
+Ключ словаря имеет тип [UInt64](../../../sql-reference/data-types/int-uint.md).
+
 Если `preallocate` имеет значение `true` (по умолчанию `false`), хеш-таблица будет предварительно определена (это ускорит загрузку словаря). Используйте этот метод только в случае, если:
 
 - Источник поддерживает произвольное количество элементов (пока поддерживается только источником `ClickHouse`).
@@ -125,6 +157,8 @@ LAYOUT(HASHED(PREALLOCATE 0))
 
 Аналогичен `hashed`, но при этом занимает меньше места в памяти и генерирует более высокую загрузку CPU.
 
+Ключ словаря имеет тип [UInt64](../../../sql-reference/data-types/int-uint.md).
+
 Для этого типа размещения также можно задать `preallocate` в значении `true`. В данном случае это более важно, чем для типа `hashed`.
 
 Пример конфигурации:
@@ -181,6 +215,8 @@ LAYOUT(COMPLEX_KEY_SPARSE_HASHED())
 
 Словарь полностью хранится в оперативной памяти. Каждый атрибут хранится в массиве. Ключевой атрибут хранится в виде хеш-таблицы, где его значение является индексом в массиве атрибутов. Словарь может содержать произвольное количество элементов с произвольными идентификаторами. На практике количество ключей может достигать десятков миллионов элементов.
 
+Ключ словаря имеет тип [UInt64](../../../sql-reference/data-types/int-uint.md).
+
 Поддерживаются все виды источников. При обновлении данные (из файла, из таблицы) считываются целиком.
 
 Пример конфигурации:
@@ -220,6 +256,7 @@ LAYOUT(COMPLEX_KEY_HASHED_ARRAY())
 
 Словарь хранится в оперативной памяти в виде хэш-таблицы с упорядоченным массивом диапазонов и соответствующих им значений.
 
+Ключ словаря имеет тип [UInt64](../../../sql-reference/data-types/int-uint.md).
 Этот способ размещения работает также как и hashed и позволяет дополнительно к ключу использовать дипазоны по дате/времени (произвольному числовому типу).
 
 Пример: таблица содержит скидки для каждого рекламодателя в виде:
@@ -355,6 +392,8 @@ RANGE(MIN StartDate MAX EndDate);
 
 Словарь хранится в кэше, состоящем из фиксированного количества ячеек. Ячейки содержат часто используемые элементы.
 
+Ключ словаря имеет тип [UInt64](../../../sql-reference/data-types/int-uint.md).
+
 При поиске в словаре сначала просматривается кэш. На каждый блок данных, все не найденные в кэше или устаревшие ключи запрашиваются у источника с помощью `SELECT attrs... FROM db.table WHERE id IN (k1, k2, ...)`. Затем, полученные данные записываются в кэш.
 
 Если ключи не были найдены в словаре, то для обновления кэша создается задание и добавляется в очередь обновлений. Параметры очереди обновлений можно устанавливать настройками `max_update_queue_size`, `update_queue_push_timeout_milliseconds`, `query_wait_timeout_milliseconds`, `max_threads_for_updates`
@@ -414,6 +453,8 @@ LAYOUT(CACHE(SIZE_IN_CELLS 1000000000))
 
 Похож на `cache`, но хранит данные на SSD, а индекс в оперативной памяти. Все параметры, относящиеся к очереди обновлений, могут также быть применены к SSD-кэш словарям.
 
+Ключ словаря имеет тип [UInt64](../../../sql-reference/data-types/int-uint.md).
+
 ``` xml
 <layout>
     <ssd_cache>
@@ -446,7 +487,7 @@ LAYOUT(SSD_CACHE(BLOCK_SIZE 4096 FILE_SIZE 16777216 READ_BUFFER_SIZE 1048576
 
 Словарь не хранит данные локально и взаимодействует с источником непосредственно в момент запроса.
 
-Ключ словаря имеет тип `UInt64`.
+Ключ словаря имеет тип [UInt64](../../../sql-reference/data-types/int-uint.md).
 
 Поддерживаются все виды [источников](external-dicts-dict-sources.md), кроме локальных файлов.