Описание основных методов EntitySchemaQuery. Часть 1

1. Общее описание

EntitySchemaQuery (в дальнейшем ESQ) представляет собой высокоуровневый класс, позволяющий собирать сложные запросы, используя только понятия путей к колонкам объекта таблицы (в дальнейшем схемы) относительно корневой таблицы (RootSchema).

2. Конструкторы

public EntitySchemaQuery() – конструктор по умолчанию. Используется исключительно для внутренних целей и не применим в конфигурации.

public EntitySchemaQuery(EntitySchema rootSchema) – конструктор принимающий экземпляр схемы, которая будет использоваться как корневая RootSchema.
Где: rootSchema - экземпляр схемы.

public EntitySchemaQuery(EntitySchemaManager entitySchemaManager, string sourceSchemaName) - конструктор принимающий экземпляр менеджера схем и имя схемы. Осуществляется поиск схемы по имени в менеджере и заполнение свойства RootSchema.
Где: entitySchemaManager - экземпляр менеджера схем. sourceSchemaName – имя схемы в менеджере.

public EntitySchemaQuery(EntitySchemaQuery source) – конструктор копирования. Объект создается на основании экземпляра переданного объекта.
Где: source – экземпляр объекта-источника копирования.

3. Свойства

public EntitySchema RootSchema – корневая схема ESQ. Все пути к колонкам схем, в том числе и других, задаются относительно этой корневой схемы. Заполняется при создании объекта.
Изменение: только чтение
Значение по умолчанию: null

public EntitySchemaQueryColumn PrimaryQueryColumn – колонка ESQ созданная по первичной колонке корневой схемы. Заполняется при первом обращении.
Изменение: только чтение
Значение по умолчанию: экземпляр созданный по первичной колонке корневой схемы

public EntitySchemaQueryColumnCollection Columns – коллекция добавленных ESQ колонок участвующих в конечном запросе.
Изменение: только чтение с возможность наполнения коллекции
Значение по умолчанию: содержит колонку из свойства PrimaryQueryColumn

