# Конфигурации IBM watsonx.data Spark

## Требования к инстансу

Для использования IBM watsonx.data Spark с адаптером `dbt-watsonx-spark` необходимо убедиться, что инстанс имеет подключённый каталог, который поддерживает создание, переименование, изменение и удаление объектов, таких как таблицы и представления. Пользователь, подключающийся к инстансу через адаптер `dbt-watsonx-spark`, должен обладать необходимыми правами доступа к целевому каталогу.

Подробные инструкции по настройке, включая развёртывание watsonx.data, добавление Spark-движка, настройку хранилищ, регистрацию источников данных и управление правами доступа, см. в официальной документации IBM:

* Документация watsonx.data Software: [IBM watsonx.data Software Guide](https://www.ibm.com/docs/en/watsonx/watsonxdata/2.1.x)
* Документация watsonx.data SaaS: [IBM watsonx.data SaaS Guide](https://cloud.ibm.com/docs/watsonxdata?topic=watsonxdata-getting-started)

## Свойства сессии

В инстансах IBM watsonx.data SaaS/Software можно [задавать свойства сессии](https://sparkdb.io/docs/current/sql/set-session.html), чтобы изменять текущую конфигурацию для пользовательской сессии.

Чтобы временно изменить свойства сессии для конкретной dbt-модели или группы моделей, используйте [dbt hook](https://docs.getdbt.tech/reference/resource-configs/pre-hook-post-hook.md). Например:

```sql
{{
  config(
    pre_hook="set session query_max_run_time='10m'"
  )
}}
```

## Свойства коннекторов

IBM watsonx.data SaaS/Software поддерживает различные Spark-специфичные свойства коннекторов, которые позволяют управлять представлением данных, производительностью выполнения и форматом хранения.

Подробную информацию о поддерживаемых конфигурациях для каждого источника данных см. здесь:

* [Каталог watsonx.data SaaS](https://cloud.ibm.com/docs/watsonxdata?topic=watsonxdata-reg_database)
* [Каталог watsonx.data Software](https://www.ibm.com/docs/en/watsonx/watsonxdata/2.1.x?topic=components-adding-data-source)

### Дополнительная конфигурация

Адаптер `dbt-watsonx-spark` позволяет задавать дополнительные параметры конфигурации в профиле каталога:

* `Catalog:` указывает каталог, который будет использоваться для Spark-подключения. Плагин автоматически определяет тип формата файлов `(Iceberg, Hive или Delta)` на основе типа каталога.
* `use_ssl:` включает SSL-шифрование для защищённых соединений.

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

```yaml
project_name:
  target: "dev"
  outputs:
    dev:
      type: watsonx_spark
      method: http
      schema: [schema name]
      host: [hostname]
      uri: [uri]
      catalog: [catalog name]
      use_ssl: false
      auth:
        instance: [Watsonx.data Instance ID]
        user: [username]
        apikey: [apikey]
```

***

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

Поддерживаемые форматы файлов зависят от типа каталога:

* **Iceberg Catalog:** поддерживает таблицы **Iceberg**.
* **Hive Catalog:** поддерживает таблицы **Hive**.
* **Delta Lake Catalog:** поддерживает таблицы **Delta**.
* **Hudi Catalog:** поддерживает таблицы **Hudi**.

Плагин **автоматически** определяет тип формата файлов на основе каталога, указанного в конфигурации.

Формат файлов также можно указать непосредственно в dbt-моделях. Например:

```sql
{{
  config(
    materialized='table',
    file_format='iceberg' or 'hive' or 'delta' or 'hudi'
  )
}}
```

**Дополнительную информацию** см. в [документации.](https://spark.apache.org/docs/3.5.3/sql-ref-syntax.html#sql-syntax)

## Seeds и подготовленные выражения (prepared statements)

Вы можете настраивать типы данных столбцов либо в файле `dbt_project.yml`, либо в property-файлах, в зависимости от поддерживаемых dbt возможностей. Подробнее о конфигурации seed-данных и лучших практиках см. в [документации по настройке dbt seeds](https://docs.getdbt.tech/reference/seed-configs.md).

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

Адаптер `dbt-watsonx-spark` поддерживает материализацию таблиц, позволяя управлять тем, как данные хранятся и запрашиваются в watsonx.data Spark.

Дополнительную информацию о настройке материализаций см. в [документации по материализациям dbt](https://docs.getdbt.tech/reference/resource-configs/materialized.md).

### Таблицы

Адаптер `dbt-watsonx-spark` позволяет создавать и обновлять таблицы с помощью материализации `table`, что упрощает работу с данными в watsonx.data Spark.

### Представления

Если материализация явно не указана, адаптер по умолчанию автоматически создаёт представления (views).

### Инкрементальные таблицы

Инкрементальная материализация поддерживается, но требует дополнительной настройки секционирования и оптимизации производительности.

#### Рекомендации

* **Проверьте права доступа:** убедитесь, что в каталоге или схеме включены необходимые права для создания таблиц.
* **Изучите документацию коннектора:** ознакомьтесь с разделом watsonx.data Spark [data ingestion in watsonx.data](https://www.ibm.com/docs/en/watsonx/watsonxdata/2.1.x?topic=data-overview-ingestion), чтобы убедиться, что он поддерживает создание и изменение таблиц.

## Неподдерживаемые возможности

Несмотря на широкие возможности, адаптер `dbt-watsonx-spark` имеет ряд ограничений:

* **Incremental Materialization**: поддерживается, но требует дополнительной настройки секционирования и оптимизации производительности.

* **Materialized Views**: нативно не поддерживаются в Spark SQL в Watsonx.data.

* **Snapshots**: не поддерживаются из‑за отсутствия встроенного механизма snapshot в Spark.

* **Производительность**:

  * Для больших наборов данных может потребоваться настройка параметров Spark, таких как количество shuffle‑партиций и распределение памяти.
  * Некоторые преобразования могут быть ресурсоёмкими из‑за in‑memory модели обработки Spark.

Понимание этих возможностей и ограничений позволяет максимально эффективно использовать dbt с Watsonx.data Spark для масштабируемых преобразований данных и аналитики.
