Distributed-таблица сама не хранит пользовательские строки: она направляет чтение на remote database/table из cluster config. Поэтому неполный результат начинайте с SHOW CREATE TABLE на конкретном initiator, а не с OPTIMIZE или восстановления parts. Одна неверная ссылка способна стабильно исключить shard при полностью исправных local tables.

Успешный SELECT тоже не гарантирует полный охват. Настройка skip_unavailable_shards разрешает ClickHouse молча пропустить недоступные shards. Для диагностического запроса отключите её и сохраните исключение; в рабочем dashboard не меняйте профиль глобально без оценки доступности.

Неполные строки возникают на чтении и на записи

НаблюдениеКакой слой подозреватьЧто сравнить
Direct local SELECT содержит строки, Distributed нетTopology, remote database/table, accessSHOW CREATE и system.clusters
SELECT успешен при недоступном shardSilent skipskip_unavailable_shards и query settings
Результат зависит от initiatorРазный cluster config или DNS cachesystem.clusters на каждом входном узле
Новых строк нет, старые читаютсяОчередь background INSERTsystem.distribution_queue
Один shard всегда пустSharding key или producer пишет напрямую иначеПуть INSERT и распределение ключей

Topology читается с узла, принявшего запрос

SHOW CREATE TABLE analytics.events_all;

SELECT cluster, shard_num, replica_num,
       host_name, host_address, port, is_local
FROM system.clusters
WHERE cluster = 'analytics_cluster'
ORDER BY shard_num, replica_num;

SELECT count() FROM analytics.events_all
SETTINGS skip_unavailable_shards = 0;

Имена замените своими. SHOW CREATE показывает реальные аргументы Distributed(cluster, database, table, sharding_key). system.clusters строится из конфигурации текущего сервера, поэтому выполните запрос на каждом endpoint, куда балансируется клиент. Пароли и полный cluster config в тикет не копируйте.

Replica заменяет replica, но не другой shard

ClickHouse выбирает доступную replica внутри каждого shard. Replicas содержат копии одного набора данных, тогда как shards содержат разные части; для полного чтения нужен хотя бы один доступный replica каждого shard. Добавление replicas в один shard не компенсирует отсутствие другого.

Проверьте remote table отдельно через cluster-aware запрос или прямое подключение с тем же user. Сопоставьте database, table schema и права. Ошибка table missing может оказаться скрытой режимом skip, а имя macro — разворачиваться по-разному на узлах.

Фоновая запись имеет собственную локальную очередь

При asynchronous INSERT в Distributed новые blocks сначала сохраняются на initiator и позже отправляются на shards. system.distribution_queue показывает локальные файлы, is_blocked, error_count, last_exception и объём ожидающих данных. Эта таблица объясняет потерю свежих INSERT, но не неполный SELECT старых данных.

  • Собрать system.distribution_queue на каждом узле, который принимает INSERT.
  • Проверить destination и last_exception, не удаляя queued files вручную.
  • Сопоставить sharding key с реальным распределением ключей по local tables.
  • Отделить очередь Distributed от replication_queue локальной ReplicatedMergeTree.
  • Перед переотправкой убедиться, что повтор блока не нарушит дедупликацию и бизнес-суммы.

Исправление не должно маскировать неполные ответы

Для отчётов, где частичный результат опаснее ошибки, держите skip_unavailable_shards выключенным и алертируйте failure. Если деградированный ответ допустим для observability, явно добавляйте признак неполноты и ограничение числа или доли пропущенных shards, поддерживаемое вашей версией. Молчаливый ноль без provenance обычно хуже временной ошибки.

Контрольное окно подтверждает все shards

  1. Выбрать закрытый временной диапазон и посчитать local rows на каждом shard.
  2. Выполнить Distributed-запрос с тем же фильтром и skip_unavailable_shards=0.
  3. Сверить query_id и query_log по всем replicas, которых коснулся запрос.
  4. Повторить через каждый initiator endpoint и получить одинаковый итог.
  5. Для новой записи дождаться пустой distribution_queue и повторить сверку.

Для расследования нужны SHOW CREATE, обезличенные строки system.clusters и distribution_queue, query_id, версия ClickHouse и локальные counts по shards. Данные таблицы и credentials не нужны. Такой набор показывает, потеряны ли строки, не отправлены или просто не прочитаны текущей topology.

Проверенные источники