# Семантическая структура

подсказка

Обратите внимание: в этом руководстве по лучшим практикам пока не используется [новая спецификация YAML](https://docs.getdbt.tech/docs/build/latest-metrics-spec.md). Мы работаем над обновлением руководства, чтобы вскоре оно соответствовало новой спецификации и структуре файлов!

Подробнее о новой спецификации см. в разделе [Создание метрик](https://docs.getdbt.tech/docs/build/metrics-overview.md).

## Файлы и папки

Первое, что вам нужно определить, это как вы будете последовательно структурировать ваш код. Есть две рекомендуемые лучшие практики на выбор:

* 🏡 **Совмещайте код семантического слоя** в системе «один YAML‑файл на модель витрины».

  * Это позволяет разместить документацию, data tests, unit tests, семантические модели и метрики в одном унифицированном файле, который соответствует витрине, смоделированной в dbt.
  * Вы жертвуете большим размером файла в обмен на меньшее количество переходов между файлами.
  * Проще для новых (greenfield) проектов, которые разрабатывают Semantic Layer параллельно с dbt‑моделями.

* 🏘️ **Создайте подпапку** `models/semantic_models/`.

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

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

подсказка

Убедитесь, что все семантические модели и метрики сохранены в каталоге, определенном в [`model-paths`](https://docs.getdbt.tech/reference/project-configs/model-paths.md) (или в его подкаталоге, например, `models/semantic_models/`). Если вы сохраните их за пределами этого пути, это приведет к созданию пустого файла `semantic_manifest.json`, и ваши семантические модели или метрики не будут распознаны.

## Именование

Далее, установите систему для последовательного именования файлов:

* 1️⃣ Если вы используете **один YAML-файл на хранилище**, то у вас будет `orders.sql` и `orders.yml`.
* 📛 Если вы используете **подход с параллельной подпапкой**, для уникальности имен файлов рекомендуется использовать **префикс `sem_`, например, `sem_orders.yml`** для выделенной семантической модели и метрик, которые строятся на основе `orders.sql` и `orders.yml`.

## Не можете определиться?

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