# Обновление до v1.11

Доступно в v1

## Ресурсы

* [Журнал изменений dbt v1.11](https://github.com/dbt-labs/dbt/blob/1.11.latest/CHANGELOG.md)
* [Руководство по установке CLI dbt v1](https://docs.getdbt.tech/docs/local/install-dbt.md)
* [Руководство по обновлению платформы dbt](https://docs.getdbt.tech/docs/dbt-versions/upgrade-dbt-platform-version.md)

## Что нужно знать перед обновлением

dbt Labs стремится обеспечивать обратную совместимость для всех версий 1.x. Любые изменения поведения будут сопровождаться [флагом изменения поведения](https://docs.getdbt.tech/reference/global-configs/behavior-changes.md#behavior-change-flags), чтобы предоставить время для миграции существующих проектов. Если после обновления возникнет ошибка, сообщите нам об этом, [создав issue](https://github.com/dbt-labs/dbt/issues/new).

dbt предоставляет функциональность новых версий dbt v1 через [каналы выпуска](https://docs.getdbt.tech/docs/dbt-versions/dbt-release-tracks.md) с автоматическим обновлением. Если вы выбрали канал выпуска **v1 Latest** в dbt, вам уже доступны все возможности, исправления и другая функциональность последней версии dbt v1! Если вы выбрали канал выпуска **v1 Compatible**, вы получите доступ к ним в следующем ежемесячном выпуске **v1 Compatible** после выхода финальной версии dbt v1.11.

## Новые и изменённые возможности и функциональность

Новые возможности и функциональность, доступные в dbt v1.11

### Пользовательские функции (UDF)

В dbt v1.11 появилась поддержка пользовательских функций (UDF), позволяющая определять и регистрировать собственные функции в хранилище данных. Как и макросы, UDF способствуют повторному использованию кода, но при этом являются объектами хранилища, поэтому одну и ту же логику можно повторно использовать в инструментах за пределами dbt.

Основные возможности:

* **Определение UDF как полноценных ресурсов dbt**: создавайте файлы UDF в каталоге `functions/` с соответствующей конфигурацией YAML.
* **Выполнение**: создавайте, обновляйте и переименовывайте UDF в рамках выполнения DAG с помощью `dbt build --select "resource_type:function"`
* **Интеграция с DAG**: при выполнении `dbt build` UDF создаются до моделей, которые на них ссылаются, что обеспечивает корректное управление зависимостями.
* **Новый макрос `function()`**: ссылайтесь на UDF в моделях с помощью макроса Jinja `{{ function('function_name') }}`.
* **Отложенное разрешение ссылок**: при запуске команды dbt с `--defer` и `--state` вызовы `function()` разрешаются в UDF из манифеста состояния, поэтому вы можете запускать модели, зависящие от UDF, без предварительного создания этих UDF.

Подробнее об UDF, включая предварительные требования, способы определения и использования, читайте в [документации по UDF](https://docs.getdbt.tech/docs/build/udfs.md).

### Префикс `DBT_ENGINE_` для переменных окружения

Переменные окружения для настройки движка используют префикс `DBT_ENGINE_`. Например, `DBT_STATE` становится `DBT_ENGINE_STATE`, `DBT_PROJECT_DIR` — `DBT_ENGINE_PROJECT_DIR` и так далее. Полное соответствие приведено в разделе [О флагах (глобальные настройки)](https://docs.getdbt.tech/reference/global-configs/about-global-configs.md).

### Управление изменениями устаревшего поведения

В dbt v1.11 появились новые флаги для [управления изменениями устаревшего поведения](https://docs.getdbt.tech/reference/global-configs/behavior-changes.md). Вы можете включить недавно представленные изменения (отключённые по умолчанию) или отключить устоявшиеся изменения (включённые по умолчанию), задав соответственно значения `true` / `false` для `flags` в `dbt_project.yml`.

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

* (Новый, отключён по умолчанию) [`require_unique_project_resource_names`](https://docs.getdbt.tech/reference/global-configs/behavior-flags/require_unique_project_resource_names.md). По умолчанию этот флаг имеет значение `false`. При таком значении, если два ресурса без версий в одном пакете имеют одинаковое имя, dbt продолжает работу и выдаёт предупреждение [`DuplicateNameDistinctNodeTypesDeprecation`](https://docs.getdbt.tech/reference/deprecations.md#duplicatenamedistinctnodetypesdeprecation). При значении `true` dbt выдаёт ошибку `DuplicateResourceNameError`.

* (Новый, отключён по умолчанию) [`require_ref_searches_node_package_before_root`](https://docs.getdbt.tech/reference/global-configs/behavior-flags/require_ref_searches_node_package_before_root.md). По умолчанию этот флаг имеет значение `false`. При таком значении, когда dbt разрешает `ref()` в модели пакета, он *сначала* ищет целевую модель в корневом проекте, а затем — в пакете, где определена модель. При значении `true` dbt ищет в пакете, где определена модель, *прежде чем* искать в корневом проекте.

### Предупреждения об устаревших возможностях включены по умолчанию

Предупреждения об устаревших возможностях, выявленных при проверке по JSON-схеме, теперь включены по умолчанию при валидации файлов конфигурации YAML (таких как `schema.yml` и `dbt_project.yml`) в проектах, использующих адаптеры Snowflake, Databricks, BigQuery и Redshift.

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

По умолчанию вы увидите следующие предупреждения об устаревших возможностях:

* [CustomKeyInConfigDeprecation](https://docs.getdbt.tech/reference/deprecations.md#customkeyinconfigdeprecation)
* [CustomKeyInObjectDeprecation](https://docs.getdbt.tech/reference/deprecations.md#customkeyinobjectdeprecation)
* [CustomTopLevelKeyDeprecation](https://docs.getdbt.tech/reference/deprecations.md#customtoplevelkeydeprecation)
* [MissingPlusPrefixDeprecation](https://docs.getdbt.tech/reference/deprecations.md#missingplusprefixdeprecation)
* [SourceOverrideDeprecation](https://docs.getdbt.tech/reference/deprecations.md#sourceoverridedeprecation)

Предупреждения каждого типа можно подавить с помощью настройки проекта [warn-error-options](https://docs.getdbt.tech/reference/global-configs/warnings.md#configuration). Например, чтобы подавить все перечисленные выше предупреждения, добавьте в `dbt_project.yml`:

dbt\_project.yml

```yml

flags:
  warn_error_options:
    silence:
      - CustomTopLevelKeyDeprecation
      - CustomKeyInConfigDeprecation
      - CustomKeyInObjectDeprecation
      - MissingPlusPrefixDeprecation
      - SourceOverrideDeprecation
```

Кроме того, для подавления конкретных предупреждений из командной строки можно использовать флаг `--warn-error-options`:

```sh
dbt parse --warn-error-options '{"silence": ["CustomTopLevelKeyDeprecation", "CustomKeyInConfigDeprecation", "CustomKeyInObjectDeprecation", "MissingPlusPrefixDeprecation", "SourceOverrideDeprecation"]}'
```

Чтобы подавить *все* предупреждения об устаревших возможностях, добавьте в `dbt_project.yml`:

dbt\_project.yml

```yml

flags:
  warn_error_options:
    silence:
      - Deprecations
```

Аналогично все предупреждения об устаревших возможностях можно подавить с помощью флага командной строки `--warn-error-options`:

```sh
dbt parse --warn-error-options '{"silence": ["Deprecations"]}'
```

## Возможности и функциональность отдельных адаптеров

### Snowflake

* Адаптер Snowflake поддерживает базовую материализацию в виде таблицы для таблиц Iceberg, зарегистрированных в каталоге Glue через [базу данных, связанную с каталогом](https://docs.snowflake.com/en/user-guide/tables-iceberg-catalog-linked-database#label-catalog-linked-db-create). Подробнее см. в разделе [Glue Data Catalog](https://docs.getdbt.tech/docs/build/iceberg/adapters/snowflake-iceberg-support.md#external-catalogs).
* В динамических таблицах поддерживается настройка `cluster_by`. Подробнее см. в разделе [Кластеризация динамических таблиц](https://docs.getdbt.tech/reference/resource-configs/snowflake-configs.md#dynamic-table-clustering).
* В динамических таблицах поддерживается настройка `immutable_where`. Подробнее см. в разделе [Настройки Snowflake](https://docs.getdbt.tech/reference/resource-configs/snowflake-configs.md#immutable-where).
* Вы можете задать [`copy_grants: true`](https://docs.getdbt.tech/reference/resource-configs/snowflake-configs.md#copy-grants-dynamic-tables) для динамической таблицы, чтобы dbt добавлял `COPY GRANTS` при её повторном создании во время `--full-refresh`. Значение по умолчанию — `false`.
* Задайте параметр [`refresh_warehouse`](https://docs.getdbt.tech/reference/resource-configs/snowflake-configs.md#refresh-warehouse), чтобы выбрать, какой вычислительный склад Snowflake будет выполнять автоматические обновления динамической таблицы. Этот параметр независим от `snowflake_warehouse`, который используется для выполнения DDL. Например, для обновлений можно использовать склад меньшего размера, а для DDL — большего. Если `refresh_warehouse` не задан, `snowflake_warehouse` используется и для выполнения DDL, и для автоматических обновлений.

### BigQuery

* Для повышения производительности dbt может выполнять один пакетный запрос при проверке актуальности источников по метаданным вместо отдельного запроса для каждого источника. Чтобы включить эту возможность, задайте для [bigquery\_use\_batch\_source\_freshness](https://docs.getdbt.tech/reference/global-configs/bigquery-changes.md#the-bigquery_use_batch_source_freshness-flag) значение `true`.

### Redshift

* Новый параметр подключения профиля `datasharing` позволяет `dbt-redshift` использовать собственные команды Redshift для работы с метаданными (команды `SHOW`, такие как `SHOW TABLES` и `SHOW COLUMNS`) вместо таблиц системного каталога PostgreSQL, таких как `pg_*` и `information_schema`. Это обеспечивает доступ между базами данных и кластерами с помощью [Redshift Datasharing](https://docs.aws.amazon.com/redshift/latest/dg/datashare-overview.html). Подробности настройки см. в разделе [Настройка Redshift](https://docs.getdbt.tech/docs/local/connect-data-platform/redshift-setup.md?version=1.12#datasharing).
* Параметр подключения профиля `drop_without_cascade` обеспечивает формирование инструкций `DROP TABLE/VIEW/MATERIALIZED VIEW` без `CASCADE`. Redshift обрабатывает граф зависимостей `CASCADE` при каждом `DROP`, что создаёт дополнительные накладные расходы в больших кластерах. Если у объектов вашего проекта нет зависимых объектов (например, используются только представления без привязки к схеме), можно задать `drop_without_cascade: true`, чтобы избежать этих затрат. Если этот параметр включён и зависимый объект существует, Redshift выдаёт ошибку. Подробности настройки см. в разделе [Настройка Redshift](https://docs.getdbt.tech/docs/local/connect-data-platform/redshift-setup.md).

### Spark

* Добавлены новые настройки профиля для улучшения [обработки повторных попыток для подключений PyHive](https://docs.getdbt.tech/reference/resource-configs/spark-configs.md#retry-handling-for-pyhive-connections):

  * `poll_interval`: определяет, как часто адаптер опрашивает сервер Thrift, чтобы проверить, завершился ли асинхронный запрос.
  * `query_timeout`: задаёт общий тайм-аут (в секундах) выполнения запроса. Если во время опроса выясняется, что запрос превысил заданную длительность, возникает ошибка `DbtRuntimeError`. Это помогает предотвратить бесконечное зависание запросов.
  * `query_retries`: обрабатывает потерю соединения во время опроса состояния запроса, автоматически выполняя повторные попытки.

### Starburst/Trino

* Адаптер Starburst/Trino поддерживает скалярные SQL-[UDF](https://docs.getdbt.tech/docs/build/udfs.md). Подробности настройки и ограничения см. в разделе [Настройки Starburst/Trino](https://docs.getdbt.tech/reference/resource-configs/trino-configs.md#user-defined-functions).

## Другие изменения в кратком обзоре

В dbt v1.11 также доступны следующие изменения:

* Флаг [`--sqlparse`](https://docs.getdbt.tech/reference/global-configs/sqlparse.md) задаёт параметры `MAX_GROUPING_DEPTH` и `MAX_GROUPING_TOKENS` библиотеки [`sqlparse`](https://sqlparse.readthedocs.io/en/latest/api.html#security-and-performance-considerations), когда dbt разбирает SQL во время компиляции.
* Команда `dbt ls` теперь может выводить вложенные ключи. Это упрощает отладку проекта и устранение неполадок. Пример: `dbt ls --output json --output-keys config.materialized`
* Метаданные манифеста теперь включают `run_started_at`, что позволяет точнее отслеживать время начала запусков dbt.
* При отключении модели её модульные тесты также автоматически отключаются.
* Вы можете использовать новые функции [`config.meta_get()`](https://docs.getdbt.tech/reference/dbt-jinja-functions/config.md#configmeta_get) и [`config.meta_require()`](https://docs.getdbt.tech/reference/dbt-jinja-functions/config.md#configmeta_require) для доступа к пользовательским настройкам, хранящимся в `meta`. Эти функции также перенесены в dbt v1.10.