Кастомные таблицы
«После того, как бизнес-данные были централизованы и интегрированы, ценность базы данных больше, чем сумма ранее существовавших частей».
— Ларри Эллисон, основатель Oracle
Независимо от того, по какой причине вы создаете приложение (для личного использования, для ваших клиентов, для управления вашим бизнесом), при разработке приложения вам нужен доступ к данным. Вы можете хранить свои данные в разных местах, но важно чтобы у вас был сервис базы данных (БД) и доступ к ней.
Кастомные таблицы — удобное и практичное хранилище данных, которое вы можете использовать как составную часть решения, создаваемого на Metabot, так и как отдельный сервис, доступный по API из других приложений и платформ.
Кастомные таблицы от Metabot — это альтернатива (или дополнение) к таким продуктам как Google Sheets, AirTable и Notion, созданное специально для разработки приложений с бизнес-логикой.
Примеры использования:
- таблица пользователей для регистрации/авторизации и личного кабинета в мессенджере
- таблицы заявок или заказов, заполняемая ботом, как замена формы
- таблицы, представляющие операционную модель вашего бизнеса (ERP)
- таблицы для учёта выдачи материалов на мероприятии
Используя кастомные таблицы в сочетании с диалоговыми сценариями, JavaScript и API конструктором вы сможете создать фронтенд и бэкэнд, которая заменят вам мобильное приложение и серверный бэкэнд.
Таблицы незаменимы при реализации глубоких интеграций мессенджеров в процессы предприятия, диалогового интерфейса к системам предприятия и диалогового подключенного опыта (CCX) — таблицы используются для хранения данных для синхронизации систем.
Обращаться к таблицам вы можете прямо в диалоговых сценариях вашего бота, через методы JS: вы сможете выполнять операции работы с таблицей, такие как, поиска записей, их редактирования, удаления.
Если вам необходимо обратиться к таблицам Metabot из внешних систем, для этого вы можете создать внутренние API эндпоинты.
С помощью плагина вы сможете расширить методы работы с таблицами, например, сделав прямые обращение к базе данных и вызов SQL.
Работа с SQL доступна на выделенном сервере и в on-premise коробочной версии.
Конструктор таблиц
Конструктор таблиц находится в верхнем меню бота в разделе Таблицы:
Он предназначен для работы с таблицами, например, для создания таблиц, их форматирования и удаления.
Для создания таблицы необходимо нажать кнопку Создать:
В открывшемся окне Создание таблицы можно заполнить информацию о создаваемой таблице:
- Активна - если опция отключена, то просмотр и редактирование будут недоступны, также таблица будет скрыта из меню быстрого доступа.
- Синхронизация структуры - если опция отключена, то синхронизация структуры таблицы с базой данных (БД) не будет выполняться. Отключение опции используется когда все поля в БД создаются вручную.
Опция Синхронизация структуры доступна только администраторам платформы.
- Отображать в меню - если данная опция включена, то таблица будет отображаться в выпадающем списке раздела Таблицы верхнего меню бота.
- Наименование - название таблицы, которое будет использоваться при обращении к ней методами.
В имени таблицы можно указывать только латиницу (только нижний регистр), цифры и подчеркивание.
- Заголовок в интерфейсе - название таблицы, которое будет отображаться в интерфейсе.
- Комментарий - пояснение к таблице.
- JSON словарь - JSON словарь используется для отображения данных, а также для построения форм редактирования данных. Генерируется автоматически при редактировании структуры таблицы или нажатии на кнопку "Обновить все поля" на странице списка таблиц.
После создания таблицы появляются функции ее редактирования, удаления, создания полей и их обновления в БД:
Конструктор полей
Чтобы заполнить таблицу данными, нужно для начала создать ей соответствующие поля. Это можно сделать при помощи операции Структура:
Первым полем любой таблицы всегда является ID строки. Это поле создается автоматически при создании таблицы и не подлежит удалению. По этому полю вы сможете идентифицировать отдельные строки таблицы, а также искать и редактировать записи через JS.
Остальные необходимые поля можно добавить щелкнув по кнопке Создать:
В открывшемся окне Создание поля необходимо заполнить информацию о создаваемом поле:
- Активно - если опция отключена, то поле не будет доступно для просмотра и редактирования.
- Наименование - название поля, которое будет использоваться при обращении к нему методами.
В имени поля можно указывать только латиницу (только нижний регистр), цифры и подчеркивание.
- Заголовок в интерфейсе - название поля, которое будет отображаться в интерфейсе.
- Тип - тип данных поля (текст, число, число с точкой и т.д.)
- Обязательное поле - если данная опция включена, то в поле не может быть задано значение NULL.
- Значение по умолчанию - предустановленное значение поля.
- Размер - максимальное количество символов в данном поле.
- Точность - количество символов в числе после точки.
- Подсказка в интерфейсе - подсказка отображаемая в интерфейса в режиме просмотра и редактирования данных.
- Всплывающая подсказка в интерфейсе - подсказка в интерфейсе, возникающая при наведении мышкой на знак вопроса рядом с полем.
После создания и настройки всех ячеек таблицы можно провести обновление таблицы в базе данных платформы. Для это необходимо в конструкторе таблиц нажать Обновить все поля в БД:
Это синхронизирует и обновит таблицу в базе данных, а так же сгенерирует ее JSON словарь (Структуру таблицы).
На текущий момент, в качестве базы данных платформа Metabot поддерживает PostgreSQL.
Формирование модели данных через текстовое описание мета-словаря на базе JSON в текущей версии не доступно.
Просмотр и редактирование данных
После создания структуры таблицы можно вручную заполнить ее данными. Для этого необходимо зайти в Данные в конструкторе таблиц либо, если вы включали опцию Отображать в меню, то нажать на название таблицы в выпадающем списке раздела Таблицы верхнего меню бота.
После этого нажмите на кнопку Создать и добавьте необходимые данные.
После создания запись появится в таблице. Записи так же можно редактировать и удалять.
По итогу у вас получится таблица, которая может выглядеть, например, так:
Данная таблица "Регионы" будет использоваться для примеров использования методов далее.
JS методы для работы с кастомными таблицами
К кастомным таблицам можно обращаться из JS следующими методами:
| Название метода | Метод |
| Создание записи | table.createItem(string $tableName, array|object $data): ScriptCustomTableItem |
| Поиск записей |
table.find(string $tableName, array|object $columns = [], array|object $where = [], array|object $orderBy = [], ?int $limit = null, ?int $offset = null): array |
| Подсчет количества записей |
table.count(string $tableName, array|object $where = []): int |
|
Подсчет суммы по полю |
table.sum(string $tableName, string $column, array|object $where = []): int |
|
Поиск максимального значения по полю |
table.max(string $tableName, string $column, array|object $where = []): mixed|null |
|
Обновление записи |
item.update(array|object $data): bool |
|
Удаление записи |
item.delete(): bool |
|
Получить форматированную дату по названию поля |
item.getDateFormatted(string $fieldName, string $format = 'Y-m-d H:i:s', ?string $timeZone = null): string|null |
|
Получить форматированную дату из произвольной строки |
item.getDateFormattedString(string|DateTimeInterface $date, string $toFormat = 'Y-m-d H:i:s', string|null $fromFormat = 'Y-m-d H:i:s', string|null $toTimeZone = null, string|null $fromTimeZone = null): string|null |
|
Перезагрузить данные записи из БД |
item.reload(): bool |
За объект item принимаем запись кастомной таблицы полученную с помощью table.createItem или table.find.
Каждый из методов подробнее расписан ниже.
Создание записи
table.createItem(string $tableName, array|object $data)Описание:
Создает запись в таблице и возвращает значение этой записи, как объект.
Атрибуты:
| Имя | Тип | Описание |
|
tableName |
string | Наименование таблицы, в которой будет создана запись |
| data | array | object ( json{} ) | Значения | значение записи |
Возвращает:
ScriptCustomTableItem - все значения полей записи в формате объекта.
Пример:
Добавление данных в кастомную таблицу regions:
var region = {
"name": "Юго-Восточный",
"comment": "Cоздано через v8"
};
var newRegion = table.createItem('regions', region);Поиск записей
table.find(string $tableName, array|object $columns = [], array|object $where = [], array|object $orderBy = [], ?int $limit = null, ?int $offset = null): arrayОписание:
Ищет записи в таблице и возвращает их в виде массива объектов.
Атрибуты:
| Имя | Тип | Описание |
| tableName | string | Наименование таблицы, в которой будет найдена запись |
|
columns |
array | object ( json{} ) | Столбцы которые будут возвращены в ответе |
|
where |
array | object ( json{} ) | Условие, которое будет проверяться при поиске |
|
orderBy |
array | object ( json{} ) | Устанавливает в какой последовательности будут возвращены выходные значения |
|
limit |
int | Устанавливает максимальное количество возвращенных значений |
|
offset |
int | Устанавливает смещение |
Возвращает:
array - массив объектов (найденных записей).
Примеры:
Получение всех регионов (лимит 100):
var items = table.find('regions');
var regions = [];
for(var i = 0; i < items.length; i++) { // добавление поочередно всех записей в объект regions
var item = items[i];
regions.push({"id": item.id, "name": item.name, "comment": item.comment});
}Получение трех значений поля region с id больше двух:
var columns = ['region'];
var where = [["id", ">", 2]];
var orderBy = [];
var limit = 3;
var offset = 0;
let items = table.find('regions', columns, where, orderBy, limit, offset);Подсчет количества записей
table.count(string $tableName, array|object $where = [])Описание:
Ищет записи соответствующие условию метода в таблице и возвращает их количество.
Атрибуты:
| Имя | Тип | Описание |
| tableName | string | Наименование таблицы, в которой будет создана запись |
| where | array | object ( json{} ) | Условие, которое будет проверяться при поиске |
Возвращает:
int - количество записей в формате числа.
Примеры:
Получение количества всех записей в таблице:
var regionsCount = table.count("regions");
memory.setAttr('regionsCount', regionsCount);Получение количества записей с id больше 2:
var countRegionIdsGreather2 = table.count("regions", [["id", ">", 2]]);
memory.setAttr('countRegionIdsGreather2', countRegionIdsGreather2);Подсчет суммы по полю
table.sum(string $tableName, string $column, array|object $where = [])Описание:
Ищет записи соответствующие условию метода в таблице и возвращает сумму их значений.
Атрибуты:
| Имя | Тип | Описание |
| tableName | string | Наименование таблицы, в которой будет создана запись |
| column | string | Наименование поля из которого будут браться значения |
| where | array | object ( json{} ) | Условие, которое будет проверяться при поиске |
Возвращает:
int - сумма всех значений поля в виде числа.
Примеры:
Подсчет суммы всех значений записей поля id в таблице regions:
var sumRegionIds = table.sum("regions", 'id');
memory.setAttr('sumRegionIds', sumRegionIds);Подсчет суммы значений записей поля id в таблице regions с id больше нуля:
var sumRegionIds = table.sum("regions", 'id', [["id", ">", 0]]);
memory.setAttr('sumRegionIds', sumRegionIds);Поиск максимального значения по полю
table.max(string $tableName, string $column, array|object $where = [])Описание:
Ищет записи соответствующие условию метода в таблице и возвращает наибольшее по значению из них.
Атрибуты:
| Имя | Тип | Описание |
| tableName | string | Наименование таблицы, в которой будет создана запись |
| column | string | Наименование поля из которого будут браться значения |
| where | array | object ( json{} ) | Условие, которое будет проверяться при поиске |
Возвращает:
mixed - максимальное среди всех значений поля в том же типе, что в таблице
или
null - если максимальное значение не было найдено.
Примеры:
Нахождение максимального значения в поле id в таблице regions:
var maxRegionId = table.max("regions", 'id');
memory.setAttr('maxRegionId', maxRegionId);Нахождение максимального значения в поле id в таблице regions с id больше нуля:
var maxRegionId = table.max("regions", 'id', [["id", ">", 0]]);
memory.setAttr('maxRegionId', maxRegionId);Обновление записи
item.update(array|object $data)Описание:
Изменяет значение указанной записи item в таблице.
Атрибуты:
| Имя | Тип | Описание |
| data | array | object ( json{} ) | Значения | значение записи |
Возвращает:
bool - подтверждение удачного изменения записи.
Пример:
Обновление записи item:
var items = table.find('regions');
var item = items[0];
item.update({"name": item.name, "num": 77});Удаление записи
item.delete()Описание:
Удаляет указанную запись item в таблице.
Возвращает:
bool - подтверждение удачного удаления записи.
Пример:
Удаление всех записей из таблицы:
var items = table.find('regions');
for(var i = 0; i < items.length; i++) {
items[i].delete();
}Получить форматированную дату по названию поля
item.getDateFormatted(string $fieldName, string $toFormat = 'Y-m-d H:i:s', string|null $toTimeZone = null, string|null $fromTimeZone = null)Описание:
Возвращает значение даты измененного формата из запрашиваемого поля.
Атрибуты:
| Имя | Тип | Описание |
| fieldName | string | Наименование поля из которого будет браться значение |
| toFormat | string |
Формат даты, например: 'Y-m-d H:i:s' (Y - год; m - месяц; d - день; H - часы; i - минуты; s - секунды.) |
| toTimeZone | string|null | Часовой пояс в ответе |
| fromTimeZone | string|null | Часовой пояс в запросе |
Возвращает:
string -
или
null - если дата не требует форматирования.
Пример:
Возвращает значение даты измененного формата из поля create:
var date = item.getDateFormatted('create', 'd-m-Y H:i:s', 'Y-m-d H', 'UTC', '+3');Получить форматированную дату из произвольной строки
item.getDateFormattedString(string $date, string $toFormat = 'Y-m-d H:i:s', string|null $fromFormat = 'Y-m-d H:i:s', string|null $toTimeZone = null, string|null $fromTimeZone = null)Описание:
Меняет формат введенной даты.
Атрибуты:
| Имя | Тип | Описание |
| date | string |
Дата |
| toFormat | string |
Формат даты в ответе, например: 'Y-m-d H:i:s' (Y - год; m - месяц; d - день; H - часы; i - минуты; s - секунды.) |
| fromFormat | string|null |
Формат даты в запросе |
| toTimeZone | string|null | Часовой пояс в ответе |
| fromTimeZone | string|null | Часовой пояс в запросе |
Возвращает:
string -
или
null - если дата не требует форматирования.
Пример:
var date = item.getDateFormattedString('2022-02-01 12', 'd-m-Y H:i:s', 'Y-m-d H', 'UTC', '+3');Возвращает 01-02-2022 09:00:00
Перезагрузить данные записи из бд
item.reload()Описание:
Перезагружает значение записи из бд в таблицу.
Возвращает:
bool - подтверждение удачной перезагрузки записи.
Пример:
Перезагрузка всех записей таблицы:
var items = table.find('regions');
for(var i = 0; i < items.length; i++) {
items[i].reload();
}
Нет комментариев