Обработка данных

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

Конфигурационный файл data.config.yaml (или data.config.json) определяет, каким образом будут обработаны данные перед их подключением к сайту. В нем же настраивается генерация страниц из данных.

Файл пишется в формате yaml или json. Состоит из списка действий над данными (массив объектов). Все действия, описанные в файле производятся последовательно, кроме генерации страниц — страницы генерируются строго после того, как будут произведены все остальные действия.

У каждого действия есть обязательные параметры dataset и task. Ниже — общая схема, все примеры тут и ниже — в формате yaml.

- task: <название действия>
  dataset: <имя датасета>
  ... остальные параметры могут меняться в зависимости от действия

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

Данные, которые не являются таблицей, можно использовать на страницах, вставлять в шаблоны, но обрабатывать их не получится.

Действия с данными

slugify

Создает новую колонку на основе выбранной, в которой каждому значению из выбранной колонки соотвествует уникальная строка, состоящая из букв латинского алфавита, цифр и знаков подчеркивания. Эта функция нужна для создания страниц — результат ее выполнения всегда можно использовать как часть URL, при этом она сохранияет человекочитаемость.

Например, если у вас есть табличка с именами актеров, а вам нужно создать по странице для каждого из них, можно с помощью slugify добавить столбец, который потом использовать при генерации страниц как имя файла:

- task: slugify
  dataset: tables.movies
  input_col: actor_name
  output_col: actor_page_name

Параметры:

input_col — колонка, на основе которой будет создана новая колонка
output_col — имя новой колонки

idfy (0.1.7)

Создает новую колонку или переписывает указанную, заменяя уникальные значения числовыми идентификаторами (id), начиная с единицы. Порядок нумерации соответствует порядку появления значений в колонке.

- task: idfy
  dataset: tables.movies
  input_col: actor_name

input_col — колонка, из содержимого которой будут сгенерированы id
output_col — если указано, имя колонки, в которую будут помещены id. Если не указаны, будет переписана исходная колонка.

hash (0.1.4)

Создает новую колонку на основе выбранной, в которую помещает хэш содержимого выбранной колонки. Удобно, когда нужно использовать в URL слишком длинные значения. По-умолчанию генерируется хэш длиной в ≈23 символа. При установленной опции long генерируется более длинный хэш.

- task: hash
  dataset: tables.movies
  long: true
  input_col: very_long_name
  output_col: name_hash

Параметры:

input_col — колонка, на основе которой будет создана новая колонка
output_col — имя новой колонки
long — использовать более длинный хэш

combine (0.1.4)

Создает новую колонку на основе нескольких выбранных. Содержимое выбранных колонок конкатенируется и хэшируется.

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

По-умолчанию генерируется хэш длиной в ≈23 символа. При установленной опции long генерируется более длинный(≈43 символа) хэш.

- task: combine
  dataset: tables.movies
  long: false
  input_cols:
    - actor_name
    - director_name
  output_col: director_actor

Параметры:

input_cols — список колонок, на основе которой будет создана новая колонка
output_col — имя новой колонки
long — использовать более длинный хэш

sort

Сортирует датасет по заданной колонке.

Параметры:

col— по какой колонке сортировать
as_number — логическое значение — интерпретировать ли содержимое колонки как число. Результат может быть неожиданным, так как локаль не учитывается.
desc— логическое значение, сортировка в нисходящем порядке.

del_cols

Удаляет колонки из таблицы. Бывает нужно, если вы хотите сохранить таблицу для Java Script, чтобы не сохранять и не скачивать лишние данные.

cols — список имен колонок на удаление

- task: del_cols
  dataset: examples.movies
  cols: ["minutes_long", "budget", "rating_metacritic"]

aggregate

Внимание: данные лучше подготавливать заранее при помощи более подходящих инструментов! Действие aggregate позволяет делать простые агрегации — сумма, число, медиана. Например, так можно добавить в табличку, в которой перечислены актеры и фильмы, в которых они снимались, количество фильмов с участием каждого актера:

- task: aggregate
  dataset: table.actors
  type: count_u
  col: movie_name
  group_by: actor_name # Необязательный параметр.
  output_col: filmed_in

Параметры:

type — тип аггрегации, count, count_u, sum, average, median
col — колонка, в которой будет производится агрегация
group_by — необязательно, колонка, по которой будут сгруппированы значения
output_col — название новой колонки, в которую будут записаны результаты

unpivot (скоро!)

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

Исходная таблица

name	department	age	city	salary
Alice	Engineering	25	NYC	70000
Bob	Design	30	LA	65000
Charlie	Management	35	Chicago	80000

Код

- task: unpivot
  columns: ['age', 'city', 'salary']
  key_column: "attribute"
  value_column: "value"

Результат

name	department	attribute	value
Alice	Engineering	age	25
Alice	Engineering	city	NYC
Alice	Engineering	salary	70000
Bob	Design	age	30
Bob	Design	city	LA
Bob	Design	salary	65000
Charlie	Management	age	35
Charlie	Management	city	Chicago
Charlie	Management	salary	80000

Параметры

columns — список колонок, которые надо «развернуть».
key_column — заголовок колонки, в которую будут помещены заголовки развернутых колонок.
value_column — заголовок колонки для их значений.

Генерация страниц

Действие render генерирует страницы из табличных данных. Действия render выполняются после всех остальных.

Тип генерации определяются параметром type (см. ниже). Остальные параметры определяют расположение и содержание сгенерированных страниц.

path — Полный адрес сгенерированной страницы
meta — Метаданные, можно заполнить любые.
markdown или html — Можно сгенерировать текст страницы как в markdown, так и сразу в html, во втором случае текст не будет обработан парсером markdown. Теги шаблонизатора будут обработаны в любом случае.

В значения свойств можно вставлять значения из столбцов обрабатываемого датасета при помощи простого синтакисиса подстановки:

  task: render
  dataset: examples.movies
  type: row
  # Имя файла будет сгенерировано из столбца movie_slug
  path: /examples/movies/[movie_slug].html
  meta:
  # Заголовок страницы = поле name
    title: "[name]"

Примеры использования смотрите в разделе «Примеры»

type: row

Самое простое: страницы генерируются для каждой строки таблицы. В поле local_data сгенерированной страницы будет доступна таблица из одной строки.

type: col

Страницы генерируются для каждого уникального значения в заданном столбце. В сгенерированной странице, в поле local_data в процессе генерации будет доступна выборка из таблицы, т. е. все строки, в которых значение выбранного столбца — одинаково.

Эти данные можно перебрать при помощи тегов шаблонизатора, и/или при помощи Java Script API сохранить для использования в клиентских скриптах.

type: key

В этом случае страницы генерируются для каждого ключа (поля) в объекте. Таким образом можно сгенерировать данные из JSON, либо для каждого датасета (файла) в поддиректории. Для этого в параметре dataset надо указать директорию, а не конечный файл.

Для замены доступно только одно значение — key, данные из файлов (полей объекта) будут доступны в переменной local_data.