Шортхенды полей: сокращённая запись

В Vega и Vega-Lite сокращённые формы записи используются для уменьшения объёма спецификаций и повышения читаемости JSON-описаний визуализаций. На практике шортхенды затрагивают несколько уровней: определение полей данных, описание каналов кодирования, агрегации, преобразования и ссылки на значения внутри выражений. Понимание этих механизмов критично для работы с декларативной моделью визуализации, где каждая лишняя строка усложняет поддержку спецификации.

Наиболее распространённый шортхенд в Vega-Lite — сокращённая запись канала через строку вместо объекта.

Полная форма:

"x": {
  "field": "price",
  "type": "quantitative"
}

Сокращённая форма:

"x": "price"

При использовании сокращённой записи система автоматически:

  • выводит field из строки;
  • пытается определить type по данным (число, строка, дата);
  • применяет стандартные настройки масштаба и оси.

Это поведение особенно важно при прототипировании графиков, где структура данных уже известна.

Неявное определение типа данных

При сокращённой записи поля тип данных часто не указывается явно, что приводит к автоматическому выводу типа:

"x": "year"

Если значения в поле интерпретируются как числа, применяется quantitative, если как категории — nominal, если как даты — temporal.

Полная форма эквивалентна:

"x": {
  "field": "year",
  "type": "quantitative"
}

Автовывод типа работает корректно только при отсутствии неоднозначностей, например строковых чисел или смешанных форматов.

Сокращение в выражениях доступа к данным

В Vega выражениях используется объект datum, предоставляющий доступ к текущей записи. Полная форма обращения:

datum["price"]

Сокращённая форма:

datum.price

Такой доступ является стандартом JavaScript-выражений внутри Vega. Однако при наличии специальных символов в имени поля приходится использовать скобочную нотацию:

datum["unit-price"]

Шортхенд полей в трансформациях

В блоке transform часто используется сокращённая запись, где объект поля заменяется строкой.

Формат агрегации

Полная форма:

{
  "aggregate": [
    {
      "op": "mean",
      "field": "price",
      "as": "avg_price"
    }
  ]
}

Сокращённая форма:

{
  "aggregate": [
    {
      "op": "mean",
      "field": "price"
    }
  ]
}

В этом случае имя выходного поля генерируется автоматически, например mean_price.

Сокращённые операции преобразований

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

{
  "filter": "datum.price > 100"
}

Здесь price используется без дополнительного описания типа или структуры данных, а контекст datum задаёт область видимости.

Сокращённые объявления в encoding: повторное использование полей

Vega-Lite позволяет многократно использовать одно поле без дублирования метаданных.

Полная форма:

"encoding": {
  "x": { "field": "sales", "type": "quantitative" },
  "y": { "field": "sales", "type": "quantitative" }
}

Сокращённая форма:

"encoding": {
  "x": "sales",
  "y": "sales"
}

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

Шортхенд для константных значений

Вместо объекта с value допускается передача примитивов:

Полная форма:

"color": { "value": "steelblue" }

Сокращённая форма:

"color": "steelblue"

Такой подход применяется только для шкалируемых или фиксированных каналов, где не требуется привязка к полю данных.

Сокращённые формы в scale и axis через наследование полей

При указании канала без объекта Vega-Lite автоматически создаёт базовые компоненты масштаба и оси.

Пример:

"x": "date"

Эквивалент развернутой спецификации включает:

  • scale с типом временной шкалы при распознавании даты;
  • axis с форматированием временных меток;
  • encoding с неявным полем и типом.

Это поведение формирует основу декларативной модели: структура визуализации выводится из минимального описания данных.

Шортхенд в сортировках

В сортировке также допускается сокращённая форма, где поле указывается строкой:

Полная форма:

"sort": {
  "field": "price",
  "order": "descending"
}

Сокращённая форма:

"sort": "-price"

Знак минус указывает на убывающий порядок. Отсутствие знака — на возрастающий.

Сокращённые ссылки на поля в facet и repeat

В фасетировании данных используется минимальная форма задания поля:

"facet": {
  "field": "category",
  "type": "nominal"
}

Сокращённая запись:

"facet": "category"

При использовании repeat поле также может быть задано строкой:

"repeat": "column"

Система интерпретирует строку как имя поля данных.

Шортхенды в Vega (низкоуровневый слой)

Vega как основа Vega-Lite также поддерживает сокращённые формы через выражения и ссылки.

Доступ к полям

datum.value

вместо:

datum["value"]

Использование сигналов

Сигналы могут быть использованы напрямую в выражениях:

width / 2

где width — сигнал, а не поле данных.

Неявные преобразования типов

Сокращённая запись часто приводит к автоматическому приведению типов:

  • строки интерпретируются как категории;
  • числа как количественные значения;
  • ISO-строки как временные метки.

Пример:

"x": "2024-01-01"

может быть интерпретировано как временное значение без явного указания temporal.

Ограничения шортхендов

Сокращённые формы применимы только при соблюдении условий:

  • отсутствие неоднозначных типов данных;
  • отсутствие сложных преобразований;
  • отсутствие пользовательских шкал и форматтеров;
  • отсутствие конфликтов между несколькими источниками данных.

При нарушении этих условий требуется развернутая форма с явным указанием всех параметров.

Приоритет развёрнутой формы

Несмотря на удобство сокращений, Vega-Lite всегда использует развёрнутую модель внутри компилятора. Это означает, что:

  • шортхенд является лишь синтаксическим сахаром;
  • при компиляции спецификация нормализуется;
  • поведение визуализации определяется итоговой полной структурой.

Любая сокращённая запись эквивалентна развернутому JSON-дереву, где все поля, типы и параметры явно определены.

Оглавление