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

В этом разделе описаны все материализации, доступные в dbt-clickhouse, включая экспериментальные возможности.

В следующей таблице показаны конфигурации, общие для некоторых доступных материализаций. Подробную информацию об общих конфигурациях моделей dbt см. в документации dbt:

Примечание: для материализованных представлений поддерживаются все движки *MergeTree.

Если при подключении dbt к ClickHouse с использованием одного из указанных выше движков у вас возникают проблемы, сообщите о них здесь.

В ClickHouse есть несколько типов/уровней «настроек». В приведенной выше конфигурации модели можно настраивать два их типа. settings означает предложение SETTINGS, используемое в DDL-операторах типа CREATE TABLE/VIEW, то есть обычно это настройки, специфичные для конкретного движка таблицы ClickHouse. Новый query_settings используется для добавления предложения SETTINGS в запросы INSERT и DELETE, применяемые при материализации модели ( включая инкрементные материализации). Существуют сотни настроек ClickHouse, и не всегда очевидно, какая из них является настройкой таблицы, а какая — настройкой пользователя (хотя последние, как правило, доступны в таблице system.settings.) В целом рекомендуется использовать значения по умолчанию, а к использованию этих свойств следует подходить только после тщательного изучения и тестирования.

ПРИМЕЧАНИЕ: Чтобы использовать указанные ниже параметры конфигурации столбца, необходимо включить контракты моделей.

models:
  - name: table_column_configs
    description: 'Testing column-level configurations'
    config:
      contract:
        enforced: true
    columns:
      - name: ts
        data_type: timestamp
        codec: ZSTD
      - name: x
        data_type: UInt8
        ttl: ts + INTERVAL 1 DAY

dbt автоматически определяет тип данных каждого столбца, анализируя SQL, используемый для создания модели. Однако в некоторых случаях этот процесс может определять тип данных неточно, что приводит к конфликтам с типами, указанными в свойстве data_type контракта. Чтобы избежать этого, мы рекомендуем использовать функцию CAST() в SQL модели, чтобы явно указать нужный тип. Например:

{{
    config(
        materialized="materialized_view",
        engine="AggregatingMergeTree",
        order_by=["event_type"],
    )
}}

select
  -- event_type может быть определён как String, но предпочтительнее использовать LowCardinality(String):
  CAST(event_type, 'LowCardinality(String)') as event_type,
  -- countState() может быть определён как `AggregateFunction(count)`, но может потребоваться изменить тип используемого аргумента:
  CAST(countState(), 'AggregateFunction(count, UInt32)') as response_count, 
  -- maxSimpleState() может быть определён как `SimpleAggregateFunction(max, String)`, но может также потребоваться изменить тип используемого аргумента:
  CAST(maxSimpleState(event_type), 'SimpleAggregateFunction(max, LowCardinality(String))') as max_event_type
from {{ ref('user_events') }}
group by event_type

Модель dbt можно создать как представление ClickHouse и настроить, используя следующий синтаксис:

Файл проекта (dbt_project.yml):

models:
  <resource-path>:
    +materialized: view

Или блок config (models/<model_name>.sql):

{{ config(materialized = "view") }}

Модель dbt можно создать в виде таблицы ClickHouse и настроить, используя следующий синтаксис:

Файл проекта (dbt_project.yml):

models:
  <resource-path>:
    +materialized: table
    +order_by: [ <column-name>, ... ]
    +engine: <engine-type>
    +partition_by: [ <column-name>, ... ]

Или блок config (models/<model_name>.sql):

{{ config(
    materialized = "table",
    engine = "<engine-type>",
    order_by = [ "<column-name>", ... ],
    partition_by = [ "<column-name>", ... ],
      ...
    ]
) }}

Вы можете добавлять индексы пропуска данных к материализациям table, используя конфигурацию indexes:

{{ config(
        materialized='table',
        indexes=[{
          'name': 'your_index_name',
          'definition': 'your_column TYPE minmax GRANULARITY 2'
        }]
) }}

