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

Функция

Описание

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

Вычисление на сервере

Вычисление в браузере

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

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

Возвращает новую таблицу данных. Не изменяет исходную таблицу table.

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

DataTable

Да

Да

addColumnsEx(DataTable table, DataTable columnsToAdd, boolean concurrent)

Похожа на функцию addColumns(), за исключением того, что Формат and Значение добавляемых столбцов определяются одним аргументом columnsToAdd типа DataTable.

Таблица columnsToAdd должна содержать два поля, Format и Value которые будут использованы как строка формата и выражение для значения.

Поле Format закодировано в строку, согласно разделу кодирование формата.

Значение Value для этого поля рассчитывается вычислением выражения которое может содержать ссылки на другие ячейки этой таблицы.

Если ряд не определен в ссылке, она возвращается к текущему ряду (т.е. к тому, для которого рассчитывается значение нового поля

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

Возвращает новую таблицу данных. Не изменяет исходную таблицу table.

DataTable

Да

Да

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

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

Возвращает новую таблицу данных. Не изменяет исходную таблицу table.

DataTable

Да

Да

adjustRecordLimits(DataTable table, Integer minRecords, Integer maxRecords)

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

Возвращает новую таблицу данных. Не изменяет исходную таблицу table.

DataTable

Да

Да

aggregate(Object tableOrMask, String expression, Object initialValue)

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

Выражение обычно оперирует двумя значениями: значением предыдущего вычисления, ссылка на которое осуществляется с помощью {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

Да

Да

array(String fieldName [, Object value1, Object value2,…])

Создает таблицу в виде массива с одним столбцом из аргументов valueN. Единственное поле таблицы будет называться fieldName. Тип поля определяется типом первого найденного аргумента value, не являющегося NULL. Если значение не указано или все указанные значения являются NULL, тип поля будет String.

Пример: array("integers",1,2,3,4) создаст таблицу с одним полем с именем "integers" и четырьмя строками с последовательными значениями 1, 2, 3 и 4.

DataTable

Да

Нет

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)

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

Изменяет и возвращает исходную таблицу table. Возвращает новую DataTable в случае, если исходная таблица неизменяема.

DataTable

Да

Да

collect(DataTable|String tableOrMask, String expression)

Одновременно обрабатывает записи входной таблицы (если tableOrMask - таблица данных) или контексты, соответствующие маске (если tableOrMask - строка маски), вычисляя выражение для каждой записи или контекста. Если первым аргументом является таблица данных, она становится таблицей по умолчанию для вычисляемого выражения, и текущая обрабатываемая строка становится строкой по умолчанию. Если первым аргументом является маска контекста, то текущий обрабатываемый контекст становится контекстом по умолчанию для вычисляемого выражения. Выражение должно возвращать таблицу. Все возвращаемые таблицы объединяются с помощью логики функции union(), и возвращается результирующая таблица.

DataTable

Да

Нет

convert(DataTable table, String format [, Boolean useVisibleSeparators)

Конвертирует таблицу table в формат, определяемый аргументом format. Формат кодируется в строку согласно разделу кодирование формата. Необязательный параметр useVisibleSeparators по умолчанию имеет значение true, что указывает на то, что в строке формата используются видимые разделители. Если используются невидимые разделители, useVisibleSeparators следует установить в значение false.

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

Возвращает новую таблицу данных. Не изменяет исходную таблицу table.

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

DataTable

Да

Да

copy(DataTable source, DataTable target)

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

Изменяет и возвращает таблицу target. Возвращает новую DataTable в случае, если исходная таблица target неизменяема.

DataTable

Да

Да

count(DataTable | Number value1 [, DataTable | Number value2, ...])

Возвращает количество числовых значений, найденных в списке предоставленных таблиц и значений.

Integer

Да

Нет

countBlank(DataTable | Number value1 [, DataTable | Number value2, ...])

Возвращает количество значений null и пустых строк, найденных в списке предоставленных таблиц и значений.

Integer

Да

Нет

countIf(DataTable table1, String condition1 [, DataTable table2, String condition2, ...])

Проверяет каждую из предоставленных таблиц для подсчета значений, соответствующих условиям. Возвращает общее количество найденных совпадающих значений. Условие - это выражение, которое может ссылаться на проверяемое значение с помощью переменной окружения “value”, то есть через ссылку {env/value}.

Integer

Да

Нет

decode(String stringToDecode)

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

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

DataTable

Да

Да

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

Изменяет описание поля field1 на description1 и т.д.

Возвращает новую таблицу данных. Не изменяет исходную таблицу table.

Пример: 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)

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

Возвращает новую таблицу данных. Не изменяет исходную таблицу table.

DataTable

Да

Да

encode(DataTable table [, boolean useVisibleSeparators])

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

String

Да

Да

exists(DataTable table, String field, Object value)

Возвращает true, если таблица table содержит запись, в которой значения поля field равно value. В противном случае возвращает false.

Boolean

Да

Нет

filter(DataTable table, String filterExpression)

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

Возвращает новую таблицу данных. Не изменяет исходную таблицу table.

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

DataTable

Да

Да

getFormat(DataTable table [, Boolean useVisibleSeparators [, Boolean asTable]]])

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

