> ## 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 OSS, v2 и Platform (бета)

> Состояние ClickHouse adapter в dbt OSS, dbt v2 и на платформе dbt

Поддерживается в ClickHouse

[Бета](https://github.com/ClickHouse/dbt-clickhouse/issues/660)

dbt переписывают на новом движке, и ClickHouse участвует в этом с самого начала. ClickHouse уже работает с новым движком dbt на Rust — как в dbt OSS, так и в dbt v2, — и впервые появилась возможность подключаться к ClickHouse с платформы dbt. Ваш проект при этом не меняется: те же models, тесты и profiles, которые сегодня выполняются на dbt Core 1.x, работают и на новом движке; отличается только бинарный файл.

ClickHouse — первый adapter от сообщества, доступный в dbt OSS, dbt v2 и на платформе dbt. Собственные adapter'ы dbt выходят одновременно с нами; мы первые за пределами dbt Labs. Python-adapter для dbt Core 1.x, `dbt-clickhouse`, никуда не исчезает: мы поддерживаем его в актуальном состоянии вместе с releases dbt 1.x и развиваем оба adapter'а параллельно.

> [!WARNING]
>
> **Не готово к продакшну.** Adapter ClickHouse для dbt OSS и dbt v2, а также подключение с платформы dbt пока не являются generally available (GA). Используйте их только в проектах для разработки или в staging.

> [!NOTE]
>
> **Документация по dbt Core 1.x применима и к dbt OSS, и к dbt v2.** Adapter ведёт себя одинаково на обоих движках: profiles, конфигурации models, материализации и macros, описанные на других страницах о dbt, работают без изменений в dbt OSS, dbt v2 и на платформе dbt. Исключения перечислены в таблице [паритет v1 и v2](#parity) ниже.

> [!NOTE]
>
> **dbt OSS** — это сборка движка v2 с открытым исходным кодом (Apache 2.0). О том, как она соотносится с dbt v2 и платформой dbt, см. [терминология и доступность](#terminology).

Актуальный статус отслеживается в [ClickHouse/dbt-clickhouse#660](https://github.com/ClickHouse/dbt-clickhouse/issues/660) (паритет v2 с v1, по одной подзадаче на каждую область) и [ClickHouse/dbt-clickhouse#555](https://github.com/ClickHouse/dbt-clickhouse/issues/555) (dbt v2).

#### Попробуйте ClickHouse на платформе dbt

Если вы хотите протестировать закрытую бета-версию, зарегистрируйтесь через [форму закрытой беты dbt Labs](https://docs.google.com/forms/d/e/1FAIpQLScjHwRchnKarq_RpNM7hATjphNFxqBEePmAwRtSpMWG1snGHA/viewform). Форма принадлежит dbt Labs, поэтому указанные вами данные поступают в dbt Labs, а не в ClickHouse. После получения доступа настройте соединение, следуя инструкциям из раздела [Connect ClickHouse](https://docs.getdbt.com/docs/platform/connect-data-platform/connect-clickhouse) документации dbt.

## Терминология и доступность

dbt существует в нескольких формах, и один и тот же adapter может работать в нескольких из них. В таблице поясняется каждое название и текущий уровень поддержки ClickHouse.

| Термин | Что это | Статус в ClickHouse и как получить |
| - | - | - |
| **dbt Core 1.x** | Движок dbt на Python, с открытым исходным кодом (Apache 2.0). Наш adapter — `dbt-clickhouse`, он сопровождается в [организации ClickHouse на GitHub](https://github.com/ClickHouse/dbt-clickhouse) и устанавливается вместе с `dbt-core`. | **GA, поддерживается.** Продолжает получать releases параллельно с dbt v2. |
| **dbt OSS** | Полностью переписанный на Rust движок dbt, с открытым исходным кодом (Apache 2.0). Новая версия включает все возможности v1 и ряд улучшений производительности. | **Бета.** Следуйте [руководству по обновлению до dbt v2](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v2) и [странице настройки ClickHouse для v2](https://docs.getdbt.com/docs/local/connect-data-platform/clickhouse-setup?version=2) в документации dbt. Adapter ClickHouse входит в состав бинарного файла dbt; отдельный package устанавливать не нужно. |
| **dbt v2** | dbt OSS плюс дополнительные возможности от dbt Labs: понимание SQL, статический анализ, LSP, extension для VS Code и учёт столбцов. Закрытый исходный код, лицензия — [dbt Product Licensing Agreement](https://www.getdbt.com/dbt-fusion-engine-license-agreement). | **Бета.** Adapter работает с бинарным файлом v2, но новые возможности SQL для ClickHouse пока недоступны. |
| **dbt platform** | Размещённый dbt, ранее dbt Cloud: Studio IDE, запуск jobs по расписанию, окружения, Catalog, Semantic Layer. Платформа работает только на dbt v2, поэтому ClickHouse на платформе — это adapter v2. | **Закрытая бета-версия.** См. [как запросить доступ](#request-access). Настройка: [Connect ClickHouse](https://docs.getdbt.com/docs/platform/connect-data-platform/connect-clickhouse) в документации dbt. |

## Статус бета

Мы проверяем adapter dbt v2 на наборе интеграционных тестов dbt Core 1.x из `dbt-clickhouse`. Статус бета означает, что основные сценарии работы с dbt и набор возможностей ClickHouse Cloud работают в рамках документированных ограничений; полный паритет с v1 и поддержка самоуправляемых кластеров появятся позже.

**На сегодняшний день** adapter проходит более 81% полного набора тестов v1 и 92% тестов, применимых к ClickHouse Cloud. Все материализации достигли паритета (`view`, `table`, `incremental`, `materialized_view`, `dictionary`, `snapshot`, `seed`, `ephemeral`) — вместе с полным набором конфигураций таблиц, контрактов моделей, тестов данных и unit tests, сохранением документации, `clickhouse_s3source()` и настройками соединения dbt Core 1.x. Оставшиеся сбои связаны с перечисленными ниже работами по самоуправляемым кластерам и несколькими различиями на стороне движка. Полную картину по каждой возможности см. в разделе [паритет v1 и v2](#parity).

**Дальнейшие шаги**: DDL с предложением ON CLUSTER и distributed материализации для самоуправляемых кластеров, привилегии, `dbt clone`, `dbt source freshness` на основе metadata таблиц, исправление оставшихся bugs и прохождение полного набора тестов v1 для достижения полного паритета. Прогресс по всем этим направлениям отслеживается в [ClickHouse/dbt-clickhouse#660](https://github.com/ClickHouse/dbt-clickhouse/issues/660), где для каждой области заведён отдельный вложенный issue.

Переход в GA есть в roadmap и состоится в ближайшее время. Мы обновим документацию, как только всё будет готово.

### Не входит в бета-версию

Помимо перечисленных ниже расхождений с v1, ряд возможностей, доступных только в v2, пока не входит в текущий объём работ, но появится в скором времени:

* **Semantic Layer / MetricFlow.** Поддержка ClickHouse ещё не добавлена. Отслеживается в [dbt-labs/metricflow#2124](https://github.com/dbt-labs/metricflow/pull/2124).
* **Интеллектуальная поддержка ClickHouse SQL в dbt v2** (validation с учётом dialect, статический анализ, LSP, распознавание столбцов в extension для VS Code). На сегодняшний день adapter работает с бинарным файлом dbt v2, но эти возможности пока не поддерживает. До тех пор для проектов ClickHouse статический анализ принудительно выставлен в `off`, а движок не записывает происхождение данных на уровне столбца. Отслеживается в [#736](https://github.com/ClickHouse/dbt-clickhouse/issues/736).
* **Дополнительные методы аутентификации** помимо username и password на платформе dbt.

## Сравнение v1 и v2

В таблицах ниже возможности, доступные в `dbt-clickhouse` (v1), сопоставлены с их статусом в адаптере dbt v2. Все перечисленные возможности поддерживаются в v1, если в примечаниях не указано иное; столбец статуса относится к dbt v2 и в равной мере применим к dbt OSS. Ход работы по каждому ещё не реализованному пункту отслеживается в [ClickHouse/dbt-clickhouse#660](https://github.com/ClickHouse/dbt-clickhouse/issues/660).

Поддерживается работает уже сейчас · Частичная поддержка работает с ограничениями · Пока нет ожидает реализации.

### Материализации

| Возможность | Что делает | dbt v2 | Notes |
| - | - | - | - |
| `view` | Стандартное представление dbt. | Поддерживается | |
| `table` | Полная пересборка с настройками движка и DDL. | Поддерживается | |
| `incremental` | Добавление или слияние новых строк. | Поддерживается | |
| `materialized_view` | Материализованное представление ClickHouse, выполняющее преобразование в момент вставки. | Поддерживается | |
| `dictionary` | Словарь ClickHouse для поиска по ключу и JOIN. | Поддерживается | |
| `snapshot` | Медленно меняющиеся измерения типа 2. | Поддерживается | |
| `seed` | Загрузка CSV-файлов в виде таблиц. | Поддерживается | Числовые типы столбцов выводятся как `Int64`/`Float64` вместо `Int32`/`Float32`; чтобы задать их явно, используйте `column_types`. |
| `ephemeral` | Встроенный CTE, объект не создаётся. | Поддерживается | |
| `distributed_table`, `distributed_incremental` | Сегментированные таблицы за движком Distributed. | Пока нет | |

### Конфигурация модели

| Возможность | Назначение | dbt v2 | Notes |
| - | - | - | - |
| Движок, `ORDER BY`, `PARTITION BY`, `PRIMARY KEY` | Основные средства управления DDL для MergeTree. | Поддерживается | |
| TTL | Истечение срока жизни строк и столбцов. | Поддерживается | |
| Настройки таблиц и запросов | `SETTINGS` для отдельной модели в DDL и при вставке. | Поддерживается | |
| Проекции, индексы, `sql_header` | Вторичные структуры и SQL-префикс. | Поддерживается | |
| Контракты и ограничения моделей | Типы столбцов и ограничения, проверяемые при сборке. | Поддерживается | |
| Изменение схемы для инкрементальных моделей | `on_schema_change` добавляет или синхронизирует столбцы. | Поддерживается | |
| `codec` и `ttl` для столбца | Сжатие и истечение срока жизни на уровне отдельного столбца. | Поддерживается | |

### Тестирование и документация

| Возможность | Что делает | dbt v2 | Notes |
| - | - | - | - |
| Тесты данных | Generic- и singular-тесты. | Поддерживается | |
| Unit-тесты | Проверка логики модели на фиксированных входных данных. | Поддерживается | |
| Сохранение документации | Описания записываются в виде комментариев ClickHouse. | Частичная | Описания, содержащие `;`, приводят к ошибке. |
| Формирование каталога и документации | Метаданные столбцов для сайта документации. | Поддерживается | |
| Происхождение данных на уровне столбца | Отслеживание столбцов по всему DAG. | Частичная | Новинка v2, реализована через SQL-компилятор; в v1 недоступна. На платформе dbt происхождение данных отображается только при отключённом заключении идентификаторов в кавычки в `dbt_project.yml`; для происхождения на стороне движка требуется диалект ClickHouse SQL. |

### Кластер и Cloud

| Возможность | Назначение | dbt v2 | Примечания |
| - | - | - | - |
| ClickHouse Cloud | Рекомендуемая бета-конфигурация. | Поддерживается | |
| Согласованность между репликами | `select_sequential_consistency` и связанные настройки чтения после записи. | Поддерживается | |
| Предложение `ON CLUSTER` и реплицируемые движки | Распространение DDL в самоуправляемых кластерах. | Пока нет | Многоузловые кластеры в ClickHouse Cloud поддерживаются. Другие конфигурации, в которых для распространения DDL требуется `ON CLUSTER`, пока не поддерживаются. Для самоуправляемых развертываний тестируйте только на одноузловых кластерах. |
| `EXCHANGE TABLES` | Атомарная подмена при перестроении. | Поддерживается | |
| Пользовательские настройки соединения | `custom_settings` на уровне профиля. | Поддерживается | |
| Версия сервера ClickHouse | Минимальная версия сервера. | Поддерживается | 25.3+ на обоих движках. Для чтения столбцов `UUID` в v2 требуется 26.7+ (более старые серверы не умеют преобразовывать `UUID` в Arrow). |

### Макросы и операции

| Возможность | Назначение | dbt v2 | Примечания |
| - | - | - | - |
| Макрос табличной функции S3 | `clickhouse_s3source()` читает данные напрямую из S3 в модели. | Поддерживается | |
| Межбазовые макросы | Вспомогательные макросы, например из `dbt-utils`. | Поддерживается | |
| Привилегии | Команды `GRANT` из конфигурации модели. | Пока нет | |
| `dbt clone` | `CLONE AS` без копирования данных между окружениями. | Пока нет | |
| Query ID в результатах выполнения | `query_id` в `adapter_response` для сопоставления с `system.query_log`. | Пока нет | |
| `query-comment` | Настройка комментария к запросу. | Пока нет | `query-comment: null` пока не учитывается. |
| Интеграция с каталогом (Iceberg) | Материализация во внешние каталоги. | Пока нет | Отсутствует и в v1; обходные решения описаны в документации. |

### Подключение и аутентификация

| Возможность | Назначение | dbt v2 | Примечания |
| - | - | - | - |
| Protocol | Как dbt взаимодействует с ClickHouse. | Поддерживается | ADBC (Arrow поверх HTTP) в v2; HTTP и native в v1. |
| Имя пользователя и пароль, TLS | Стандартная аутентификация. | Поддерживается | |
| Клиентские сертификаты mTLS | `client_cert`, `client_cert_key`, `verify`. | Пока нет | Требуется доработка драйвера; параметры принимаются, но игнорируются. |
| Параметры HTTP client | `connect_timeout`, `send_receive_timeout`, `sync_request_timeout`, `compress_block_size`, `server_host_name`. | Пока нет | Принимаются, но игнорируются; `server_host_name` недоступен. |
