Власні картки на дашбордах нативної статистики

Якщо серед готових карток нативної статистики нема потрібного показника, його можна порахувати власним запитом. Запит пишуть на SQL до бази MySQL інстансу або як aggregation pipeline до Mongo. Перед збереженням його перевіряють кнопкою «Протестувати», а збережену картку кладуть на власний дашборд поруч із готовими. Фільтри дашборда (період, канал, оператор тощо) можна підставити в запит.

Коли знадобиться

• Потрібен показник, якого нема серед готових карток: власне групування, поле чи розріз.
• Аналітику потрібна таблиця з тими колонками, які він сам обере, з вивантаженням у CSV/XLSX.
• Потрібно швидко перевірити гіпотезу на даних інстансу, не замовляючи нову картку.

Що важливо знати

• Функція внутрішня. Її вмикає лише команда ConnectiveOne і лише для своїх адміністраторів; на інстансах клієнтів вона не вмикається. Потрібні нативна статистика і власні дашборди.
• Запит лише читає дані. Дозволено один запит SELECT або WITH. Зміни даних, кілька запитів через ;, службові схеми (mysql, information_schema, performance_schema, sys) і функції на кшталт SLEEP відхиляються ще до виконання. Вдруге це перевіряє сама база: запит виконується в сесії лише для читання.
• Лише поточна база інстансу. Звертатися до таблиць іншої бази на тому самому сервері (інша_база.таблиця) не можна: такий запит відхиляється і під час тесту, і під час збереження, і під час показу картки. Таблиці своєї бази пишіть без префікса або з назвою поточної бази. Псевдонім таблиці, що збігся з назвою іншої бази на сервері, теж відхиляється — дайте йому іншу назву.
• Лише видимі символи в запиті MySQL. Керівні символи (крім табуляції й переносу рядка), невидимі символи (нульової ширини, BOM, знаки напрямку тексту) і нестандартні пробіли (нерозривний, вузький тощо) заборонені будь-де в запиті, навіть у лапках: перевірка й база могли б прочитати такий запит по-різному. Такі символи часто потрапляють у текст під час копіювання з документів чи месенджерів — передрукуйте пробіли. Якщо такий символ потрібен у значенні, задайте його через CHAR() (нерозривний пробіл — CHAR(0xC2A0 USING utf8mb4)) або передайте значенням фільтра.
• Коментарі /*! … */ з номером версії (/*!50700 … */), /*M! … */ і коментар усередині такого коментаря відхиляються, якщо сервер міг би прочитати їх по-різному залежно від версії. Звичайні коментарі --, # і /* … */ дозволені.
• Mongo — строгий JSON {"collection": "…", "pipeline": [ … ]}. Стадії запису ($out, $merge), службові стадії, $where, $function і $accumulator, колекції system.*, а також звертання до іншої бази ({"db": …, "coll": …} у $lookup, $unionWith, $graphLookup) заборонені.
• Ліміти виконання: до 30 секунд на запит, до 10 000 рядків результату. Якщо рядків більше, буде показано перші 10 000 з позначкою, що результат обрізано; файл вивантаження тоді закінчується рядком-приміткою про обрізання. Ті самі ліміти діють для тесту, для картки на дашборді й для вивантаження.
• Ліміти картки: назва до 120 символів, запит до 20 000 символів, до 20 прив'язок фільтрів, до 200 власних карток на інстанс.
• Одна картка — одне джерело. MySQL і Mongo в одній картці поєднати не можна.
• Картка на дашборді — посилання. Якщо змінити запит, усі дашборди з цією карткою покажуть нові дані. Якщо видалити картку, на дашбордах на її місці буде сіра плитка «Картка недоступна».

Права доступу

Права видає адміністратор у Налаштування → Ролі → Статистика.

За замовчуванням право «Власні картки» вимкнене. Без «Збереження» дашбордів воно не діє.

Перш ніж видати «Власні картки», врахуйте: це право дає змогу прочитати будь-яку несистемну таблицю MySQL чи колекцію Mongo інстансу, без обмеження роллю, скіл-групою чи оператором. Видавайте його лише довіреним внутрішнім користувачам, наприклад аналітикам.

Перед початком

• На інстансі ввімкнено нативну статистику, власні дашборди і власні картки.
• Ваша роль має «Збереження» в рядку «Власні дашборди» і право «Власні картки».
• Ви знаєте, в якій таблиці чи колекції лежать потрібні дані і як називаються поля.

Покрокова інструкція: створити картку

1. Відкрийте Меню → Статистика → «Власні дашборди», оберіть дашборд і натисніть «Редагувати».

