Работа с базой данных

SDK предоставляет мощный API для работы с коллекциями базы данных EMD Cloud. Вы можете выполнять CRUD операции, фильтровать данные с помощью MongoDB-style запросов, сортировать и пагинировать результаты.

Создание экземпляра database

Для работы с коллекцией необходимо создать экземпляр database, указав ID коллекции:

const usersDb = emdCloud.database('users-collection-id');
const ordersDb = emdCloud.database('orders-collection-id');
const productsDb = emdCloud.database('products-collection-id');

подсказка

Каждый экземпляр привязан к конкретной коллекции, поэтому создавайте отдельные экземпляры для каждой коллекции, с которой работаете.

Ключевые особенности

Human-Readable Names

Многие методы поддерживают параметр useHumanReadableNames, который заменяет технические идентификаторы колонок (например, col_xxx) на читаемые имена полей (например, name, email, status) в JSON ответах.

// С техническими идентификаторами
{
  "col_123": "Иван",
  "col_456": "ivan@example.com"
}

// С читаемыми именами (useHumanReadableNames: true)
{
  "name": "Иван",
  "email": "ivan@example.com"
}

Режимы сохранения

Операции обновления поддерживают два режима:

SYNC (по умолчанию) — синхронное сохранение, ждет завершения операции
ASYNC — асинхронное сохранение, возвращает результат сразу

Методы чтения данных

getRows()

Получает список записей с поддержкой фильтрации, сортировки и пагинации.

Синтаксис

await db.getRows(options, callOptions);

Параметры

Параметр	Тип	Описание
`query`	`object`	MongoDB-style запрос с операторами `$and`, `$or`, `$eq`, `$ne`, `$gt`, `$lt` и др.
`sort`	`array`	Массив объектов сортировки: `[{column: 'fieldName', sort: 'asc\|desc'}]`
`limit`	`number`	Максимальное количество записей (по умолчанию: 50)
`page`	`number`	Номер страницы для пагинации (начиная с 0)
`search`	`string`	Текстовый поиск по коллекции
`hasOptimiseResponse`	`boolean`	Оптимизация размера ответа
`useHumanReadableNames`	`boolean`	Использовать читаемые имена полей

Примеры

Простой запрос:

const result = await usersDb.getRows({
  limit: 20,
  page: 0
});

console.log('Всего пользователей:', result.count);
console.log('Данные:', result.data);

С фильтрацией:

const result = await usersDb.getRows({
  query: {
    "$and": [
      { "data.status": { "$eq": "active" } },
      { "data.age": { "$gt": 18 } }
    ]
  },
  limit: 50
});

С сортировкой:

const result = await usersDb.getRows({
  sort: [
    { column: "createdAt", sort: "desc" },
    { column: "name", sort: "asc" }
  ],
  limit: 20
});

С читаемыми именами:

const result = await usersDb.getRows({
  query: {
    "$and": [{ "data.status": { "$eq": "active" } }]
  },
  useHumanReadableNames: true
}, {
  authType: 'auth-token'
});

// Результат с читаемыми именами полей
console.log(result.data[0].name); // вместо result.data[0].col_123

Текстовый поиск:

const result = await usersDb.getRows({
  search: "Иван",
  limit: 10
});

countRows()

Подсчитывает количество записей, соответствующих запросу, без возврата самих данных.

Синтаксис

await db.countRows(options, callOptions);

Параметры

Параметр	Тип	Описание
`query`	`object`	MongoDB-style запрос
`search`	`string`	Текстовый поиск
`createdAt`	`string`	Фильтр по дате создания

Примеры

const result = await usersDb.countRows({
  query: {
    "$and": [{ "data.status": { "$eq": "active" } }]
  }
});

console.log('Активных пользователей:', result.count);

getRow()

Получает одну запись по её уникальному идентификатору.

Синтаксис

await db.getRow(rowId, options, callOptions);

Параметры

Параметр	Тип	Описание
`rowId`	`string`	Уникальный ID записи
`useHumanReadableNames`	`boolean`	Использовать читаемые имена полей

Примеры

const user = await usersDb.getRow(
  '60a7c8b8f123456789abcdef',
  { useHumanReadableNames: true },
  { authType: 'auth-token' }
);

console.log('Пользователь:', user.name, user.email);

Методы создания и обновления

createRow()

Создает новую запись в коллекции.

Синтаксис

await db.createRow(rowData, options, callOptions);

Параметры

Параметр	Тип	Описание
`rowData`	`object`	Данные для новой записи
`user`	`string`	ID пользователя для связи с записью
`notice`	`string`	Комментарий к операции
`useHumanReadableNames`	`boolean`	Использовать читаемые имена в ответе

Примеры

