# Сохраненные запросы

Сохраненные запросы — это способ сохранить часто используемые запросы в MetricFlow. Вы можете сгруппировать метрики, измерения и фильтры, которые логически связаны, в сохраненный запрос. Сохраненные запросы являются узлами и видны в dbt DAG.

Сохранённые запросы служат основой, позволяя [настраивать экспорты](#configure-exports) в конфигурации сохранённого запроса. Экспорты расширяют эту функциональность, позволяя [запускать сохранённые запросы по расписанию и записывать их результаты](https://docs.getdbt.tech/docs/use-dbt-semantic-layer/exports.md) непосредственно в вашей платформе данных с помощью [планировщика заданий dbt](https://docs.getdbt.tech/docs/deploy/job-scheduler.md).

## Параметры

Чтобы создать сохраненный запрос, обратитесь к следующей таблице параметров.

подсказка

Обратите внимание, что мы используем точечную нотацию (`.`), чтобы указать, является ли параметр вложенным в другой параметр. Например, `query_params.metrics` означает, что параметр `metrics` вложен в `query_params`.

(Версии dbt: v1.9 и новее)

| Параметр                   | Тип               | Обязательный | Описание                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| -------------------------- | ----------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                     | String            | Required     | Имя объекта сохранённого запроса.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `description`              | String            | Required     | Описание сохранённого запроса.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `label`                    | String            | Required     | Отображаемое имя для сохранённого запроса. Это значение будет показано в downstream‑инструментах.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `config`                   | String            | Optional     | Используйте свойство [`config`](https://docs.getdbt.tech/reference/resource-properties/config.md) для задания конфигураций сохранённого запроса. Поддерживаются конфигурации `cache`, [`enabled`](https://docs.getdbt.tech/reference/resource-configs/enabled.md), `export_as`, [`group`](https://docs.getdbt.tech/reference/resource-configs/group.md), [`meta`](https://docs.getdbt.tech/reference/resource-configs/meta.md), [`tags`](https://docs.getdbt.tech/reference/resource-configs/tags.md) и [`schema`](https://docs.getdbt.tech/reference/resource-configs/schema.md). |
| `config.cache.enabled`     | Object            | Optional     | Объект с вложенным ключом, который используется для указания, должен ли сохранённый запрос заполнять [cache](https://docs.getdbt.tech/docs/use-dbt-semantic-layer/sl-cache.md). Принимает значение `true` или `false`. По умолчанию `false`.                                                                                                                                                                                                                                                                                                                                            |
| `limit`                    | Integer           | Optional     | Максимальное количество строк, которое нужно вернуть.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `order_by`                 | String            | Optional     | Метрики и group by, по которым нужно упорядочить запрос.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `query_params`             | Structure         | Required     | Содержит параметры запроса.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `query_params.metrics`     | List or String    | Optional     | Список метрик, которые будут использоваться в запросе, в формате, соответствующем интерфейсу командной строки.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `query_params.group_by`    | List or String    | Optional     | Список Entities и Dimensions, которые будут использоваться в запросе, включая `Dimension` или `TimeDimension`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `query_params.where`       | List or String    | Optional     | Список строк, которые могут включать объекты `Dimension` или `TimeDimension`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `exports`                  | List or Structure | Optional     | Список экспортов, задаваемых внутри структуры exports.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `exports.name`             | String            | Required     | Имя объекта экспорта.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `exports.config`           | List or Structure | Required     | Свойство [`config`](https://docs.getdbt.tech/reference/resource-properties/config.md) для задания параметров экспорта.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `exports.config.export_as` | String            | Required     | Тип экспорта, который нужно выполнить. В настоящее время доступны варианты table или view, а в ближайшем будущем — cache.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `exports.config.schema`    | String            | Optional     | [Schema](https://docs.getdbt.tech/reference/resource-configs/schema.md) для создания таблицы или представления. Этот параметр нельзя использовать для кэширования.                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `exports.config.alias`     | String            | Optional     | [Alias](https://docs.getdbt.tech/reference/resource-configs/alias.md) таблицы, используемый при записи таблицы или представления. Этот параметр нельзя использовать для кэширования.                                                                                                                                                                                                                                                                                                                                                                                                    |

Если вы используете несколько метрик в сохраненном запросе, то вы сможете ссылаться только на общие измерения, которые эти метрики разделяют в `group_by` или `where` выражениях. Используйте префикс имени сущности с объектом Dimension, например `Dimension('user__ds')`.

## Настройка сохраненного запроса

Используйте сохранённые запросы (saved queries) для определения и управления общими запросами Semantic Layer в YAML, включая метрики и измерения. Сохранённые запросы позволяют организовывать и повторно использовать типовые запросы MetricFlow внутри проектов dbt. Например, вы можете группировать связанные метрики для более удобной структуры, а также включать часто используемые измерения и фильтры.

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

В следующем примере вы можете задать сохраненный запрос в файле `semantic_model.yml`:

semantic\_model.yml

(Версии dbt: v1.9 и новее)

```yaml
saved_queries:
  - name: test_saved_query
    description: "{{ doc('saved_query_description') }}"
    label: Test saved query
    config:
      cache:
        enabled: true | false
        tags: 'my_tag'
    query_params:
      metrics:
        - simple_metric
      group_by:
        - "Dimension('user__ds')"
      where:
        - "{{ Dimension('user__ds', 'DAY') }} <= now()"
        - "{{ Dimension('user__ds', 'DAY') }} >= '2023-01-01'"
    exports:
      - name: my_export
        config:
          export_as: table 
          alias: my_export_alias
          schema: my_export_schema_name
```

Обратите внимание, что параметр `export_as` можно задать как для сохранённого запроса, так и в конфигурации экспорта [config](https://docs.getdbt.tech/reference/resource-properties/config.md), при этом значение, указанное в конфигурации экспорта, имеет приоритет. Если какой‑либо ключ не задан в конфигурации экспорта, он будет унаследован из конфигурации сохранённого запроса.

#### Where выражение

Используйте следующий синтаксис для ссылки на сущности, измерения, временные измерения или метрики в фильтрах и обратитесь к [Метрики как измерения](https://docs.getdbt.tech/docs/build/ref-metrics-in-filters.md) для получения подробной информации о том, как использовать метрики как измерения с фильтрами метрик:

```yaml
filter: | 
  {{ Entity('entity_name') }}

filter: |  
  {{ Dimension('primary_entity__dimension_name') }}

filter: |  
  {{ TimeDimension('time_dimension', 'granularity') }}

filter: |  
  {{ Metric('metric_name', group_by=['entity_name']) }}
```

#### Сохранённые запросы на уровне проекта

Чтобы включить сохраненные запросы на уровне проекта, вы можете задать конфигурацию `saved-queries` в файле [`dbt_project.yml`](https://docs.getdbt.tech/reference/dbt_project.yml.md). Это сэкономит вам время на настройку сохраненных запросов в каждом файле:

dbt\_project.yml

```yaml
saved-queries:
  my_saved_query:
    +cache:
      enabled: true
```

Для получения дополнительной информации о `dbt_project.yml` и соглашениях об именах конфигураций, см. [страницу справки dbt\_project.yml](https://docs.getdbt.tech/reference/dbt_project.yml.md#naming-convention).

Чтобы собрать `saved_queries`:

* Убедитесь, что в вашей среде задана правильная [переменная окружения](https://docs.getdbt.tech/docs/use-dbt-semantic-layer/exports.md#set-environment-variable).
* Выполните команду `dbt build --resource-type saved_query`, используя [флаг `--resource-type`](https://docs.getdbt.tech/reference/global-configs/resource-type.md).

## Настройка экспортов

После того как вы настроили сохранённый запрос и задали базовый блок, можно настроить экспорты в YAML-файле конфигурации `saved_queries` (в том же файле, где определены ваши метрики). Это также позволит автоматически [запускать экспорты](#run-exports) на вашей платформе данных с помощью [планировщика заданий dbt](https://docs.getdbt.tech/docs/deploy/job-scheduler.md).

После того как вы настроили сохранённый запрос и задали базовый блок, вы можете сконфигурировать экспорты в YAML‑файле конфигурации `saved_queries` (в том же файле, где находятся определения метрик). Это также позволит вам [запускать экспорты](#run-exports) автоматически внутри вашей платформы данных с помощью [планировщика заданий ](https://docs.getdbt.tech/docs/deploy/job-scheduler.md).

Следующий пример показывает сохраненный запрос с экспортом:

semantic\_model.yml

(Версии dbt: v1.9 и новее)

```yaml
saved_queries:
  - name: order_metrics
    description: Relevant order metrics
    config:
      tags:
        - order_metrics
    query_params:
      metrics:
        - orders
        - large_order
        - food_orders
        - order_total
      group_by:
        - Entity('order_id')
        - TimeDimension('metric_time', 'day')
        - Dimension('customer__customer_name')
        - ... # Дополнительные group_by
      where:
        - "{{TimeDimension('metric_time')}} > current_timestamp - interval '1 week'"
         - ... # Дополнительные where выражения
    exports:
      - name: order_metrics
        config:
          export_as: table # Доступные варианты: table, view
          alias: my_export_alias # Необязательно — по умолчанию используется имя Export
          schema: my_export_schema_name # Необязательно — по умолчанию используется схема деплоя
```

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

Настроив экспорты, вы можете пойти дальше и запускать их, чтобы автоматически записывать результаты сохранённых запросов на вашей платформе данных с помощью [планировщика заданий dbt](https://docs.getdbt.tech/docs/deploy/job-scheduler.md). Эта возможность доступна только при использовании [Semantic Layer в dbt](https://docs.getdbt.tech/docs/use-dbt-semantic-layer/dbt-sl.md).

Для получения дополнительной информации о том, как запускать экспорты, обратитесь к документации [Экспорты](https://docs.getdbt.tech/docs/use-dbt-semantic-layer/exports.md).

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

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

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

 Как я могу выбрать 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)
* Настройка [кэширования](https://docs.getdbt.tech/docs/use-dbt-semantic-layer/sl-cache.md)
