Фрагменты SQL

Фрагменты SQL — это переиспользуемые части SQL или других прямых запросов. Любой пользователь с правами на редактор прямых запросов может создавать и редактировать фрагменты — после этого они будут доступны всем авторам прямых запросов.

Например, если вы часто пишете запросы с несколькими таблицами, можно сохранить SQL‑код с join-ами как фрагмент — и затем переиспользовать этот код в разных запросах, в том числе другими пользователями.

Фрагменты можно использовать, чтобы стандартизировать KPI и фильтры на SQL — аналогично тому как в конструкторе запросов используются метрики и сегменты. Например, вы можете закрепить точную формулу выручки или критерии «активного пользователя».

Также с помощью фрагментов удобно определять набор переиспользуемых фильтров для SQL‑запросов.

Создание фрагмента

В редакторе прямых запросов:

1. Откройте редактор прямых запросов, нажав + Новый > SQL-запрос или + Новый > Прямой запрос в правом верхнем углу.

2. Напишите SQL (или другой прямой код) и выделите фрагмент, который хотите сохранить для повторного использования. Это не обязательно должен быть весь запрос. Например, можно выделить:

   orders AS o
   LEFT JOIN products AS p ON o.product_id = p.id
   WHERE p.category = {{category}}
   

   Внутри фрагмента можно использовать:

   • SQL‑параметры, например {{param}},
   • ссылки на другие фрагменты, например {{snippet: orders}} (Glarus BI обнаружит и запретит циклические ссылки),
   • ссылки на сохранённые запросы или модели, например {{#123-orders-model}}.

3. Щёлкните правой кнопкой по выделенному фрагменту и выберите Сохранить как фрагмент, чтобы создать фрагмент.

   

4. Задайте название и описание фрагмента. Названия фрагментов должны быть уникальными (включая названия архивированных фрагментов).

5. Сохраните.

Также можно создать новый фрагмент из боковой панели "Фрагменты":

1. Откройте редактор прямых запросов, нажав + Новый > SQL-запрос или + Новый > Прямой запрос в правом верхнем углу.
2. Откройте боковую панель "Фрагменты", нажав кнопку Фрагменты над окном редактора.
3. Введите код, который хотите сохранить как переиспользуемый фрагмент.
4. Сохраните.

Использовать фрагмент

Вы можете вставить сохранённый фрагмент в запрос — при этом добавится ссылка вида {{snippet: }}:

SELECT
  *
FROM
 {{snippet: orders and products}}

Чтобы добавить фрагмент в прямой код, начните вводить {{snippet: }} — Glarus BI предложит варианты автодополнения для доступных фрагментов.

Ссылки на фрагменты чувствительны к пробелам, поэтому вводите {{snippet: Products}}: без пробела между {{ и snippet и с пробелом между : и названием фрагмента.

Когда вы выполняете запрос, Glarus BI «под капотом» заменяет ссылку на фрагмент его SQL‑кодом.

Также можно просто выбрать фрагмент для вставки из боковой панели "Фрагменты":

1. Откройте боковую панель фрагментов, нажав кнопку "Фрагменты" над окном редактора.
2. Найдите фрагмент. Результаты поиска включают только те фрагменты, на которые у вас есть разрешения.
3. Наведите курсор на фрагмент и нажмите стрелку слева от названия, чтобы вставить его в запрос.

Если во фрагменте используются псевдонимы (aliases), в основном запросе нужно ссылаться на эти псевдонимы. Например, если фрагмент содержит products AS p, то вне фрагмента нужно использовать псевдоним p для обращения к столбцам этой таблицы (например, p.column_name).

Предпросмотр запроса с фрагментами

Glarus BI хранит фрагмент как ссылку и не показывает полный SQL с подстановкой кода фрагмента прямо в редакторе. Полный запрос, который Glarus BI отправит в базу данных, можно посмотреть, нажав значок глаз над редактором.

Редактирование фрагментов

Редактирование фрагментов — удобный способ сразу изменить множество запросов. Например, вы сохранили SQL‑код, который извлекает данные пользователей из таблиц X, Y и Z, как фрагмент User Data, но вам нужно изменить способ получения данных (например, добавить столбец или таблицу). Достаточно обновить SQL во фрагменте — и все запросы, которые используют User Data, начнут использовать обновлённый код.

Чтобы отредактировать фрагмент:

1. Откройте боковую панель "Фрагменты", нажав значок "Фрагменты SQL" над окном редактора.

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

3. Нажмите стрелку вниз справа от названия фрагмента, затем нажмите "Редактировать".

Вы сможете изменить код, название и описание фрагмента.

• Изменение названия фрагмента. Переименование обновит название фрагмента во всех запросах, где он используется. Переименование не сломает существующие запросы, которые ссылаются на фрагмент, но сломает другие фрагменты, которые ссылаются на этот фрагмент.

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

Архивирование фрагментов

Архивирование помогает убрать устаревшие или менее актуальные фрагменты из поля зрения.

Когда вы архивируете фрагмент, он перестаёт появляться в автодополнении и в списке фрагментов в боковой панели. Архивирование не влияет на существующие запросы, которые используют фрагмент, поэтому архивировать можно безопасно.

Чтобы архивировать фрагмент:

1. Откройте боковую панель "Фрагменты", нажав значок Фрагменты SQL над окном редактора.
2. Найдите фрагмент.
3. Нажмите стрелку вниз справа от названия фрагмента, затем нажмите Изменить.
4. Нажмите Архив.

Доступ к архивированным фрагментам можно получить из меню боковой панели, нажав "Архивные фрагменты" в левом нижнем углу панели.

Несмотря на то, что фрагмент нельзя удалить, его можно архивировать и разархивировать в любой момент.

Два фрагмента не могут иметь одинаковое название: даже если фрагмент архивирован, он всё равно может использоваться в запросах.

SQL‑параметры во фрагментах

Во фрагментах можно использовать SQL‑параметры. Например, можно сохранить фрагмент с таким SQL‑кодом:

WHERE
  {{created_at}}
AND category = {{category}}
GROUP BY {{time_grouping}}

Когда фрагмент с параметрами добавлен в SQL‑запрос, Glarus BI покажет виджет для параметра фрагмента.

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

Настройки параметров фрагмента задаются в конкретном запросе, а не в самом фрагменте, поэтому настройки не используются совместно между разными запросами на основе одного и того же фрагмента. Например, если у вас есть фрагмент:

WHERE {{created_at}}

вы можете вставить его в один запрос и сопоставить параметр фрагмента со столбцом CREATED_AT, а в другом запросе сопоставить тот же параметр со столбцом CANCELED_AT.

Если у вас есть несколько фрагментов с параметрами с одинаковым названием, запрос будет использовать только один экземпляр параметра. Например, если {{snippet: 1}} содержит параметр {{var}}, и {{snippet: 2}} тоже содержит параметр {{var}}, запрос покажет только один параметр {{var}} и использует его значение в обоих фрагментах.

Разрешения на фрагменты

Любой пользователь, у которого есть разрешения на редактор прямых запросов хотя бы для одной из подключённых баз данных, сможет открыть боковую панель фрагментов — и сможет создавать, редактировать, архивировать и разархивировать любые фрагменты, даже если эти фрагменты предназначены для баз данных, к которым у пользователя нет доступа на SQL‑редактирование.

Зачем использовать фрагменты?

Фрагменты полезны для:

• Стандартизации

Как в вашей организации определяется «популярный продукт»? По количеству проданных единиц? Или по отзывам со средней оценкой выше 4? Вы можете определить критерии популярности и оформить их как фрагмент, например {{snippet: popular products}}, чтобы этот код вставлялся во все запросы, которые используют фрагмент. Если со временем определение изменится, достаточно обновить SQL фрагмента — и изменение попадёт во все запросы.

Так же, как сегменты (именованные фильтры или наборы фильтров) и метрики (именованные вычисления) помогают стандартизировать аналитику, фрагменты позволяют поддерживать корректность и единообразие SQL между командами.

• Эффективности

Часто копируете и вставляете SQL? Не хотите помнить, какие внешние ключи к каким таблицам относятся? Напишите сложный join один раз, сохраните его как фрагмент и используйте фрагмент по мере надобности.

• Обучения

Фрагменты помогают развивать навыки тех, кто только начинает работать с SQL (и даже опытных аналитиков), «показывая» им ваш «канонический SQL» более эффективные или более сложные запросы. Читать, копировать и развивать качественный код — один из лучших способов учиться. Это также экономит время: люди могут взять код фрагмента, изменить его под другую задачу и сохранить как новый фрагмент для повторного использования.

Узнать больше

• SQL-фрагменты, сохранённые запросы и просмотры (документация Metabase, англ.).
• Руководство по устранению неполадок с SQL-запросами.