search string side menu

Работа в системе > EQL-поиск / Синтаксис EQL-запроса

Синтаксис EQL-запроса

EQL-запрос по своей структуре похож на SQL-запрос, написанный на языке SQL. При написании EQL-запроса используйте следующие рекомендации:

  1. Простые поля типа Строка или Число можно сравнивать с другими полями того же типа или с константами.
  2. Поля, которые являются ссылкой на другой объект, можно сравнивать только с идентификатором этого объекта. Например: Contacts = 2 — поиск контрагентов, имеющих контактное лицо с идентификатором 2.
  3. Вы можете использовать только три типа констант:
    • число (целое или дробное) — целую и дробную части числа следует разделять точкой;
    • строка — эту константу нужно задавать в одинарных кавычках, например (Name LIKE ’%ООО%’);
    • элементы true и false.
  1. Другие константы можно создать одним из способов:
    • через функции, например StartDate = DateTime(2016, 03, 02, 11, 00));
    • строками в функциях, например OR TypeUid = TypeReference(’Task’) OR Uid = Guid(’xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx’)).
  1. Чтобы в строку добавить апостроф (’), продублируйте его, например: Name LIKE ’%Задача ’’Подписание пакета документов’’%’ — поиск всех задач, название которых содержит комбинацию Задача ’Подписание пакета документов’.
  2. Для запроса используйте данные о структуре объектов системы. Эту информацию можно найти с помощью подсказки в строке ввода запроса или в дизайнере на вкладке Объекты в карточке объекта, открыв вкладку «Свойства».

Далее рассмотрим основные возможности создания EQL-запросов.

Логические операторы

Логические операторы (AND, OR, NOT) соединяют между собой несколько условий и имеют разный приоритет. Если в выражении используется несколько операторов, они выполняются в следующем порядке:

    1. Управление приоритетом.
    2. Операторы отрицания NOT (логическое НЕ).
    3. Операторы AND (логическое И).
    4. Операторы OR (логическое ИЛИ).

Управление приоритетом

Чтобы обозначить приоритет среди выражений в сложном запросе, используйте круглые скобки, например:
(Name LIKE ’%ООО%’ OR Name LIKE ’%ЗАО%’) AND (Region = 6) — поиск контрагентов из Уральского региона, в названии которых есть слова «ООО» или «ЗАО». Вместе с оператором OR использованы круглые скобки, чтобы обозначить его приоритет перед оператором AND.

AND (логическое И)

Этот оператор соединяет два условия, которые выполняются в результате поиска, например:
Name LIKE ’%Ушаков%’ AND Name LIKE ’%Иван%’ AND Name LIKE ’%Петрович%’ — поиск контрагентов, в названии которых есть слова «Ушаков», «Иван» и «Петрович».

OR (логическое ИЛИ)

В результатах поиска будет выполнено хотя бы одно из условий, которые соединяет этот оператор, например:
Name LIKE ’%ООО%’ OR Name LIKE ’%ЗАО%’ — поиск контрагентов, в названии которых есть слова «ООО» или «ЗАО».

NOT (логическое НЕ)

В результатах поиска не будет выполняться условие, перед которым указан этот оператор, например:
NOT (Name LIKE ’%ООО%’ OR Name LIKE ’%ЗАО%’) — поиск контрагентов, в названии которых нет слов «ООО» или «ЗАО».

Операторы сравнения

Используя эти операторы, можно сравнивать между собой несколько полей объектов, значений выражений или констант. Если условие является истинным и выполняется, значением всего выражения является true, а если условие не выполняется и является ложным — false.

Операторы LIKE, IN, IS — регистронезависимые, т. е. результаты запроса будут одинаковы независимо от регистра текста. Например, на запрос Name LIKE ’%Мир%’ будут получены результаты «Мир» и «мир».

Рассмотрим подробнее все операторы сравнения.

Равенство (=)

Этот оператор используйте для проверки на точное равенство первого операнда второму. Строки сравниваются с учётом регистра. Если точное сравнение строк не требуется и нужно проверить строку на наличие подстроки, используйте оператор LIKE.

Не применяйте оператор равенства для дат, т. к. точное совпадение даты и времени маловероятно. Для сравнения дат используйте операторы <, >, <= или >=.

Пример запроса:
Responsible = CurrentUser() — поиск контрагентов, для которых текущий пользователь является ответственным.

Неравенство (<>)

Этот оператор проверяет неравенство значений. При сравнении строк учитывается регистр. Пример запроса:
Responsible <> CurrentUser() — поиск контрагентов, для которых текущий пользователь не является ответственным.