String | DataTable

Да

Да

getQuality(Data Table table)

Принимает любую таблицу table в качестве аргумента и возвращает свойство Quality аргумента table, если оно существует.

Integer

Да

Да

getTimestamp(Data Table table)

Принимает любую таблицу table в качестве аргумента и возвращает свойство Timestamp аргумента table, если оно существует.

Date

Да

Да

hasField(DataTable table, String field)

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

Boolean

Да

Да

hselect(DataTable table, Integer rowToSelect, Integer rowToCheck, Object value [, Boolean exactMatch])

Сканирует таблицу по столбцам и находит столбец, в котором rowToCheck равен (если exactMatch равен true или не указан) или ближе всего (если exactMatch равен false) к value. Возвращает значение строки rowToSelect из этой записи. Возвращает null, если exactMatch равен true или не указан и не найдена ни одна подходящая запись. Если exactMatch равен false, таблица должна быть отсортирована по полю rowToCheck в порядке возрастания, чтобы получить правильные результаты.

Object

Да

Нет

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

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

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

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

Возвращает новую таблицу данных. Не изменяет исходную таблицу sourceTable.

DataTable

Да

Да

join(DataTable left, DataTable right)

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

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

Возвращает новую таблицу данных. Не изменяет исходные таблицы left и right.

DataTable

Да

Да

match(Object searchKey, DataTable table [, Integer searchType [, Boolean zeroBased]])

Ищет и возвращает относительную позицию значения searchKey в однострочной или одностолбцовой таблице table>.

Если searchType равен 1, что является значением по умолчанию, предполагается, что таблица отсортирована по возрастанию, и возвращается наибольшее значение, меньшее или равное searchKey. Если searchType равен 0, возвращается позиция точного совпадения в несортированной таблице. Если searchType равен -1, предполагается, что диапазон отсортирован по убыванию, и возвращается наименьшее значение, большее или равное searchKey.

По-умолчанию нумерация позиций начинается с единицы, но это можно изменить с помощью параметра zeroBased.

Integer

Да

Нет

print(DataTable table, String expression, String separator)

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

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

String

Да

Да

processBindings(DataTable table)

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

Изменяет и возвращает исходный экземпляр таблицы table.

DataTable

Да

Нет

records(DataTable table)

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

Integer

Да

Да

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

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

Возвращает новую таблицу данных. Не изменяет исходную таблицу table.

DataTable

Да

Да

removeRecords(DataTable table, String fieldToCheck, Object value)

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

Возвращает новую таблицу данных. Не изменяет исходную таблицу table.

DataTable

Да

Да

select(DataTable table, String fieldToSelect, String fieldToCheck, Object value [, Boolean exactMatch])

