Инструкция по подключению Yandex DataLens к MacroData

Для аналитиков, знакомых с SQL

#1. Введение

#MacroData — готовые данные для аналитики

Для построения дашбордов в DataLens вам понадобятся данные из MacroCRM. MacroData — это готовая база данных с заранее подготовленными таблицами, которая даёт прямой доступ к ключевым сущностям системы: заявкам, сделкам, звонкам, объектам, встречам и многому другому. Таблицы MacroData уже структурированы и содержат нужные поля с понятными названиями — это значит, что при написании SQL-запросов для датасетов вы работаете с готовой, хорошо организованной схемой, а не выстраиваете её самостоятельно. Подробное описание всех таблиц и полей доступно в документации MacroDataПереход на внешний сайтhttps://api.macroserver.ru/docs/macroData/1/.

#Что такое Yandex DataLens

Yandex DataLens — это облачный BI-инструмент от Яндекса для построения интерактивных отчётов и дашбордов. Он подключается напрямую к базе данных через SQL-запрос, позволяет настраивать визуализации и публиковать готовые отчёты для команды.

Вся работа ведётся внутри одного воркбука — рабочего пространства, куда собираются все объекты отчёта.

#Иерархия объектов

Прежде чем начать, важно понять структуру объектов в DataLens. Каждый объект опирается на предыдущий:

• Воркбук — рабочее пространство, в котором хранятся все объекты проекта.
• Подключение — настройки доступа к базе данных (хост, порт, логин, пароль).
• Датасет — SQL-запрос поверх подключения; DataLens строит на его основе аналитику.
• Чарт — визуализация данных на основе датасета (диаграмма, таблица, индикатор).
• Дашборд — страница, на которой собраны несколько чартов и фильтры (селекторы).

Полная цепочка: Воркбук → Подключение → Датасет → Чарт → Дашборд.

{width=70%}

Рисунок 1.1 — содержимое воркбука: подключение, датасеты, чарты и дашборд

#2. Настройка окружения

#Создание воркбука

Войдите в Yandex DataLens. На главной странице перейдите в раздел «Коллекции и воркбуки». Нажмите Создать воркбук, введите название и нажмите Создать.

Воркбук станет рабочим пространством для всех объектов вашего отчёта: подключения, датасетов, чартов и дашборда.

{width=70%}

Рисунок 2.1 — начало работы

{width=70%}

Рисунок 2.2 — путь создания воркбука

{width=70%}

Рисунок 2.3 — диалоговое окно создания воркбука

#Создание подключения к базе данных

Внутри воркбука нажмите Создать → Подключение. Выберите тип базы данных — MySQL.

Заполните параметры подключения:

• Хост — адрес сервера базы данных.
• Порт — стандартный порт MySQL: 3306.
• База данных — название схемы.
• Логин — имя пользователя базы данных.
• Пароль — пароль пользователя.

Параметры подключения к базе данных предоставляет MACRO по запросу при подключении MacroData.

После заполнения нажмите Проверить подключение, затем Создать подключение.

{width=70%}

Рисунок 2.4 — создание подключения

{width=70%}

Рисунок 2.5 — выбор подключения

#Включение параметризации в подключении

Чтобы в датасетах работали параметры (подробнее см. п. 3), необходимо включить соответствующую настройку. Откройте созданное подключение, найдите пункт «Разрешить подзапросы в датасетах и параметризация источников» и активируйте его. Сохраните подключение.

{width=70%}

Рисунок 2.6 — сохранение подключения

#3. Датасеты

#Что такое датасет

Датасет — это SQL-запрос, поверх которого DataLens строит аналитику. DataLens оборачивает ваш запрос в SELECT * FROM (...) AS source, поэтому нельзя использовать CTE (WITH ...) и оконные функции — не поддерживаются в MySQL < 8.0. Всю логику реализуйте через подзапросы.

#Создание датасета и ввод SQL-запроса