Меньше (<), Больше (>)

Операторы строгого неравенства. Значение левой части выражения должно быть строго меньше (или строго больше) правой части, например:

  • AnnualIncome < 2500000 — поиск контрагентов, годовой доход которых меньше 2 500 000 рублей;
  • AnnualIncome > 2500000 — поиск контрагентов, годовой доход которых больше 2 500 000 рублей.

Меньше или равно (<=), Больше или равно (>=)

Операторы нестрогого неравенства. Значение выражения истинно, если левая часть меньше или равна правой (больше или равна правой), например:

  • CompanyDay <= DateTime(1989, 01, 03) — поиск контрагентов, дата создания которых меньше или равна 03.01.1989;
  • CompanyDay >= DateTime(1989, 01, 03) — поиск контрагентов, дата создания которых больше или равна 03.01.1989.

LIKE

Этот оператор сравнивает строковое поле с указанной маской (шаблоном). Он применяется только для строковых переменных.

Оператор LIKE используется с масками строк, например ’%Мир%’. Если в одиночных кавычках указать конкретную строку, то действие оператора будет равносильно обычному равенству. Например, запрос (Name LIKE ’%ООО%’ OR Name LIKE ’%ЗАО%’) имеет такой же смысл, как запрос (Name = ’%ООО%’ OR Name = ’%ЗАО%’).

Маска (шаблон) может содержать следующие обозначения.

1. Знак процента (%) — означает любое количество произвольных символов. Например:
Name LIKE ’%ООО%’ — поиск контрагентов, в названии которых содержится слово «ООО». По обе стороны этого слова может находиться любая комбинация символов.

2. Знак подчёркивания (_) — означает один произвольный символ. Может использоваться несколько раз для обозначения двух и более символов в тексте. Например:

  • Name like ’_A%’ — поиск контрагентов, в названии которых вторая буква А;
  • Name like ’__A%’ — поиск контрагентов, в названии которых третья буква А.

3. Апостроф (’) — поиск строк, в которых есть одинарные кавычки-апострофы. При этом в шаблоне кавычки нужно продублировать. Например:
Name LIKE ’%Задача ’’Подписание пакета документов’’%’ — поиск задач, название которых содержит фразу Задача ’Подписание пакета документов’.

IN

Этот оператор устанавливает соответствие значения определённого поля с каждым из элементов, указанных после него в скобках. Используйте его для сравнения значения поля с небольшим количеством элементов.

Если поле является объектом, значения поля нужно передавать в виде идентификаторов, например: Contacts in (1, 2, 3).

Если поле является простым типом, значения можно передавать в виде конкретных значений, например: Name in (’Имя1’, ’Имя2’).

Пример запроса:
CreationAuthor in (CurrentUser(), 1) — поиск контрагентов, которые были созданы текущим пользователем или пользователем с идентификатором 1.

IS NULL, IS EMPTY

Оператор IS используется только в сочетании с NULL или EMPTY:

  • IS NULL — проверяет равенство левой части выражения пустому значению (Null) и применяется только к объектам с единичным выбором (например, для контрагента в поле Отрасль можно выбрать только одно значение справочника Отрасли);
  • IS EMPTY — применяется к объектам с множественным выбором.

Примеры запросов:

  • Industry IS NULL — поиск контрагентов с незаполненным полем Отрасль;
  • AnnualIncome IS NULL — поиск контрагентов, у которых не заполнено поле Годовой доход;
  • Contacts IS EMPTY — поиск контрагентов c пустым списком контактов.

Подзапросы

Подзапрос — это EQL-запрос, который вложен в другой EQL-запрос и является его составной частью. Сложность запроса ограничена по уровню вложенности и не может превышать 16 подзапросов или 1000 уровней вложенных операторов. Подзапросы нужно заключать в круглые скобки.

Подзапросы позволяют фильтровать корневые объекты по свойствам связанных объектов и составляются с помощью операторов FROM, SELECT и WHERE по одному из двух правил:

  • FROM entity SELECT property WHERE expression;
  • SELECT property FROM entity WHERE expression.

В этих правилах:

  • entity — объект, с которым работает подзапрос;
  • property — поле из текущего объекта;
  • expression — выражение для фильтрации записей объекта или вложенный запрос.

