Функции обработки таблиц данных

Функция

Описание

Тип результата

addColumns(DataTable table, String format1, String expression1, String format2, String expression2, ...)

Добавляет один и более столбцов к таблице table. Формат первого добавляемого столбца определен аргументом format1, его значение задается через expression1, и т.д. Формат закодирован в строку, согласно разделу кодирование формата (используются видимые разделители). Значение для данного поля рассчитывается путем выполнения выражения, которое может содержать ссылки на другие ячейки данной таблицы. Если ряд не определен в ссылке, она возвращается к текущему ряду (т.е. к тому, для которого рассчитывается значение нового поля).

Пример: addColumns({.:hrStorageTable}, "<usage><S>", "{hrStorageUsed} * 100 / {hrStorageSize} + ' %'") вернет копию исходной таблицы с одним новым столбцом под названием usage типа Строка. Значения для данного столбца рассчитываются при помощи выражения {hrStorageUsed} * 100 / {hrStorageSize} + ' %', которое ссылается на два других столбца той же таблицы.

DataTable

addRecords(DataTable table, Object field1, Object field2, ...)

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

DataTable

adjustRecordLimits(DataTable table, Integer minRecords, Integer maxRecords)

Настраивает минимальное и максимальное количеств записей для таблицы и возвращает модифицированную таблицу. Дополнительные пустые записи добавляются, если в таблице меньше, чем minRecords записей. Конечные записи удаляются, если в таблице больше, чем maxRecords записей.

DataTable

aggregate(DataTable|String context mask, String expression, Object initialValue)

Рассчитывает некоторое "объединенное значение" для Таблицы данных (если исходный аргумент является Таблицей данных) или количество контекстов (если исходный аргумент является Строкой, представляющей маску контекста). Если первый аргумент - Таблица данных, она проходит через каждую ее запись и рассчитывает выражение; исходная Таблица данных, таким образом, становится таблицей по умолчанию, а текущий ряд - рядом по умолчанию. Если источником является маска контекста, выражение рассчитывается для каждого контекста, соответствующего маске, он становится контекстом по умолчанию.

Выражение обычно оперирует двумя значениями: значением предыдущего вычисления, ссылка на которое осуществляется с помощью {env/previous}  (см. Ссылки среды) и значением(ями) из текущего контекста/записи, которые доступны через стандартные ссылки. Во время первого вычисления, {env/previous} возвращает значение аргумента initialValue.

Пример 1: aggregate("users.*.devices.*", "{env/previous} + ({.:status$connectionStatus} == 1 ? 1 : 0)", 0)

Данное выражение ({.:status$connectionStatus} == 1)  рассчитает количество устройств онлайн в системе,  пройдя через все контексты устройств (маска users.*.devices.*) и добавляя 1 к "объединенному" значению, если устройство в сети. Начальное значение равно нулю.

Пример 2: aggregate({}, '{env/previous} || ({prtCoverStatus} == "open")', false)

В данном случае, результат рассчитывается путем прохождения через все записи таблицы данных по умолчанию (возвращенной ссылкой {}). Начальное "объединенное" значение является false. Конечный результат будет true, если поле prtCoverStatus равно open хотя бы в одной записи, и false в противном случае.

Пример 3: aggregate({}, max({env/previous}, {field}), 0)

Вышеуказанное выражение вернет максимальное значение, обнаруженное в столбце field.

Пример 4: aggregate({}, '({env/previous} * {#row} + {field}) / ({#row} + 1)', 0)

Вышеуказанное выражение рассчитает среднее значение столбца field.

Object

cell(DataTable table, String field [, Integer row [, Boolean description]] )

Возвращает значение ячейки Таблицы данных, проходящей в первом аргументе. Ячейка задана параметрами field и row. Если ряд не задан, возвращается значение field в первом ряду. Если field является числом, оно рассматривается как индекс поля вместо его имени.

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

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

