Поле format и formatType

В Vega и Vega-Lite работа с внешними данными и их интерпретацией опирается на два тесно связанных, но концептуально разных механизма — format и formatType. Эти поля определяют, как исходный источник данных преобразуется в внутреннее представление, пригодное для последующей визуализации и трансформаций.

Поле format задаёт структуру и правила разбора входного набора данных. Оно используется внутри блока data, когда данные загружаются из внешнего источника через url, либо передаются как встроенный массив.

Базовая форма:

{
  "data": {
    "url": "data.csv",
    "format": {
      "type": "csv"
    }
  }
}

Ключевая задача format — указать:

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

format.type: определение типа данных

Поле type внутри format определяет, каким парсером будет обработан входной поток.

Основные поддерживаемые типы

CSV

{
  "format": {
    "type": "csv"
  }
}

CSV является наиболее распространённым табличным форматом. Vega использует стандартный CSV-парсер, где:

  • первая строка обычно содержит заголовки
  • разделитель по умолчанию — запятая
  • строки преобразуются в объекты

TSV

{
  "format": {
    "type": "tsv"
  }
}

TSV аналогичен CSV, но использует табуляцию как разделитель. Применяется при работе с данными, где запятые могут встречаться внутри значений.

JSON

{
  "format": {
    "type": "json"
  }
}

JSON-формат предполагает, что данные уже структурированы как массив объектов или вложенная структура. Vega не требует дополнительного парсинга, кроме чтения файла.

DSV (Delimiter-Separated Values)

{
  "format": {
    "type": "dsv",
    "delimiter": ";"
  }
}

DSV используется, когда разделитель отличается от стандартных CSV/TSV. Поле delimiter становится обязательным.

TopoJSON

{
  "format": {
    "type": "topojson",
    "feature": "countries"
  }
}

TopoJSON применяется для геоданных. Поле feature указывает, какую коллекцию геометрий извлекать из структуры.

format.parse: контроль типов полей

Помимо определения формата, Vega позволяет явно указать, как интерпретировать отдельные поля после загрузки.

{
  "format": {
    "type": "csv",
    "parse": {
      "date": "date",
      "value": "number"
    }
  }
}

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

  • "number" — преобразование в число
  • "boolean" — логический тип
  • "date" — дата (ISO или кастомные форматы)
  • "string" — явное оставление строкой

Поведение парсера

Если parse не задан, Vega пытается автоматически определить типы, но результат может быть неоднозначным, особенно для:

  • чисел в строковом виде
  • дат без стандартизированного формата
  • смешанных колонок

Отличие format в Vega и Vega-Lite

Vega-Lite выступает как декларативный надстройщик и использует более упрощённую модель данных. Однако при компиляции спецификации она преобразуется в полноценный Vega-spec, где format становится частью нижнего уровня.

Vega-Lite пример

{
  "data": {
    "url": "data.csv",
    "format": {
      "type": "csv"
    }
  }
}

После компиляции в Vega это остаётся практически без изменений, но дополняется внутренними трансформациями и нормализацией структуры.

formatType: исторический и расширяемый механизм

Поле formatType относится к более низкоуровневому API Vega (не Vega-Lite напрямую) и используется для определения способа декодирования данных через регистрируемые парсеры.

Базовая идея

{
  "data": {
    "url": "data.custom",
    "format": {
      "type": "custom",
      "formatType": "myParser"
    }
  }
}

Здесь:

  • type задаёт логическую категорию
  • formatType указывает конкретный обработчик

Когда используется formatType

formatType становится актуальным в следующих случаях:

  • регистрация пользовательских загрузчиков данных
  • работа с расширенными форматами (binary, protobuf, custom encodings)
  • интеграция с внешними системами парсинга

Vega поддерживает механизм регистрации:

  • кастомных парсеров
  • кастомных трансформеров загрузки

Взаимодействие type и formatType

Логика обработки строится по приоритету:

  1. type определяет базовый класс формата
  2. formatType уточняет конкретную реализацию обработки
  3. дополнительные параметры (parse, property, feature) применяются поверх результата

Пример сложной конфигурации

{
  "data": {
    "url": "geo.topojson",
    "format": {
      "type": "topojson",
      "feature": "states",
      "formatType": "topojson"
    }
  }
}

Здесь одновременно заданы:

  • географический тип данных
  • конкретная коллекция объектов
  • механизм обработки формата

Частые ошибки при работе с format и formatType

Несоответствие типа и реального содержимого

{
  "format": {
    "type": "csv"
  }
}

при фактическом JSON-файле приводит к некорректному парсингу или полной потере данных.

Игнорирование parse

Данные могут быть загружены корректно, но интерпретированы неправильно:

  • числа остаются строками
  • даты не распознаются
  • фильтры и масштабы работают некорректно

Использование formatType без регистрации

Если указан formatType, но соответствующий парсер не зарегистрирован, Vega:

  • либо игнорирует параметр
  • либо вызывает ошибку загрузки данных

Особенности поведения при вложенных данных

Для JSON-структур сложной вложенности format не выполняет глубокую нормализацию. В таких случаях требуется:

  • предварительная трансформация данных
  • использование transform (flatten, calculate, filter)

Связь с системой трансформаций

Хотя format отвечает только за загрузку, он часто выступает первым этапом цепочки обработки:

  1. format — декодирование источника
  2. transform — преобразование структуры
  3. encoding — отображение в визуальные каналы

Ошибки на уровне format распространяются на всю последующую цепочку, так как ломают исходную модель данных.

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

При загрузке Vega фактически выполняет следующую последовательность:

  • чтение источника (url)
  • выбор парсера по format.type
  • применение formatType (если задан)
  • преобразование значений через parse
  • нормализация данных в массив объектов
  • передача результата в pipeline визуализации

Значение точной типизации данных

Корректная настройка format напрямую влияет на:

  • работу шкал (scale domains)
  • агрегации (aggregate transforms)
  • временные оси (time scale)
  • геометрические операции (geo projections)

Ошибки в format чаще проявляются не на этапе загрузки, а в виде некорректной визуализации: смещённые оси, пустые графики, неверные группировки.

Оглавление