Примеры запросов:

  • Contractor in (FROM Contact SELECT Contractor WHERE Name = PARENT.Subject AND Contractor in (FROM Sale SELECT Contractor WHERE Name = ROOT.Subject)) — поиск задач, у которых название сделки совпадает с названием задачи. При этом, если название свойства совпадает с зарезервированным словом (без учёта регистра), тогда это свойство нужно указывать в квадратных скобках, например: [Parent] = 1;
  • Contractor in (from Sale select Contractor where Contractor = PARENT.Contractor and SaleStatus in (Enum(’Postponed’))) and Contractor in (Responsible = CurrentUser()) — поиск контактов, с отложенными сделками для текущего пользователя;
  • Contacts IN (Priority IN (Enum(’High’), Enum(’Low’))) — поиск контрагентов, контакты которых имеют высокий и низкий приоритет. В этом случае Контрагент является корневым объектом. Контакт — объект, связанный с корневым объектом Контрагент, а Приоритет — поле связанного объекта Контакт. В таком запросе подзапрос нужен, чтобы указать, что сравнивается поле Приоритет у объекта Контакт. Сначала в подзапросе будет работать оператор IN (поиск контактов с высоким и низким приоритетом), а затем в запросе оператор IN осуществит поиск контрагентов с контактами, выбранными в подзапросе.

Функции

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

COUNT()

Эта системная функция применяется для построения сложных подзапросов. Результатом её выполнения является целое число. Правила построения функции:

  • COUNT(property), где property — поле типа Список;
  • COUNT(query), где query — это подзапрос, построенный по правилу FROM entity WHERE expression, в котором:
    • entity — объект, с которым работает подзапрос;
    • expression — выражение для фильтрации записей объекта или вложенный запрос.
  • COUNT(function), где function — это функция вида QueryInFunction, возвращающая в качестве результата список.

Примеры запросов:

  • COUNT(Contacts) > 0 — поиск контрагентов, у которых есть контакты;
  • COUNT(FROM Contact WHERE NOT Skype IS NULL AND Contractor = PARENT.Id) >= 1 — поиск контрагентов, количество контактов которых не менее одного, при условии, что поле Skype у контактов заполнено и контрагент контакта совпадает с текущим;
  • COUNT(GroupUsers(1)) — количество пользователей группы с id = 1.

Функции вида QueryFunctionResult

Пользовательские функции вида QueryFunctionResult используются для получения определённого значения. К ним относятся следующие функции.

  1. DateTime(год, месяц, день, [час], [минута], [секунда], [миллисекунда]) — получение даты и времени. В квадратных скобках указаны необязательные параметры.
    В этой функции можно использовать следующие параметры:
    • Now — текущая дата и время с точностью до секунды. Например, CreationDate <= DateTime(’Now’);
    • Today — текущая дата в формате <дд:мм:гг>, где дд — число месяца, мм — месяц, гг — две последние цифры года. Например: CreationDate <= DateTime(’Today’);
    • MinValue — минимально допустимое значение переменной типа Дата/время;
    • MaxValue — максимально допустимое значение переменной типа Дата/время.

Пример запроса:
CreationDate <= DateTime(2021, 12, 17, 11, 15) — поиск контрагентов, дата создания которых меньше или равна 17.12.2021 года 11 часов 15 минут.

  1. Guid(’уникальный идентификатор в строковом представлении’) — в параметр этой функции передаётся идентификатор объекта в строковом представлении. Функция возвращает уникальный идентификатор объекта в виде числа. Сравнивать значение этой функции можно только с такими же значениями идентификаторов, в строковом или числовом представлении. Пример запроса:
    Uid = Guid(’27E70DFE-2A76-4F1D-A99A-CDF31C62D618’) — поиск контрагентов с указанным идентификатором.
  2. TypeReference(’имя класса объекта’) — получение ссылки на тип объекта. Имя класса объекта отображается в дизайнере в карточке объекта на вкладке Общие в блоке Структура данных. Пример запроса:
    TypeUid = TypeReference(’ContractorLegal’) — поиск всех юридических лиц.
  3. Reference(идентификатор типа объекта, идентификатор объекта) — возвращает значение объекта. Оба параметра функции обязательны для заполнения. Пример запроса:
    ZapolnenyDogovory = Reference(’298b2c71-619f-463c-95b2-8e029085680d’, 15) — поиск ответов на вопрос по указанным идентификаторам.
  4. DropDownItem(’значение выпадающего списка’) — возвращает значение выпадающего списка. В качестве параметра укажите одно из значений выпадающего списка. Список значений указан в настройках свойства типа Выпадающий список на вкладке Общие в поле Элементы списка. Пример запроса:
    SpisokFilialov = DropDownItem(’Новосибирский филиал’) — поиск по указанному филиалу.
  5. WorkTime(дней, часов, минут) — получение интервала рабочего времени. Например:
    Interval > WorkTime(1, 0, 00) — поиск всех объектов, в которых указан интервал более 1 рабочего дня.