Пример: cell({users:list()}, "firstname", 5) вернет поле firstname из 6-го ряда (индекс = 5) таблицы,  содержащей список учетных записей пользователей (полученный с помощью контекстной функции list()  из контекста Пользователи).

Object

clear(DataTable table)

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

DataTable

convert(DataTable table, String format)

Конвертирует таблицу в формат, определяемый аргументом format. Формат кодируется в строку согласно разделу кодирование формата (используются видимые разделители). После создания новой пустой таблицы заданного формата, функция оптимальным образом копирует все данные из таблицы в новую при помощи операции интеллектуальное копирование Таблицы данных.

Пример: выражение convert({}, '<<f1><S><A=123>> <<f2><B>>') создаст таблицу со строковым полем  f1 и полем Boolean f2 и скопирует все данные из таблицы данных в только что созданную. Если в таблице по умолчанию поле f1 является целочисленным, его тип будет конвертирован, но все данные сохранятся.

DataTable

copy(DataTable source, DataTable target)

Копирует максимально возможное количество данных из исходной таблицы в целевую таблицу и возвращает целевую таблицу. Добавляет/удаляет записи из целевой таблицы для соответствия количеству записей в исходной таблице (если это позволяет формат целевой таблицы). При необходимости конвертирует типы значений.

DataTable

decode(String stringToDecode)

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

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

DataTable

describe(DataTable table, String field1, String description1, String field2, String description2, ...)

Изменяет описание поля field1 на description1 и т.д. Возвращает таблицу.

Пример: describe({.:ifTable}, "ifDescr", "Name", "ifAdminStatus", "Status", "ifType", "Type", "ifSpeed", "Speed") возвращает копию исходной таблицы, где описания полей ifDescr, ifAdminStatus, ifType, и ifSpeed изменяются на Name, Status, Type и Speed соответственно.

DataTable

description(DataTable table)

Возвращает описание таблицы, т.е. результат вычисления ее выражения названия.

String

distinct(DataTable table)

Удаляет дубли записей из таблицы и возвращает отфильтрованную таблицу.

DataTable

encode(DataTable table [, boolean useVisibleSeparators])

Кодирует таблицу в строку в соответствии с правилами кодирования таблицы данных.

String

filter(DataTable table, String filterExpression)

Возвращает таблицу, содержащую только те строки исходной таблицы, которые соответствуют filterExpression.

Пример: filter({users:list()}, "contains({firstname}, 'John')") вернет только тех пользователей, чьи имена соедржат строку John.

DataTable

getFormat(DataTable table [, Boolean useVisibleSeparators])

Возвращает формат таблицы в виде Строки. Видимость разделителей определяется параметром useVisibleSeparators. Если этот параметр не задан, используются невидимые разделители.

String

hasField(DataTable table, String field)

Возвращает true, если таблица имеет поле под названием поле. В противном случае возвращает false.

Boolean

intersect(DataTable sourceTable, String fieldInSourceTable, DataTable sampleTable, String fieldInSampleTable [, Boolean filterType])

Возвращает таблицу, содержащую те же строки, что и sourceTable, за исключением тех, которые были найдены в sampleTable, если filterType true.

Возвращает таблицу, содержащую те же строки, что и sourceTable, за исключением тех, которые не были найдены в sampleTable, если filterType false или не задан.

Сравнивает записи в sourceTable и sampleTable по значениям полей fieldInSourceTable и fieldInSampleTable.

DataTable

join(DataTable left, DataTable right)

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

Если в левой таблице есть ключевые поля, функция join сопоставит записи из правой таблицы, используя эти ключевые поля.

DataTable

print(DataTable table, String expression, String separator)

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

Пример: print({users:list()}, "{firstname}", ", ") вернет имена пользователей, например, Amanda, Michelle, John, Donald, Paul

String

records(DataTable table)

Возвращает количество записей (строк) в таблице.

Integer

removeColumns(DataTable table, String column1, String column2, ...)

Удаляет несколько столбцов из таблицы.

