# Документы семантического слоя Apache Ossie

Полезно знать

Доступно начиная с dbt v1.12 или в [канале релизов v1 Latest](https://docs.getdbt.tech/docs/dbt-versions/dbt-release-tracks.md).

dbt v1.12 поддерживает стандарт [Apache Ossie](https://github.com/apache/ossie) для определения семантических моделей и метрик. Вы можете размещать файлы `.json` в формате Ossie в каталоге `osi/` в корне проекта или настроить [`osi-paths`](https://docs.getdbt.tech/reference/project-configs/osi-paths.md) в `dbt_project.yml`, чтобы использовать один или несколько пользовательских каталогов с путями относительно корня проекта. dbt разбирает эти файлы и добавляет их содержимое в манифест вместе с семантическими моделями, определёнными в собственном формате dbt. Определения из Ossie и семантические модели в собственном формате dbt могут сосуществовать в одном проекте.

## Предварительные требования

* Необходимо использовать dbt v1.12. Поддержка v2 появится в ближайшее время.
* Документы Ossie должны использовать версию `0.1.0` или `0.1.1`. Любая другая строка версии вызывает ошибку разбора.

## Определение семантических моделей с помощью документов Ossie

Чтобы определить семантические модели с помощью документов Ossie:

1. Создайте каталог `osi/` в корне проекта dbt, на том же уровне, что и `dbt_project.yml`. Чтобы вместо него использовать один или несколько пользовательских каталогов, настройте [`osi-paths`](https://docs.getdbt.tech/reference/project-configs/osi-paths.md) в `dbt_project.yml`, указав пути относительно корня проекта.

2. Добавьте в каталог один или несколько файлов Ossie `.json`. Файлы можно распределять по подкаталогам: dbt сканирует всё дерево каталогов.

   Поле `source` должно содержать полное расположение модели dbt из этого проекта в хранилище данных в формате `database.schema.alias` (например, `my_database.my_schema.fct_orders`). dbt сопоставляет каждый набор данных с моделью по базе данных, схеме и псевдониму модели. Значение `source` каждого набора данных должно соответствовать модели dbt. Ограничения на источники наборов данных описаны в разделе [Ограничения](#limitations).

   Ниже приведён пример документа Ossie, который определяет семантическую модель на основе модели dbt с именем `fct_orders`:

   ```json
   {
     "version": "0.1.1",
     "semantic_model": [
       {
         "name": "orders",
         "datasets": [
           {
             "name": "orders",
             "source": "my_database.my_schema.fct_orders"
           }
         ]
       }
     ]
   }
   ```

   В этом примере определяется только семантическая модель. Чтобы добавить метрики, включите в семантическую модель массив `metrics` в соответствии со [спецификацией Ossie](https://github.com/apache/ossie).

3. Выполните любую команду, которая запускает компиляцию, например `dbt compile` или `dbt run`. dbt автоматически обнаруживает и разбирает файлы Ossie.

Полученные семантические модели (и метрики, если они определены в документах Ossie) появляются в [артефактах dbt](https://docs.getdbt.tech/reference/artifacts/dbt-artifacts.md) в каталоге `target/`, включая [`manifest.json`](https://docs.getdbt.tech/reference/artifacts/manifest-json.md), [`semantic_manifest.json`](https://docs.getdbt.tech/reference/artifacts/sl-manifest.md) и [`osi_document.json`](https://docs.getdbt.tech/reference/artifacts/sl-manifest.md#osi-document).

## Ограничения

* dbt сканирует каталоги Ossie только в корневом проекте (они настраиваются через [`osi-paths`](https://docs.getdbt.tech/reference/project-configs/osi-paths.md), по умолчанию используется `osi/`). Файлы Ossie в установленных пакетах зависимостей игнорируются.
* Источник каждого набора данных Ossie должен соответствовать модели dbt. Документы Ossie, ссылающиеся на источники (sources), seeds, snapshots или внешние таблицы, не поддерживаются.
* Если конвертер Ossie встречает неподдерживаемые типы метрик или другие конструкции, эти элементы отбрасываются, а dbt выдаёт предупреждение (код события `I078`), но разбор продолжается. Предупреждения отображаются в CLI и записываются в `logs/dbt.log`; дополнительные сведения см. в разделе [События и журналы](https://docs.getdbt.tech/reference/events-logging.md).