public EntitySchemaQueryFilterCollection Filters – коллекция добавленных ESQ фильтров участвующих в конечном запросе.
Изменение: только чтение с возможность наполнения коллекции.
Значение по умолчанию: пустая коллекция public QueryJoinRightLevel JoinRightState – параметр определяющий условие наложение прав если схема администрируется по записям при использовании связанных таблиц.
Изменение: чтение и запись
Значение по умолчанию: вычитывается из системной настройки «QueryJoinRightLevel». Если настройка не задана то значение равно EnabledForAdditionalColumns;
Доступные значения: QueryJoinRightLevel.EnabledAlways – всегда QueryJoinRightLevel.EnabledForAdditionalColumns – накладывать только если из связанной схемы в запросе используются колонки отличные первичной(PrimaryColumn) и первичной для отображения( QueryJoinRightLevel.Disabled – никогда не накладывать

public bool IsDistinct – убирать или нет дубли в результирующем наборе данных
Изменение: чтение и запись
Значение по умолчанию: false
Пример:

var esq = new EntitySchemaQuery(EntitySchemaManager, " ESQCityNA"); esq.IsDistinct = true; esq.AddColumn("Id"); string sqlText = esq.GetSelectQuery(CurrentConnection).GetSqlText();
SqlText:

SELECT DISTINCT "Id" FROM "ESQCityNA" "ESQCityNA"
4. Методы
a. Методы управления колоноками

public void AddColumn(EntitySchemaQueryColumn queryColumn) – добавляет созданную ранее ESQ колонку в коллекцию колонок
Где: queryColumn – экземпляр колонки.
Пример:

var esq = new EntitySchemaQuery(); var column = new EntitySchemaQueryColumn(); esq.AddColumn(column);

public EntitySchemaQueryColumn AddColumn(string columnPath) – создает и добавляет ESQ колонку по пути к колонке схемы относительно корневой RootSchema схемы(объекта)
Где: columnPath – путь к колонке схемы относительно корневой схемы.
Возвращает: экземпляр созданной колонки.
Пример:

var esq = new EntitySchemaQuery(EntitySchemaManager, "City"); esq.AddColumn("Name"); string sqlText = esq.GetSelectQuery(CurrentConnection).GetSqlText();
SqlText запроса:

SELECT "Name" FROM "City"

public EntitySchemaQueryColumn AddColumn(EntitySchemaQueryFunction function) – создает и добавляет ESQ колонку по переданной функции.
Где: function – экземпляр ESQ функции.
Возвращает: экземпляр созданной колонки.
Пример:

var esq = new EntitySchemaQuery(EntitySchemaManager, "City"); var func = esq.CreateIsNullFunction("Name", "Code"); esq.AddColumn(func); string sqlText = esq.GetSelectQuery(CurrentConnection).GetSqlText();
SqlText запроса:

SELECT NVL("City"."Name", "City"."Code") "IsNull" FROM "City" "City"

public EntitySchemaQueryColumn AddColumn(string columnPath, AggregationTypeStrict aggregationType, out EntitySchemaQuery subQuery) – создает и добавляет ESQ колонку в виде подзапроса, возвращающего результат указанной агрегирующей функции, по пути к колонке схемы относительно корневой RootSchema схемы(объекта).
Где: columnPath – путь к колонке схемы относительно корневой схемы. aggregationType – значение перечисления типов агрегирующих функций

public enum AggregationTypeStrict { Count, Sum, Avg, Min, Max } subQuery – ссылка на созданный подзапрос, помещенный в колонку
Возвращает: экземпляр созданной колонки.
Пример:

var esq = new EntitySchemaQuery(EntitySchemaManager, "ESQCountryNA"); EntitySchemaQuery subEsq = null; esq.AddColumn("[ESQCityNA:Country].Name", AggregationTypeStrict.Count, out subEsq); string sqlText = esq.GetSelectQuery(CurrentConnection).GetSqlText();
SqlText запроса:

SELECT ( SELECT COUNT("SubESQCityNA"."Id") "Count" FROM "ESQCityNA" "SubESQCityNA" WHERE "SubESQCityNA"."CountryId" = "ESQCountryNA"."Id") "SubESQCityNA" FROM "ESQCountryNA" "ESQCountryNA"

public void RemoveColumn(string columnName) – удаляет ESQ колонку из коллекции колонок по имени
Где: columnName – имя удаляемой колонки

public void AddAllSchemaColumns() – создает набор ESQ колонок по всем колонкам корневой таблицы

public EntitySchemaQueryColumn AddColumn(object parameterValue, DataValueType parameterDataValueType) – создает и добавляет колонку-параметр которая будет выбирать значение переданного параметра.
Где: parameterValue – значение параметра parameterDataValueType – тип параметра Возвращает: экземпляр созданной колонки.

public EntitySchemaQueryColumn AddColumn(EntitySchemaQuery subQuery) – создает и добавляет колонку-подзапрос на основании переданного подзапроса
Где: subQuery – подзапрос
Возвращает: экземпляр созданной колонки. b. Методы добавления фильтров

public IEntitySchemaQueryFilterItem CreateFilter(FilterComparisonType comparisonType, string leftExpressionColumnPath, params string[] rightExpressionColumnPaths) – создает и возвращает фильтр по двум колонкам.
Где: comparisonType – тип сравнения leftExpressionColumnPath – путь к колонке в левой части фильтра rightExpressionColumnPaths – пути к колонке в правой части фильтра
Возвращает: экземпляр созданного фильтра
Пример:

var esq = new EntitySchemaQuery(EntitySchemaManager, "ESQCityNA"); esq.AddColumn("Id"); var filter = esq.CreateFilter(FilterComparisonType.Equal, "ModifiedOn", "CreatedOn"); esq.Filters.Add(filter); string sqlText = esq.GetSelectQuery(CurrentConnection).GetSqlText();
SqlText запроса:

SELECT "ESQCityNA"."Id" "Id" FROM "ESQCityNA" "ESQCityNA" WHERE "ESQCityNA"."ModifiedOn" = "ESQCityNA"."CreatedOn"

public IEntitySchemaQueryFilterItem CreateFilter(FilterComparisonType comparisonType, string leftExpressionColumnPath, EntitySchemaQueryFunction rightExpressionValue) – создает фильтр по колонке и функции
Где: comparisonType – тип сравнения leftExpressionColumnPath – путь к колонке в левой части фильтра rightExpressionValue – экземпляр функции в правой части фильтра
Возвращает: экземпляр созданного фильтра
Пример:

var esq = new EntitySchemaQuery(EntitySchemaManager, "ESQCityNA"); esq.AddColumn("Id"); var func = esq.CreateIsNullFunction("ModifiedOn", "CreatedOn"); var filter = esq.CreateFilter(FilterComparisonType.Equal, "ModifiedOn", func); esq.Filters.Add(filter); string sqlText = esq.GetSelectQuery(CurrentConnection).GetSqlText();
SqlText запроса:

SELECT "ESQCityNA"."Id" "Id" FROM "ESQCityNA" "ESQCityNA" WHERE "ESQCityNA"."ModifiedOn" = NVL("ESQCityNA"."ModifiedOn", "ESQCityNA"."CreatedOn")

public IEntitySchemaQueryFilterItem CreateFilter(FilterComparisonType comparisonType, string leftExpressionColumnPath, EntitySchemaQueryMacrosType macrosType) – создает фильтр по колонке и значению макроса.
Где: comparisonType – тип сравнения leftExpressionColumnPath – путь к колонке в левой части фильтра macrosType – значение перечисления макроса определяющее функциональность фильтра
Значения:

public enum EntitySchemaQueryMacrosType { None, CurrentUser, CurrentUserContact, Yesterday, Today, Tomorrow, PreviousWeek, CurrentWeek, NextWeek, PreviousMonth, CurrentMonth, NextMonth, PreviousQuarter, CurrentQuarter, NextQuarter, PreviousHalfYear, CurrentHalfYear, NextHalfYear, PreviousYear, CurrentYear, NextYear }
Возвращает: экземпляр созданного фильтра
Пример:

var esq = new EntitySchemaQuery(EntitySchemaManager, "ESQCityNA"); esq.AddColumn("Id"); var filter = esq.CreateFilter(FilterComparisonType.Equal, "ModifiedOn", EntitySchemaQueryMacrosType.CurrentMonth); esq.Filters.Add(filter); string sqlText = esq.GetSelectQuery(CurrentConnection).GetSqlText();
SqlText запроса:

SELECT "ESQCityNA"."Id" "Id" FROM "ESQCityNA" "ESQCityNA" WHERE ("ESQCityNA"."ModifiedOn" >= :P1 AND "ESQCityNA"."ModifiedOn" :P2)

public IEntitySchemaQueryFilterItem CreateFilter(FilterComparisonType comparisonType, string leftExpressionColumnPath, EntitySchemaQuery rightExpressionValue) – создает фильтр по колонке и подзапросу
Где: comparisonType – тип сравнения leftExpressionColumnPath – путь к колонке в левой части фильтра rightExpressionValue – подзапрос в правой части фильтра
Возвращает: экземпляр созданного фильтра
Пример:

var esq = new EntitySchemaQuery(EntitySchemaManager, "ESQCityNA"); esq.AddColumn("Id"); var subEsq = new EntitySchemaQuery(EntitySchemaManager, "ESQCityNA"); subEsq.AddColumn(subEsq.CreateAggregationFunction(AggregationTypeStrict.Max, "ModifiedOn")); var filter = esq.CreateFilter(FilterComparisonType.Equal, "ModifiedOn", subEsq); esq.Filters.Add(filter); string sqlText = esq.GetSelectQuery(CurrentConnection).GetSqlText();
SqlText запроса:

SELECT "ESQCityNA"."Id" "Id" FROM "ESQCityNA" "ESQCityNA" WHERE "ESQCityNA"."ModifiedOn" = (SELECT MAX("ESQCityNA"."ModifiedOn") "Max" FROM "ESQCityNA" "ESQCityNA")

public IEntitySchemaQueryFilterItem CreateFilter(FilterComparisonType comparisonType, string leftExprColumnPath, AggregationTypeStrict leftExprAggregationType, object rightExprParameterValue, out EntitySchemaQuery leftExprSubQuery) – создает фильтр с агрегирующим подзапросом по колонке в левой и значением в правой части фильтра
Где: comparisonType – тип сравнения leftExprColumnPath – путь к колонке в левой части фильтра leftExprAggregationType – тип агрегирующей функции rightExpressionValue – значение в правой части фильтра leftExprSubQuery – возвращаемый экземпляр созданного подзапроса
Возвращает: экземпляр созданного фильтра
Пример:

var esq = new EntitySchemaQuery(EntitySchemaManager, "ESQCountryNA"); esq.AddColumn("Id"); EntitySchemaQuery subEsq = null; var filter = esq.CreateFilter(FilterComparisonType.GreaterOrEqual, "[ESQCityNA:Country].Name", AggregationTypeStrict.Count, 5, out subEsq); esq.Filters.Add(filter); string sqlText = esq.GetSelectQuery(CurrentConnection).GetSqlText();
SqlText запроса:

SELECT "ESQCountryNA"."Id" "Id" FROM "ESQCountryNA" "ESQCountryNA" WHERE (SELECT COUNT("SubESQCityNA"."Id") "Count" FROM "ESQCityNA" "SubESQCityNA" WHERE "SubESQCityNA"."CountryId" = "ESQCountryNA"."Id") >= 5

public IEntitySchemaQueryFilterItem CreateFilterWithParameters(FilterComparisonType comparisonType, bool useDisplayValue, string leftExpressionColumnPath, params object[] rightExpressionParameterValues) – создает фильтр по колонке в левой части и параметром или несколькими параметрами в правой части
Где: comparisonType – тип сравнения useDisplayValue – определяет для колонок типа справочник использовать ли в фильтре хранимое или отображаемое значение leftExprColumnPath – путь к колонке в левой части фильтра rightExpressionParameterValues – значения в правой части фильтра
Возвращает: экземпляр созданного фильтра
Пример:

var esq = new EntitySchemaQuery(EntitySchemaManager, "ESQCountryNA"); esq.AddColumn("Id"); var filter = esq.CreateFilterWithParameters(FilterComparisonType.Equal, "CreatedOn", new DateTime()); esq.Filters.Add(filter); string sqlText = esq.GetSelectQuery(CurrentConnection).GetSqlText();
SqlText запроса:

SELECT "ESQCountryNA"."Id" "Id" FROM "ESQCountryNA" "ESQCountryNA" WHERE "ESQCountryNA"."CreatedOn" = :P1

public IEntitySchemaQueryFilterItem CreateIsNullFilter(string leftExpressionColumnPath) – создает фильтр проверки колонки на пустое значение
Где: leftExpressionColumnPath – путь к колонке по которой строится фильтр
Возвращает: экземпляр созданного фильтра
Пример:

var esq = new EntitySchemaQuery(EntitySchemaManager, "ESQCountryNA"); esq.AddColumn("Id"); var filter = esq.CreateIsNullFilter("CreatedOn"); esq.Filters.Add(filter); string sqlText = esq.GetSelectQuery(CurrentConnection).GetSqlText();
SqlText запроса:

var esq = new EntitySchemaQuery(EntitySchemaManager, "ESQCountryNA"); esq.AddColumn("Id"); var filter = esq.CreateIsNullFilter("CreatedOn"); esq.Filters.Add(filter); string sqlText = esq.GetSelectQuery(CurrentConnection).GetSqlText();