Функции обработки таблиц данных
Раздел описывает функции языка выражений, относящиеся к обработке таблиц данных.
Функция
Описание
Тип результата
Вычисление на сервере
Вычисление в браузере
addColumns(DataTable table, String format1, String expression1, String format2, String expression2, ...)
Добавляет один и более столбцов к таблице table. Формат первого добавляемого столбца определен аргументом format1, его значение задается через expression1, и т.д. Формат закодирован в строку, согласно разделу кодирование формата (используются видимые разделители). Значение для данного поля рассчитывается путем выполнения выражения, которое может содержать ссылки на другие ячейки данной таблицы. Если ряд не определен в ссылке, она возвращается к текущему ряду (т.е. к тому, для которого рассчитывается значение нового поля).
Пример: 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.
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)
Рассчитывает некоторое "объединенное значение" для Таблицы данных (если первый аргумент является Таблицей данных) или количество контекстов (если первый аргумент является Строкой, представляющей маску контекста). Если первый аргумент - Таблица данных, aggregate рассчитывает выражение для каждой записи; исходная Таблица данных, таким образом, становится таблицей по умолчанию, а текущий ряд - рядом по умолчанию. Если источником является маска контекста, выражение рассчитывается для каждого контекста, соответствующего маске, он становится контекстом по умолчанию.
Выражение обычно оперирует двумя значениями: значением предыдущего вычисления, ссылка на которое осуществляется с помощью {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
Да
Да
getQuality(Data Table table)
Принимает любую таблицу table в качестве аргумента и возвращает свойство Quality аргумента table, если оно существует.
Integer
Да
Да
getTimestamp(Data Table table)
Принимает любую таблицу table в качестве аргумента и возвращает свойство Timestamp аргумента table, если оно существует.
Date
Да
Да
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
Да
Да
processBindings(DataTable table)
Выполняет все привязки таблицы определенные форматом аргумента table и возвращает обновленную таблицу.
DataTable
Да
Нет
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
Да
Да
setNestedField(DataTable table, Object value, String field1, Integer row1 [, String field2, Integer row2, ...])
Обновляет ячейку подтаблицу таблицы table на значение аргумента value. Вложенная подтаблица, которая должна быть обновлена, указывается серией пар аргументов поля field строки row.
DataTable
Да
Нет
setQuality(Data Table table, Integer quality)
Устанавливает свойство Quality в таблице table в значение quality и возвращает обновленную таблицу table.
Удаляет свойство Quality если аргумент quality равен NULL.
DataTable
Да
Нет
setTimestamp(Data Table table, Date timestamp)
Устанавливает свойство Timestamp в таблице table в значение timestamp и возвращает обновленную таблицу table.
Удаляет свойство Timestamp если аргумент timestamp равен NULL.
DataTable
Да
Нет
sort(DataTable table, String field, boolean ascending)
Сортирует записи таблицы в соответствии с естественным порядком значений поля. Значение флажка возрастание определяет порядок сортировки.
DataTable
Да
Да
subtable(DataTable table, Integer firstRecord, Integer recordCount, String field1, String field2, ...)
Принимает таблицу table в качестве аргумента и возвращает другую таблицу, содержащую только те поля, имена которых определяются аргументами field. Формат и содержание сохраняются в возвращаемой подтаблице.
Если аргумент firstRecord указан (не null), то в результирующую таблицу копируются только записи, начиная с нулевого индекса firstRecord.
Если аргумент recordCount указан (не null), то ограничивается количество записей, которые будут добавлены в результирующую таблицу.
Пример: subtable({users:list()}, "firstname", "lastname") вернет таблицу с двумя столбцами, содержащими имя и фамилию всех пользователей AggreGate 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 [, 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
Да
Да