BaSys.Docs

Работа с табличными данными.

Класс DataTable предназначен для работы с табличными данными. Он обеспечивает хранение и обработку структурированных данных, поддерживая операции фильтрации, сортировки, группировки и агрегации. Полный список доступных операций приведен в таблице Методы.

Свойства

• columns: DataTableColumn[] - массив объектов, описывающих колонки таблицы.
• rows: object[] - массив строк, где каждая строка представляет набор значений, соответствующих колонкам таблицы.

Использование объекта DataTable

Обработка данных осуществляется через методы объекта DataTable. Многие методы DataTable поддерживают конвейерный способ вызова, что позволяет вызывать несколько методов подряд. Это делает код более лаконичным и читаемым, а также упрощает сложную обработку данных.

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

Создание объекта DataTable

Объект DataTable может быть создан при помощи функции createTable или путем инициализации объекта с помощью ключевого слова new. Также объект DataTable возвращается в качестве результата запросов к БД.

createTable

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

Синтаксис

createTable(columnSettings)

Параметры

• columnSettings (необязательный): DataTableColumn[] - массив колонок таблицы. Если массив пустой, будет создана пустая таблица.

или

• columnSettings (необязательный): string[] - массив строковых описаний таблицы формата ‘name <dataType>’. Если массив пустой, будет создана пустая таблица. Установка значений по-умолчанию не предусмотрена.

или

• columnSettings (необязательный): string - строковое описание колонок таблицы разделенное запятыми:
• ‘name1 <dataType1>, …, nameN <dataTypeN>’.

Возвращаемое значение

DataTable

Примеры

В данном примере создается таблица, содержащая четыре колонки: product, quantity, amount и is_available. Колонка quantity по умолчанию имеет значение 1. Для колонки явно не указан тип данных, и по-умолчанию данной колонке назначается тип ‘string’.

createTable([
    {name: 'product'},
    {name: 'quantity', dataType: 'number', defaultValue: 1},
    {name: 'amount', dataType: 'number'},
    {name: 'is_available', dataType: 'boolean'}
])

Более компактный вариант синтаксиса. В качестве параметров передается массив строковых описаний колонок. Описание колонки должно соответствовать формату: ‘name <dataType>’. Обращаем внимание, что установка значения по-умолчанию в данном варианте синтаксиса не предусмотрена.

createTable(['product', 'qauntity number', 'amount number', 'is_available boolean'])

Компактный вариант синтаксиса. В качестве параметра передается строковое описание колонок таблицы. Описания отдельных колонок разделены запятыми.

createTable('product, qauntity number, amount number, is_available boolean')

Методы

Метод	Возвращает	Описание
addColumn	DataTable	Добавление колонки в таблицу
addRow	DataTable	Добавление строки в таблицу
avg	DataTable	Вычисление среднего по колонке таблицы
clear	DataTable	Очистка строк таблицы
clone	DataTable	Создание копии таблицы
count	DataTable	Подсчет количества строк в таблице
deleteColumn	DataTable	Удаление колонки таблицы
distributeFifo	DataTable	Распределение FIFO
distributeLifo	DataTable	Распределение LIFO
innerJoin	DataTable	Внутреннее соединение таблиц
filter	DataTable	Фильтрация строк таблицы
fullJoin	DataTable	Полное внешнее соединение таблиц
getColumn	DataTableColumn	Поиск колонки таблицы по имени
groupBy	DataTable	Группировка таблицы
leftJoin	DataTable	Левое внешнее соединение таблиц
load	DataTable	Добавление данных в таблицу
max	DataTable	Вычисление максимума по колонке таблицы
min	DataTable	Вычисление минимума по колонке таблицы
newRow	Object	Создание новой строки таблицы
rightJoin	DataTable	Правое внешнее соединение таблиц
process	DataTable	Обработка строк таблицы
orderBy	DataTable	Сортировка строк таблицы
sum	DataTable	Вычисление суммы по колонке таблицы
union	DataTable	Объединение уникальных строк таблиц
unionAll	DataTable	Объединение всех строк таблиц

addColumn

Добавляет колонку в таблицу. Конфигурация колонки может передана в виде объекта или в виде строкового описания.

Синтаксис

dataTable.addColumn(column)

Параметры

• column: DataTableColumn - объект-описание колонки таблицы.

или

• column: string - строковое описание колонки таблицы формата ‘name <dataType>’.

Возвращаемое значение

DataTable

Примеры

Конфигурация колонки передается в виде объекта.

createTable().addColumn({ name: 'period', dataType: 'date'})

Конфигурация колонки передается в виде строкового описания.

