Creatio development guide

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:

None 0 Тип фильтра не определен.
CompareFilter 1 Фильтр сравнения. Используется для сравнения результатов выражений.
IsNullFilter 2 Фильтр, определяющий, является ли проверяемое выражение пустым или нет.
Between 3 Фильтр, проверяющий, входит ли проверяемое выражение в диапазон выражений.
InFilter 4 Фильтр, проверяющий, равно ли проверяемое выражение одному из выражений.
Exists 5 Фильтр существования по заданному полю.
FilterGroup 6 Группа фильтров. Группы фильтров могут вкладываться друг в друга, т.е. коллекция сама может быть элементом другой коллекции.
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 Конечное выражение диапазона фильтрации.
TrimDateTimeParameterToDate bool Признак, указывающий отсекать ли время для параметров типа дата-время.
Key string Ключ фильтра в коллекции фильтров Items.
IsAggregative bool Признак того, что фильтр является агрегирующим.
LeftExpressionCaption string Заголовок левой части сравнения.
ReferenceSchemaName string Имя схемы объекта, на которую ссылается левая часть фильтра, если тип колонки — справочник.

 

Класс BaseExpression является базовым классом выражений. Он определен в пространстве имен Terrasoft.Nui.ServiceModel.DataContract библиотеки Terrasoft.Nui.ServiceModel. Свойства экземпляра этого класса заполняются в зависимости от свойства ExpressionType, которое и задает тип выражения. Полный перечень свойств класса BaseExpression приведен в табл. 2.

Табл. 2. — Основные свойства класса BaseExpression

Свойство Тип Описание
ExpressionType EntitySchemaQueryExpressionType

Тип выражения, определяющий значение, которое будет содержаться в добавляемой колонке. Задается значением перечисления EntitySchemaQueryExpressionType пространства имен Terrasoft.Core.Entities, определенного в библиотеке классов Terrasoft.Core. Для InsertQuery устанавливается значение EntitySchemaQueryExpressionType.Parameter.

Значения перечисления EntitySchemaQueryExpressionType:

SchemaColumn 0 Колонка схемы
Function 1 Функция
Parameter 2 Параметр
SubQuery 3 Вложенный запрос
ArithmeticOperation 4 Арифметическая операция
ColumnPath string Путь к колонке относительно корневой схемы. Правила построения путей см. в статье "Использование EntitySchemaQuery для построения запросов к базе данных".
Parameter Parameter

Определяет значение, которое будет содержаться в добавляемой колонке. Имеет тип Parameter, определенный в пространстве имен Terrasoft.Nui.ServiceModel.DataContract.

FunctionType FunctionType

Тип функции. Задается значением из перечисления FunctionType, определенного в пространстве имен Terrasoft.Nui.ServiceModel.DataContract.

Значения перечисления FunctionType:

None 0 Не определен
Macros 1 Макрос
Aggregation 2 Агрегирующая функция
DatePart 3 Часть даты
Length 4 Длина
MacrosType EntitySchemaQueryMacrosType

Тип макроса. Задается значением перечисления EntitySchemaQueryMacrosType, определенного в пространстве имен Terrasoft.Core.Entities.

FunctionArgument BaseExpression Аргумент функции. Принимает значение, если функция определена с параметром. Класс BaseExpression определен в пространстве имен Terrasoft.Nui.ServiceModel.DataContract, является предком для класса ColumnExpresion и имеет такой же набор свойств.
DatePartType DatePart

Часть даты. Задается значением из перечисления DatePart, определенного в пространстве имен Terrasoft.Nui.ServiceModel.DataContract.

Значения перечисления DatePart:

None 0 Не определен
Day 1 День
Week 2 Неделя
Month 3 Месяц
Year 4 Год
Weekday 5 День недели
Hour 6 Час
HourMinute 7 Минута

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, а значение колонки [ФИО] начинается с символа "Ч".

Алгоритм реализации кейса

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 = "Ч"
            }
        }
    }
}

Полностью исходный код выполнения данного примера можно скачать здесь.

Смотрите также

© Terrasoft 2002-2016.

Был ли данный материал полезен?

Как можно улучшить эту статью?