DataTable

removeRecords(DataTable table, String fieldToCheck, Object value)

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

DataTable

select(DataTable table, String fieldToSelect, String fieldToCheck, Object value)

Сканирует каждый ряд в таблице и проверяет, равняется ли значение поля fieldToCheck значению. Если оно true, возвращает значение fieldToSelect из текущей записи. Если в таблице не обнаружено совпадающих записей, данная функция вернет NULL.

Пример: select({users:list()}, "firstname", "username", "john") вернет имя пользователя со  значением поля username john, выбранным из таблицы статистики пользователей (см. пример выше).

Object

set(DataTable table, String field, Integer row, Object value)

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

DataTable

setMultiple(DataTable table, String field, Object value [, String condition])

Сканирует каждую строку таблицы и задает значение на поле, если выражение условия - true. Устанавливает значение на поле для всех строк в таблице, если условие отсутствует.

DataTable

sort(DataTable table, String field, boolean ascending)

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

DataTable

subtable(DataTable table, String field1, String field2, ...)

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

Пример: subtable({users:list()}, "firstname", "lastname") вернет таблицу с двумя столбцами, содержащими имя и фамилию всех пользователей SberMobile Server.

DataTable

table(String format, Object field1, Object field2, ...)

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

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

Пример: table("<<from><I>><<to><I>>", 2, 5, 3, 7) вернет таблицу с двумя столбцами с Целыми числами и две строки. Первая строка будет иметь поле from, равное 2, и поле to, равное 5. Значение второй строки будет from=3 и to=7.

Если формат не задан, эта функция создаст таблицу с пустым форматом (например, без столбцов). Затем эту таблицу можно расширить, используя другие функции обработки таблиц.

DataTable

tableFromCSV(String csv, String header, String delimiter [, String format])

Функция принимает документ CSV как входные данные и преобразует его в таблицу данных.

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

Формат таблицы может быть определен с помощью параметра формат, который должен быть корректным форматом таблицы данных, кодированной в строку. Количество столбцов, определенных форматом, должно соответствовать количеству столбцов в файле CSV.

Параметр заголовок определяет содержание первой строки в файле CSV. Значение параметра зависит от того, определен формат или нет.
 

Если формат определен, заголовок может быть следующим:

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

• skip
  Первая строка CSV файла пропускается (считается незначимыми данными).

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

• names
  Имена полей таблицы данных импортируются из первой строки CSV файла. Если имя оказывается пустым, оно заменяется номером соответствующего столбца. Тип полей таблицы данных установлен на строку.

• descriptions
  Описания полей таблицы данных импортируются из первой строки CSV файла. Номера соответствующих столбцов используются как имена полей таблицы данных. Тип полей таблицы данных установлен на строку.
   

Функция использует следующие настройки (описаны в опциях импорта/экспорта в CSV):

• Использовать ограничитель текста: не использовать.

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

• Символ комментария: знак номера (#).

DataTable

tableFromJSON(String json [, boolean convertUnequalFieldTypesToString])

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

Если указан и активирован параметр convertUnequalFieldTypesToString, функция преобразуем значения столбцов в строку, если в этих столбцах имеются значения разных типов.

DataTable

tableToJSON(DataTable table)

Функция принимает таблицу данных как входные данные и преобразует ее в JSON документ.

Согласно спецификации, объект JSON  - это неупорядоченное множество пар имя/значение, поэтому нельзя гарантировать соблюдение определенного порядка элементов в результирующем документе JSON.

String

union(DataTable first, DataTable second [, DataTable third] [, DataTable …])

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

DataTable

validate(DataTable table [, Boolean throwErrors])

Выполняет валидаторы таблицы для проверки правильности данных в таблице. 

Если параметр throwErrors false или отсутствует, возвращает null в случае успеха и сообщение об ошибке при сбое валидации.

Если параметр throwErrors true, возвращает саму таблицу. В этом случае все ошибки выдаются как исключения фукнции.

Object