Внутри воркбука нажмите Создать → Датасет. Выберите созданное подключение. Чтобы перейти к редактору SQL, нажмите на значок «три точки» рядом с источником и выберите «Редактировать SQL-запрос». Вставьте запрос и нажмите Применить.

{width=70%}

Рисунок 3.1 — набор полей при выборе подключения в датасете

{width=70%}

Рисунок 3.2 — переход к редактору SQL через меню «три точки»

#Какие таблицы использовать

При создании датасета в качестве источника используются таблицы MacroData. Выбор таблицы зависит от того, что вы хотите анализировать. Для анализа воронки продаж и работы с заявками подключайте таблицу estate_buysПереход на внешний сайтhttps://api.macroserver.ru/docs/macroData/1/#/?id=estate_buys — она содержит все заявки с датами, статусами, менеджерами, источниками и UTM-метками. Для анализа закрытых сделок используйте estate_dealsПереход на внешний сайтhttps://api.macroserver.ru/docs/macroData/1/#/?id=estate_deals, где хранятся суммы, даты, типы договоров и программы покупки. Ассортимент объектов и их текущие статусы содержатся в estate_sellsПереход на внешний сайтhttps://api.macroserver.ru/docs/macroData/1/#/?id=estate_sells, а информация о домах и ЖК — в estate_housesПереход на внешний сайтhttps://api.macroserver.ru/docs/macroData/1/#/?id=estate_houses.

Если вам нужен анализ коммуникаций — подключайте callsПереход на внешний сайтhttps://api.macroserver.ru/docs/macroData/1/#/?id=calls: там собраны все звонки с типами (входящий/исходящий), статусами и длительностью. Данные по встречам с клиентами хранятся в estate_meetingsПереход на внешний сайтhttps://api.macroserver.ru/docs/macroData/1/#/?id=estate_meetings.

#Параметры датасета

Параметры передают в SQL значения из селекторов дашборда. В запросе параметр указывается как {{start_date}}.

{width=70%}

Рисунок 3.3 — SQL-запрос с параметрами {{start_date}} и {{end_date}}

{width=70%}

Рисунок 3.4 — включение параметризации в датасете

#Ошибки валидации при изменении датасета

Если вы удалили из SQL поле, которое использовалось в вычисляемых полях или чартах, DataLens покажет ошибку валидации. Найдите все ссылки на это поле и исправьте или удалите их — ошибки подсвечиваются в редакторе датасета.

{width=70%}

Рисунок 3.5 — раздел «Параметры» в настройках датасета

#Вычисляемые поля

Вычисляемые поля создаются в разделе «Поля» датасета и позволяют добавить логику без изменения SQL.

Пример — количество дней от создания заявки до первой брони:

IF(NOT ([first_booking_date] IS NULL), [first_booking_date] - [buy_date], NULL)

Ограничения: ISNULL() → используйте [поле] IS NULL; DATEDIFF() → [date2] - [date1]; FIXED LOD не поддерживается — выносите в SQL-подзапросы.

{width=70%}

Рисунок 3.6 — добавление вычисляемого поля

{width=70%}

Рисунок 3.7 — список полей датасета с полями к удалению

#Полезные таблицы для маркетинговой аналитики

Для анализа эффективности рекламы MacroData предоставляет сразу несколько взаимосвязанных таблиц. В estate_buys_utmПереход на внешний сайтhttps://api.macroserver.ru/docs/macroData/1/#/?id=estate_buys_utm хранятся UTM-метки каждой заявки — источник, кампания, канал, а также идентификаторы коллтрекинга. Фактические расходы на рекламу в разрезе дат, ЖК и UTM-кампаний содержатся в advertising_expensesПереход на внешний сайтhttps://api.macroserver.ru/docs/macroData/1/#/?id=advertising_expenses. Объединив эти две таблицы через общие UTM-поля, можно построить полноценный отчёт CPL (стоимость заявки) в разрезе каналов.

