> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# структура словаря cache

> Хранит словарь в кэше фиксированного размера в памяти.

Тип структуры словаря `cached` хранит словарь в кэше с фиксированным количеством ячеек.
Эти ячейки содержат часто используемые элементы.

Ключ словаря имеет тип [UInt64](/ru/reference/data-types/int-uint).

При обращении к словарю сначала выполняется поиск в кэше. Для каждого блока данных все ключи, которые не найдены в кэше или являются устаревшими, запрашиваются из источника с помощью `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`.

Для словарей cache можно задать срок действия данных в кэше — [lifetime](/ru/reference/statements/create/dictionary/lifetime). Если с момента загрузки данных в ячейку прошло больше времени, чем `lifetime`, значение ячейки не используется, и ключ считается устаревшим. При следующем обращении этот ключ будет запрошен повторно. Это поведение можно настроить с помощью параметра `allow_read_expired_keys`.

Это наименее эффективный из всех способов хранения словарей. Производительность кэша сильно зависит от правильности настроек и сценария использования. Словарь типа cache показывает хорошую производительность только при достаточно высокой доле попаданий в кэш (рекомендуется 99% и выше). Среднюю долю попаданий можно посмотреть в таблице [system.dictionaries](/ru/reference/system-tables/dictionaries).

Если параметр `allow_read_expired_keys` установлен в 1 (по умолчанию — 0), словарь может поддерживать асинхронные обновления. Если клиент запрашивает ключи и все они есть в кэше, но некоторые из них устарели, словарь вернет клиенту устаревшие ключи и асинхронно запросит их из источника.

Чтобы повысить производительность кэша, используйте подзапрос с `LIMIT` и вызывайте функцию вне словаря.

Поддерживаются все типы источников.

Пример настроек:

<Tabs>
  <Tab title="DDL">
    ```sql theme={null}
    LAYOUT(CACHE(SIZE_IN_CELLS 1000000000))
    ```
  </Tab>

  <Tab title="Файл конфигурации">
    ```xml theme={null}
    <layout>
        <cache>
            <!-- Размер кэша в количестве ячеек. Округляется вверх до степени двойки. -->
            <size_in_cells>1000000000</size_in_cells>
            <!-- Позволяет читать устаревшие ключи. -->
            <allow_read_expired_keys>0</allow_read_expired_keys>
            <!-- Максимальный размер очереди обновления. -->
            <max_update_queue_size>100000</max_update_queue_size>
            <!-- Максимальный тайм-аут в миллисекундах для помещения задачи обновления в очередь. -->
            <update_queue_push_timeout_milliseconds>10</update_queue_push_timeout_milliseconds>
            <!-- Максимальный тайм-аут ожидания в миллисекундах для завершения задачи обновления. -->
            <query_wait_timeout_milliseconds>60000</query_wait_timeout_milliseconds>
            <!-- Максимальное число потоков для обновления словаря cache. -->
            <max_threads_for_updates>4</max_threads_for_updates>
        </cache>
    </layout>
    ```
  </Tab>
</Tabs>

<br />

Задайте достаточно большой размер кэша. Чтобы подобрать количество ячеек, нужно поэкспериментировать:

1. Задайте некоторое значение.
2. Выполняйте запросы, пока кэш полностью не заполнится.
3. Оцените потребление памяти с помощью таблицы `system.dictionaries`.
4. Увеличивайте или уменьшайте количество ячеек, пока не будет достигнут требуемый уровень потребления памяти.

<Note>
  Не рекомендуется использовать ClickHouse в качестве источника для этой структуры. Поиск по словарю требует случайных точечных чтений, а ClickHouse не оптимизирован под такой шаблон доступа.
</Note>