borislav/clickhouse

ClickHouse implementation for PHP projects

1.0.0 2022-10-10 09:46 UTC

Requires

• ramsey/uuid-doctrine: ^1.8
• smi2/phpclickhouse: ^1.4
• symfony/serializer: *

MIT

• Boris

README

1. Сущность/Entity

   1. Каждая сущность = отдельная таблица

   2. Название сущности = inTheLowerCase(название таблицы)

   3. Название свойств сущности = название столбцов

   4. Каждая сущность, которая работает через ClickHouse, должна имплементировать интерфейс ClickHouseEntityInterface (необходимо для нормализации и денормализации).

2. Репозиторий/Repository

   1. Каждый репозиторий должен наследоваться от ClickHouseRepository (является базовым репозиторием и имеет дефолтный функционал) и интерфейс репозитория, аналогично, должен быть унаследован от ClickHouseRepositoryInterface.
   2. (Perhaps) Конструктор базового/абстрактного репозитория принимает 3 аргумента: normalizer, denormalizer, entityClass. Если в процессе работы возникают ошибки при записи, возможно, вам стоит изменить формат данных или же проверить, как ваша сущность выглядит в нормализованном виде и правильно ли она маппится на таблицу. При необходимости, смотреть в ClickHouseEntityNormalizer.

3. Клиент/Adapter

   1. Паттер адаптер, который закрывает взаимодствеие с ClickHouse через интерфейс с методами select, insert, query и ping. Реализует прямой доступ к HTTP интерфейсу ClickHouse.

   2. !!!Важно: в коде, мы должны везде закрываться не реализацией, т.е. типом самого класса адаптера, а его интерфейсом, для возможности подмены реализации.

   3. !!!Важно: в частности, ClickHouseClientAdapter реализует метод query, который третьим аргументом(isAwaitableQuery) принимает логическое значение и если оно истинно, то добавляет в запрос уникальный ключ и возвращает как результат инстас ClickHouseSyncResponse (подробнее о Response|SyncResponse в следующем пункте #4).

4. Ответ/Response

   Из любого метода адаптера, кроме метода ping мы получаем экземпляр класса ClickHouseResponse или же ClickHouseSyncResponse.

   1. ClickHouseSyncResponse - обертка для класса Statement, реализующая дополнительный функционал по ожиданию запросов (ALTER TABLE t DELETE|UPDATE - в ClickHouse выполняются в background-e, т.е. операция полностью не завершена, но ответ уже пришел). Данный класс позволяет вам с помощью методов await и isDone явно дождаться ответа и фиксации данных.
      1. await - ожидает, пока запрос не завершится, залипает в цикле, максимум на 10 минут (конфигурируется через параметр).
      2. isDone - единоразовая проверка без залипания, полезно, если ждем фиксацию + выполняем какую-то доп. обработку или т.п..
   2. ClickHouseResponse - простая обертка для ответа из ClickHouse, является родителем для ClickHouseSyncResponse (советуется использовать метод isSyncable для определения, является ли экземляр сихронизируемым). Простой proxy-класс скрывающий реализацию.

5. Примесь/Trait

   1. ClickHouseClientTrait - единственный функционал, который позволяет получить вышеописанный Adapter для работы с ClickHouse.

   2. Требования для использования trait-a:

      1. Класс, в котором подключается trait, должен имплементировать интерфейс ClickHouseClientTraitInterface, либо же вы получите соответствующее исклчюение.

6. Миграция/Migration

   1. Должна имплементировать ClickHouseMigrationInterface и использовать вышеописанный trait явно ($this->clickhouse()->(select|insert|query|ping)(...);).

7. Тест/Test

   1. Если тест нуждается/взаимодействует с ClickHouse, то данный тест нужно унаследовать от ClickHouseSetUpTestCase, далее, использовать по усмотрению, явно через trait или же через репозиторий, который можно получить черзе EntityManager в любом тесте.

   2. !!!Важно: если вы переопределяете методы setUp или tearDown, нужно вызвать родительский метод (parent::(tearDown|setUp)();), либо явно очистить таблицы в тестовой БД в ClickHouse ($this->clearTables();). !!!Важно: очистка таблиц не произойдет и будет выброшено исключение, если вы пытаетесь использовать этот метод не в тестовой среде.

   3. На данный момент для сущностей, которые работают с ClickHouse нельзя создать фикстуры (в дальнейшем, возможно, этот функционал будет реализован). Загрузку данных, можно реализовать явно, создав отдельный метод в тесте.

8. Исключение/Exception

   1. Все исключения, которые возникают при работе с ClickHouse, имплементируют ClickHouseExceptionInterface и наследуются от ClickHouseException. Соответственно, могут быть перехвачены базовым интефейсом \Throwable.

9. Запрос/Request (only syncable)

   1. В данном кейсе нужно отметить, что если вы попытаетесь отправить запрос типа Sync, т.е. указав isAwaitableQuery параметр в значение true и в переданом SQL-e не будет условия WHERE, то получите соотвествующее исклчюение и том, что запросы данного вида не разрешены. Вы должны всегда явно указывать WHERE {condition} для запросов типа Sync.