#4. Чарты

#Что такое чарт

Чарт — это визуализация данных из датасета. Каждый чарт создаётся отдельно и добавляется на дашборд. Один датасет может быть основой для любого количества чартов.

#Создание чарта

Нажмите Создать → Чарт в воркбуке, затем выберите датасет.

{width=70%}

Рисунок 4.1 — меню «Создать» → «Чарт» в воркбуке

В редакторе чарта левая панель показывает все поля датасета:

• Измерения (синие) — текст, дата, булево. Используются для группировки.
• Показатели (зелёные) — числа. При перетаскивании автоматически агрегируются.

{width=70%}

Рисунок 4.2 — общий вид редактора чарта с левой панелью полей

#Тип чарта

Выбирается в верхнем левом углу редактора. Доступные типы: Линейная диаграмма, Диаграмма с областями, Нормированная диаграмма с областями, Столбчатая диаграмма, Нормированная столбчатая диаграмма, Линейчатая диаграмма, Нормированная линейчатая диаграмма, Точечная диаграмма, Круговая диаграмма, Кольцевая диаграмма, Индикатор, Древовидная диаграмма, Таблица, Сводная таблица, Карта, Комбинированная диаграмма.

{width=70%}

Рисунок 4.3 — выпадающий список типов чартов

#Примеры метрик на основе MacroData

Большинство типовых отчётов по недвижимости строится на нескольких ключевых таблицах MacroData. Динамику поступления заявок удобно считать через estate_buysПереход на внешний сайтhttps://api.macroserver.ru/docs/macroData/1/#/?id=estate_buys (поле created_at), группируя по неделям или месяцам. Для воронки продаж используйте estate_buys_statuses_logПереход на внешний сайтhttps://api.macroserver.ru/docs/macroData/1/#/?id=estate_buys_statuses_log — таблица хранит полную историю переходов между статусами с датами и позволяет точно считать время на каждом этапе. Если нужен срез по менеджерам или отделам, подключайте usersПереход на внешний сайтhttps://api.macroserver.ru/docs/macroData/1/#/?id=users и company_departmentsПереход на внешний сайтhttps://api.macroserver.ru/docs/macroData/1/#/?id=company_departments через JOIN по manager_id.

#Настройки чарта

Иконка ⚙ рядом с типом чарта открывает настройки: заголовок, тултип и параметры, специфичные для типа. Например, для «Таблицы» здесь настраивается пагинация.

{width=70%}

Рисунок 4.4 — панель настроек чарта через иконку шестерёнки

#QL-чарты

QL-чарт не строится на основе датасета: SQL пишется прямо в редакторе, DataLens строит визуализацию по его результату.

Ограничения:

• Тип «Сводная таблица» недоступен.
• QL-чарты нельзя подключить к селекторам дашборда. Для дашбордов с общей фильтрацией используйте обычные чарты на основе датасета.

#Секции редактора

• X / Строки — ось X или строки таблицы.
• Y / Столбцы — ось Y или столбцы таблицы.
• Показатель — для чартов без осей X/Y: Индикатор, Круговая, Кольцевая, Древовидная.
• Цвет — разбивка по цвету.
• Подписи — значения на визуализации.
• Сортировка — порядок данных.
• Фильтры — фильтрация внутри чарта.

Рисунок 4.5 — секции редактора с заполненными полями

#Агрегация