2. Натисніть «+ Картки» і в групі «Власні картки» натисніть «+ Власна картка».

3. Введіть назву, оберіть джерело (MySQL або Mongo) і вигляд: число, таблиця, стовпчики, лінія, область, круг або рядки.

4. Напишіть запит. Приклад для MySQL — кількість кімнат за каналами:

   SELECT kw_channel AS channel, COUNT(*) AS rooms
   FROM op_chat_rooms
   WHERE 1=1 [[AND {{period}}]]
   GROUP BY kw_channel
   

5. Якщо картка має реагувати на фільтри дашборда, додайте прив'язки (див. нижче). У прикладі це прив'язка фільтра «Дата» до плейсхолдера period і поля op_chat_rooms.createdAt.

6. Натисніть «Протестувати». Запит виконається з фільтрами, які зараз вибрані на дашборді, і внизу з'явиться результат у вибраному вигляді та рядок «Виконано за … с · рядків: N».

7. Натисніть «Зберегти». Картка з'явиться в групі «Власні картки», і її можна додати на дашборд, як готову.

Приклад для Mongo — діалоги за каналами:

{"collection": "statistics",
 "pipeline": [
   {"$match": "{{period}}"},
   {"$group": {"_id": "$channel", "dialogs": {"$sum": 1}}},
   {"$project": {"_id": 0, "channel": "$_id", "dialogs": 1}}
 ]}

Тут прив'язка фільтра «Дата» до period і поля createdAt. Дати в запиті пишуть як {"$date": "2026-10-01T00:00:00Z"}.

Фільтри дашборда в запиті

Фільтр потрапляє в запит лише через прив'язку: фільтр → плейсхолдер → поле. Плейсхолдер пишуть у запиті як {{назва}} (латиниця в нижньому регістрі, цифри, _). Поле для MySQL — колонка або таблиця.колонка, для Mongo — шлях до поля без $.

• Блок [[ … ]] — необов'язкова частина запиту. Якщо фільтр у блоці не вибрано, блок прибирається. Тому WHERE 1=1 [[AND {{period}}]] працює і з періодом, і без нього.
• Значення фільтрів екрануються перед підстановкою в запит, тож лапки чи спецсимволи у значенні запит не зламають.
• Дужки [[ і ]] пишуться лише в самому запиті, не всередині рядка в лапках, назви в зворотних лапках чи коментаря. Інакше запит буде відхилено.
• Плейсхолдер без прив'язки — помилка «невідомий плейсхолдер».
• Часовий пояс. Для MySQL межі періоду — це календарні дати так, як вони записані в таблиці. Селектор «Часовий пояс» їх не зсуває, так само як у готових SQL-картках нативної статистики. Для Mongo межі періоду рахуються в поясі, вибраному в панелі.
• Картка без прив'язок не реагує на фільтри дашборда і завжди показує одне й те саме.

Як результат стає графіком

Окремого налаштування осей нема, вигляд береться з типів і порядку колонок результату:

• стовпчики, лінія, область, рядки — категорія або дата і числа. Категорією стає перша нечислова колонка, числові колонки стають значеннями, хоч би де вони стояли в результаті. Так у Mongo $project поле-число може йти раніше за назву. Якщо всі колонки числові або всі текстові, категорією стає перша колонка. Для стовпчиків з накопиченням поверніть три колонки: дата, категорія, значення;
• круг — дві колонки: назва і число, у будь-якому порядку;
• число — перша числова колонка першого рядка;
• таблиця — усі колонки, з вивантаженням у CSV/XLSX.

Дайте колонкам зрозумілі псевдоніми через AS: вони стануть заголовками. Дві колонки з однаковою назвою — помилка.

Змінити або видалити картку

1. У режимі редагування дашборда відкрийте «+ Картки» → «Власні картки».
2. Натисніть олівець біля картки, щоб змінити її, або ✕, щоб видалити. Перед видаленням система покаже, на скількох дашбордах лежить картка.

Якщо картку щойно змінив хтось інший, збереження не пройде: оновіть картку й повторіть зміни.

Як переконатися, що все вдалось

• Тест показує результат і рядок «Виконано за … с · рядків: N».
• Порівняйте число з тим самим запитом у базі за ті самі дати.
• Змініть період на дашборді й натисніть «Застосувати»: картка з прив'язкою до дати змінить число, картка без прив'язок — ні.

Можливі проблеми

Пов'язані матеріали

• Власні дашборди в нативній статистиці
• Як застосувати фільтри звіту
• Як експортувати дані статистики