Перейти к основному содержимому

JSON

Поле типа JSON используется для хранения структурированных данных в формате JSON (JavaScript Object Notation).

Основные характеристики​

  • Тип данных: JSON объект или массив
  • Максимальный размер: До 16 МБ
  • Валидация: Автоматическая проверка корректности JSON
  • Вложенность: Поддержка любого уровня вложенности

Когда использовать JSON​

JSON поля идеально подходят для:

  • Динамических структур данных с переменным набором полей
  • Конфигураций и настроек приложений
  • Метаданных с произвольной структурой
  • API ответов от внешних сервисов
  • Сложных объектов, которые не требуют отдельных полей

Настройки поля​

При создании поля типа "JSON" доступны следующие настройки:

  • Название поля: Отображаемое имя поля
  • Системное имя: Уникальный идентификатор для API
  • Описание: Подсказка для пользователей
  • Обязательное поле: Требовать заполнения
  • Значение по умолчанию: JSON объект или массив по умолчанию
  • Схема валидации: JSON Schema для проверки структуры (опционально)

Примеры использования​

Настройки пользователя​

{
  "name": "preferences",
  "type": "json",
  "default": {
    "theme": "light",
    "language": "ru",
    "notifications": {
      "email": true,
      "push": false
    }
  }
}

Адрес​

{
  "name": "address",
  "type": "json",
  "default": {
    "country": "",
    "city": "",
    "street": "",
    "building": "",
    "apartment": "",
    "zipCode": ""
  }
}

Метаданные товара​

{
  "name": "metadata",
  "type": "json",
  "default": {}
}

Характеристики товара​

{
  "name": "specifications",
  "type": "json",
  "default": {
    "dimensions": {
      "width": 0,
      "height": 0,
      "depth": 0,
      "unit": "cm"
    },
    "weight": {
      "value": 0,
      "unit": "kg"
    },
    "materials": []
  }
}

Работа через API​

Создание записи​

const record = await emd.database.collection('users').create({
  name: 'Иван Иванов',
  preferences: {
    theme: 'dark',
    language: 'ru',
    notifications: {
      email: true,
      push: true,
      sms: false
    }
  }
});

Чтение JSON поля​

const record = await emd.database.collection('users').get(recordId);
console.log(record.preferences.theme); // 'dark'
console.log(record.preferences.notifications.email); // true

Обновление всего объекта​

await emd.database.collection('users').update(recordId, {
  preferences: {
    theme: 'light',
    language: 'en',
    notifications: {
      email: false,
      push: true,
      sms: false
    }
  }
});

Обновление вложенного поля​

// Обновить только тему, сохранив остальные настройки
const record = await emd.database.collection('users').get(recordId);
await emd.database.collection('users').update(recordId, {
  preferences: {
    ...record.preferences,
    theme: 'dark'
  }
});

// Или используя точечную нотацию (если поддерживается)
await emd.database.collection('users').update(recordId, {
  'preferences.theme': 'dark'
});

Добавление элемента в массив​

const record = await emd.database.collection('products').get(recordId);
const specs = record.specifications;
specs.materials.push('Алюминий');

await emd.database.collection('products').update(recordId, {
  specifications: specs
});

Поиск по JSON полям​

Поиск по вложенному полю​

// Найти пользователей с темной темой
const users = await emd.database.collection('users').find({
  'preferences.theme': 'dark'
});

// Найти пользователей с включенными email уведомлениями
const users = await emd.database.collection('users').find({
  'preferences.notifications.email': true
});

Проверка существования поля​

const records = await emd.database.collection('products').find({
  'specifications.dimensions': { $exists: true }
});

Валидация с JSON Schema​

Вы можете определить схему для валидации структуры JSON:

{
  "name": "address",
  "type": "json",
  "schema": {
    "type": "object",
    "required": ["country", "city"],
    "properties": {
      "country": { "type": "string" },
      "city": { "type": "string" },
      "street": { "type": "string" },
      "building": { "type": "string" },
      "apartment": { "type": "string" },
      "zipCode": { "type": "string", "pattern": "^\\d{6}$" }
    }
  }
}

Примеры сложных структур​

Корзина покупок​

{
  items: [
    {
      productId: "prod_123",
      name: "Ноутбук",
      quantity: 1,
      price: 89990,
      options: {
        color: "Серебристый",
        memory: "16GB"
      }
    },
    {
      productId: "prod_456",
      name: "Мышь",
      quantity: 2,
      price: 1990
    }
  ],
  total: 93970,
  currency: "RUB"
}

История изменений​

{
  changes: [
    {
      timestamp: "2025-11-25T10:30:00Z",
      user: "user_123",
      field: "status",
      oldValue: "В работе",
      newValue: "Завершена"
    },
    {
      timestamp: "2025-11-25T11:15:00Z",
      user: "user_456",
      field: "priority",
      oldValue: "Средний",
      newValue: "Высокий"
    }
  ]
}

Конфигурация виджета​

{
  type: "chart",
  config: {
    chartType: "line",
    dataSource: "sales_collection",
    xAxis: "date",
    yAxis: "revenue",
    filters: {
      status: "completed",
      dateRange: {
        from: "2025-01-01",
        to: "2025-12-31"
      }
    },
    styling: {
      colors: ["#3b82f6", "#ef4444"],
      showLegend: true,
      showGrid: true
    }
  }
}

Отображение в интерфейсе​

В админ-панели JSON поля отображаются:

  • Компактный вид: Однострочное представление для таблиц
  • Развернутый вид: Форматированный JSON с подсветкой синтаксиса
  • Редактор: Monaco Editor или аналогичный для редактирования
  • Древовидный вид: Для удобной навигации по структуре

Рекомендации​

Когда использовать JSON​

  • ✅ Динамические структуры с переменным набором полей
  • ✅ Настройки и конфигурации
  • ✅ Временное хранение данных из внешних API
  • ✅ Метаданные с произвольной структурой

Когда НЕ использовать JSON​

  • ❌ Данные, по которым нужен частый поиск (создайте отдельные поля)
  • ❌ Данные, которые нужно агрегировать (используйте числовые поля)
  • ❌ Связи между записями (используйте тип Relation)
  • ❌ Большие объемы данных (используйте отдельную коллекцию)

Лучшие практики​

  • Определяйте схему валидации для критичных данных
  • Документируйте структуру JSON в описании поля
  • Используйте значения по умолчанию для обязательных полей
  • Избегайте глубокой вложенности (максимум 3-4 уровня)
  • Не храните файлы или большие бинарные данные в JSON
  • Используйте понятные имена ключей
  • Поддерживайте консистентность структуры между записями

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

  • Максимальный размер: 16 МБ
  • Поиск по вложенным полям может быть медленнее обычных полей
  • Нет автоматической индексации вложенных полей
  • Сложнее валидировать и поддерживать целостность данных

Отличие от других типов​

  • JSON vs String: JSON обеспечивает структуру и валидацию
  • JSON vs Relation: JSON для произвольных данных, Relation для связей между коллекциями
  • JSON vs отдельные поля: JSON для динамических структур, отдельные поля для фиксированной схемы