Кликните на символ перед названием поля в секции чарта (# для числовых, T для строковых, календарь для дат), чтобы изменить агрегацию: Сумма, Количество, Количество уникальных, Среднее, Минимум, Максимум.

Для уникальных заявок: «Количество уникальных» по estate_buy_id. Для сделок — по deal_id.

#Вычисляемые поля в редакторе чарта

Нажмите + над списком полей → «Добавить поле». В редакторе формулы доступна кнопка Помощь с формулами — встроенный ИИ-ассистент DataLens для отладки формул.

{width=70%}

Рисунок 4.6 — кнопка «+» и редактор формулы с кнопкой «Помощь с формулами»

#Сортировка

Нельзя добавить в сортировку поле, вычисленное через f(x) в интерфейсе — только поля из датасета. Если нужна сортировка по агрегату, используйте тип «Таблица» с интерактивной сортировкой по столбцам.

#Сохранение

Нажмите Сохранить в правом верхнем углу. Дайте чарту понятное название.

#5. Дашборд

#Что такое дашборд

Дашборд — страница с набором чартов, текстовых блоков и селекторов на общем холсте. Создаётся отдельно от чартов — чарты должны быть готовы заранее.

#Создание дашборда

Нажмите Создать → Дашборд в воркбуке.

{width=70%}

Рисунок 5.1 — меню «Создать» → «Дашборд» в воркбуке

#Интерфейс редактора

Нижняя панель содержит кнопки добавления элементов:

• Чарт — визуализация из воркбука.
• Селектор — фильтр (подробнее в разделе 6).
• Текст — текстовый блок.
• Заголовок — крупный заголовок секции.

{width=70%}

Рисунок 5.2 — пустой холст с нижней панелью добавления элементов

#Добавление чарта

Нажмите Чарт, выберите чарт из воркбука и нажмите Добавить. Блок на холсте можно перемещать и изменять размер за правый нижний угол.

{width=70%}

Рисунок 5.3 — диалог выбора чарта для добавления на дашборд

#Финансовые и плановые показатели

Для дашбордов с финансовой аналитикой подключайте таблицу financesПереход на внешний сайтhttps://api.macroserver.ru/docs/macroData/1/#/?id=finances — она содержит все денежные поступления по сделкам с датами, суммами и привязкой к объекту и контакту. Планы продаж и их фактическое исполнение доступны через estate_sales_plans_metricsПереход на внешний сайтhttps://api.macroserver.ru/docs/macroData/1/#/?id=estate_sales_plans_metrics: там хранятся плановые и фактические значения по количеству сделок, суммам и площадям в разрезе менеджеров, отделов, ЖК и периодов.

#Связи между элементами

Настройка области действия селекторов — через «Связи» в панели настроек дашборда (⚙ в верхней панели). Подробнее — в разделе 6.

#Сохранение и режимы

Нажмите Сохранить. После сохранения открывается режим просмотра. Для редактирования нажмите Редактировать. Для выхода без сохранения — Отменить.

{width=70%}

Рисунок 5.4 — готовый дашборд в режиме просмотра с кнопкой «Редактировать»

#6. Селекторы

#Что такое селектор

Селектор — элемент фильтрации на дашборде. Пользователь выбирает значение, и все связанные чарты перефильтровываются. Добавляется из нижней панели кнопкой Селектор.

#Типы селекторов

• Список — выпадающий список, поддерживает множественный выбор.
• Поле ввода — ручной ввод.
• Календарь — выбор даты или диапазона.
• Чекбокс — переключатель.

#Создание селектора

Селекторы создаются группой («Группа селекторов»). Несколько селекторов добавляются через + Добавить.

• Датасет и поле — хотя указывается конкретный датасет, селектор фильтрует все чарты с совпадающим именем поля.
• Тип — список, ввод, календарь или чекбокс.
• Значение по умолчанию — начальное значение при открытии дашборда.
• Множественный выбор — несколько значений одновременно.

{width=70%}

Рисунок 6.1 — диалог «Группа селекторов» с выбором поля из датасета

#Параметрические селекторы (для дат)

Для фильтрации по диапазону дат создайте два селектора — «Начало периода» и «Конец периода». В качестве источника выберите «Ручной ввод» — при выборе датасета параметры в списке полей не отображаются. Введите имя параметра вручную: start_date и end_date.

{width=70%}

Рисунок 6.2 — настройка селектора с ручным вводом параметра start_date, тип «Календарь»

#Связи селекторов с чартами

DataLens иногда подтягивает связи автоматически. Если нет — настройте вручную через «Связи» (⚙ в верхней панели). Достаточно настроить связь с одним чартом — DataLens по аналогии применит к остальным.

В диалоге для каждой пары «селектор — чарт» выберите: «игнорировать», «входящая связь» (чарт фильтруется) или «исходящая связь».

{width=70%}

Рисунок 6.3 — диалог «Связи» с настройкой входящих связей

#Кнопки «Применить» и «Сбросить»

Применить — запускает фильтрацию сразу по всем селекторам. Сбросить — возвращает к значениям по умолчанию.

{width=70%}

Рисунок 6.4 — дашборд с кнопками «Применить» и «Сбросить»

#7. Встраивание отчёта в MacroCRM

#Зачем это нужно

Дашборд из DataLens можно встроить в MacroCRM, чтобы сотрудники открывали его в привычном интерфейсе. Все функции просмотра сохраняются: фильтрация и выгрузка данных из чартов.

#Шаг 1. Открыть публичный доступ в DataLens

В режиме просмотра нажмите «три точки ...» в правом верхнем углу → «Публичный доступ» → активируйте переключатель.

Предупреждение можно проигнорировать: дашборд доступен только по прямой ссылке, без ссылки его не найти ни в интернете, ни внутри DataLens.

Скопируйте ссылку кнопкой Скопировать ссылку.

{width=70%}

Рисунок 7.1 — окно «Настройка публичного доступа» с переключателем и кнопкой «Скопировать ссылку»

#Шаг 2. Создать отчёт в MacroBI

MacroCRM → «Отчёты» → MacroBI. Создайте дашборд, введите название.

В окне редактирования активируйте «Внешний» → вставьте ссылку DataLens. Затем активируйте «Опубликован» → Сохранить.

{width=70%}

Рисунок 7.2 — окно MacroBI: активны «Опубликован» и «Внешний», вставлена ссылка DataLens

#Настройка доступа по ролям

В поле «Доступ ролям» выберите роли, которым будет виден отчёт на главной странице CRM.

{width=70%}

Рисунок 7.3 — поле «Доступ ролям» с выпадающим списком ролей

#Шаг 3. Открыть отчёт в CRM

На главной странице MacroCRM в левом меню найдите дашборд и нажмите на него. Откроется встроенный фрейм с дашбордом DataLens — со всеми селекторами и возможностью выгрузки данных.

{width=70%}

Рисунок 7.4 — главная страница CRM с открытым дашбордом во встроенном фрейме

#8. Экспорт и импорт воркбука

#Зачем это нужно

Воркбук можно выгрузить в JSON-файл и использовать как шаблон для другого клиента или проекта — не нужно создавать всё с нуля.

#Экспорт

В правом верхнем углу воркбука нажмите «три точки ...» → Экспортировать. DataLens сохранит .json-файл на ваш компьютер со структурой всех объектов воркбука.

{width=70%}

Рисунок 8.1 — меню воркбука с пунктом «Экспортировать»

#Импорт

При создании воркбука в диалоге «Создать воркбук» есть секция «Импорт из файла» с кнопкой Выбрать файл. Выберите .json-файл — DataLens восстановит структуру со всеми объектами.

{width=70%}

Рисунок 8.2 — диалог «Создать воркбук» с секцией «Импорт из файла»

Подробнее в официальной документации: Экспорт и импорт воркбукаПереход на внешний сайтhttps://yandex.cloud/ru/docs/datalens/workbooks-collections/workbooks

#9. Справочник таблиц MacroData

#Основные таблицы MacroData

Ниже приведён краткий справочник наиболее востребованных таблиц MacroData для аналитики в сфере недвижимости. Полное описание всех таблиц с полями и связями доступно в документации MacroDataПереход на внешний сайтhttps://api.macroserver.ru/docs/macroData/1/.