table_service_config

Секция table_service_config содержит параметры конфигурации для сервиса таблиц, включая настройки спиллинга.

resource_manager

В подсекции resource_manager задаются параметры управления ресурсами сервиса таблиц.

Кэш level table векторного индекса

Level table (indexImplLevelTable) векторного индекса vector_kmeans_tree хранит центроиды, к которым YDB обращается на каждом шаге спуска по дереву кластеров во время векторного поиска. Чтобы не перечитывать эти центроиды из распределённого хранилища при каждом запросе, YDB может кэшировать их в памяти на каждом узле базы данных.

Кэш создаётся отдельно на каждом узле, использует LRU-вытеснение и наращивает свой размер до указанного лимита постепенно.

table_service_config:
  resource_manager:
    kqp_level_cache_max_size_bytes: 0
    kqp_level_cache_increase_batch_size_bytes: 33554432

resource_manager.kqp_level_cache_max_size_bytes

Тип: uint64
По умолчанию: 0 (кэш отключён)
Описание: Максимальный размер кэша level table векторного индекса в байтах на один узел базы данных. Установка ненулевого значения включает кэш.

resource_manager.kqp_level_cache_increase_batch_size_bytes

Тип: uint64
По умолчанию: 33554432 (32 МиБ)
Описание: Шаг увеличения размера кэша level table. Кэш растёт порциями такого размера до значения kqp_level_cache_max_size_bytes и уменьшается такими же порциями при снижении лимита.

Лимиты памяти выполнения запросов

В подсекции resource_manager задаётся порог спиллинга относительно пула памяти запросов на узле. Размер этого пула регулируется параметрами query_execution_limit_percent / query_execution_limit_bytes в memory_controller_config.

table_service_config:
  resource_manager:
    spilling_percent: 80

resource_manager.spilling_percent

Тип: double
По умолчанию: 80
Описание: Порог заполнения пула памяти запросов, при котором YDB начинает считать спиллинг предпочтительным способом управления памятью. Базой для расчёта служит пул Query Processor, размер которого задаётся query_execution_limit_percent / query_execution_limit_bytes.

Когда суммарное потребление памяти запросами на узле превышает spilling_percent процентов от доступного пула, вычислительные операции, поддерживающие спиллинг (Grace Hash Join, агрегации и др.), получают сигнал выгружать промежуточные данные на диск вместо дальнейшего наращивания потребления RAM.

Например, при значении по умолчанию 80 спиллинг активируется, когда пул запросов заполнен примерно на 80%.

Порог применяется к общему пулу памяти запросов на узле (размер — см. query_execution_limit_percent / query_execution_limit_bytes).

Взаимодействие с другими параметрами

spilling_percent определяет, когда пул запросов на узле настолько заполнен, что дальнейший рост в RAM должен уступить место спиллингу. activities_limit_percent ограничивает память активностей в целом и косвенно влияет на доступный объём RAM, но не заменяет пул, относительно которого считается spilling_percent.

Рекомендации

• Уменьшайте spilling_percent (например, до 70), если нужно раньше переводить тяжёлые запросы на диск и снизить риск исчерпания пула памяти;
• Увеличивайте spilling_percent (например, до 90), если дисковый спиллинг слишком часто снижает производительность, а на узле достаточно RAM;
• Согласовывайте spilling_percent с query_execution_limit_percent / query_execution_limit_bytes: при увеличении лимита пула запросов можно поднять порог спиллинга, если на узле достаточно RAM.

spilling_service_config

Спиллинг — это механизм управления памятью в YDB, который временно сохраняет данные на диск при нехватке оперативной памяти.

Включение

Спиллинг включён по умолчанию. Следующий параметр управляет включением и отключением сервиса спиллинга.

local_file_config.enable

Расположение: table_service_config.spilling_service_config.local_file_config.enable
Тип: boolean
По умолчанию: true
Описание: Включает или отключает сервис спиллинга. При отключении (false) спиллинг не функционирует, что может привести к ошибкам при обработке больших объёмов данных.

Возможные ошибки

• Spilling Service not started / Service not started — попытка использования спиллинга при выключенном Spilling Service. См. Spilling Service not started

table_service_config:
  spilling_service_config:
    local_file_config:
      enable: true

Основные параметры конфигурации

table_service_config:
  spilling_service_config:
    local_file_config:
      root: ""
      max_total_size: 21474836480

Конфигурация директории

local_file_config.root

Тип: string
По умолчанию: "" (временная директория)
Описание: Файловая директория для сохранения файлов спиллинга. Директория должна существовать заранее и быть доступна процессу ydbd на чтение и запись: YDB её не создаёт — см. Требования к директории root. Если значение не задано, используется временная директория ОС — см. Директория по умолчанию.

Для каждого процесса ydbd внутри root создается отдельная директория:

spilling-tmp-<node_id>-<spilling_service_id>-<username>

Где:

• node_id — идентификатор узла
• spilling_service_id — уникальный идентификатор экземпляра (GUID), который создаётся при инициализации Spilling Service один раз при запуске процесса ydbd
• username — имя пользователя ОС, под которым запускается процесс ydbd

Файлы спиллинга хранятся внутри каждой такой директории.

Пример полного пути к директории спиллинга:

