DataService. Фильтрация данных
Glossary Item Box
Общие положения
Во время выполнения операций службы DataService часто необходимо выполнять фильтрацию данных. Так, например, при чтении записей раздела необходимо произвести выборку только тех записей, которые соответствуют определенному критерию или нескольким критериям. Для формирования этих критериев в приложении bpm'online предусмотрен класс Filters.
Класс Filters
Класс Filters определен в пространстве имен Terrasoft.Nui.ServiceModel.DataContract библиотеки классов Terrasoft.Nui.ServiceModel.dll. Для простоты восприятия иерархическую структуру фильтра Filters удобно представить в формате объекта JSON:
"Filters":{ "RootSchemaName":["Название корневой схемы"], "FilterType":[Тип фильтра], "ComparisonType":[Тип сравнения], "LogicalOperation":[Логическая операция], "IsNull":[Признак проверки на заполненность], "IsEnabled":[Признак активности], "IsNot":[Признак использования оператора отрицания], "SubFilters":[Фильтры подзапроса], "Items":[Коллекция группы фильтров], "LeftExpression":[Выражение, подлежащее проверке], "RightExpression":[Выражение фильтрации], "RightExpressions":[Массив выражений фильтрации], "RightLessExpression":[Начальное выражение диапазона фильтрации], "RightGreaterExpression":[Конечное выражение диапазона фильтрации], "TrimDateTimeParameterToDate":[Признак отсекания времени для параметров типа дата/время], "Key":["Ключ фильтра в коллекции фильтров"], "IsAggregative":[Признак агрегирующего фильтра], "LeftExpressionCaption":["Заголовок выражения, подлежащего проверке"], "ReferenceSchemaName":["Название ссылочной схемы"] }
Основные свойства класса Filters и их возможные значения представлены в таблице 1.
Табл. 1. — Свойства класса Filters
Свойство | Тип | Описание | |||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
RootSchemaName | string | Строка, содержащая название корневой схемы объекта добавляемой записи. | |||||||||||||||||||||
FilterType | FilterType |
Тип фильтра. Задается значением перечисления FilterType пространства имен Terrasoft.Nui.ServiceModel.DataContract. Значения перечисления FilterType:
|
|||||||||||||||||||||
ComparisonType | FilterComparisonType |
Тип операции сравнения. Задается значением перечисления FilterComparisonType пространства имен Terrasoft.Core.Entities. |
|||||||||||||||||||||
LogicalOperation | LogicalOperationStrict | Логическая операция. Тип не допускает значение None, определен в перечислении LogicalOperationStrict пространства имен Terrasoft.Common. | |||||||||||||||||||||
IsNull | bool | Признак проверки на заполненность проверяемого выражения. | |||||||||||||||||||||
IsEnabled | bool | Признак того, что фильтр активен и будет учитываться при построении запроса. | |||||||||||||||||||||
IsNot | bool | Определяет, использовать ли логический оператор отрицания. | |||||||||||||||||||||
SubFilters | Filters | Фильтры подзапроса. Не могут содержать фильтры с другими подзапросами. | |||||||||||||||||||||
Items | Dictionary<string, Filter> | Коллекция, содержащая группу фильтров. | |||||||||||||||||||||
LeftExpression | BaseExpression | Выражение в левой части сравнения, т.е. выражение, подлежащее проверке. Класс BaseExpression определен в пространстве имен Terrasoft.Nui.ServiceModel.DataContract. | |||||||||||||||||||||
RightExpression | BaseExpression | Выражение фильтрации, которое будет сравниваться с выражением, содержащимся в свойстве LeftExpression. | |||||||||||||||||||||
RightExpressions | BaseExpression[ ] | Массив выражений, которые будут сравниваться с выражением, содержащимся в свойстве LeftExpression. | |||||||||||||||||||||
RightLessExpression | BaseExpression | Начальное выражение диапазона фильтрации. | |||||||||||||||||||||
RightGreaterExpression | BaseExpression | Конечное выражение диапазона фильтрации. | |||||||||||||||||||||
TrimDateTime |
bool | Признак, указывающий отсекать ли время для параметров типа дата-время. | |||||||||||||||||||||
Key | string | Ключ фильтра в коллекции фильтров Items. | |||||||||||||||||||||
IsAggregative | bool | Признак того, что фильтр является агрегирующим. | |||||||||||||||||||||
LeftExpressionCaption | string | Заголовок левой части сравнения. | |||||||||||||||||||||
ReferenceSchemaName | string | Имя схемы объекта, на которую ссылается левая часть фильтра, если тип колонки — справочник. |
Класс BaseExpression является базовым классом выражений. Он определен в пространстве имен Terrasoft.Nui.ServiceModel.DataContract библиотеки Terrasoft.Nui.ServiceModel. Свойства экземпляра этого класса заполняются в зависимости от свойства ExpressionType, которое и задает тип выражения. Полный перечень свойств класса BaseExpression приведен в табл. 2.
Табл. 2. — Основные свойства класса BaseExpression
Свойство | Тип | Описание | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
ExpressionType | EntitySchemaQuery |
Тип выражения, определяющий значение, которое будет содержаться в добавляемой колонке. Задается значением перечисления EntitySchemaQueryExpressionType пространства имен Terrasoft.Core.Entities, определенного в библиотеке классов Terrasoft.Core. Для InsertQuery устанавливается значение EntitySchemaQueryExpressionType.Parameter. Значения перечисления EntitySchemaQuery
|
||||||||||||||||||||||||
ColumnPath | string | Путь к колонке относительно корневой схемы. Правила построения путей см. в статье "Использование EntitySchemaQuery для построения запросов к базе данных". | ||||||||||||||||||||||||
Parameter | Parameter |
Определяет значение, которое будет содержаться в добавляемой колонке. Имеет тип Parameter, определенный в пространстве имен Terrasoft.Nui.ServiceModel.DataContract. |
||||||||||||||||||||||||
FunctionType | FunctionType |
Тип функции. Задается значением из перечисления FunctionType, определенного в пространстве имен Terrasoft.Nui.ServiceModel.DataContract. Значения перечисления FunctionType:
|
||||||||||||||||||||||||
MacrosType | EntitySchemaQuery |
Тип макроса. Задается значением перечисления EntitySchemaQueryMacrosType, определенного в пространстве имен Terrasoft.Core.Entities. |
||||||||||||||||||||||||
FunctionArgument | BaseExpression | Аргумент функции. Принимает значение, если функция определена с параметром. Класс BaseExpression определен в пространстве имен Terrasoft.Nui.ServiceModel.DataContract, является предком для класса ColumnExpresion и имеет такой же набор свойств. | ||||||||||||||||||||||||
DatePartType | DatePart |
Часть даты. Задается значением из перечисления DatePart, определенного в пространстве имен Terrasoft.Nui.ServiceModel.DataContract. Значения перечисления DatePart:
|
||||||||||||||||||||||||
AggregationType |
AggregationType | Тип агрегирующей функции. Задается значением из перечисления AggregationType, определенного в пространстве имен Terrasoft.Common, определенного в библиотеке классов Terrasoft.Common. | ||||||||||||||||||||||||
AggregationEvalType | AggregationEvalType | Область применения агрегирующей функции. Задается значением из перечисления AggregationEvalType, определенного в пространстве имен Terrasoft.Core.DB, определенного в библиотеке классов Terrasoft.Core. | ||||||||||||||||||||||||
SubFilters | Filters | Коллекция фильтров вложенных запросов. Имеет тип Filters, определенный в пространстве имен Terrasoft.Nui.ServiceModel.DataContract. |
Подробно об использовании фильтров в клиентской части изложено в статье "Работа с фильтрами EntitySchemaQuery". Далее рассматривается пример использования фильтров в запросах к службе DataService из стороннего приложения.
Пример использования фильтров в стороннем приложении
Описание кейса
Необходимо создать консольное приложение, которое, используя службу DataService, прочитает записи раздела [Контакт] со следующими колонками:
- Id;
- ФИО;
- Количество активностей — агрегирующая колонка, отображающая количество активностей данного контакта.
При этом необходимо отфильтровать данные таким образом, чтобы были прочитаны только те контакты, у которых количество активностей находится в диапазоне от 1 до 3, а значение колонки [ФИО] начинается с символа "Ч".
Пример реализации
Полностью исходный код выполнения данного примера можно посмотреть в репозитории GitHub здесь.
Алгоритм реализации кейса
1. Создать и настроить проект консольного приложения C#, выполняющий чтение записей
Для выполнения этого шага последовательности реализации кейса необходимо выполнить пример чтения записей в стороннем приложении, изложенный в статье "DataService. Чтение записи. Пример".
Результат реализации экземпляра класса запроса на чтение записей с нужными колонками в сокращенной форме:
// Экземпляр класса запроса. var selectQuery = new SelectQuery() { // Название корневой схемы. RootSchemaName = "Contact", // Добавление колонок в запрос. Columns = new SelectQueryColumns() { // Коллекция колонок. Items = new Dictionary<string, SelectQueryColumn>() { //Колонка [ФИО]. { // Ключ. "Name", // Значение. new SelectQueryColumn() { // Выражение, задающее тип колонки. Expression = new ColumnExpression() { // Тип выражения — колонка схемы. ExpressionType = EntitySchemaQueryExpressionType.SchemaColumn, // Путь к колонке. ColumnPath = "Name" } } }, // Колонка [Количество активностей]. { "ActivitiesCount", new SelectQueryColumn() { Expression = new ColumnExpression() { // Тип выражения — вложенный запрос. ExpressionType = EntitySchemaQueryExpressionType.SubQuery, // Путь к колонке относительно корневой схемы. ColumnPath = "[Activity:Contact].Id", // Тип функции — агрегирующая. FunctionType = FunctionType.Aggregation, // Тип агрегации — количество. AggregationType = AggregationType.Count } } } } } };
2. Добавить реализацию фильтров
Для того чтобы отфильтровать необходимые данные, необходимо создать экземпляр класса коллекции фильтров Filters, заполнить необходимые свойства значениями, а затем ссылку на этот экземпляр передать в свойство Filters экзепляра класса запроса, созданного на предыдущем шаге.
Пример реализации класса коллекции фильтров:
// Фильтры запроса. var selectFilters = new Filters() { // Тип фильтра — группа. FilterType = Terrasoft.Nui.ServiceModel.DataContract.FilterType.FilterGroup, // Коллекция фильтров. Items = new Dictionary<string, Filter> { //Реализация фильтров. } }; // Добавление фильтров в запрос. selectQuery.Filters = selectFilters; // Сериализация экземпляра класса запроса на чтение в JSON-строку. var json = new JavaScriptSerializer().Serialize(selectQuery);
Свойство Items должно содержать коллекцию типа ключ-значение. В качестве ключа указывается строка, содержащая название фильтра, а в качестве значения — экземпляр класса Filter, содержащий непосредственную реализацию фильтра.
Для реализации фильтра, обеспечивающего выбор только тех контактов, у которых количество активностей попадает в диапазон от 1 до 3, в коллекцию фильтров необходимо добавить следующий экземпляр:
// Фильтрация по активностям. { // Ключ. "FilterActivities", // Значение. new Filter { // Тип фильтра — фильтр диапазона. FilterType = Terrasoft.Nui.ServiceModel.DataContract.FilterType.Between, // Тип сравнения — диапазон. ComparisonType = FilterComparisonType.Between, // Выражение, подлежащее проверке. LeftExpression = new BaseExpression() { // Тип выражения — вложенный запрос. ExpressionType = EntitySchemaQueryExpressionType.SubQuery, // Путь к колонке относительно корневой схемы. ColumnPath = "[Activity:Contact].Id", // Тип функции — агрегирующая. FunctionType = FunctionType.Aggregation, // Тип агрегации — количество. AggregationType = AggregationType.Count }, // Конечное выражение диапазона фильтрации. RightGreaterExpression = new BaseExpression() { // Тип выражения — параметр. ExpressionType = EntitySchemaQueryExpressionType.Parameter, // Параметр выражения. Parameter = new Parameter() { // Тип данных параметра — целое число. DataValueType = DataValueType.Integer, // Значение параметра. Value = 3 } }, // Начальное выражение диапазона фильтрации. RightLessExpression = new BaseExpression() { ExpressionType = EntitySchemaQueryExpressionType.Parameter, Parameter = new Parameter() { DataValueType = DataValueType.Integer, Value = 1 } } } }
Фильтрацию записей контактов, у которых значение колонки [ФИО] начинается с символа "Ч", можно выполнить, добавив в коллекцию фильтров следующий экземпляр:
// Фильтрация по имени. { // Ключ. "FilterName", // Значение. new Filter { // Тип фильтра — фильтр сравнения. FilterType = Terrasoft.Nui.ServiceModel.DataContract.FilterType.CompareFilter, // Тип сравнения — начинается выражением. ComparisonType = FilterComparisonType.StartWith, // Выражение, подлежащее проверке. LeftExpression = new BaseExpression() { // Тип выражения — колонка схемы. ExpressionType = EntitySchemaQueryExpressionType.SchemaColumn, // Путь к колонке. ColumnPath = "Name" }, // Выражение фильтрации. RightExpression = new BaseExpression() { // Тип выражения — параметр. ExpressionType = EntitySchemaQueryExpressionType.Parameter, // Параметр выражения. Parameter = new Parameter() { // Тип данных параметра — текст. DataValueType = DataValueType.Text, // Значение параметра. Value = "Ч" } } } }
Полностью исходный код выполнения данного примера можно посмотреть в репозитории GitHub здесь.