Тестирование вашей интеграции с ClickHouse

Проверьте свою интеграцию в обоих режимах развертывания ClickHouse и на датасетах, которые задействуют систему типов ClickHouse в реалистичном масштабе, прежде чем отправлять её на проверку. Эта страница определяет, что значит «протестировано» на базовом уровне. Формальная валидация — отдельный процесс для партнёров, переходящих на более высокие партнёрские уровни.

См. Создание интеграций, чтобы узнать о путях ингестии и использования, а Документирование вашей интеграции — чтобы понять, как публиковать результаты.

Проверьте оба режима развертывания. Большинство клиентов используют либо один, либо другой, и в некоторых случаях поведение различается (аутентификация, сеть, доступные возможности).

• ClickHouse Cloud: зарегистрируйтесь для бесплатного пробного периода. Для уровня Development кредитная карта не требуется
• Самоуправляемый (с открытым исходным кодом): используйте последний стабильный релиз из GitHub releases. Руководство по установке — самый быстрый способ развернуть локальный экземпляр с помощью Docker

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

Функциональная корректность. Проверьте все сценарии, которые поддерживает ваша интеграция: ингестию, выполнение запросов, обнаружение схемы, обработку ошибок и повторное подключение. Если ваш продукт предоставляет конечным пользователям доступ к SQL, убедитесь, что запросы, которые генерирует интерфейс, корректно проходят полный цикл.

Покрытие системы типов. ClickHouse поддерживает Array, Tuple, Map, JSON, Nested, LowCardinality, Decimal, варианты Date и DateTime, UUID, IPv4 и IPv6, Enum, а также типы агрегатных функций. Интеграции часто сталкиваются с проблемами при работе с вложенными массивами, глубоко вложенными кортежами и JSON-столбцами. Ваша клиентская библиотека и интерфейс должны корректно обрабатывать такие случаи и как минимум выдавать понятную ошибку, а не молча обрезать данные или отображать их некорректно.

Масштаб. Тестируйте на таких размерах результирующих наборов и таком числе строк, с которыми будут работать ваши клиенты. Для пользовательских BI-интерфейсов это часто означает таблицы от сотен миллионов до миллиардов строк, а также результирующие наборы — от отдельных агрегатов до десятков тысяч строк. Неограниченные чтения (SELECT *) должны предсказуемо завершаться ошибкой или использовать пагинацию, а не зависать.

Аутентификация. Проверьте как минимум одно соединение с включенным TLS. Если вы предоставляете конфигурацию аутентификации, протестируйте каждый описанный вами режим (имя пользователя и пароль поверх TLS, mTLS, клиентский SSL-сертификат).

Жизненный цикл соединения. Убедитесь, что система адекватно ведет себя при разрыве соединений, перезапуске сервера и медленных запросах. Многие эскалации связаны с обработкой соединений, а не с семантикой запросов.

Полный список доступен в разделе Демонстрационные наборы данных. Следующие четыре датасета покрывают большинство сценариев тестирования интеграций:

• GitHub events: 3.1B строк со вложенными полезными нагрузками событий. Лучше всего подходит для массивов, кортежей и вложенных типов
• NYC taxi data: миллиарды строк с хорошо известной схемой. Подходит для тестирования пропускной способности и операций чтения
• Stack Overflow: реляционные данные из нескольких таблиц для BI-сценариев с активным использованием JOIN
• Hacker News: 28M строк, быстро загружается, удобен для итеративной работы

Для валидации в экстремальном масштабе используйте WikiStat (~0.5 триллиона записей).

Когда вы отправляете интеграцию на проверку, укажите:

• протестированные версии ClickHouse (Cloud и с открытым исходным кодом)
• датасеты и их примерный масштаб (число строк, размер на диске)
• типы, с которыми работает ваша интеграция, и типы, с которыми она не работает (это станет разделом Known limits в вашей документации)
• особенности производительности, о которых стоит предупредить, например пороговые значения результирующего набора, при которых поведение меняется

Короткий отчёт о тестировании сокращает число итераций проверки. Достаточно одного абзаца и таблицы.