createTable().addColumn('period date')

addRow

Добавляет строку в таблицу. Данные строки могут быть переданы в виде массива значений. В этом случае важно соблюдать позицию значения в массиве. Кроме того данные могут быть переданы в виде объекта. Пропущенные значения будут инициализированы значениями по-умолчанию.

Синтаксис

dataTable.addRow(data)

Параметры

• data: object[] - массив, содержащий данные добавляемой строки.

или

• data: object - объект, содержащий данные добавляемой строки.

Возвращаемое значение

DataTable

Пример

// Создание таблицы
var tableRates = createTable([{ name: 'period', dataType: 'date'}, { name: 'person'}, { name: 'rate', dataType: 'number'}, { name: 'isWorking', dataType: 'boolean'}])
  // Добавление строки таблицы. Данные передаются в виде массива значений. Важна соблюдать позицию значения в массиве.
  .addRow(['2024-09-01', 'Person 1', 1000, true])
  // Добавление строки таблицы. Данные передаются в виде объекта.
  .addRow({person: 'Person 2', period: '2024-08-01', isWorking: false, rate: 2000});
return tableRates;

avg

Вычисляет среднее значений по указанной колонке таблицы.

Синтаксис

dataTable.min(columnName)

Параметры

• columnName: string - имя колонки таблицы, по которой вычисляется среднее значение.

Возвращаемое значение

number

Пример

// Создание таблицы.
var tableRates = createTable([
  { name: 'period', dataType: 'date'}, 
  { name: 'person'}, 
  { name: 'rate', dataType: 'number'}, 
  { name: 'isWorking', dataType: 'boolean'}])
  // Добавление данных в таблицу.
  .load([
    [new Date('2024-09-01'), 'Person 2', 2000, true],
    [new Date('2024-05-01'), 'Person 3', 3000, true],
    [new Date('2024-11-01'), 'Person 1', 1000, false],
    [new Date('2024-04-01'), 'Person 4', 4000, true],
  ]);
// Вычисление среднего по колонке 'rate'.
return tableRates.avg('rate');

clear

Очищает строки таблицы. Колонки остаются неизменными.

Синтаксис

dataTable.clear()

Параметры

нет

Возвращаемое значение

DataTable

clone

Создает копию таблицы. Копируется как структура таблицы (колонки) так и данные.

Синтаксис

dataTable.clone()

Параметры

нет

Возвращаемое значение

DataTable

Пример

// Создание таблицы товаров и добавление строки в таблицу.
var productsTable = createTable([{ name: 'product'}, { name: 'quantity', dataType: 'number'}]).addRow(['product 1', 100]);
// Создание копии таблицы и добавление новой колонки. Таблица товаров productsTable остается неизменной.
var copyTable = productsTable.clone().addColumn({ name: 'amount', dataType: 'number'});
return copyTable;

count

Подсчитывает количество строк в таблице. Если указано имя колонки, подсчитываются только строки, в которых значения в указанной колонке не пустые. Проверка на заполненность значений выполняется в соответствии с правилами JavaScript, где значения null, undefined, пустая строка (‘’), 0, false считаются пустыми.

Синтаксис

dataTable.count(columnName)

Параметры

• columnName (необязательный): string - имя колонки, по которой выполняется проверка на заполненность значений. Если параметр не указан, функция вернёт общее количество строк в таблице. Если параметр указан, возвращается количество строк, где значения в данной колонке не пустые.

Возвращаемое значение

• number - Количество строк в таблице или количество строк с заполненными значениями в указанной колонке.

Пример

// Создание таблицы.
var tableRates = createTable([
  { name: 'period', dataType: 'date'}, 
  { name: 'person'}, 
  { name: 'rate', dataType: 'number'}, 
  { name: 'isWorking', dataType: 'boolean'}])
  // Добавление данных в таблицу.
  .load([
    [new Date('2024-09-01'), 'Person 2', 2000, true],
    [new Date('2024-05-01'), 'Person 3', 3000, true],
    [new Date('2024-11-01'), 'Person 1', 1000, false],
    [new Date('2024-04-01'), 'Person 4', 4000, true],
  ]);
// Вычисление количества строк с заполненным полем isWorking.
return tableRates.count('isWorking');

deleteColumn

Удаляет колонку таблицы.

Синтаксис

dataTable.deleteColumn(columnName)

Параметры

• columnName: string - имя колонки таблицы.

Возвращаемое значение

DataTable

Пример

createTable([{ name: 'product'}, { name: 'quantity', dataType: 'number'}, { name: 'price', dataType: 'number'}])
  .addRow(['product 1', 100, 10]).deleteColumn('quantity')

