# Изменения в поведении адаптера Databricks

Ниже приведены текущие [флаги изменения поведения](https://docs.getdbt.tech/reference/global-configs/behavior-changes.md#behavior-change-flags), которые специфичны для `dbt-databricks`:

| Флаг                                                                                        | `dbt-databricks`: Intro | `dbt-databricks`: Maturity | Статус                                   |
| ------------------------------------------------------------------------------------------- | ----------------------- | -------------------------- | ---------------------------------------- |
| [`use_info_schema_for_columns`](#use-information-schema-for-columns)                        | 1.9.0                   | Неприменимо                | **Удалён в 1.11.0**                      |
| [`use_user_folder_for_python`](#use-users-folder-for-python-model-notebooks)                | 1.9.0                   | 1.11.0                     | Значение по умолчанию изменено на `true` |
| [`use_materialization_v2`](#use-restructured-materializations)                              | 1.10.0                  | Пока не определено         | Активен                                  |
| [`use_managed_iceberg`](#use-managed-iceberg)                                               | 1.11.0                  | 1.12.0                     | Активен                                  |
| [`use_replace_on_for_insert_overwrite`](#use-replace-on-for-insert_overwrite-strategy)      | 1.11.0                  | 1.12.0                     | Активен, значение по умолчанию — `true`  |
| [`use_describe_as_json_for_relation_metadata`](#use-describe-as-json-for-relation-metadata) | 1.12.0                  | Пока не определено         | Активен, значение по умолчанию — `false` |

## Используйте information schema для столбцов

Удалён в v1.11.0

Флаг `use_info_schema_for_columns` был **удалён**, начиная с dbt-databricks v1.11.0. Адаптер теперь использует [`DESCRIBE EXTENDED ... AS JSON`](https://docs.databricks.com/aws/en/sql/language-manual/sql-ref-syntax-aux-describe-table) (доступно в DBR 16.2+) для эффективного получения информации о сложных типах данных, что устраняет необходимость в этом флаге.

Если вы всё ещё используете этот флаг в конфигурации проекта, его можно безопасно удалить. Новый подход обеспечивает лучшую производительность и не требует выполнения операций `REPAIR TABLE`, которые были необходимы при использовании `information_schema`.

### Документация для предыдущих версий

*Применяется к dbt-databricks версии v1.11 и более ранних версий* В версиях 1.9 и 1.10 флаг `use_info_schema_for_columns` по умолчанию имел значение `false`.

При установке этого флага в `true` для получения метаданных столбцов таблиц Unity Catalog использовалась `information_schema` вместо `describe extended`. Эта настройка помогала избежать проблем, связанных с тем, что `describe extended` обрезает информацию, когда тип данных — сложная структура (struct).

При установке этого флага в `True` для получения метаданных колонок таблиц Unity Catalog использовался `information_schema`, а не `describe extended`. Это помогало обходить проблемы, при которых `describe extended` усекал информацию, если тип данных представлял собой сложную структуру (`struct`).

Для сложных типов

Если сложный тип получен в результате обработки JSON с помощью `from_json`, есть альтернативный вариант: использовать [`parse_json` для создания колонки типа `variant`](https://docs.databricks.com/aws/en/sql/language-manual/functions/parse_json). Тип `variant` может быть разумной альтернативой с точки зрения производительности и при этом позволяет избежать проблем с усечением типов.

## Используйте папку пользователя для блокнотов моделей Python

Значение по умолчанию изменено в v1.11.0

Начиная с dbt-databricks v1.11.0, флаг `use_user_folder_for_python` по умолчанию имеет значение **`true`**.

Флаг `use_user_folder_for_python` определяет, где в Databricks хранятся загруженные ноутбуки Python-моделей:

* **`true` (по умолчанию в v1.11+)**: Ноутбуки записываются в `/Users/{{current user}}/{{catalog}}/{{schema}}/`.
* **`false` (по умолчанию в v1.9-v1.10)**: Ноутбуки записываются в `/Shared/dbt_python_models/{{schema}}/`.

Databricks признал запись в папку `Shared` устаревшей, так как она не соответствует лучшим практикам управления и безопасности. Использование пользовательских папок обеспечивает лучшую изоляцию, контроль доступа и соответствует модели безопасности Unity Catalog.

Чтобы сохранить прежнее поведение для обратной совместимости, можно явно установить для этого флага значение `false` в файле `dbt_project.yml`:

```yaml
flags:
  use_user_folder_for_python: false
```

## Используйте реструктурированные материализации

Флаг `use_materialization_v2` по умолчанию имеет значение `false` и управляет включением существенно переработанных основных материализаций в `dbt-databricks`, пока они находятся на экспериментальной стадии.

При значении `true` адаптер `dbt-databricks` использует обновлённую логику для всех типов моделей (представлений, таблиц, инкрементальных моделей и seed-данных). Также становятся доступны дополнительные необязательные параметры конфигурации для более тонкой настройки:

* `view_update_via_alter` — Если этот параметр включён, адаптер пытается обновить представление на месте с помощью alter view, а не заменить его с помощью create or replace.
* `use_safer_relation_operation` — Если этот параметр включён (а `view_update_via_alter` не задан), обновление моделей dbt становится безопаснее: объекты базы данных предварительно подготавливаются, а затем переименовываются, чтобы сбои не нарушали работу текущей версии таблицы или представления.

Эти параметры не обязательны для получения основных преимуществ данного флага — таких как улучшенная производительность и поддержка колонок и ограничений, — однако они находятся за флагом, поскольку вносят более существенные изменения в поведение materialization.

В версии v1.11.0 этот флаг по умолчанию останется установленным в `false`. Учитывая отзывы об отсутствии атомарности (обновлений по принципу «всё или ничего») в новой материализации, мы не будем включать его автоматически. Мы изучим другие способы получить те же преимущества без потери атомарности. Учитывая отзывы об отсутствии атомарности в новом подходе к материализации, мы не будем переключать этот флаг на `true`. Вместо этого мы будем исследовать новые способы получить те же преимущества, сохранив атомарность.

### Изменения в materialization Seed

Materialization для seeds должна иметь минимальные отличия между старой и новой реализациями, так как основное изменение заключается в удалении вызовов методов, которые не поддерживаются Databricks, например операций с транзакциями.

### Изменения в materialization View

Если флаг `use_materialization_v2` установлен в `true`, доступны два параметра конфигурации модели, которые позволяют настроить обработку материализации в виде представления при обнаружении существующего отношения в целевом расположении.

* `view_update_via_alter` — обновляет view «на месте» с помощью `alter view`, вместо использования `create or replace`. Это позволяет сохранить историю view, метаданные и улучшает совместимость с Unity Catalog. Пример конфигурации:

schema.yml

```yaml
models:
  - name: market_summary
    config:
      materialized: view
      view_update_via_alter: true
    
    columns:
      - name: country
        data_tests:
          - unique
          - not_null
...
```

В настоящее время Databricks SQL не поддерживает изменение комментария view с помощью alter.

Поэтому при изменении описания view его необходимо пересоздавать.

* `use_safer_relation_operations` — при включении (и если не задан `view_update_via_alter`) этот параметр делает обновления моделей более безопасными за счёт создания новой relation во временном месте, её замены на существующую и последующего удаления старой relation. Пример конфигурации:

schema.yml

```yaml
models:
  - name: market_summary
    config:
      materialized: view
      use_safer_relation_operations: true
    
    columns:
      - name: country
        data_tests:
          - unique
          - not_null
...
```

Этот параметр конфигурации может увеличить затраты и повлиять на историю Unity Catalog.

Хотя этот подход эквивалентен стандартной materialization view в dbt, он создаёт больше объектов UC по сравнению с альтернативами. Так как в этой конфигурации не используется атомарный `create or replace...`, история объекта в Unity Catalog может вести себя не так, как вы ожидаете. Тщательно взвесьте необходимость использования этой настройки в широком масштабе.

### Изменения в materialization Table

Этот флаг может увеличить затраты на хранение таблиц.

Как и в случае с view, эти изменения materialization могут привести к росту затрат. Используется больше временных объектов, что соответствует materialization в других адаптерах dbt. Мы считаем эти изменения экспериментальными, в том числе потому, что у нас недостаточно данных для точной оценки влияния на стоимость. При этом преимущества заключаются в улучшении производительности, безопасности и возможности реализовать функции, которые невозможно добавить в текущей materialization.

Когда `use_materialization_v2` установлен в `true`, обновляются все пути выполнения материализаций. Ключевое изменение заключается в том, что создание таблицы отделено от вставки строк в неё. Такое разделение значительно повышает производительность при добавлении комментариев к таблицам, поскольку добавлять комментарии при создании таблицы быстрее, чем с помощью отдельных операторов `alter table`. Оно также устраняет проблемы совместимости в Databricks, где создание таблицы и вставка данных за один шаг не позволяют задавать комментарии.

Кроме того, это изменение позволяет поддерживать другие возможности на уровне колонок — например, column-level masks — которые несовместимы со вставкой данных во время создания таблицы. Хотя эти функции не включены в версию 1.10.0, теперь их можно добавить в будущих релизах.

#### Constraints

В течение нескольких релизов dbt-databricks поддерживал как реализацию [constraints](https://docs.getdbt.tech/reference/resource-properties/constraints.md) в dbt, так и собственную, более раннюю альтернативу под названием `persist_constraints`. С флагом `use_materialization_v2` мы начинаем постепенно выводить `persist_constraints` из использования и полностью переходим на нативную поддержку ограничений в dbt.

Одним из новых улучшений стала поддержка поля `expression` для первичных и внешних ключей. Это позволяет передавать дополнительные опции Databricks — например, использование [`RELY`, чтобы сообщить оптимизатору Databricks, что он может использовать ограничение для переписывания запросов](https://docs.databricks.com/aws/en/sql/language-manual/sql-ref-syntax-ddl-create-table-constraint).

Разделение `create` и `insert` также меняет поведение ограничений. Ранее таблица создавалась сразу с данными, а затем применялись ограничения. Если новые данные нарушали ограничение, выполнение завершалось ошибкой — но к этому моменту корректная таблица из предыдущего запуска уже была заменена.

Как и в случае с view, вы можете выбирать между производительностью и безопасностью с помощью флага [`use_safer_relation_operations`](#usesaferrelation_operations). Независимо от выбранной настройки, новый подход к materialization гарантирует, что данные, нарушающие ограничения, не попадут в целевую таблицу.

#### `use_safer_relation_operations`

При использовании этой конфигурации для таблиц сначала создаётся staging-таблица. После успешной вставки данных она переименовывается и заменяет целевую materialization. Поскольку Databricks не поддерживает откаты, это более безопасный подход: если ошибка произойдёт до переименования, исходная таблица останется нетронутой. Это даёт время на отладку без риска нарушить работу downstream-зависимостей.

Если этот параметр установлен в `false` (значение по умолчанию), целевая таблица всё равно не будет содержать данные, нарушающие ограничения, однако она может оказаться пустой, если вставка завершится ошибкой из-за constraint. Ключевое различие — заменяем ли мы целевую таблицу напрямую или используем подход staging + rename.

Этот параметр конфигурации может увеличить затраты и повлиять на историю Unity Catalog.

Как и в случае с view, использование дополнительных временных объектов приводит к созданию большего числа объектов UC со своей историей. Тщательно оцените, действительно ли вам необходимо такое поведение.

### Изменения в materialization Incremental

Все изменения, описанные в разделе [Table materialization](#changes-to-the-table-materialization), также применимы к incremental materialization.

Также был добавлен новый параметр конфигурации: `incremental_apply_config_changes`.

Этот параметр позволяет контролировать, должен ли dbt применять изменения таких свойств, как `tags`, `tblproperties` и комментарии, во время incremental-запусков. Многие пользователи хотели иметь возможность настраивать метаданные таблиц в Databricks — например, AI-сгенерированные комментарии — без того, чтобы dbt их перезаписывал. Ранее dbt-databricks всегда применял обнаруженные изменения при incremental-запусках.

При использовании материализации V2 теперь можно установить `incremental_apply_config_changes` в `false`, чтобы отключить это поведение. (По умолчанию используется значение `true`, чтобы сохранить прежнее поведение.)

Пример конфигурации:

schema.yml

```yaml
models:
  - name: incremental_market_updates
    config:
      materialized: incremental
      incremental_apply_config_changes: false
...
```

## Используйте управляемый Iceberg

Когда вы задаёте для `table_format` значение `iceberg`, флаг `use_managed_iceberg` определяет, как создаётся таблица. По умолчанию этот флаг имеет значение `false`, и dbt создаёт таблицу [UniForm](https://www.databricks.com/blog/delta-uniform-universal-format-lakehouse-interoperability). Если установить значение `true`, dbt создаёт [управляемую таблицу Iceberg](https://docs.databricks.com/aws/en/tables/managed).

## Используйте `replace on` для стратегии `insert_overwrite`

Флаг `use_replace_on_for_insert_overwrite` определяет, какой синтаксис SQL генерирует dbt для инкрементальных моделей, использующих стратегию `insert_overwrite`. По умолчанию этот флаг имеет значение `true`, при котором для динамической перезаписи разделов/кластеров используется синтаксис [`insert into ... replace on`](https://docs.databricks.com/aws/en/sql/language-manual/sql-ref-syntax-dml-insert-into#replace-on), что соответствует поведению при использовании кластерных вычислительных ресурсов. Когда флаг установлен в `false`, `insert_overwrite` полностью очищает таблицу при использовании SQL-хранилищ. Флаг не влияет на кластерные вычислительные ресурсы, поскольку при их использовании `insert_overwrite` всегда выполнял динамическую перезапись разделов/кластеров.

| Значение флага        | Генерируемый SQL                                                                                                                 | Описание                                                                                           |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `true` (по умолчанию) | [`INSERT INTO ... REPLACE ON`](https://docs.databricks.com/aws/en/sql/language-manual/sql-ref-syntax-dml-insert-into#replace-on) | Использует новейший рекомендуемый синтаксис Databricks для замены соответствующих разделов.        |
| `false`               | `INSERT OVERWRITE`                                                                                                               | Использует более старый синтаксис Spark для перезаписи разделов. Зависит от настроек сеанса Spark. |

Если ранее вы полагались на это поведение для полной замены содержимого таблицы без удаления существующих метаданных, оно сохраняется и при значении флага `true`, если вы не используете разделы или кластеры liquid clustering. Такие способы оптимизации размещения данных обычно дают существенный эффект только для таблиц размером около 1 ТБ и более, а при таком объёме регулярная замена всех данных, вероятно, уже не лучший подход.

## Использование `DESCRIBE AS JSON` для получения метаданных отношений

Флаг `use_describe_as_json_for_relation_metadata` определяет, как dbt получает метаданные на уровне отношений для таблиц и представлений Databricks, такие как ограничения (первичный ключ, внешний ключ и запрет значений NULL), маски столбцов, фильтры строк и описания представлений. Он принимает два значения:

* **`false`** (по умолчанию): dbt выполняет несколько запросов к `information_schema` для каждого отношения, чтобы получить эти метаданные.
* **`true`**: dbt получает все эти метаданные одним вызовом [`DESCRIBE TABLE EXTENDED ... AS JSON`](https://docs.databricks.com/aws/en/sql/language-manual/sql-ref-syntax-aux-describe-table) для каждого отношения.

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

#### Требования

dbt использует `DESCRIBE AS JSON` для конкретного отношения, только когда выполняются *все* следующие условия:

* Отношение находится в Unity Catalog (а не в Hive metastore).
* Отношение не является внешней таблицей (foreign table).
* Вычислительный ресурс является SQL-хранилищем или работает на DBR версии 17.3 или более поздней.

Если какое-либо условие не выполняется, dbt возвращается к запросам к `information_schema` для этого отношения. Такой переход выполняется отдельно для каждого отношения, поэтому флаг можно безопасно включать в проектах со смешанными типами вычислительных ресурсов.