Вы можете добавлять проекции в материализации table и distributed_table с помощью конфигурации projections. Для каждой записи проекции требуется ключ query или index (но не оба).

Примечание: Для distributed таблиц проекция применяется к таблицам _local, а не к прокси-таблице distributed. Примечание: Указание одновременно query и index в одной записи проекции вызывает ошибку на этапе компиляции.

Используйте query, чтобы задать полный запрос проекции:

{{ config(
       materialized='table',
       projections=[
           {
               'name': 'your_projection_name',
               'query': 'SELECT department, avg(age) AS avg_age GROUP BY department'
           }
       ]
) }}

Используйте index как синтаксический сахар для легковесных индексных проекций, использующих виртуальный столбец _part_offset. В качестве ключа сортировки укажите имя одного столбца или список столбцов:

{{ config(
       materialized='table',
       projections=[
           {
               'name': 'proj_by_age',
               'index': 'age'
           }
       ]
) }}

{{ config(
       materialized='table',
       projections=[
           {
               'name': 'proj_by_dept_age',
               'index': ['department', 'age']
           }
       ]
) }}

dbt-clickhouse автоматически генерирует DDL с учётом версии:

Модель типа table будет пересоздаваться при каждом запуске dbt. Это может оказаться непрактичным и чрезвычайно затратным для больших результирующих наборов или сложных преобразований. Чтобы решить эту проблему и сократить время сборки, модель dbt можно создать как инкрементальную таблицу ClickHouse и настроить с помощью следующего синтаксиса:

Определение модели в dbt_project.yml:

models:
  <resource-path>:
    +materialized: incremental
    +order_by: [ <column-name>, ... ]
    +engine: <engine-type>
    +partition_by: [ <column-name>, ... ]
    +unique_key: [ <column-name>, ... ]
    +inserts_only: [ True|False ]

Или блок config в models/<model_name>.sql:

{{ config(
    materialized = "incremental",
    engine = "<engine-type>",
    order_by = [ "<column-name>", ... ],
    partition_by = [ "<column-name>", ... ],
    unique_key = [ "<column-name>", ... ],
    inserts_only = [ True|False ],
      ...
    ]
) }}

Ниже перечислены конфигурации, характерные для этого типа материализации:

dbt-clickhouse поддерживает три стратегии для инкрементальных моделей.

Исторически ClickHouse поддерживал обновления и удаления лишь ограниченно — в виде асинхронных «мутаций». Чтобы эмулировать ожидаемое поведение dbt, dbt-clickhouse по умолчанию создает новую временную таблицу, содержащую все незатронутые (не удаленные и не измененные) «старые» записи, а также все новые или обновленные записи, а затем меняет местами или выполняет EXCHANGE этой временной таблицы с существующим отношением инкрементальной модели. Это единственная стратегия, которая сохраняет исходное отношение, если что-то пойдет не так до завершения операции; однако, поскольку она требует полного копирования исходной таблицы, ее выполнение может быть довольно дорогим и медленным.

Стратегия delete+insert использует легковесное удаление, чтобы удалить затронутые строки, а затем вставить новые. Поскольку она не копирует всю таблицу, её производительность значительно выше, чем у стратегии «legacy». Если в профиле задать use_lw_deletes: true, delete+insert станет инкрементальной стратегией по умолчанию.

При использовании этой стратегии следует учитывать несколько важных ограничений:

• Она работает непосредственно с затронутой таблицей, не создавая промежуточных или временных таблиц, поэтому при возникновении проблемы во время операции данные в инкрементальной модели, скорее всего, окажутся в некорректном состоянии.
• Для неё требуется настройка ClickHouse allow_nondeterministic_mutations. Адаптер автоматически включает её в своих сеансах, когда это возможно. Если включить её нельзя (например, она доступна пользователю dbt только для чтения), поведение зависит от способа выбора стратегии: модели, использующие стратегию по умолчанию, незаметно переключаются на стратегию legacy, модели, в которых явно задана delete+insert или microbatch, завершаются ошибкой во время выполнения, а use_lw_deletes: true в профиле вызывает ошибку при подключении.
• В некоторых крайне редких случаях использование недетерминированных incremental_predicates может привести к состоянию гонки для обновляемых или удаляемых элементов. Чтобы обеспечить согласованные результаты, инкрементальные предикаты должны включать только подзапросы к данным, которые не будут изменяться во время инкрементальной материализации.