filter

Фильтрует строки таблицы на основе заданного условия. Условие передается в виде стрелочной функции (предиката), которая принимает строку таблицы в качестве аргумента и возвращает логическое значение (true или false). Если предикат возвращает true, строка включается в результат фильтрации, в противном случае строка исключается.

Синтаксис

dataTable.filter(predicate)

Параметры

• predicate: (row) => boolean — стрелочная функция, принимающая в качестве аргумента объект строки таблицы и возвращающая true, если строка должна быть включена в результат фильтрации, и false в противном случае.

Возвращаемое значение

DataTable

Пример

// Создание таблицы.
var tableRates = createTable([
  { name: 'period', dataType: 'date'}, 
  { name: 'person'}, 
  { name: 'rate', dataType: 'number'}, 
  { name: 'isWorking', dataType: 'boolean'}])
  // Добавление данных в таблицу.
  .load([
    ['2024-09-01', 'Person 1', 1000, true],
    ['2024-09-01', 'Person 2', 2000, true],
    ['2024-09-01', 'Person 3', 3000, true],
    ['2024-09-01', 'Person 4', 4000, true],
  ])
  // Выполнение фильтрации.
  .filter(row=> row.rate > 2000)
return tableRates;

getColumn

Выполняет поиск колонки по имени.

Синтаксис

dataTable.getColumn(columnName)

Параметры

• columnName: string - имя колонки.

Возвращаемое значение

DataTableColumn

Пример

// Создание таблицы товаров и добавление строки в таблицу.
var productsTable = createTable([{ name: 'product'}, { name: 'quantity', dataType: 'number'}]).addRow(['product 1', 100]);
// Поиск колонки по имени.
var column = productsTable.getColumn('quantity');
return column;

groupBy

Выполняет группировку строк таблицы по указанным ключевым колонкам и применяет агрегатные функции к выбранным колонкам.

Синтаксис

dataTable.groupBy(keyColumns, groupingColumns)

Параметры

• keyColumns: string[] - Массив строк с именами колонок, по которым будут сгруппированы строки. Эти колонки будут использоваться как уникальные идентификаторы групп.
• groupingColumns: GroupingColumn[] - Массив объектов, описывающих колонки для агрегации и применяемые к ним агрегатные функции. Каждый объект может включать имя колонки, псевдоним и агрегатную функцию.
• Допустимые значения агрегатных функций:
• ‘avg’ - среднее значение;
• ‘count’ - количество элементов;
• ‘max’ - максимальное значение;
• ‘min’ - минимальное значение;
• ‘sum’ - сумма значений.

Возвращаемое значение

DataTable - сгруппированная таблица данных.

Пример

// Создание таблицы.
var tableProducts = createTable(
  [{name: 'product'}, { name: 'product_group'}, { name: 'store'}, { name: 'quantity', dataType: 'number'}])
  // Заполнение таблицы данными.
  .load([
    ['Product 1', 'Group 1', 'Store 1', 86],
    ['Product 19', 'Group 3', 'Store 3', 89],
    ['Product 16', 'Group 4', 'Store 1', 75],
    ['Product 14', 'Group 2', 'Store 1', 18],
    ['Product 12', 'Group 2', 'Store 3', 77],
    ['Product 25', 'Group 3', 'Store 2', 32]
  ])
  // Выполнение группировки по полю product_group c вычисленим различных агрегатных функций.
  .groupBy(['product_group'], [
    'quantity', 
    {name: 'quantity', alias:'q_max', aggregate:'max'},
    {name: 'quantity', alias:'q_min', aggregate:'min'},
    {name: 'quantity', alias:'q_avg', aggregate:'avg'},
    {name: 'quantity', alias:'q_count', aggregate:'count'}
  ]);

return tableProducts;

load

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

Синтаксис

dataTable.load(data)

Параметры

• data: any[] - массив объектов или массив, содержащий массивы значений полей строк.

Возвращаемое значение

DataTable

Пример

// Создание таблицы.
var tableRates = createTable([
  { name: 'period', dataType: 'date'}, 
  { name: 'person'}, 
  { name: 'rate', dataType: 'number'}, 
  { name: 'isWorking', dataType: 'boolean'}])
  // Добавление данных в таблицу. Первая строка передается как массив значений полей строки. 
  // В этом случае важно соблюдать порядок значений.
  // Вторая строка добавляется в виде объекта.
  .load([
    ['2024-09-01', 'Person 1', 1000, true],
    { person: 'Person 2', period: '2024-08-01', isWorking: false, rate: 2000}
  ])