/tmp/spilling-tmp-1-1144b692-f1e5d361-f3960fe8-f607582e-kikimr

Где:

• /tmp — значение параметра root (или системная временная директория, если root не задан)
• 1 — идентификатор узла
• 1144b692-f1e5d361-f3960fe8-f607582e — идентификатор экземпляра Spilling Service
• kikimr — имя пользователя ОС

Требования к директории root

YDB не создаёт директорию root: она должна существовать до запуска узлов. Создать её заранее должен администратор кластера или система развёртывания. Процесс ydbd создаёт внутри root только свою поддиректорию.

Всем пользователям ОС, под которыми запускаются узлы базы данных, нужен доступ на чтение и запись в root: узел создаёт там свою поддиректорию, пишет в неё файлы спиллинга и читает их. Если статические и динамические узлы запускаются под разными пользователями ОС и используют один и тот же root, права нужны каждому из этих пользователей — например, режим 1777, где sticky-бит не даёт пользователям удалять чужие поддиректории.

Директория по умолчанию

Если root не задан, используется временная директория ОС того процесса ydbd, который запускает узел:

• если в окружении процесса задана переменная TMPDIR — берётся её значение;
• иначе используется /tmp.

Требования, описанные выше, относятся и к этой директории, но обычно /tmp уже существует с режимом 1777 и подходит без дополнительной настройки.

Тем не менее рекомендуется задавать root явно — отдельной директорией и лучше на отдельном диске.

Очистка директорий при старте

Каждый запуск процесса пишет в свою директорию с новым spilling_service_id, а файлы спиллинга нужны только во время работы процесса, поэтому директории прошлых запусков удаляются. Очистка выполняется при старте Spilling Service асинхронно.

Удаляются директории, у которых node_id и username совпадают с текущим процессом, а spilling_service_id отличается от идентификатора текущего запуска. Так после аварийного завершения процесса (например, SIGKILL или отключение питания) место освобождается при следующем старте узла.

Не удаляются:

• сам root — YDB его не создаёт и не удаляет, а только пишет внутрь;
• директории других узлов (spilling-tmp-<other_node_id>-...) — эти узлы могут работать прямо сейчас;
• директории с тем же node_id, но другим username — под этим пользователем ОС может работать другой процесс ydbd;
• любые посторонние файлы и директории внутри root — имя должно полностью соответствовать формату, в том числе содержать spilling_service_id в виде GUID.

Возможные ошибки

• Permission denied — недостаточные права доступа к директории. См. Permission denied

local_file_config.max_total_size

Тип: uint64
По умолчанию: 21474836480 (20 GiB)
Описание: Максимальный суммарный размер всех файлов спиллинга на каждом узле. При превышении лимита операции спиллинга завершаются ошибкой. Общий лимит спиллинга во всем кластере равен сумме значений max_total_size со всех узлов.

Рекомендации

• Устанавливайте значение исходя из доступного дискового пространства

Возможные ошибки

• Total size limit exceeded: X/YMb — превышен максимальный суммарный размер файлов спиллинга. См. Total size limit exceeded

Управление памятью

Связь с memory_controller_config

Активация спиллинга тесно связана с настройками контроллера памяти. Подробная конфигурация memory_controller_config описана в отдельной статье.

Ключевым параметром для спиллинга является activities_limit_percent, который определяет объем памяти, выделяемый для активностей по обработке запросов. От этого параметра зависит доступная память для пользовательских запросов и, соответственно, частота активации спиллинга.

Порог спиллинга в resource_manager

Непосредственный порог, при котором вычислительные операции переключаются на спиллинг, регулируется параметром resource_manager.spilling_percent. Он определяет, при каком заполнении пула памяти Query Processor промежуточные данные запроса начинают выгружаться на диск. Размер пула задаётся в memory_controller_config. Подробнее см. раздел Лимиты памяти выполнения запросов.

Влияние на спиллинг

• При увеличении activities_limit_percent больше памяти доступно для запросов → спиллинг активируется реже
• При уменьшении activities_limit_percent меньше памяти доступно для запросов → спиллинг активируется чаще
• При уменьшении spilling_percent спиллинг включается при меньшем заполнении пула запросов
• При увеличении spilling_percent задачи дольше наращивают потребление RAM, прежде чем перейти к спиллингу

Требования к файловой системе

Файловые дескрипторы

Примеры конфигурации

Высоконагруженная система

Для максимальной производительности в высоконагруженных системах рекомендуется увеличить размер спиллинга:

table_service_config:
  spilling_service_config:
    local_file_config:
      root: ""
      max_total_size: 107374182400   # 100 GiB

Ограниченные ресурсы

Для систем с ограниченными ресурсами рекомендуется использовать консервативные настройки:

table_service_config:
  spilling_service_config:
    local_file_config:
      root: ""
      max_total_size: 5368709120     # 5 GiB

Полный пример

table_service_config:
  spilling_service_config:
    local_file_config:
      enable: true
      root: "/var/spilling"
      max_total_size: 53687091200    # 50 GiB

См. также

• Концепция спиллинга
• Архитектура Spilling Service
• Устранение неполадок спиллинга
• Конфигурация контроллера памяти
• Мониторинг YDB
• Диагностика производительности