> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> С помощью dbt вы можете преобразовывать данные и создавать модели в ClickHouse
# Интеграция dbt с ClickHouse
export const ClickHouseSupportedBadge = () => {
return
Поддерживается в ClickHouse
;
};
## Адаптер dbt-clickhouse
**dbt** (data build tool) позволяет аналитикам данных преобразовывать данные в своих хранилищах, просто записывая запросы SELECT. dbt материализует эти запросы SELECT в объекты базы данных в виде таблиц и представлений, то есть выполняет T в [Extract Load and Transform (ELT)](https://en.wikipedia.org/wiki/Extract,_load,_transform). Вы можете создать модель, определённую оператором SELECT.
В dbt эти модели можно связывать друг с другом и объединять в слои, что позволяет строить более высокоуровневые сущности. Шаблонный SQL, необходимый для связывания моделей, генерируется автоматически. Кроме того, dbt определяет зависимости между моделями и гарантирует, что они создаются в правильном порядке с помощью ориентированного ациклического графа (DAG).
dbt совместим с ClickHouse через [адаптер с поддержкой ClickHouse](https://github.com/ClickHouse/dbt-clickhouse).
## Связанные страницы
| Страница | Описание |
| ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| [Возможности и конфигурации](/docs/ru/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations) | Описание доступных возможностей и общих настроек |
| [Материализации](/docs/ru/integrations/connectors/data-ingestion/etl-tools/dbt/materializations) | Доступные материализации и их конфигурации |
| [Материализованные представления](/docs/ru/integrations/connectors/data-ingestion/etl-tools/dbt/materialization-materialized-view) | Подробная документация по материализации materialized\_view |
| [Руководства](/docs/ru/integrations/connectors/data-ingestion/etl-tools/dbt/guides) | Руководства по использованию dbt с ClickHouse |
## Поддерживаемые возможности
Список поддерживаемых возможностей:
* [x] Материализация таблиц
* [x] Материализация представлений
* [x] Инкрементальная материализация
* [x] Инкрементальная материализация Microbatch
* [x] Materialized View materializations (использует форму `TO` для MATERIALIZED VIEW, экспериментально)
* [x] Seeds
* [x] Источники
* [x] Генерация документации
* [x] Тесты
* [x] Снимки
* [x] Большинство макросов dbt-utils (теперь входят в dbt-core)
* [x] Эфемерная материализация
* [x] Материализация distributed таблиц (экспериментально)
* [x] Инкрементальная материализация distributed таблиц (экспериментально)
* [x] Контракты
* [x] Специфичные для ClickHouse конфигурации столбцов (кодек, TTL...)
* [x] Специфичные для ClickHouse настройки таблиц (индексы, проекции...)
Поддерживаются все возможности вплоть до dbt-core 1.10, включая флаг `--sample`; также устранены все предупреждения об устаревании для будущих версий. **Интеграции с каталогами** (например, Iceberg), появившиеся в dbt 1.10, пока не поддерживаются адаптером нативно, но доступны обходные решения. Подробности см. в [разделе Catalog Support](/docs/ru/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations#catalog-support).
Этот адаптер по-прежнему недоступен для использования в [dbt Cloud](https://docs.getdbt.com/docs/dbt-cloud/cloud-overview), но мы рассчитываем добавить его в ближайшее время. За дополнительной информацией обратитесь в службу поддержки.
## Концепции dbt и поддерживаемые материализации
dbt вводит понятие модели. Она определяется как SQL-оператор, который может объединять множество таблиц. Модель может быть «материализована» несколькими способами. Материализация представляет собой стратегию сборки для SELECT-запроса модели. Код материализации — это типовой SQL-код, который оборачивает ваш запрос `SELECT` в оператор, чтобы создать новое или обновить существующее отношение.
dbt предоставляет 5 типов материализации. Все они поддерживаются `dbt-clickhouse`:
* **view** (по умолчанию): Модель создаётся как представление в базе данных. В ClickHouse это создаётся как [view](/docs/ru/reference/statements/create/view).
* **table**: Модель создаётся как таблица в базе данных. В ClickHouse это создаётся как [table](/docs/ru/reference/statements/create/table).
* **ephemeral**: Модель не создаётся напрямую в базе данных, а подставляется в зависимые модели как CTE (Common Table Expressions, общие табличные выражения).
* **incremental**: Изначально модель материализуется как таблица, а при последующих запусках dbt выполняет вставку новых строк и обновляет изменённые строки в таблице.
* **materialized view**: Модель создаётся как materialized view в базе данных. В ClickHouse это создаётся как [materialized view](/docs/ru/reference/statements/create/view#materialized-view).
Дополнительные синтаксические конструкции и секции определяют, как эти модели должны обновляться при изменении лежащих в их основе данных. Как правило, dbt рекомендует начинать с материализации view, пока производительность не станет критичной. Материализация table повышает производительность на этапе выполнения запроса, сохраняя результаты запроса модели в виде таблицы, но ценой увеличения объёма хранилища. Подход incremental развивает эту идею дальше, позволяя фиксировать последующие обновления исходных данных в целевой таблице.
[Текущий адаптер](https://github.com/silentsokolov/dbt-clickhouse) для ClickHouse также поддерживает материализации **dictionary**, **distributed table** и **distributed incremental**. Адаптер также поддерживает dbt [снимки](https://docs.getdbt.com/docs/building-a-dbt-project/snapshots#check-strategy) и [seed](https://docs.getdbt.com/docs/building-a-dbt-project/seeds).
Ниже перечислены [экспериментальные возможности](/docs/ru/reference/settings/beta-and-experimental-features) в `dbt-clickhouse`:
| Тип | Поддерживается? | Подробности |
| -------------------------------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Материализация Materialized View | Да. Создание с явной целевой таблицей — бета | Создаёт [materialized view](/docs/ru/reference/statements/create/view#materialized-view). |
| Материализация Distributed table | Да, экспериментальная | Создаёт [distributed таблица](/docs/ru/reference/engines/table-engines/special/distributed). |
| Материализация Distributed incremental | Да, экспериментальная | Инкрементальная модель, основанная на той же идее, что и distributed table. Обратите внимание, что поддерживаются не все стратегии; подробнее см. в [соответствующем разделе документации](/docs/ru/integrations/connectors/data-ingestion/etl-tools/dbt/materializations#materialization-distributed-incremental). |
| Материализация Dictionary | Да, экспериментальная | Создаёт [словарь](/docs/ru/reference/engines/table-engines/special/dictionary). |
## Настройка dbt и адаптера ClickHouse
### Установите dbt-core и dbt-clickhouse
dbt предлагает несколько способов установки интерфейса командной строки (CLI); они подробно описаны [здесь](https://docs.getdbt.com/dbt-cli/install/overview). Мы рекомендуем устанавливать и dbt, и dbt-clickhouse с помощью `pip`.
```sh theme={null}
pip install dbt-core dbt-clickhouse
```
### Укажите в dbt сведения о подключении к нашему экземпляру ClickHouse.
Настройте профиль `clickhouse-service` в файле `~/.dbt/profiles.yml` и задайте свойства `schema`, `host`, `port`, `user` и `password`. Полный список параметров конфигурации подключения доступен на странице [Возможности и конфигурации](/docs/ru/integrations/connectors/data-ingestion/etl-tools/dbt/features-and-configurations):
```yaml theme={null}
clickhouse-service:
target: dev
outputs:
dev:
type: clickhouse
schema: [ default ] # База данных ClickHouse для dbt-моделей
# Необязательно
host: [ localhost ]
port: [ 8123 ] # По умолчанию 8123, 8443, 9000, 9440 в зависимости от настроек secure и driver
user: [ default ] # Пользователь для всех операций с базой данных
password: [ ] # Пароль пользователя
secure: True # Использовать TLS (собственный протокол) или HTTPS (HTTP-протокол)
```
### Создайте проект в dbt
Теперь вы можете использовать этот профиль в одном из существующих проектов или создать новый с помощью:
```sh theme={null}
dbt init project_name
```
В каталоге `project_name` обновите файл `dbt_project.yml`, указав имя профиля для подключения к серверу ClickHouse.
```yaml theme={null}
profile: 'clickhouse-service'
```
### Проверка подключения
Выполните команду `dbt debug` в CLI, чтобы проверить, может ли dbt подключиться к ClickHouse. Убедитесь, что в ответе есть строка `Connection test: [OK connection ok]`, которая указывает на успешное подключение.
Перейдите на [страницу руководств](/docs/ru/integrations/connectors/data-ingestion/etl-tools/dbt/guides), чтобы узнать больше об использовании dbt с ClickHouse.
### Тестирование и развертывание ваших моделей (CI/CD)
Существует множество способов тестирования и развертывания вашего dbt-проекта. dbt предлагает рекомендации по [лучшим практикам организации рабочих процессов](https://docs.getdbt.com/best-practices/best-practice-workflows#pro-tips-for-workflows) и [CI-задачам](https://docs.getdbt.com/docs/deploy/ci-jobs). Мы рассмотрим несколько стратегий, но имейте в виду, что их, возможно, потребуется существенно адаптировать под ваш конкретный сценарий использования.
#### CI/CD с простыми тестами данных и модульными тестами
Один из простых способов быстро запустить CI-конвейер — поднять кластер ClickHouse в рамках задачи, а затем запустить на нём ваши модели. Перед запуском моделей в этот кластер можно вставить тестовые данные. Для заполнения промежуточного окружения частью данных из продакшн-окружения можно просто использовать [seed](https://docs.getdbt.com/reference/commands/seed).
После вставки данных вы можете запустить [тесты данных](https://docs.getdbt.com/docs/build/data-tests) и [модульные тесты](https://docs.getdbt.com/docs/build/unit-tests).
Шаг CD может быть таким же простым, как запуск `dbt build` на продакшн-кластере ClickHouse.
#### Более полный этап CI/CD: используйте свежие данные и тестируйте только затронутые модели
Одна из распространённых стратегий — использовать задачи [Slim CI](https://docs.getdbt.com/best-practices/best-practice-workflows#run-only-modified-models-to-test-changes-slim-ci), при которых повторно развертываются только изменённые модели (и их зависимости выше и ниже по графу). Этот подход использует артефакты из запусков в продакшн (то есть [манифест dbt](https://docs.getdbt.com/reference/artifacts/manifest-json)), чтобы сократить время выполнения проекта и избежать расхождения схем между средами.
Чтобы среды разработки оставались синхронизированными и модели не запускались на устаревших развертываниях, можно использовать [clone](https://docs.getdbt.com/reference/commands/clone) или даже [defer](https://docs.getdbt.com/reference/node-selection/defer).
Мы рекомендуем использовать выделенный кластер или сервис ClickHouse для тестовой среды (то есть staging-среды), чтобы не влиять на работу вашей среды продакшн. Чтобы тестовая среда была репрезентативной, важно использовать подмножество данных из продакшн, а также запускать dbt так, чтобы не допускать расхождения схем между средами.
* Если вам не нужны свежие данные для тестирования, можно восстановить резервную копию данных из продакшн в staging-среду.
* Если вам нужны свежие данные для тестирования, можно использовать сочетание [table function `remoteSecure()`](/docs/ru/reference/functions/table-functions/remote) и refreshable materialized views, чтобы выполнять вставку с нужной частотой. Другой вариант — использовать Объектное хранилище как промежуточное хранилище, периодически записывать в него данные из вашего продакшн-сервиса, а затем импортировать их в staging-среду с помощью table functions для Объектного хранилища или ClickPipes (для непрерывной ингестии).
Использование выделенной среды для CI-тестирования также позволяет проводить ручное тестирование, не затрагивая среду продакшн. Например, для тестирования можно подключить BI-инструмент к этой среде.
Для развертывания (то есть шага CD) мы рекомендуем использовать артефакты из ваших развертываний в продакшн, чтобы обновлять только те модели, которые изменились. Для этого нужно настроить Объектное хранилище (например, S3) как промежуточное хранилище для артефактов dbt. После этого можно запускать команду вида `dbt build --select state:modified+ --state path/to/last/deploy/state.json`, чтобы выборочно пересобирать минимально необходимое количество моделей на основе изменений с момента последнего запуска в продакшн.
## Устранение типичных неполадок
### Подключения
Если у вас возникают проблемы с подключением к ClickHouse из dbt, убедитесь, что выполнены следующие условия:
* Движок должен быть одним из [поддерживаемых движков](/docs/ru/integrations/connectors/data-ingestion/etl-tools/dbt/materializations#supported-table-engines).
* У вас должны быть достаточные разрешения на доступ к базе данных.
* Если вы не используете движок таблицы по умолчанию для базы данных, необходимо указать движок таблицы в конфигурации
модели.
### Понимание длительно выполняющихся операций
Некоторые операции могут занимать больше времени, чем ожидается, из-за отдельных запросов ClickHouse. Чтобы лучше понять, какие запросы выполняются дольше, повысьте [уровень логирования](https://docs.getdbt.com/reference/global-configs/logs#log-level) до `debug` — тогда будет выводиться время выполнения каждого запроса. Например, для этого можно добавить `--log-level debug` к командам dbt.
## Ограничения
У текущего адаптера ClickHouse для dbt есть несколько ограничений, о которых следует знать:
* Плагин использует синтаксис, требующий ClickHouse версии 25.3 или новее. Более старые версии ClickHouse мы не тестируем. Также в настоящее время мы не тестируем таблицы Replicated.
* Разные запуски `dbt-adapter` могут конфликтовать, если выполняются одновременно, поскольку внутри они могут использовать одинаковые имена таблиц для одних и тех же операций. Подробнее см. issue [#420](https://github.com/ClickHouse/dbt-clickhouse/issues/420).
* Сейчас адаптер материализует модели в виде таблиц с использованием [INSERT INTO SELECT](/docs/ru/reference/statements/insert-into#inserting-the-results-of-select). На практике это означает дублирование данных при повторном запуске. Очень большие датасеты (PB) могут приводить к крайне долгому времени выполнения, из-за чего некоторые модели становятся непрактичными. Чтобы повысить производительность, используйте materialized views ClickHouse, реализуя представление как `materialized: materialization_view`. Кроме того, старайтесь по возможности уменьшать количество строк, возвращаемых любым запросом, используя `GROUP BY`. Предпочтительнее модели, которые агрегируют данные, а не просто преобразуют их, сохраняя количество строк источника.
* Чтобы использовать Distributed tables для представления модели, необходимо вручную создать базовые реплицируемые таблицы на каждом узле. Затем поверх них можно создать Distributed таблицу. Адаптер не управляет созданием cluster.
* Когда dbt создает отношение (table/view) в database, оно обычно создается в виде: `{{ database }}.{{ schema }}.{{ table/view id }}`. В ClickHouse нет понятия схем. Поэтому адаптер использует `{{schema}}.{{ table/view id }}`, где `schema` — это database ClickHouse.
* Эфемерные модели/CTE не работают, если размещены перед `INSERT INTO` в операторе вставки ClickHouse, см. [https://github.com/ClickHouse/ClickHouse/issues/30323](https://github.com/ClickHouse/ClickHouse/issues/30323). Это не должно затрагивать большинство моделей, но следует учитывать, где именно эфемерная модель размещается в определениях моделей и других SQL-командах. {/* TODO проверить это ограничение, похоже, issue уже был закрыт, а исправление добавлено в 24.10 */}
## Fivetran
Коннектор `dbt-clickhouse` также можно использовать в [трансформациях Fivetran](https://fivetran.com/docs/transformations/dbt), что обеспечивает бесшовную интеграцию и возможность преобразования данных непосредственно в платформе Fivetran с помощью `dbt`.