return tableRates;

newRow

Создает новую строку таблицы и заполняет значениями по умолчанию.

Синтаксис

dataTable.newRow(pushNewRow)

Параметры

-pushNewRow (необязательный): boolean - указывает на необходимость поместить новую строку в коллекцию строк таблицы. Значение по умолчанию: true.

Возвращаемое значение

Object

Пример

Создает новую строку в таблице, заполняет значениями по умолчанию и помещает новую строку в коллекцию колонок таблицы.

createTable([{ name: 'product'}, { name: 'quantity', dataType: 'number'}]).newRow();

orderBy

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

Синтаксис

dataTable.orderBy(comparator)

Параметры

• comparator: (a, b) => number — стрелочная функция, задающая условие сортировки. Принимает два объекта строки a и b, и возвращает:
  • отрицательное число, если строка a должна предшествовать строке b (сортировка по возрастанию);
  • положительное число, если строка b должна предшествовать строке a (сортировка по убыванию);
  • 0, если строки равны и их порядок не изменяется.

Возвращаемое значение

DataTable — возвращает текущий объект DataTable с отсортированными строками.

Примеры

Выполнение сортировки по числовой колонке по возрастанию.

// Создание таблицы.
var tableRates = createTable([
  { name: 'period', dataType: 'date'}, 
  { name: 'person'}, 
  { name: 'rate', dataType: 'number'}, 
  { name: 'isWorking', dataType: 'boolean'}])
  // Добавление данных в таблицу.
  .load([
    ['2024-09-01', 'Person 2', 2000, true],
    ['2024-05-01', 'Person 3', 3000, true],
    ['2024-11-01', 'Person 1', 1000, false],
    ['2024-04-01', 'Person 4', 4000, true],
  ])
  // Выполнение сортировки по колонке rate по возрастанию.
  .orderBy( (a, b)=> a.rate - b.rate)
return tableRates;

Выполнение сортировки по колонке дат по убыванию.

// Создание таблицы.
var tableRates = createTable([
  { name: 'period', dataType: 'date'}, 
  { name: 'person'}, 
  { name: 'rate', dataType: 'number'}, 
  { name: 'isWorking', dataType: 'boolean'}])
  // Добавление данных в таблицу.
  .load([
    [new Date('2024-09-01'), 'Person 2', 2000, true],
    [new Date('2024-05-01'), 'Person 3', 3000, true],
    [new Date('2024-11-01'), 'Person 1', 1000, false],
    [new Date('2024-04-01'), 'Person 4', 4000, true],
  ])
  // Выполнение сортировки по колонке period по убыванию.
  .orderBy( (a, b)=> b.period.getTime() - a.period.getTime())
return tableRates;

max

Вычисляет максимальное значение по указанной колонке таблицы.

Синтаксис

dataTable.max(columnName)

Параметры

• columnName: string - имя колонки таблицы, по которой вычисляется максимальное значение.

Возвращаемое значение

number

Пример

// Создание таблицы.
var tableRates = createTable([
  { name: 'period', dataType: 'date'}, 
  { name: 'person'}, 
  { name: 'rate', dataType: 'number'}, 
  { name: 'isWorking', dataType: 'boolean'}])
  // Добавление данных в таблицу.
  .load([
    [new Date('2024-09-01'), 'Person 2', 2000, true],
    [new Date('2024-05-01'), 'Person 3', 3000, true],
    [new Date('2024-11-01'), 'Person 1', 1000, false],
    [new Date('2024-04-01'), 'Person 4', 4000, true],
  ]);
// Вычисление максимума по колонке 'rate'.
return tableRates.max('rate');

min

Вычисляет минимальное значение по указанной колонке таблицы.

Синтаксис

dataTable.min(columnName)

Параметры

• columnName: string - имя колонки таблицы, по которой вычисляется минимальное значение.

Возвращаемое значение

number

Пример

// Создание таблицы.
var tableRates = createTable([
  { name: 'period', dataType: 'date'}, 
  { name: 'person'}, 
  { name: 'rate', dataType: 'number'}, 
  { name: 'isWorking', dataType: 'boolean'}])
  // Добавление данных в таблицу.
  .load([
    [new Date('2024-09-01'), 'Person 2', 2000, true],
    [new Date('2024-05-01'), 'Person 3', 3000, true],
    [new Date('2024-11-01'), 'Person 1', 1000, false],
    [new Date('2024-04-01'), 'Person 4', 4000, true],
  ]);
// Вычисление минимума по колонке 'rate'.
return tableRates.min('rate');

process

