# О командах dbt docs

(Версии dbt: v2.0 и новее)

С dbt v2 используйте [dbt Docs v2](https://docs.getdbt.tech/docs/build/view-documentation.md#dbt-docs-v2), чтобы создать и просмотреть документацию проекта локально. Команда `dbt docs generate` собирает сайт, а `dbt docs serve` запускает предпросмотр.

Чтобы создать только метаданные каталога (`catalog.json`), используйте [флаг `--write-catalog`](#--write-catalog-flag).

dbt Docs v2 предназначен для локального запуска и размещения в собственной инфраструктуре. В dbt platform используйте [Catalog](https://docs.getdbt.tech/docs/explore/build-and-view-your-docs.md): это облачное представление документации, которое задания обновляют автоматически. Подробнее см. [Поведение на платформе](#dbt-platform-behavior).

## dbt Docs v2

Сайт dbt Docs v2 собирается локально или в вашем пайплайне, например в GitHub Actions, и размещается в вашей инфраструктуре. На dbt platform вместо него используется [Catalog](https://docs.getdbt.tech/docs/explore/build-and-view-your-docs.md). Подробнее см. [Поведение на платформе](#dbt-platform-behavior).

При компиляции или сборке проекта v2 создаёт артефакты Parquet вместо статического `manifest.json`, который загружался в браузер. Команда `dbt docs generate` экспортирует сайт как набор статических файлов: одностраничное приложение и эти артефакты. Их можно разместить на любом файловом хостинге. Браузер читает Parquet напрямую через DuckDB-WASM (WebAssembly), поэтому отдельный сервер с состоянием не нужен и просмотр остаётся быстрым даже для крупных проектов.

### Сборка сайта

Команда `dbt docs generate` компилирует проект, записывает индекс и экспортирует сайт документации:

```shell
dbt docs generate
```

По умолчанию dbt записывает сайт в `target/`: `target/index.html`, `target/assets/` и индекс в `target/index/`. Структура совпадает с dbt v1. Файл `index.html` можно отдавать из `target/` так же, как в v1, поэтому пайплайн с командой `dbt docs generate && mv target public` продолжит работать.

Чтобы записать автономную копию сайта в другой каталог, используйте `--output-dir`:

```shell
dbt docs generate --output-dir site
```

Будет создан каталог `site/` с приложением, ресурсами с хешами в именах и копией индекса. Его можно разместить в S3, GitHub Pages, Netlify, GitLab Pages или на аналогичном хостинге статических файлов.

Чтобы пропустить компиляцию и экспортировать существующий индекс, используйте `--no-compile`. Если индекса нет, команда завершится ошибкой:

```shell
dbt docs generate --no-compile
```

#### Зависимости столбцов и дополнительные метаданные

Чтобы добавить типы столбцов, выведенные из SQL моделей, и зависимости на уровне столбцов, запустите `dbt build`, `dbt run` или `dbt compile` с флагами [`--generate-info-schema`](https://docs.getdbt.tech/docs/build/dbt-information-schema.md) и [`--static-analysis strict`](https://docs.getdbt.tech/docs/build/about-static-analysis.md), затем экспортируйте сайт:

```shell
dbt build --generate-info-schema --static-analysis strict
dbt docs generate --no-compile
```

Флаг `--no-compile` пропускает этап компиляции в `dbt docs generate` и экспортирует существующий индекс.

Если при сборке сайта сведения о зависимостях столбцов не были добавлены, dbt Docs v2 скрывает соответствующие функции.

### Локальный запуск dbt Docs v2

Чтобы просмотреть сайт локально, выполните:

```shell
dbt docs serve
```

Команда `dbt docs serve` открывает документацию на вашем компьютере. На dbt platform для просмотра проекта используйте Catalog. Подробнее см. [Поведение на платформе](#dbt-platform-behavior).

Команда `dbt docs serve` собирает сайт, если его ещё нет или он старше индекса, а затем отдаёт статические файлы. По умолчанию сервер запускается на порту `8580`, и сайт открывается в браузере. Порт можно изменить флагом `--port`:

```shell
dbt docs serve --port 8081
```

Флаг `--target-path` позволяет изменить каталог, из которого dbt читает артефакты:

```shell
dbt docs serve --target-path ~/Developer/internal-analytics/target
```

Сайт состоит из статических файлов, поэтому вместо локального сервера можно разместить его в объектном хранилище или на хостинге статических сайтов.

### Страница обзора проекта

Как и в dbt Docs v1, начальная страница dbt Docs v2 использует блок документации `__overview__`. dbt ищет блоки `{% docs %}` в каталогах `docs-paths`, поэтому файл `models/overview.md` находится по умолчанию. Файл `docs/overview.md` будет найден, только если в проекте задано `docs-paths: ["docs"]`. Если блок обзора не задан, dbt использует стандартную страницу.

## Флаг `--write-catalog`

Флаг `--write-catalog` создаёт артефакт [`catalog.json`](https://docs.getdbt.tech/reference/artifacts/catalog-json.md) с метаданными таблиц и представлений, созданных моделями проекта. Флаг только собирает метаданные. Чтобы собрать сайт документации, используйте [dbt Docs v2](#dbt-docs-v2).

При локальном запуске dbt добавляйте этот флаг явно. Он поддерживается следующими командами:

* `dbt build`
* `dbt run`
* `dbt parse`
* `dbt compile`

**Пример**:

```shell
dbt build --write-catalog
```

Задания на dbt platform

Задания dbt v2 на dbt platform автоматически обновляют метаданные Catalog при каждом запуске, поэтому флаг `--write-catalog` в них не нужен. Подробнее см. [Поведение на платформе dbt](#dbt-platform-behavior).

### Локальный запуск

При локальном запуске dbt v2 добавьте флаг `--write-catalog`, чтобы сгенерировать метаданные каталога:

```shell
dbt build --write-catalog
```

### Отличие от docs generate

Обе команды записывают артефакты. Сайт документации, который можно открыть в браузере, создаёт только `dbt docs generate`.

|                       | Флаг `--write-catalog`                                                                                        | Команда `dbt docs generate`                                                                        |
| --------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Что создаёт           | `catalog.json` и артефакты, которые команда создаёт и без флага                                               | `index.html`, `assets/` и файлы индекса                                                            |
| Для чего используется | Метаданные для [Catalog](https://docs.getdbt.tech/docs/explore/build-and-view-your-docs.md) и API метаданных | Статический сайт, который можно просмотреть через `dbt docs serve` или разместить на хостинге      |
| Где работает          | Локально и на dbt platform. В заданиях dbt v2 на платформе команда добавляется автоматически.                 | Только локально в v2. В заданиях dbt platform вместо неё выполняется `dbt compile --write-catalog` |

## Команды для сбора метаданных

Флаги собирают разные метаданные для разных задач. Выберите подходящую команду из списка. В [Справочнике флагов](#flag-reference) указано, какие данные создаёт каждый флаг и куда он их записывает.

* Чтобы показать выведенные типы столбцов моделей и зависимости столбцов в [dbt Docs v2](#dbt-docs-v2):

  ```shell
  dbt build --generate-info-schema --static-analysis strict
  dbt docs generate --no-compile
  ```

* Чтобы создать [информационную схему dbt](https://docs.getdbt.tech/docs/build/dbt-information-schema.md) с выведенными типами столбцов моделей и зависимостями столбцов:

  ```shell
  dbt build --generate-info-schema --static-analysis strict
  ```

* Чтобы создать информационную схему dbt с выведенными типами и зависимостями столбцов моделей, типами из хранилища и всеми столбцами источников, используемых выбранными узлами:

  ```shell
  dbt build --generate-info-schema --static-analysis strict --write-catalog
  ```

* Чтобы создать информационную схему dbt только с типами столбцов из хранилища:

  ```shell
  dbt build --generate-info-schema --write-catalog
  ```

* Чтобы создать [`catalog.json`](https://docs.getdbt.tech/reference/artifacts/catalog-json.md) с типами столбцов из хранилища:

  ```shell
  dbt build --write-catalog
  ```

#### Справочник флагов

В таблице указано, какие метаданные создаёт каждый флаг и куда они записываются:

| Флаг                                                                                        | Описание                                                                                                                                                                                                                                                                                               | Куда записываются данные                                                             |
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| [`--generate-info-schema`](https://docs.getdbt.tech/docs/build/dbt-information-schema.md)  | Создаёт [информационную схему dbt](https://docs.getdbt.tech/docs/build/dbt-information-schema.md). Добавьте `--static-analysis strict`, чтобы включить выведенные типы и зависимости столбцов моделей.                                                                                                | `target/info_schema/v1/`                                                             |
| [`--static-analysis strict`](https://docs.getdbt.tech/docs/build/about-static-analysis.md) | Включает выведенные типы и зависимости столбцов при использовании вместе с `--generate-info-schema`.                                                                                                                                                                                                   | Зависит от флага, с которым используется                                             |
| [`--write-catalog`](#--write-catalog-flag)                                                  | Создаёт [`catalog.json`](https://docs.getdbt.tech/reference/artifacts/catalog-json.md) с типами столбцов из хранилища.<br /><br />Вместе с `--generate-info-schema` в `dbt build` или `dbt run` записывает типы из хранилища и все столбцы источников для выбранных узлов в информационную схему dbt. | `target/catalog.json` (и `target/info_schema/v1/` вместе с `--generate-info-schema`) |

dbt Docs v2 читает метаданные из информационной схемы dbt. Файл `catalog.json` — отдельный артефакт для внешних инструментов.

## Поведение на платформе dbt

dbt Docs v2 предназначен для локального запуска и размещения в собственной инфраструктуре. На dbt platform используйте [Catalog](https://docs.getdbt.tech/docs/explore/build-and-view-your-docs.md), где доступно актуальное представление проекта:

* Каждый запуск задания v2 в dbt platform автоматически обновляет метаданные Catalog. Отдельный шаг генерации документации не нужен.
* Если добавить в задание шаг `dbt docs generate`, dbt автоматически выполнит вместо него `dbt compile --write-catalog` и направит вас в Catalog. Задание не создаст статический сайт или файл `index.html`.
* Чтобы дать коллегам, которые не разрабатывают в dbt, доступ к проекту, добавьте необходимое число [мест с правом чтения](https://docs.getdbt.tech/docs/platform/manage-access/seats-and-users.md). Доступ к Catalog включён и для разработчиков, и для пользователей с правом чтения.