# Конфигурации Apache Spark

Если вы используете Databricks, используйте `dbt-databricks`

Если вы используете Databricks, рекомендуется использовать адаптер `dbt-databricks` вместо `dbt-spark`. Если вы все еще используете dbt-spark с Databricks, рассмотрите возможность [миграции с адаптера dbt-spark на адаптер dbt-databricks](https://docs.getdbt.tech/guides/migrate-from-spark-to-databricks.md).

Для версии этой страницы для Databricks обратитесь к разделу [Настройка Databricks](https://docs.getdbt.tech/docs/local/connect-data-platform/databricks-setup.md).

примечание

См. [Конфигурация Databricks](https://docs.getdbt.tech/reference/resource-configs/databricks-configs.md) для версии этой страницы для Databricks.

## Конфигурация таблиц

При материализации модели как `table`, вы можете включить несколько дополнительных конфигураций, специфичных для плагина dbt-spark, в дополнение к стандартным [конфигурациям модели](https://docs.getdbt.tech/reference/model-configs.md).

| Параметр                               | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Обязательный?                 | Пример                                                                                             |
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------- |
| file\_format                           | Формат файла, который будет использоваться при создании таблиц (`parquet`, `delta`, `iceberg`, `hudi`, `csv`, `json`, `text`, `jdbc`, `orc`, `hive` или `libsvm`).                                                                                                                                                                                                                                                                                                                 | Optional                      | `parquet`                                                                                          |
| location\_root [1](#user-content-fn-1) | Создаваемая таблица использует указанный каталог для хранения своих данных. К этому пути будет добавлен алиас таблицы.                                                                                                                                                                                                                                                                                                                                                             | Optional                      | `/mnt/root`                                                                                        |
| partition\_by                          | Разбивает создаваемую таблицу на партиции по указанным столбцам. Для каждой партиции создаётся отдельный каталог.                                                                                                                                                                                                                                                                                                                                                                  | Optional                      | `date_day`                                                                                         |
| clustered\_by                          | Каждая партиция в создаваемой таблице будет дополнительно разбита на фиксированное количество бакетов по указанным столбцам.                                                                                                                                                                                                                                                                                                                                                       | Optional                      | `country_code`                                                                                     |
| buckets                                | Количество бакетов, которые будут созданы при кластеризации.                                                                                                                                                                                                                                                                                                                                                                                                                       | Да, если задан `clustered_by` | `8`                                                                                                |
| tblproperties                          | Свойства таблицы, которые настраивают её поведение. Набор доступных свойств зависит от формата файла, см. справочную документацию ([Iceberg](https://iceberg.apache.org/docs/latest/configuration/#table-properties), [Parquet](https://spark.apache.org/docs/3.5.4/sql-data-sources-parquet.html#data-source-option), [Delta](https://docs.databricks.com/aws/en/delta/table-properties#delta-table-properties), [Hudi](https://hudi.apache.org/docs/sql_ddl/#table-properties)). | Optional                      | `# Iceberg Example
tblproperties:
  read.split.target-size: 268435456
  commit.retry.num-retries: 10` |

## Инкрементальные модели

dbt стремится предложить полезные, интуитивно понятные абстракции моделирования с помощью встроенных конфигураций и материализаций. Поскольку существует так много вариаций между кластерами Apache Spark в мире, не говоря уже о мощных функциях, предлагаемых пользователям Databricks форматом файлов Delta и пользовательским временем выполнения, понимание всех доступных опций само по себе является задачей.

В качестве альтернативы, вы можете использовать формат файлов Apache Iceberg или Apache Hudi с временем выполнения Apache Spark для построения инкрементальных моделей.

По этой причине плагин dbt-spark сильно полагается на конфигурацию [`incremental_strategy`](https://docs.getdbt.tech/docs/build/incremental-strategy.md). Эта конфигурация указывает, как инкрементальная материализация должна строить модели в запусках после первого. Она может быть установлена на одно из трех значений:

* **`append`** (по умолчанию): Вставка новых записей без обновления или перезаписи существующих данных.
* **`insert_overwrite`**: Если указано `partition_by`, перезаписать разделы в таблица новыми данными. Если `partition_by` не указано, перезаписать всю таблицу новыми данными.
* **`merge`** (только для форматов файлов Delta, Iceberg и Hudi): Сопоставление записей на основе `unique_key`; обновление старых записей, вставка новых. (Если `unique_key` не указан, все новые данные вставляются, аналогично `append`.)
* `microbatch` Реализует [стратегию микропакетов](https://docs.getdbt.tech/docs/build/incremental-microbatch.md) с использованием `event_time` для определения временных диапазонов для фильтрации данных.

Каждая из этих стратегий имеет свои плюсы и минусы, которые мы обсудим ниже. Как и в случае любой конфигурации модели, `incremental_strategy` может быть указан в `dbt_project.yml` или в блоке `config()` файла модели.

### Стратегия `append`

Следуя стратегии `append`, dbt выполнит оператор `insert into` со всеми новыми данными. Привлекательность этой стратегии заключается в ее простоте и функциональности на всех платформах, типах файлов, методах подключения и версиях Apache Spark. Однако эта стратегия *не может* обновлять, перезаписывать или удалять существующие данные, поэтому она, вероятно, будет вставлять дублирующиеся записи для многих источников данных.

Указание `append` в качестве инкрементальной стратегии является необязательным, так как это стратегия по умолчанию, используемая, когда ничего не указано.

### Исходный код

spark\_incremental.sql

```sql
{{ config(
    materialized='incremental',
    incremental_strategy='append',
) }}

--  Все строки, возвращаемые этим запросом, будут добавлены к существующей таблице

select * from {{ ref('events') }}
{% if is_incremental() %}
  where event_ts > (select max(event_ts) from {{ this }})
{% endif %}
```

### Код выполнения

spark\_incremental.sql

```sql
create temporary view spark_incremental__dbt_tmp as

    select * from analytics.events

    where event_ts >= (select max(event_ts) from {{ this }})

;

insert into table analytics.spark_incremental
    select `date_day`, `users` from spark_incremental__dbt_tmp
```

### Стратегия `insert_overwrite`

Эта стратегия наиболее эффективна, когда она указана вместе с параметром `partition_by` в конфигурации модели. dbt выполнит [атомарный оператор `insert overwrite`](https://downloads.apache.org/spark/docs/3.0.0/sql-ref-syntax-dml-insert-overwrite-table.html), который динамически заменяет все партиции, попавшие в ваш запрос. При использовании этой инкрементальной стратегии обязательно повторно выбирайте (*re-select*) **все** релевантные данные для каждой партиции.

Если `partition_by` не указано, то стратегия `insert_overwrite` атомарно заменит все содержимое таблицы, перезаписывая все существующие данные только новыми записями. Однако схема столбцов таблицы остается прежней. Это может быть желательным в некоторых ограниченных обстоятельствах, так как это минимизирует время простоя при перезаписи содержимого таблицы. Операция сопоставима с выполнением `truncate` + `insert` в других базах данных. Для атомарной замены таблиц в формате Delta используйте материализацию `table` (которая выполняет `create or replace`) вместо этого.

**Примечания по использованию:**

* Эта стратегия не поддерживается для таблиц с `file_format: delta`.
* Эта стратегия недоступна при подключении через SQL-эндпоинты Databricks (`method: odbc` + `endpoint`).
* Если вы подключаетесь через кластер Databricks + драйвер ODBC (`method: odbc` + `cluster`), вы **должны** включить `set spark.sql.sources.partitionOverwriteMode DYNAMIC` в [конфигурации Spark кластера](https://docs.databricks.com/clusters/configure.html#spark-config), чтобы динамическая замена разделов работала (`incremental_strategy: insert_overwrite` + `partition_by`).

[![Кластер Databricks: Конфигурация Spark](/img/reference/databricks-cluster-sparkconfig-partition-overwrite.png?v=2 "Кластер Databricks: Конфигурация Spark")](#)Кластер Databricks: Конфигурация Spark

### Исходный код

spark\_incremental.sql

```sql
{{ config(
    materialized='incremental',
    partition_by=['date_day'],
    file_format='parquet',
    incremental_strategy='insert_overwrite'
) }}

/*
  Каждый раздел, возвращаемый этим запросом, будет перезаписан
  при выполнении этой модели
*/

with new_events as (

    select * from {{ ref('events') }}

    {% if is_incremental() %}
    where date_day >= date_add(current_date, -1)
    {% endif %}

)

select
    date_day,
    count(*) as users

from events
group by 1
```

### Код выполнения

spark\_incremental.sql

```sql
create temporary view spark_incremental__dbt_tmp as

    with new_events as (

        select * from analytics.events


        where date_day >= date_add(current_date, -1)


    )

    select
        date_day,
        count(*) as users

    from events
    group by 1

;

insert overwrite table analytics.spark_incremental
    partition (date_day)
    select `date_day`, `users` from spark_incremental__dbt_tmp
```

### Стратегия `merge`

**Примечания по использованию:** Инкрементальная стратегия `merge` требует:

* `file_format: delta, iceberg или hudi`
* Databricks Runtime 5.1 и выше для формата файлов delta
* Apache Spark для формата файлов Iceberg или Hudi

dbt выполнит [атомарный оператор `merge`](https://docs.databricks.com/spark/latest/spark-sql/language-manual/merge-into.html), который выглядит почти идентично поведению слияния по умолчанию в Snowflake и BigQuery. Если указан `unique_key` (рекомендуется), dbt обновит старые записи значениями из новых записей, которые совпадают по ключевому столбцу. Если `unique_key` не указан, dbt откажется от критериев совпадения и просто вставит все новые записи (аналогично стратегии `append`).

### Исходный код

merge\_incremental.sql

```sql
{{ config(
    materialized='incremental',
    file_format='delta', # или 'iceberg' или 'hudi'
    unique_key='user_id',
    incremental_strategy='merge'
) }}

with new_events as (

    select * from {{ ref('events') }}

    {% if is_incremental() %}
    where date_day >= date_add(current_date, -1)
    {% endif %}

)

select
    user_id,
    max(date_day) as last_seen

from events
group by 1
```

### Код выполнения

target/run/merge\_incremental.sql

```sql
create temporary view merge_incremental__dbt_tmp as

    with new_events as (

        select * from analytics.events


        where date_day >= date_add(current_date, -1)


    )

    select
        user_id,
        max(date_day) as last_seen

    from events
    group by 1

;

merge into analytics.merge_incremental as DBT_INTERNAL_DEST
    using merge_incremental__dbt_tmp as DBT_INTERNAL_SOURCE
    on DBT_INTERNAL_SOURCE.user_id = DBT_INTERNAL_DEST.user_id
    when matched then update set *
    when not matched then insert *
```

## Сохранение описаний моделей

В dbt поддерживается сохранение документации на уровне relation.<br />Подробнее о настройке сохранения документации см. [документацию](https://docs.getdbt.tech/reference/resource-configs/persist_docs.md).

Когда опция `persist_docs` настроена должным образом, вы сможете увидеть описания моделей в поле `Comment` команды `describe [table] extended` или `show table extended in [database] like '*'`.

## Всегда `schema`, никогда `database`

Apache Spark использует термины "schema" и "database" взаимозаменяемо. dbt понимает `database` как существующий на более высоком уровне, чем `schema`. Таким образом, вы *никогда* не должны использовать или устанавливать `database` в качестве конфигурации узла или в целевом профиле при запуске dbt-spark.

Если вы хотите управлять схемой/базой данных, в которой dbt будет материализовать модели, используйте конфигурацию `schema` и макрос `generate_schema_name` *только*.

## Конфигурации формата файлов по умолчанию

Чтобы получить доступ к расширенным функциям инкрементальных стратегий, таким как [снимки](https://docs.getdbt.tech/docs/build/snapshots.md) и инкрементальная стратегия `merge`, вы захотите использовать формат файлов Delta, Iceberg или Hudi в качестве формата файлов по умолчанию при материализации моделей как таблиц.

Это довольно удобно сделать, установив конфигурацию верхнего уровня в вашем файле проекта:

dbt\_project.yml

```yml
models:
  +file_format: delta # или iceberg или hudi
  
seeds:
  +file_format: delta # или iceberg или hudi
  
snapshots:
  +file_format: delta # или iceberg или hudi
```

(Версии dbt: v1.11 и новее)

## Обработка повторных попыток для подключений PyHive

При использовании методов подключения HTTP или Thrift вы можете настроить, как dbt обрабатывает опрос состояния, тайм-ауты и повторные попытки подключения для длительно выполняющихся запросов. Эти настройки помогают предотвратить зависание запросов на неопределённое время и автоматически восстанавливаться после разрывов соединения во время выполнения запроса.

Доступны три конфигурации профиля:

| Параметр        | Тип     | По умолчанию | Описание                                                                                                                                                                               |
| --------------- | ------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `poll_interval` | Integer | 5            | Как часто (в секундах) адаптер опрашивает Thrift-сервер, чтобы проверить, завершился ли асинхронный запрос.                                                                            |
| `query_timeout` | Integer | None         | Максимальная продолжительность выполнения запроса (в секундах). Если во время опроса запрос превышает это значение, dbt выбрасывает `DbtRuntimeError`. По умолчанию тайм-аут не задан. |
| `query_retries` | Integer | 1            | Сколько раз адаптер повторяет попытку при потере соединения во время выполнения запроса.                                                                                               |

Адаптер перехватывает определённые исключения соединения (такие как `ConnectionResetError`, `BrokenPipeError` и `TTransportException`) и выполняет повторную попытку с новым курсором при потере соединения. После исчерпания всех попыток dbt выбрасывает `DbtRuntimeError` и предлагает увеличить значение `query_retries` в вашем профиле.

## Footnotes

1. Если вы настраиваете `location_root`, dbt указывает путь размещения в выражении `create table`. Это изменяет тип таблицы с «managed» на «external» в Spark/Databricks. [↩](#user-content-fnref-1)