const newUser = await usersDb.createRow(
  {
    name: 'Иван Иванов',
    email: 'ivan@example.com',
    status: 'active',
    age: 25
  },
  {
    notice: 'Создан через API'
  },
  {
    authType: 'auth-token'
  }
);

console.log('Создан пользователь с ID:', newUser._id);

updateRow()

Обновляет существующую запись.

Синтаксис

await db.updateRow(rowId, rowData, options, callOptions);

Параметры

Параметр	Тип	Описание
`rowId`	`string`	ID записи для обновления
`rowData`	`object`	Данные для обновления
`user`	`string`	ID пользователя
`notice`	`string`	Комментарий к операции
`saveMode`	`'SYNC'\|'ASYNC'`	Режим сохранения (по умолчанию: SYNC)
`useHumanReadableNames`	`boolean`	Использовать читаемые имена

Примеры

Синхронное обновление:

const updated = await usersDb.updateRow(
  '60a7c8b8f123456789abcdef',
  {
    status: 'inactive',
    updatedAt: new Date().toISOString()
  },
  {
    notice: 'Деактивирован пользователь',
    saveMode: 'SYNC'
  },
  {
    authType: 'auth-token'
  }
);

Асинхронное обновление:

// Для быстрого ответа без ожидания завершения
const updated = await usersDb.updateRow(
  '60a7c8b8f123456789abcdef',
  { lastSeen: new Date().toISOString() },
  { saveMode: 'ASYNC' }
);

bulkUpdate()

Обновляет несколько записей, соответствующих запросу, за одну операцию.

Синтаксис

await db.bulkUpdate(payload, callOptions);

Параметры

Параметр	Тип	Описание
`query`	`object`	MongoDB-style запрос для выбора записей
`data`	`object`	Данные для обновления
`notice`	`string`	Комментарий к операции

Примеры

// Активировать всех пользователей со статусом "pending"
const result = await usersDb.bulkUpdate(
  {
    query: {
      "$and": [{ "data.status": { "$eq": "pending" } }]
    },
    data: {
      status: "active",
      activatedAt: new Date().toISOString()
    },
    notice: "Массовая активация пользователей"
  },
  {
    authType: 'auth-token'
  }
);

console.log('Обновлено записей:', result.updated);

Методы удаления

deleteRow()

Удаляет одну запись по её ID.

Синтаксис

await db.deleteRow(rowId, callOptions);

Примеры

await usersDb.deleteRow(
  '60a7c8b8f123456789abcdef',
  { authType: 'auth-token' }
);

console.log('Запись удалена');

deleteRows()

Удаляет несколько записей по их ID за одну операцию.

Синтаксис

await db.deleteRows(rowIds, callOptions);

Примеры

const result = await usersDb.deleteRows(
  [
    '60a7c8b8f123456789abcdef',
    '60a7c8b8f123456789abcdeg',
    '60a7c8b8f123456789abcdeh'
  ],
  { authType: 'auth-token' }
);

console.log('Удалено записей:', result.deleted);

Специальные методы

triggerButton()

Запускает действие кнопки на конкретной записи. Используется для выполнения кастомных workflow или действий, определенных в вашей коллекции.

Синтаксис

await db.triggerButton(rowId, columnId, callOptions);

Параметры

Параметр	Тип	Описание
`rowId`	`string`	ID записи с кнопкой
`columnId`	`string`	ID колонки с кнопкой

Примеры

// Одобрить заказ через кнопку
const result = await ordersDb.triggerButton(
  '60a7c8b8f123456789abcdef',
  'approve-button-column-id',
  { authType: 'auth-token' }
);

console.log('Действие выполнено:', result);

MongoDB-style запросы

SDK поддерживает MongoDB-style операторы для построения сложных запросов:

Операторы сравнения

// Равно
{ "data.status": { "$eq": "active" } }

// Не равно
{ "data.status": { "$ne": "deleted" } }

// Больше
{ "data.age": { "$gt": 18 } }

// Больше или равно
{ "data.age": { "$gte": 18 } }

// Меньше
{ "data.price": { "$lt": 1000 } }

// Меньше или равно
{ "data.price": { "$lte": 1000 } }

// В списке значений
{ "data.status": { "$in": ["active", "pending"] } }

// Не в списке
{ "data.status": { "$nin": ["deleted", "banned"] } }

Логические операторы

// И (все условия должны выполняться)
{
  "$and": [
    { "data.status": { "$eq": "active" } },
    { "data.age": { "$gte": 18 } }
  ]
}

// ИЛИ (хотя бы одно условие)
{
  "$or": [
    { "data.status": { "$eq": "active" } },
    { "data.status": { "$eq": "pending" } }
  ]
}

// Комбинированные запросы
{
  "$and": [
    {
      "$or": [
        { "data.type": { "$eq": "premium" } },
        { "data.type": { "$eq": "vip" } }
      ]
    },
    { "data.status": { "$eq": "active" } }
  ]
}

