Как правильно читать и записывать DateTime в кастомные таблицы

📅 Работа с датой и временем в Metabot

В Metabot работа с датой и временем имеет важную особенность, о которой легко не узнать — в документации она описана фрагментарно.
Этот урок объясняет как правильно работать с DateTime, чтобы данные гарантированно сохранялись в базе данных и корректно отображались.

🔹 Как хранятся дата и время в базе данных

В кастомных таблицах Metabot используется база данных PostgreSQL.

Поля типа даты и времени имеют тип:

DATETIME

Это означает:

• дата и время хранятся без временной зоны
• формат хранения:

YYYY-MM-DD HH:mm:ss

Пример корректного значения в базе:

2026-01-17 11:48:06

❌ Частая ошибка: запись new Date() напрямую

В JavaScript на платформе Metabot нельзя напрямую записывать объект Date в кастомную таблицу.

❌ Неправильно:

table.createItem('nav_actor_missions', {
  completed_at: new Date()
});

Такое значение не будет сохранено, даже если остальные поля записались успешно.

Причина:
new Date() — это JS-объект, а база данных ожидает строку.

❌ Почему не работает toISOString()

Многие пробуют использовать ISO-строку:

new Date().toISOString()
// "2026-01-17T08:48:06.921Z"

❌ Это тоже не работает для DATETIME.

Почему:

• символ T между датой и временем
• суффикс Z (UTC)
• миллисекунды .921

Все эти элементы не совместимы с DATETIME без таймзоны.

✅ Правильный способ: getDateFormattedString

В Metabot есть встроенный безопасный метод, который решает проблему полностью:

✔ bot.getDateFormattedString()

let now = new Date();
let nowStr = bot.getDateFormattedString(now);
// "2026-01-17 11:48:06"

Это канонический формат, который:

• корректно сохраняется в DATETIME
• не ломает апдейты
• не зависит от БД-драйвера

🧠 Важно понимать про временные зоны

Как это работает в Metabot:

• new Date() возвращает время в таймзоне сервера
• в базу данных дата пишется без таймзоны
• при чтении из БД вы получаете время сервера

👉 Это нормально и правильно.

Когда учитывать таймзону пользователя?

• при выводе в интерфейс
• в отчётах
• в аналитике

Но не при записи в БД.

🔁 Преобразование дат (FAQ)

📌 Преобразовать строку даты в нужный формат

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 — это не абстрактный объект, а строка кастомной таблицы (элемент Custom Table), полученная, например, через:

• table.find(...)
• table.createItem(...)
• row в результате update()

Каждый такой item (строка кастомной таблицы) имеет тот же метод getDateFormattedString, что и объект bot.

Это означает:

• ✅ bot.getDateFormattedString(...) — используется для форматирования текущего времени, логов, дат из внешних источников
• ✅ item.getDateFormattedString(...) — используется для форматирования дат, связанных с конкретной строкой таблицы

Метод работает одинаково в обоих случаях и возвращает строку в формате, совместимом с DATETIME.

📖 Подробнее о методе item.getDateFormattedString и его использовании см. в отдельной документации: 👉 https://docs.metabot24.ru/books/05-low-code-full-code/page/itemgetdateformattedstring

📌 Использовать дату из логов или БД

data.msg_at = bot.getDateFormattedString(
  new Date(lastLog.updated_at)
);

📌 Генерация идентификаторов с датой

let sessionId = leadId + '_' + bot.getDateFormattedString(
  new Date(),
  'YmdHis'
);

Результат:

12345_20260117114806

🧩 Пример: корректная запись DateTime в кастомную таблицу

let now = new Date();
let nowStr = bot.getDateFormattedString(now);

table.createItem('nav_actor_missions', {
  actor_id: leadId,
  status: 'completed',
  completed_at: nowStr
});

✔ Дата сохранится
✔ Ошибок не будет
✔ Поле не останется NULL

🚨 Итоговые правила (коротко)

❌ Нельзя:

• писать new Date() напрямую
• писать toISOString()
• писать ISO-строки с T и Z

✅ Нужно:

• всегда использовать getDateFormattedString
• писать дату в формате Y-m-d H:i:s
• хранить дату во времени сервера

🧭 Рекомендация

Если вы работаете с кастомными таблицами и DateTime:

Считайте getDateFormattedString обязательным инструментом.
Это часть контракта между JavaScript и базой данных Metabot.