Функции вида QueryInFunction

Пользовательские функции вида QueryInFunction применяются для получения множества значений и используются после операции IN. К ним относятся следующие функции.

  1. CurrentUser() — возвращает идентификатор текущего пользователя. Пример запроса:
    CreationAuthor IN (CurrentUser(), 2) — поиск контрагентов, которые созданы текущим пользователем или пользователем с идентификатором 2.
  2. Enum(’название значение перечисления’) — возвращает идентификатор указанного значения перечисления. Пример запроса:
    Contacts IN (Priority IN (Enum(’High’), Enum(’Low’))) — поиск контрагентов, контакты которых имеют высокий и низкий приоритет.
  3. RelativeDateTime(’относительная дата начала периода’, ’относительная дата конца периода’) — получение интервала времени между относительными датами.
    Один из параметров может быть пустым. Тогда его нужно задать пустыми одинарными кавычками или значением NULL. При этом:
    • если первый параметр (дата начала периода) пустой, то интервал времени будет задан от минус бесконечности (минимально допустимого значения переменной) до второго параметра (дата конца периода);
    • если второй параметр (дата конца периода) пустой, то интервал времени будет задан от первого параметра (даты начала периода) до текущей даты.

Пример запроса:
CreationDate IN RelativeDateTime(’-1м’, ’-1м’) — поиск всех контрагентов, созданных в прошлом месяце.

  1. SubTypes(’имя класса объекта’) — получение ссылки на типы объекта и его наследников. Имя класса объекта отображается в дизайнере в карточке объекта на вкладке Общие в блоке Структура данных. Пример запроса:
    TypeUid in SubTypes(’ContractorIndividual’) — поиск всех физических лиц.
  2. CurrentUserGroups() — возвращает группы текущего пользователя.
  3. GetChiefByUser(идентификатор пользователя) — получение всех руководителей пользователя согласно оргструктуре, например:
    Responsible in GetChiefByUser(1) — поиск всех контрагентов, ответственными за которых являются вышестоящие руководители пользователя с id = 1.
  4. GetUserSubordinate(идентификатор пользователя) — получение всех подчинённых пользователей согласно оргструктуре. Пример запроса:
    Responsible in GetUserSubordinate(101) — поиск всех контрагентов, ответственными за которых являются подчинённые пользователя с id = 101.
  5. GroupUsers(идентификатор группы) — получение всех участников группы пользователей, например:
    Responsible in GroupUsers(109) — поиск всех контрагентов, ответственными за которых являются участники группы с id = 109.
  6. UserGroups(идентификатор пользователя) — возвращает все группы пользователей, участником которых является пользователь с указанным id. Например:
    Id in UserGroups(102) — поиск всех групп пользователей, участником которых является пользователь с id = 102.
  7. UserOrganisationItems(идентификатор пользователя) — получение пользователей согласно должностям оргструктуры, например:
    CreationAuthor in (FROM User SELECT Id WHERE OrganizationItems in UserOrganisationItems(1)) — поиск всех контрагентов, автором создания которых является пользователь определённой должности с id = 1.

Параметры

Параметры — это переменные, значения которых определяются в ходе выполнения сценария или процесса. Параметры повышают гибкость EQL-запросов, т. к. позволяют применять один запрос для получения результатов изменяемой переменной.

Параметры указываются в запросе после символа @. Именем параметра может быть любая строка, содержащая латинские или русские символы и цифры, а также знак «_». Имя параметра должно начинаться с буквы, например:
@ParameterName, где ParameterName — имя параметра.

Чтобы корректно использовать параметр, выполните следующие действия:

  1. Сформируйте EQL-запрос с использованием параметра, допустимых функций и операторов.
  2. Сопоставьте имя параметра и значение, которое он должен принимать. В качестве значения могут выступать переменные, свойства контекста, постоянные значения и др.

Примеры запросов с использованием параметра:

  • filter.Query = "Contact in (@Contact)"; — поиск контактов, записанных в параметре Contact;
  • filter.QueryParameters.Set("@Contact", context.Kontakty); — указание на переменную, значение которой будет записано в параметр Contact.

Можно использовать списковые параметры (переменные с типом связи Список), например:
"Contacts in @[Contacts]" — поиск любого контакта из выбранных в списке контактов параметра Contacts.

После ввода параметров в поле запроса под ним отобразятся поля для ввода значений параметров.

eql-search.html sms-notifications.html

Нашли опечатку? Выделите текст, нажмите ctrl + enter и оповестите нас