Практические примеры

Пагинация

const PAGE_SIZE = 20;
let currentPage = 0;

async function loadPage(page) {
  const result = await usersDb.getRows({
    limit: PAGE_SIZE,
    page: page,
    sort: [{ column: "createdAt", sort: "desc" }]
  });
  
  return {
    data: result.data,
    totalPages: Math.ceil(result.count / PAGE_SIZE),
    currentPage: page,
    total: result.count
  };
}

// Загрузить первую страницу
const firstPage = await loadPage(0);

Поиск и фильтрация

async function searchUsers(searchTerm, filters = {}) {
  const query = { "$and": [] };
  
  // Добавляем фильтры
  if (filters.status) {
    query["$and"].push({
      "data.status": { "$eq": filters.status }
    });
  }
  
  if (filters.minAge) {
    query["$and"].push({
      "data.age": { "$gte": filters.minAge }
    });
  }
  
  const result = await usersDb.getRows({
    query: query["$and"].length > 0 ? query : undefined,
    search: searchTerm,
    limit: 50,
    useHumanReadableNames: true
  });
  
  return result.data;
}

// Использование
const users = await searchUsers("Иван", {
  status: "active",
  minAge: 18
});

CRUD операции

// Create
const newProduct = await productsDb.createRow({
  name: "Новый товар",
  price: 999,
  category: "electronics",
  inStock: true
});

// Read
const product = await productsDb.getRow(newProduct._id);

// Update
await productsDb.updateRow(newProduct._id, {
  price: 899,
  discount: 10
});

// Delete
await productsDb.deleteRow(newProduct._id);

Best Practices

Используйте читаемые имена

// ✅ Хорошо: легко читать и поддерживать
const users = await usersDb.getRows({
  useHumanReadableNames: true
});

console.log(users.data[0].name); // понятно

Оптимизируйте запросы

// ✅ Хорошо: получаем только нужные данные
const result = await usersDb.getRows({
  query: { "$and": [{ "data.status": { "$eq": "active" } }] },
  limit: 20, // не загружаем все данные
  hasOptimiseResponse: true
});

// ❌ Плохо: загружаем все данные
const all = await usersDb.getRows({ limit: 10000 });

Обрабатывайте ошибки

try {
  const user = await usersDb.createRow(userData);
} catch (error) {
  if (error.status === 400) {
    console.error('Неверные данные:', error.message);
  } else if (error.status === 403) {
    console.error('Нет прав доступа');
  } else {
    console.error('Ошибка создания:', error);
  }
}

Следующие шаги

💬 Узнайте о работе с чатами
📁 Изучите загрузку файлов
💡 Посмотрите примеры использования

Создание экземпляра database​

Ключевые особенности​

Human-Readable Names​

Режимы сохранения​

Методы чтения данных​

getRows()​

Синтаксис​

Параметры​

Примеры​

countRows()​

Синтаксис​

Параметры​

Примеры​

getRow()​

Синтаксис​

Параметры​

Примеры​

Методы создания и обновления​

createRow()​

Синтаксис​

Параметры​

Примеры​

updateRow()​

Синтаксис​

Параметры​

Примеры​

bulkUpdate()​

Синтаксис​

Параметры​

Примеры​

Методы удаления​

deleteRow()​

Синтаксис​

Примеры​

deleteRows()​

Синтаксис​

Примеры​

Специальные методы​

triggerButton()​

Синтаксис​

Параметры​

Примеры​

MongoDB-style запросы​

Операторы сравнения​

Логические операторы​

Практические примеры​

Пагинация​

Поиск и фильтрация​

CRUD операции​

Best Practices​

Используйте читаемые имена​

Оптимизируйте запросы​

Обрабатывайте ошибки​

Следующие шаги​

Полезные ссылки​

Создание экземпляра database

Ключевые особенности

Human-Readable Names

Режимы сохранения

Методы чтения данных

getRows()

Синтаксис

Параметры

Примеры

countRows()

Синтаксис

Параметры

Примеры

getRow()

Синтаксис

Параметры

Примеры

Методы создания и обновления

createRow()

Синтаксис

Параметры

Примеры

updateRow()

Синтаксис

Параметры

Примеры

bulkUpdate()

Синтаксис

Параметры

Примеры

Методы удаления

deleteRow()

Синтаксис

Примеры

deleteRows()

Синтаксис

Примеры

Специальные методы

triggerButton()

Синтаксис

Параметры

Примеры

MongoDB-style запросы

Операторы сравнения

Логические операторы

Практические примеры

Пагинация

Поиск и фильтрация

CRUD операции

Best Practices

Используйте читаемые имена

Оптимизируйте запросы

Обрабатывайте ошибки

Следующие шаги

Полезные ссылки