Инкрементальная стратегия microbatch доступна в dbt-core начиная с версии 1.9 и предназначена для эффективной обработки масштабных преобразований временных рядов. В dbt-clickhouse она основана на существующей инкрементальной стратегии delete_insert, разбивая инкрементальную обработку на заранее определённые батчи временных рядов на основе конфигураций модели event_time и batch_size.

Помимо обработки масштабных преобразований, Microbatch позволяет:

• Повторно обрабатывать неуспешные батчи.
• Автоматически определять параллельное выполнение батчей.
• Избавиться от необходимости в сложной условной логике при дозагрузке.

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

Эта стратегия заменяет настройку inserts_only в предыдущих версиях dbt-clickhouse. При таком подходе новые строки просто добавляются в существующее отношение. В результате дубликаты строк не удаляются, и временная или промежуточная таблица не используется. Это самый быстрый подход, если дубликаты либо допустимы в данных, либо исключаются предложением WHERE/фильтром в инкрементальном запросе.

[IMPORTANT] В настоящее время стратегия insert_overwrite не полностью поддерживается для распределённых материализаций.

Выполняет следующие шаги:

1. Создаёт staging-таблицу (временную) с той же структурой, что и отношение инкрементальной модели: CREATE TABLE <staging> AS <target>.
2. Выполняет вставку только новых записей (созданных SELECT) в staging-таблицу.
3. Заменяет в целевой таблице только новые партиции (присутствующие в staging-таблице).

У этого подхода есть следующие преимущества:

• Он быстрее стратегии по умолчанию, потому что не копирует таблицу целиком.
• Он безопаснее других стратегий, потому что не изменяет исходную таблицу, пока операция INSERT не завершится успешно: в случае сбоя на промежуточном этапе исходная таблица не изменяется.
• Он реализует лучшую практику data engineering — «неизменяемость партиций». Это упрощает инкрементальную и параллельную обработку данных, откаты и т. д.

Для этой стратегии в config модели должен быть задан partition_by. Все остальные параметры config модели, специфичные для стратегии, игнорируются.

Материализация materialized_view создаёт в ClickHouse materialized view, который служит триггером вставки: он автоматически преобразует и вставляет новые строки из исходной таблицы в целевую таблицу. Это одна из самых мощных материализаций в dbt-clickhouse.

Из-за объёма материала эта материализация вынесена на отдельную страницу. Перейдите к руководству по Materialized Views, чтобы ознакомиться с полной документацией

Модель dbt можно создать в виде словаря ClickHouse. При каждом запуске dbt run словарь заменяется текущим определением модели с помощью CREATE OR REPLACE DICTIONARY.

SQL модели становится запросом к источнику словаря:

{{ config(
       materialized='dictionary',
       fields=[
           ('id', 'UInt64'),
           ('name', 'String'),
       ],
       primary_key='id',
       layout='HASHED()',
       lifetime='MIN 0 MAX 300'
) }}

select id, name from {{ source('raw', 'people') }}

При использовании source_type='http' (или параметра table) источником служит не SQL модели, однако dbt по-прежнему требует тело запроса — используйте в качестве заполнителя select 1:

{{ config(
       materialized='dictionary',
       fields=[
           ('LocationID', 'UInt16 DEFAULT 0'),
           ('Borough', 'String'),
           ('Zone', 'String'),
       ],
       primary_key='LocationID',
       layout='HASHED()',
       lifetime='MIN 0 MAX 0',
       source_type='http',
       url='https://datasets-documentation.s3.eu-west-3.amazonaws.com/nyc-taxi/taxi_zone_lookup.csv',
       format='CSVWithNames'
) }}