Обрабатывает строки таблицы, выполняя переданную стрелочную функцию для каждой строки. Функция может изменять содержимое строки или выполнять другие операции.

Синтаксис

dataTable.process(action)

Параметры

• action: (row) => void - стрелочная функция, исполняемая для каждой строки таблицы. Параметры функции:
  • row: объект, представляющий строку таблицы, который может быть изменён в процессе обработки.

Возвращаемое значение

DataTable - возвращает текущий объект DataTable, что позволяет использовать метод в цепочке вызовов.

Пример

// Создание таблицы.
var tableProducts = createTable([ 
  { name: 'product'}, 
  { name: 'price', dataType: 'number'}, 
  { name: 'quantity', dataType: 'number'}, 
  { name: 'amount', dataType: 'number'}])
  // Заполнение данных таблицы.
  .load([['Product 1', 100, 5], ['Product 2', 200, 10]])
  // Вычисление значения в колонке amount.
  .process(row=> row.amount = row.quantity * row. price);
return tableProducts;

sum

Вычисляет сумму значений по указанной колонке таблицы.

Синтаксис

dataTable.sum(columnName)

Параметры

• columnName: string - имя колонки таблицы, по которой вычисляется сумма.

Возвращаемое значение

number

Пример

// Создание таблицы.
var tableRates = createTable([
  { name: 'period', dataType: 'date'}, 
  { name: 'person'}, 
  { name: 'rate', dataType: 'number'}, 
  { name: 'isWorking', dataType: 'boolean'}])
  // Добавление данных в таблицу.
  .load([
    [new Date('2024-09-01'), 'Person 2', 2000, true],
    [new Date('2024-05-01'), 'Person 3', 3000, true],
    [new Date('2024-11-01'), 'Person 1', 1000, false],
    [new Date('2024-04-01'), 'Person 4', 4000, true],
  ]);
// Вычисление суммы по колонке 'rate'.
return tableRates.sum('rate');

union

Осуществляет объединение текущей таблицы с другой таблицей, добавляя только уникальные строки. В отличие от unionAll, выполняется проверка на уникальность строк, что может замедлять выполнение, но гарантирует отсутствие дубликатов.

Синтаксис

dataTable.union(tableToUnion)

Параметры

• tableToUnion: DataTable - таблица, которую нужно объединить с текущей таблицей. Строки из этой таблицы будут добавлены только в случае, если они отсутствуют в основной таблице.

Возвращаемое значение

DataTable - Объединённая таблица, содержащая уникальные строки из обеих таблиц.

Пример

Данный пример демонстрирует объединение двух таблиц. Строка [‘product_1’, 10, 100] в обеих таблицах одинаковая, поэтому она не будет добавлена второй раз. Однако строка [‘product_3’, 20, 4000] будет добавлена, так как она уникальна.

// Определение колонок таблиц.
var columns = [{name: 'product'}, {name: 'quantity', dataType: 'number'}, {name: 'amount', dataType: 'number'}];
// Создание основной таблицы.
var mainTable = createTable(columns)
  .addRow(['product_1', 10, 100])
  .addRow(['product_2', 5, 2000]);
// Создание таблица для объединения.
var tableToUnion = createTable(columns)
  .addRow(['product_1', 10, 100])
  .addRow( ['product_3', 20, 4000]);
// Выполнение объединения таблиц.
return mainTable.union(tableToUnion);

unionAll

Осуществляет объединение текущей таблицы с другой таблицей, добавляя все строки. В отличие от union, проверка на уникальность строк не выполняется.

Синтаксис

dataTable.union(tableToUnion)

Параметры

• tableToUnion: DataTable - таблица, которую нужно объединить с текущей таблицей.

Возвращаемое значение

DataTable - Объединённая таблица, содержащая все строки из обеих таблиц.

Пример

Данный пример демонстрирует объединение двух таблиц. Строка [“product_1”, 10, 100] в обеих таблицах одинаковая, поэтому в результирующей таблице она будет задублирована.

// Определение колонок таблиц.
var columns = [{name: 'product'}, {name: 'quantity', dataType: 'number'}, {name: 'amount', dataType: 'number'}];
// Создание основной таблицы.
var mainTable = createTable(columns)
  .addRow(['product_1', 10, 100])
  .addRow(['product_2', 5, 2000]);
// Создание таблица для объединения.
var tableToUnion = createTable(columns)
  .addRow(['product_1', 10, 100])
  .addRow( ['product_3', 20, 4000]);
// Выполнение объединения таблиц.
return mainTable.unionAll(tableToUnion);

This site is open source. Improve this page.