# Запись результатов запросов с помощью экспортов

Платформа dbt | Starter, Enterprise, Enterprise+

Экспорты расширяют возможности [saved queries](https://docs.getdbt.tech/docs/build/saved-queries.md), выполняя сохранённые запросы и записывая результат в таблицу или представление (view) на вашей платформе данных. Сохранённые запросы — это способ сохранять и повторно использовать часто применяемые запросы в MetricFlow. Экспорты выводят эту функциональность на новый уровень за счёт следующего:

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

По сути, результаты экспорта — это такие же таблицы, как и любые другие в вашей платформе данных: они позволяют запрашивать определения метрик через любой SQL-интерфейс или подключать инструменты последующей обработки без полноценной [интеграции с Semantic Layer](https://docs.getdbt.tech/docs/platform-integrations/avail-sl-integrations.md). Выполнение экспорта учитывается при подсчёте [запрошенных метрик](https://docs.getdbt.tech/docs/platform/billing/how-pricing-works.md#what-counts-as-a-queried-metric). Запросы к таблице или представлению, полученным в результате экспорта, не учитываются при подсчёте запрошенных метрик.

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

* У вас есть учетная запись dbt с тарифным планом [Starter или Enterprise](https://www.getdbt.com/pricing/).
* Вы используете одну из следующих платформ данных: Snowflake, BigQuery, Databricks, Redshift или Postgres.
* Вы используете [dbt версии](https://docs.getdbt.tech/docs/dbt-versions/upgrade-dbt-platform-version.md) 1.7 или новее.
* В вашем проекте dbt [настроен](https://docs.getdbt.tech/docs/use-dbt-semantic-layer/setup-sl.md) Semantic Layer.
* У вас есть окружение dbt с включенным [планировщиком заданий](https://docs.getdbt.tech/docs/deploy/job-scheduler.md).
* В вашем проекте dbt настроены [сохраненный запрос](https://docs.getdbt.tech/docs/build/saved-queries.md) и [экспорт](https://docs.getdbt.tech/docs/build/saved-queries.md#configure-exports). При настройке используйте [кеширование](https://docs.getdbt.tech/docs/use-dbt-semantic-layer/sl-cache.md), чтобы кешировать часто выполняемые запросы, повысить производительность и снизить затраты на вычислительные ресурсы.

## Преимущества экспортов

Следующий раздел объясняет основные преимущества использования exports:

 DRY-представление

В настоящее время создание таблиц часто предполагает генерацию десятков, сотен или даже тысяч таблиц, которые денормализуют данные в сводные таблицы или таблицы витрин метрик. Основное преимущество exports заключается в создании представления логики в стиле «Don’t Repeat Yourself (DRY)» для построения каждой метрики, измерения, соединения, фильтра и т.д. Это позволяет переиспользовать эти компоненты для долгосрочной масштабируемости, даже если вы заменяете вручную написанные SQL-модели ссылками на метрики или измерения в сохранённых запросах.

 Более простые изменения

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

 Кэширование

Используйте exports для предварительного заполнения кэша, чтобы заранее вычислять данные, необходимые для обслуживания пользователей через динамические API семантического слоя (Semantic Layer).

#### Соображения

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

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

Для этих сценариев используйте динамические [API Semantic Layer](https://docs.getdbt.tech/docs/dbt-apis/sl-api-overview.md) вместо экспорта.

## Запуск экспортов

Прежде чем запускать экспорты в среде разработки или в продакшене, убедитесь, что вы [настроили сохранённые запросы и экспорты](https://docs.getdbt.tech/docs/build/saved-queries.md) в своём проекте dbt. В конфигурации сохранённого запроса также можно использовать [кеширование](https://docs.getdbt.tech/docs/use-dbt-semantic-layer/sl-cache.md) совместно с планировщиком заданий dbt, чтобы кешировать часто выполняемые запросы, повысить производительность и сократить затраты на вычисления.

Существует два способа запуска экспорта:

* [Запускайте экспорт в среде разработки](#exports-in-development), чтобы проверить результат перед запуском в рабочей среде. В Studio IDE или любой среде на dbt v2 вместо этого выполняйте `dbt build` — предварительно задайте [переменную среды](#set-environment-variable). В [dbt platform CLI](https://docs.getdbt.tech/docs/platform/dbt-cli-installation.md) вне dbt v2 выполняйте `dbt sl export` или `dbt sl export-all`.
* [Запускайте экспорт в рабочей среде](#exports-in-production) с помощью [планировщика заданий dbt](https://docs.getdbt.tech/docs/deploy/job-scheduler.md), чтобы записывать результаты этих запросов на вашей платформе данных.

## Экспорты в разработке

Вы можете выполнить экспорт в среде разработки, если хотите проверить его результат перед запуском в производственной среде.

Этот раздел объясняет различные команды и опции, доступные для запуска экспортов в разработке.

Если ваша среда работает на dbt v2 (включая Studio IDE), используйте `dbt build` вместо следующих команд. Подробнее см. в разделе [Запуск экспортов](#run-exports).

* Используйте [команду `dbt sl export`](#exports-for-single-saved-query), чтобы протестировать и создать экспорты в среде разработки для одного сохранённого запроса. Вы также можете использовать флаг `--select`, чтобы указать конкретные экспорты из сохранённого запроса.

* Используйте команду [`dbt sl export-all`](#exports-for-multiple-saved-queries), чтобы запускать экспорты для нескольких сохраненных запросов одновременно. Эта команда предоставляет удобный способ управления и выполнения экспортов для нескольких запросов одновременно, экономя время и усилия.

### Экспорты для одного сохранённого запроса

Эти команды применимы при использовании dbt platform CLI вне Studio IDE или dbt v2. Если ваша среда работает на dbt v2, используйте вместо них `dbt build`. Подробнее см. в разделе [Запуск экспортов](#run-exports).

Используйте следующую команду для запуска экспортов в dbt platform CLI:

```bash
dbt sl export
```

Следующая таблица перечисляет параметры команды `dbt sl export`, используя префикс флага `--` для указания параметров:

| Параметры     | Тип               | Обязательный   | Описание                                                                                                      |
| ------------- | ----------------- | -------------- | ------------------------------------------------------------------------------------------------------------- |
| `name`        | Строка            | Обязательный   | Имя объекта `export`.                                                                                         |
| `saved-query` | Строка            | Обязательный   | Имя сохраненного запроса, который может быть использован.                                                     |
| `select`      | Список или строка | Необязательный | Укажите имена экспортов для выбора из сохраненного запроса.                                                   |
| `exclude`     | Строка            | Необязательный | Укажите имена экспортов для исключения из сохраненного запроса.                                               |
| `export_as`   | Строка            | Необязательный | Тип экспорта для создания из доступных типов `export_as` в конфигурации. Доступные опции: `table` или `view`. |
| `schema`      | Строка            | Необязательный | Схема для использования при создании таблицы или представления.                                               |
| `alias`       | Строка            | Необязательный | Псевдоним таблицы для использования при записи таблицы или представления.                                     |

Вы также можете запустить любой экспорт, определенный для сохраненного запроса, и записать таблицу или представление в вашей среде разработки. Обратитесь к следующему примеру команды и выводу:

```bash
dbt sl export --saved-query sq_name
```

Вывод будет выглядеть примерно так:

```bash
Polling for export status - query_id: 2c1W6M6qGklo1LR4QqzsH7ASGFs..
Export completed.
```

### Использование флага select

Для сохранённого запроса можно настроить несколько экспортов. По умолчанию для сохранённого запроса выполняются все экспорты. Вы можете использовать флаг `select` [при разработке](#exports-in-development), чтобы выбрать один или несколько экспортов. Нельзя выбрать только часть метрик или измерений из сохранённого запроса. Можно изменить только конфигурацию экспорта, например формат таблицы или схему.

Например, следующая команда запускает `export_1` и `export_2` и не работает с флагами `--alias` или `--export_as`:

```bash
dbt sl export --saved-query sq_name --select export_1,export2
```

Переопределение конфигураций экспорта

Флаг `--select` в основном используется для включения или исключения конкретных экспортов. Если вам нужно изменить эти настройки, вы можете использовать следующие флаги для переопределения конфигураций экспорта:

* `--export-as` — Определяет тип материализации (таблица или представление) для экспорта. Это создает новый экспорт с собственными настройками и полезно для тестирования в разработке.
* `--schema` — Указывает схему для использования при записи таблицы или представления.
* `--alias` — Назначает пользовательский псевдоним для записываемой таблицы или представления. Это переопределяет имя экспорта по умолчанию.

Будьте осторожны. Флаг `--select` *не может* использоваться с `alias` или `schema`.

Например, вы можете использовать следующую команду для создания нового экспорта с именем `new_export` в виде таблицы:

```bash
dbt sl export --saved-query sq_number1 --export-as table --alias new_export
```

### Экспорты для нескольких сохраненных запросов

Используйте команду `dbt sl export-all`, чтобы запускать экспорты для нескольких сохраненных запросов одновременно. Это отличается от команды `dbt sl export`, которая запускает экспорты только для одного сохраненного запроса. Например, чтобы запустить экспорты для нескольких сохраненных запросов, вы можете использовать:

```bash
dbt sl export-all
```

Вывод будет выглядеть примерно так:

```bash
Exports completed:
- Created TABLE at `DBT_SL_TEST.new_customer_orders`
- Created VIEW at `DBT_SL_TEST.new_customer_orders_export_alias`
- Created TABLE at `DBT_SL_TEST.order_data_key_metrics`
- Created TABLE at `DBT_SL_TEST.weekly_revenue`

Polling completed
```

Команда `dbt sl export-all` предоставляет гибкость для управления несколькими экспортами в одной команде.

## Экспорты в производстве

Включение и выполнение экспортов в dbt оптимизирует рабочие процессы обработки данных и обеспечивает доступ к данным в реальном времени. Это повышает эффективность работы и качество управления данными для принятия более обоснованных решений.

Экспорты используют учетные данные по умолчанию для производственной среды. Чтобы включить экспорты для выполнения сохраненных запросов и записи их в вашей платформе данных, выполните следующие шаги:

1. [Задайте переменную окружения](#set-environment-variable) в dbt.
2. [Создайте и выполните запуск задания экспорта](#create-and-execute-exports).

### Установите переменную окружения

1. Нажмите **Deploy** на верхней панели навигации и выберите **Environments**.
2. Выберите **Environment variables**.
3. [Задайте переменную окружения](https://docs.getdbt.tech/docs/build/environment-variables.md#setting-and-overriding-environment-variables) с ключом (Версии dbt: v1.11 и новее) `DBT_ENGINE_EXPORT_SAVED_QUERIES` и значением `TRUE`.

Это обеспечит включение сохранённых запросов и операций экспорта в ваше задание сборки dbt. Например, запуск `dbt build -s sq_name` эквивалентен выполнению `dbt sl export --saved-query sq_name` в планировщике заданий dbt.

Если экспорт не требуется, можно задать значение `FALSE` ((Версии dbt: v1.11 и новее) `DBT_ENGINE_EXPORT_SAVED_QUERIES=FALSE`).

[![Добавьте переменную окружения для выполнения экспорта при запуске в производственной среде.](/img/docs/dbt-platform/semantic-layer/env-var-dbt-exports.png?v=2 "Добавьте переменную окружения для выполнения экспорта при запуске в производственной среде.")](#)Добавьте переменную окружения для выполнения экспорта при запуске в производственной среде.

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

### Создание и выполнение экспортов

1. Создайте [задание развертывания](https://docs.getdbt.tech/docs/deploy/deploy-jobs.md) и убедитесь, что переменная окружения (Версии dbt: v1.11 и новее) `DBT_ENGINE_EXPORT_SAVED_QUERIES=TRUE` задана, как описано в разделе [Настройка переменной окружения](#set-environment-variable).

   * Это позволяет выполнять любой экспорт, который необходимо обновить после построения модели.
   * Используйте параметр `--select` или `-s` из [синтаксиса селекторов](https://docs.getdbt.tech/reference/node-selection/syntax.md) в команде построения, чтобы указать конкретную модель dbt или сохраненный запрос для выполнения. Например, чтобы выполнить все сохраненные запросы, расположенные ниже по графу зависимостей от семантической модели `orders`, используйте следующую команду:

   ```bash
     dbt build --select orders+
   ```

2. После того как dbt завершит построение моделей, сервер MetricFlow обрабатывает экспорты, компилирует необходимый SQL и выполняет этот SQL в вашей платформе данных. Он напрямую выполняет оператор `create table`, поэтому данные остаются внутри вашей платформы данных.

3. Просмотрите детали выполнения экспортов в логах заданий и убедитесь, что экспорт был выполнен успешно. Это помогает при поиске и устранении проблем, а также для проверки корректности. Поскольку сохранённые запросы интегрированы в DAG dbt, все выходные данные, связанные с экспортами, доступны в логах заданий.

4. Теперь ваши данные доступны в платформе данных для выполнения запросов! 🎉

## Часто задаваемые вопросы

 Могу ли я иметь несколько экспортов в одном сохраненном запросе?

Да, это возможно. Однако разница будет в имени, схеме и стратегии материализации экспорта.

 Как я могу запустить все экспорты для сохраненного запроса?

* При запусках в продакшене можно выполнить сборку сохранённого запроса, указав его непосредственно в команде сборки, или собрать модель и все экспорты, зависящие от этой модели.
* При разработке выполняйте все экспорты с помощью команды `dbt sl export --saved-query sq_name`. Если ваша среда работает на dbt v2 (включая Studio IDE), вместо этого выполняйте `dbt build`.

 Буду ли я запускать дублирующие экспорты, если несколько моделей зависят от моего сохраненного запроса?

dbt выполнит каждый экспорт только один раз, даже если он собирает несколько моделей, зависящих от сохраненного запроса. Например, у вас может быть сохраненный запрос под названием `order_metrics`, который содержит метрики как из моделей `orders`, так и `order_items`.

Вы можете запустить задание, включающее обе модели, используя `dbt build`. Это выполнит как модели `orders`, так и `order_items`, однако экспорт `order_metrics` будет выполнен только один раз.

 Могу ли я ссылаться на экспорт как на модель dbt, используя ref()

Нет, вы не сможете ссылаться на экспорт, используя `ref`. Экспорты рассматриваются как конечные узлы в вашем DAG. Изменение экспорта может привести к несоответствиям с оригинальными метриками из семантического слоя.

 Как выбрать saved\_queries по их типу ресурса?

Чтобы включить все сохраненные запросы в запуск сборки dbt, используйте флаг [`--resource-type`](https://docs.getdbt.tech/reference/global-configs/resource-type.md) и выполните команду `dbt build --resource-type saved_query`.

## Связанные документы

* [Проверка семантических узлов в CI‑задаче](https://docs.getdbt.tech/docs/deploy/ci-jobs.md#semantic-validations-in-ci)
* Настройка [caching](https://docs.getdbt.tech/docs/use-dbt-semantic-layer/sl-cache.md)
* [Semantic Layer Часто задаваемые вопросы](https://docs.getdbt.tech/docs/use-dbt-semantic-layer/sl-faqs.md)
