Datasets в Studio

Datasets в Mapbox Studio представляют собой редактируемое хранилище геоданных в формате GeoJSON, предназначенное для создания, управления и обновления пространственных объектов до их публикации в виде тайловых наборов (tilesets). Они служат промежуточным слоем между сырыми данными и визуализацией в Mapbox, обеспечивая гибкий редактор объектов и API-доступ для автоматизации.

Datasets занимают промежуточное положение между пользовательскими данными и рендерингом на карте:

  • Dataset (редактируемый слой данных) — хранит объекты GeoJSON
  • Tileset (векторные тайлы) — оптимизированная для рендеринга структура
  • Map style (стиль карты) — использует tilesets для отображения

Главная идея заключается в том, что dataset не используется напрямую в Mapbox GL JS для высокопроизводительного рендеринга, а трансформируется в tileset.

Структура Dataset

Dataset состоит из набора Feature-объектов GeoJSON:

{
  "type": "Feature",
  "id": "point-1",
  "geometry": {
    "type": "Point",
    "coordinates": [69.2401, 41.2995]
  },
  "properties": {
    "name": "Объект A",
    "type": "warehouse",
    "capacity": 1200
  }
}

Ключевые элементы:

  • geometry — геометрия (Point, LineString, Polygon)
  • properties — атрибуты объекта
  • id — уникальный идентификатор (используется для обновления)
  • type — всегда Feature

Особенность Datasets заключается в том, что они допускают частичное обновление объектов, не требуя пересборки всего слоя.

Работа с Datasets через API

Datasets управляются через Dataset API, который позволяет выполнять CRUD-операции.

Создание dataset

POST /datasets/v1/{username}

Пример тела запроса:

{
  "name": "logistics_points",
  "description": "Точки логистической инфраструктуры"
}

Добавление или обновление feature

PUT /datasets/v1/{username}/{dataset_id}/features/{feature_id}
{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [69.2401, 41.2995]
  },
  "properties": {
    "status": "active"
  }
}

Получение feature

GET /datasets/v1/{username}/{dataset_id}/features/{feature_id}

Удаление feature

DELETE /datasets/v1/{username}/{dataset_id}/features/{feature_id}

Получение всех объектов dataset

GET /datasets/v1/{username}/{dataset_id}/features

Поддерживается пагинация, что важно при больших объемах данных.

Преобразование Dataset в Tileset

Datasets не используются напрямую в рендеринге Mapbox GL JS. Для визуализации необходимо создать tileset.

Процесс:

  1. Dataset наполняется GeoJSON-объектами
  2. Выполняется публикация (upload/publish)
  3. Mapbox Studio генерирует векторные тайлы
  4. Tileset становится доступен через стиль карты

Преобразование выполняется асинхронно и может занимать от нескольких секунд до нескольких минут в зависимости от объема данных.

Использование в Mapbox GL JS

После публикации dataset в виде tileset он подключается как источник данных.

Добавление источника tileset

map.on('load', () => {
  map.addSource('logistics', {
    type: 'vector',
    url: 'mapbox://your_account.logistics_points'
  });
});

Добавление слоя отображения

map.addLayer({
  id: 'logistics-layer',
  type: 'circle',
  source: 'logistics',
  'source-layer': 'logistics_points',
  paint: {
    'circle-radius': 6,
    'circle-color': '#ff5200'
  }
});

Использование Dataset как GeoJSON (для динамических данных)

Хотя datasets обычно публикуются как tilesets, в некоторых сценариях данные могут использоваться как GeoJSON источник.

map.addSource('dynamic-data', {
  type: 'geojson',
  data: 'https://api.mapbox.com/datasets/v1/{username}/{dataset_id}/features?access_token=TOKEN'
});

Такой подход применяется для:

  • небольших наборов данных
  • частого обновления объектов
  • интерактивных приложений

Редактирование данных через Studio Interface

В Mapbox Studio Dataset Editor доступны:

  • визуальное добавление точек, линий и полигонов
  • редактирование координат перетаскиванием
  • изменение свойств объектов
  • импорт GeoJSON файлов
  • удаление и клонирование объектов

Редактор синхронизируется с Dataset API, поэтому изменения доступны сразу через запросы.

Версионирование и обновления

Datasets не имеют классического version control, но поддерживают:

  • частичные обновления features
  • атомарную замену объекта по ID
  • повторную публикацию tileset после изменений

Типичный цикл обновления:

  1. изменение feature в dataset
  2. повторный publish tileset
  3. обновление отображения на карте через новый тайловый слой (если кэш не инвалидирован автоматически)

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

  • отсутствие встроенного пространственного индекса
  • ограничение по размеру dataset (зависит от тарифа)
  • невозможность прямого использования как высокопроизводительного источника без tileset
  • задержка между изменением dataset и обновлением tileset
  • отсутствие сложных пространственных запросов (buffer, intersect) на уровне API

Преобразование GeoJSON логики в структуру Dataset

GeoJSON-логика напрямую транслируется в dataset, но требует соблюдения ряда правил:

  • координаты всегда в формате [longitude, latitude]
  • geometry должна быть валидной по спецификации RFC 7946
  • свойства должны быть сериализуемыми в JSON
  • избегается вложенная сложная структура properties для повышения совместимости

Интеграция Dataset API в серверную логику

Типичный серверный сценарий обновления данных:

import fetch from 'node-fetch';

async function updateFeature(datasetId, featureId, geometry) {
  await fetch(
    `https://api.mapbox.com/datasets/v1/{username}/${datasetId}/features/${featureId}?access_token=TOKEN`,
    {
      method: 'PUT',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        type: 'Feature',
        geometry,
        properties: {
          updatedAt: Date.now()
        }
      })
    }
  );
}

Такая схема позволяет строить динамические геоинформационные системы с обновлением данных в реальном времени.

Связь Datasets и Tilesets в рабочем процессе

Стандартная модель обработки данных:

  • ingestion: CSV / GeoJSON → Dataset
  • editing: Dataset Editor / API
  • transformation: Dataset → Tileset
  • rendering: Tileset → Mapbox GL JS

Эта цепочка позволяет разделить этапы подготовки и визуализации данных, обеспечивая масштабируемость и оптимизацию производительности на клиенте.

Поведение в Mapbox GL JS при обновлении tileset

При публикации нового tileset:

  • карта может продолжать использовать кэшированные тайлы
  • обновление зависит от параметров cache-control
  • повторная загрузка слоя может потребоваться вручную
map.removeLayer('logistics-layer');
map.removeSource('logistics');

Практическая модель использования Datasets

Типовой сценарий:

  • сбор данных (IoT, CRM, GIS)
  • запись в dataset через API
  • ручная корректировка в Studio
  • публикация tileset
  • отображение в Mapbox GL JS
  • периодические обновления dataset

Такая модель обеспечивает баланс между гибкостью редактирования и производительностью рендеринга в браузере.

Оглавление