select 1

Дополнительные примеры, в том числе словарей с разметкой range и direct, см. в тестах словарей.

distributed таблица создается следующим образом:

1. Создается временное представление с SQL-запросом, чтобы получить нужную структуру
2. Создаются пустые локальные таблицы на основе представления
3. Создается distributed таблица на основе локальных таблиц.
4. Данные вставляются в distributed таблицу и распределяются по сегментам без дублирования.

Примечания:

• Запросы dbt-clickhouse теперь автоматически включают настройку insert_distributed_sync = 1, чтобы последующие операции инкрементальной материализации выполнялись корректно. Из-за этого некоторые вставки в distributed таблицу могут выполняться медленнее, чем ожидалось.

{{
    config(
        materialized='distributed_table',
        order_by='id, created_at',
        sharding_key='cityHash64(id)',
        engine='ReplacingMergeTree'
    )
}}

select id, created_at, item
from {{ source('db', 'table') }}

CREATE TABLE db.table_local on cluster cluster (
    `id` UInt64,
    `created_at` DateTime,
    `item` String
)
    ENGINE = ReplacingMergeTree
    ORDER BY (id, created_at);

CREATE TABLE db.table on cluster cluster (
    `id` UInt64,
    `created_at` DateTime,
    `item` String
)
    ENGINE = Distributed ('cluster', 'db', 'table_local', cityHash64(id));

Ниже перечислены конфигурации, специфичные для этого типа материализации:

Инкрементальная модель, основанная на той же идее, что и distributed таблица; основная сложность заключается в корректной обработке всех инкрементальных стратегий.

1. Стратегия Append просто выполняет вставку данных в distributed таблицу.
2. Стратегия Delete+Insert создает временную distributed таблицу для работы со всеми данными на каждом сегменте.
3. Стратегия Default (Legacy) создает временную и промежуточную distributed таблицы по той же причине.

Заменяются только таблицы сегментов, поскольку distributed таблица не хранит данные. Distributed таблица перезагружается только при включенном режиме full_refresh или если структура таблицы могла измениться.

{{
    config(
        materialized='distributed_incremental',
        engine='MergeTree',
        incremental_strategy='append',
        unique_key='id,created_at'
    )
}}

select id, created_at, item
from {{ source('db', 'table') }}

CREATE TABLE db.table_local on cluster cluster (
    `id` UInt64,
    `created_at` DateTime,
    `item` String
)
    ENGINE = MergeTree;

CREATE TABLE db.table on cluster cluster (
    `id` UInt64,
    `created_at` DateTime,
    `item` String
)
    ENGINE = Distributed ('cluster', 'db', 'table_local', cityHash64(id));

Снимки dbt позволяют отслеживать изменения в изменяемой модели с течением времени. Это, в свою очередь, позволяет выполнять запросы к моделям на определённый момент времени, при которых аналитики могут "заглянуть в прошлое" и увидеть предыдущее состояние модели. Эта функциональность поддерживается коннектором ClickHouse и настраивается с помощью следующего синтаксиса:

Блок config в snapshots/<model_name>.sql:

{{
   config(
     schema = "<schema-name>",
     unique_key = "<column-name>",
     strategy = "<strategy>",
     updated_at = "<updated-at-column-name>",
   )
}}

Чтобы узнать больше о конфигурации, см. справочную страницу по конфигурациям снимков.

Поддерживаются только контракты, в которых типы столбцов должны точно совпадать. Например, контракт с типом столбца UInt32 завершится ошибкой, если модель возвращает UInt64 или другой целочисленный тип. ClickHouse также поддерживает только ограничения CHECK для всей таблицы/модели. Первичный ключ, внешний ключ, уникальные ограничения и ограничения CHECK на уровне столбца не поддерживаются. (См. документацию ClickHouse о первичных ключах и ключах ORDER BY.)