Сканирует таблицу table по строкам и находит запись, в которой поле fieldToCheck равно (если exactMatch истинно или не указано) или наиболее близко (если exactMatch ложно) к значению value. Возвращает значение поля fieldToSelect из этой записи. Возвращает null, если exactMatch истинно или не указано и не найдено ни одной подходящей записи. Если exactMatch ложно, то для получения корректных результатов таблица table должна быть отсортирована по полю fieldToCheck в порядке возрастания.

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

Object

Да

Да

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

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

Изменяет и возвращает таблицу table. Возвращает новую DataTable в случае, если исходная таблица table является неизменяемой.

DataTable

Да

Да

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

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

Возвращает новую таблицу данных. Не изменяет исходную таблицу table.

DataTable

Да

Да

setNestedField(DataTable table, Object value, String field1, Integer row1 [, String field2, Integer row2, ...])

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

Изменяет и возвращает таблицу table. Возвращает новую DataTable в случае, если исходная таблица table является неизменяемой.

DataTable

Да

Нет

setQuality(Data Table table, Integer quality)

Устанавливает свойство Quality в таблице table в значение quality и возвращает обновленную таблицу table. Удаляет свойство Quality, если аргумент quality равен NULL.

Изменяет и возвращает таблицу table. Возвращает новую DataTable в случае, если исходная таблица table является неизменяемой.

DataTable

Да

Нет

setTimestamp(Data Table table, Date timestamp)

Устанавливает свойство Timestamp в таблице table в значение timestamp и возвращает обновленную таблицу table. Удаляет свойство Timestamp, если аргумент timestamp равен NULL.

Изменяет и возвращает таблицу table. Возвращает новую DataTable в случае, если исходная таблица table является неизменяемой.

DataTable

Да

Нет

sort(DataTable table, String field, boolean ascending)

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

Возвращает новую таблицу данных. Не изменяет исходную таблицу table.

DataTable

Да

Да

subtable(DataTable table, Integer firstRecord, Integer recordCount, String field1, String field2, ...)

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

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

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

Возвращает новую таблицу данных. Не изменяет исходную таблицу table.

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

DataTable

Да

Да

structure(String fieldNamePrefix [, Object value1, Object value2,…])

Генерирует таблицу с одной записью, количество полей которой соответствует количеству аргументов valueN. Имена полей автоматически определяются путем добавления индекса, начинающегося с 1, к строке fieldNamePrefix. Тип данных каждого поля определяется типом соответствующего аргумента value. Если аргумент value равен NULL, соответствующий тип поля будет String.

Пример: structure("field", "one", 2, 3.14, array("table","chair")) создаст таблицу данных с одной строкой и следующими именами полей и значениями:

• field1: Поле типа String со значением "one" в первой строке

• field2: Поле типа Long со значением 2 в первой строке

• field3: Поле типа Double со значением 3.14 в первой строке

• field4: Поле типа DataTable с таблицей данных, выраженной array("table","chair") в первой строке

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 [, String qualifier [, Integer escapeMode [, String comment]]]])

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

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

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

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

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

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

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

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

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

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

Параметр qualifier указывает символ, который следует использовать в качестве текстового классификатора в данных. По умолчанию это двойная кавычка (").

Параметр escapeMode позволяет указать символ экранирования. Символ escape позволяет использовать в данных символ текстового классификатора:

• Для обозначения вхождения текстового классификатора в текст перед ним используйте escape-символ.

• Используйте два экземпляра текстового классификатора для представления одного экземпляра текстового классификатора.

Параметр comment позволяет указать символ комментария. Текст, следующий за символом комментария, будет игнорироваться до символа новой строки..

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

DataTable

Да

Да

tableFromJSON(String json [, Boolean convertUnequalFieldTypesToString])

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

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

DataTable

Да

Да

tableToJSON(DataTable table)

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

String

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

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

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

Возвращает новую таблицу данных. Не изменяет исходные таблицы.

DataTable

Да

Да

validate(DataTable table [, Boolean throwErrors])

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

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

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

Object

Да

Да