Dynamic Default Date Ranges In Metabase

Эта страница описывает, как настроить dashboard в Metabase так, чтобы app-metabase-embedding автоматически подставлял стартовый период в editable date filters.

Что делает backend

Для dashboard сервис:

1. читает description через GET /api/dashboard/{id};
2. ищет в нём блок @config: {...};
3. парсит period;
4. вычисляет даты относительно LocalDate.now();
5. возвращает:
6. initialParams — plain имена параметров для UI и отладки;
7. embedParams — raw-ключи Metabase, готовые для сборки embed URL.

Важно:

• в JWT editable date defaults не кладутся;
• locked embedding params по-прежнему кладутся в JWT params;
• фронт должен использовать именно embedParams.

Когда это работает

Динамические периоды работают только если одновременно выполняются все условия:

• ресурс — строго dashboard;
• в description есть блок @config: {...};
• JSON внутри @config валиден;
• period строго соответствует шаблону last_<N>_<unit>;
• N > 0;
• в dashboard удалось найти хотя бы один параметр начала периода или хотя бы один параметр конца периода;
• если параметр уже присутствует в ранее собранных params, backend его не перезаписывает.

Как настроить dashboard

1. Добавьте date filters в Metabase

В dashboard должны быть date-параметры, которые пользователь может менять вручную.

Backend ищет date-параметры в таком порядке.

Точное сопоставление для начала периода:

• date_from
• start
• from

Точное сопоставление для конца периода:

• date_to
• end
• to

Сначала backend проверяет:

• уже собранные params;
• затем availableParamNames из metadata dashboard.

Если точного совпадения нет, backend переходит к semantic matching по parameterSearchTexts. parameterSearchTexts строится из нижнего регистра и decode значений полей:

• slug
• name
• display-name
• id

Точные semantic hints для начала периода:

• date_from
• start
• from
• начал

Точные semantic hints для конца периода:

• date_to
• end
• to
• конец
• окончан

То есть custom slug будет работать только если его search text содержит один из этих фрагментов.

Примеры, которые backend сможет распознать:

• начало_периода
• конец_периода
• period_start
• period_end
• окончание_периода

Примеры, которые backend не обязан распознать:

• left_border
• right_border
• p1
• p2

2. Убедитесь, что параметры editable

Если параметр locked, backend не должен использовать его как editable default.

Нужный сценарий:

• параметр объявлен в dashboard;
• пользователь видит его в embed;
• пользователь может изменить значение вручную.

3. Добавьте config в description

В описание dashboard добавьте строку такого вида:

@config: {"period":"last_1_month"}

Допустимо, если в description есть и другой текст. Главное, чтобы внутри был один валидный блок @config:.

Примеры:

@config: {"period":"last_2_weeks"}

Дашборд для ЛК УК
@config: {"period":"last_7_days"}

Поддерживаемый формат периода

Шаблон:

last_<N>_<unit>

Где:

• N — положительное целое число;
• unit — day, days, week, weeks, month, months, year, years.

Примеры валидных значений:

• last_7_days
• last_2_weeks
• last_1_month
• last_3_months
• last_1_year

Как считаются даты

Backend использует:

date_to = LocalDate.now()
date_from = date_to.minusXxx(N)

Примеры:

• last_7_days -> date_from = today.minusDays(7)
• last_2_weeks -> date_from = today.minusWeeks(2)
• last_1_month -> date_from = today.minusMonths(1)

Примеры настройки

Вариант 1. Стандартные параметры start / end

Dashboard metadata:

description = @config: {"period":"last_1_month"}
parameters = start, end

Ответ backend:

{
  "initialParams": {
    "start": "2026-03-15",
    "end": "2026-04-15"
  },
  "embedParams": {
    "start": "2026-03-15",
    "end": "2026-04-15"
  }
}

Вариант 2. Стандартные параметры date_from / date_to

Dashboard metadata:

description = @config: {"period":"last_2_weeks"}
parameters = date_from, date_to

Ответ backend:

{
  "initialParams": {
    "date_from": "2026-04-01",
    "date_to": "2026-04-15"
  },
  "embedParams": {
    "date_from": "2026-04-01",
    "date_to": "2026-04-15"
  }
}

Вариант 3. Кириллические slug'и

Dashboard metadata:

description = @config: {"period":"last_2_weeks"}
parameters = начало_периода, конец_периода

Если Metabase хранит raw slug в URL-encoded виде, backend вернёт:

{
  "initialParams": {
    "начало_периода": "2026-04-01",
    "конец_периода": "2026-04-15"
  },
  "embedParams": {
    "%D0%BD%D0%B0%D1%87%D0%B0%D0%BB%D0%BE_%D0%BF%D0%B5%D1%80%D0%B8%D0%BE%D0%B4%D0%B0": "2026-04-01",
    "%D0%BA%D0%BE%D0%BD%D0%B5%D1%86_%D0%BF%D0%B5%D1%80%D0%B8%D0%BE%D0%B4%D0%B0": "2026-04-15"
  }
}

Для embed URL фронт должен использовать embedParams, а не initialParams.

Как фронт должен использовать ответ

Правильный путь:

• брать token как чистый JWT;
• брать embedParams;
• собирать fragment/query для Metabase из embedParams без дополнительного workaround для кириллицы.

Что не делать

• не класть editable date defaults в JWT;
• не использовать initialParams как источник raw-ключей для Metabase URL;
• не ожидать, что backend угадает произвольные slug'и без признаков начала/конца периода;
• не писать невалидный JSON в description.

Диагностика

Если период не подставился, проверьте:

1. Dashboard, а не card.
2. В description есть @config: {...}.
3. JSON валидный.
4. period соответствует шаблону last_<N>_<unit>.
5. В dashboard есть date-параметры.
6. Параметры editable.
7. Backend действительно вернул embedParams.
8. Фронт использует embedParams, а не старый workaround.

Быстрый чеклист для нового dashboard

• Создан dashboard.
• Добавлены editable date filters.
• Имена фильтров понятны backend (start/end, date_from/date_to или осмысленные custom slug'и).
• В description добавлен @config.
• Проверен ответ /api/metabase/widgets/{id}.
• Во frontend для embed используются embedParams.