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, access | SHOW CREATE и system.clusters |
| SELECT успешен при недоступном shard | Silent skip | skip_unavailable_shards и query settings |
| Результат зависит от initiator | Разный cluster config или DNS cache | system.clusters на каждом входном узле |
| Новых строк нет, старые читаются | Очередь background INSERT | system.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
- Выбрать закрытый временной диапазон и посчитать local rows на каждом shard.
- Выполнить Distributed-запрос с тем же фильтром и skip_unavailable_shards=0.
- Сверить query_id и query_log по всем replicas, которых коснулся запрос.
- Повторить через каждый initiator endpoint и получить одинаковый итог.
- Для новой записи дождаться пустой distribution_queue и повторить сверку.
Для расследования нужны SHOW CREATE, обезличенные строки system.clusters и distribution_queue, query_id, версия ClickHouse и локальные counts по shards. Данные таблицы и credentials не нужны. Такой набор показывает, потеряны ли строки, не отправлены или просто не прочитаны текущей topology.