Функция cursor

Функция cursor позволяет отправлять запросы на получение данных, доступных через обработчик сервера приложений, получать ответ с запрошенными данными в форматах xml или JSON.

Допустимые расширения:

.xml - для получения ответа в формате XML
.js/.json - для получения ответа в формате JSON

Функция осуществляет запрос к указанному классу или представлению и возвращает данные, соответствующие структуре и условиям переданного запроса. Запрос к данным передается в виде параметра GET или POST-запроса с именем query. Значение параметра представляет собой xml-документ следующей структуры:

01<query class="TWorker">
02  <item part="what" name="LastName" />
03  <item part="what" name="FirstName"/>
04  <item part="what" name="MiddleName"/>
05  <item part="what" name="BirthDate"/>
06  <item part="what" name="ContactList" value="TPerson.GetContactList" special="function">
07    <parameters>
08      <ContactType>63474</ContactType>
09    </parameters>
10  </item>
11  <item part="where" name="LastName" value="А*"/>
12  <item part="order" name="LastName"/>
13  <item part="order" name="FirstName"/>
14</query>

Элемент query имеет обязательный атрибут class. Значением атрибута class должно быть имя класса или представления, к которому будет выполняться запрос. Также может использоваться необязательный атрибут fetchall, который может принимать значения "0" (значение по умолчанию) или "1". Использование атрибута fetchall подробнее описано ниже в разделе Использование возвращаемого ответа.

Элемент query может включать в себя элементы item, передающие структуру запроса, условия отбора, сортировки, группировки. Элементы item могут включать в себя необязательные элементы (context, parameters, и т.п.; имя этого элемента не анализируется).

Состав атрибутов элемента item (обязательным является только атрибут part, остальные атрибуты можно опускать, в зависимости от использования других атрибутов):

part (обязательный атрибут) - часть запроса (what, where, order,...)
name - в простом случае (без использования special) - имя свойства класса (или поля представления), которое будет использовано в запросе; при использовании special может быть как именем свойства класса, так и другой строкой (см. подробнее ниже).
value - значение, которое в зависимости от значения атрибутов part и special, будет использовано для сравнений или для других целей; в простом случае (если part = "where", special отсутствует) будет использовано для сравнения в условии отбора при выполнении запроса.
special - вводит дополнительные возможности формирования запроса (возможности описаны ниже); от использованного значения данного атрибута может зависеть трактовка значений других атрибутов.
subQuery
joinKey
joinLink
joinSource

Допустимые значения атрибута part (можно использовать как строковые, так и числовые значения):

Строковое
значение

Числовое
значение

Назначение и пример использования

what

Элементы со значением "what" (0) атрибута part используются для формирования what-кляузы запроса. В полученном ответе каждому такому элементу будет соответствовать один xml или json элемент с именем, переданным атрибутом name.

Пример

<item part="what" name="LastName"/>

Получить значение свойства "LastName".

where

Элементы со значением "where" (1) атрибута part используются для формирования условия отбора объектов (where-кляузы запроса).
Для условий допустимо использовать "маску" (*, ?), условия ">", "<", ">=", "<=";
использование значений через ";" будет трактовано как условие "или", использование "&" будет трактовано как условие "и";
для отрицания нужно использовать "!", для условия "not null" нужно использовать "*", для условия "is null" нужно использовать "!*".
Каждый следующий where-элемент добавляет к запросу одно условие "и".

Пример

1<item part="where" name="LastName" value="Петров"/>
2<item part="where" name="FirstName" value="А*"/>

Отобрать объекты класса со значением свойства "LastName", равным "Петров", и значениями "FirstName", начинающимися с символа "А".

order

Элементы со значением "order" (2) атрибута part используются для управления сортировкой данных в возвращаемом ответе. По умолчанию (без использования атрибута special) будет выполнена сортировка "по возрастанию". Задать сортировку "по убыванию" можно, использовав значение "desc" (7) для атрибута special. Если в запросе использовано несколько элементов "order", то возвращаемый результат будет отсортирован по нескольким полям в том порядке, в котором они указаны в запросе.

Пример

1<item part="order" name="LastName/>
2<item part="order" name="BirthDate" special="desc"/>

Отсортировать результат запроса по значению свойства "LastName" по возрастанию, затем по значению свойства "BirthDate" по убыванию.

group

Элементы со значением "group" (3) атрибута part используются для управления группировкой данных в возвращаемом ответе. Если в запросе использовано несколько элементов "group", то возвращаемый результат будет сгруппирован по нескольким полям в том порядке, в котором они указаны в запросе. Для свойств, не входящих в условия группировки, можно получать значения агрегатов (количество, наименьшее/наибольшее/среднее и т.п.), используя атрибут special.

Пример

1<item part="what" name="Region"/>
2<item part="what" name="ID" special="count"/>
3<item part="what" name="BirthDate" special="min"/>
4<item part="group" name="Region"/>

Сгруппировать результат запроса по значению свойства "Region", для каждой группы вернуть значение свойства "Region", количество записей в группе и минимальное значение свойства "BirthDate" в этой группе.

having

Элементы со значением "having" (4) атрибута part позволяют накладывать условия отбора на группы в запросе с группировкой.

Пример

1<item part="what" name="Region"/>
2<item part="what" name="ID" special="count"/>
3<item part="what" name="BirthDate" special="min"/>
4<item part="group" name="Region"/>
5<item part="having" name="ID" value=">3" special="count"/>

innerJoin

outerJoin

Допустимые значения атрибута special (можно использовать как строковые, так и числовые значения):

Строковое
значение

Числовое
значение

Части запроса

Назначение и пример использования

what
where

Позволяет запрашивать идентификатор объекта или накладывать условия по идентификатору.

Пример

1<query class="TWorker">
2  <item part="what" special="ID"/>
3  <item part="what" name="LastName"/>
4  <item part="what" name="FirstName"/>
5  <item part="where" value="5500921" special="ID"/>
6</query>

Получить идентификатор объекта, значения свойств LastName, FirstName объекта с идентификатором, равным 5500921. Ответ на запрос будет содержать элемент с именем ID.

parent

what
where

Позволяет использовать в запросах идентификатор "родителя" объекта.

Пример

1<query class="TCountry">
2  <item part="what" special="ID"/>
3  <item part="what" special="parent"/>
4  <item part="what" name="Name"/>
5  <item part="what" name="Description"/>
6</query>

Получить идентификатор объекта, идентификатор родительского объекта, значения свойств Name, Description всех объектов класса TCountry. Ответ на запрос будет содержать элемент с именем Parent.

haschildren

what
where

Признак наличия дочерних объектов в иерархии. Ответ на запрос будет содержать элемент с именем HasChildren и значением "1" в случае наличия дочерних объектов и значением "0" в случае их отсутствия.

Пример

1<query class="TCountry">
2  <item part="what" name="Name"/>
3  <item part="what" name="Description"/>
4  <item part="what" special="haschildren"/>
5</query>

Получить значения свойств Name, Description, а также признак наличия дочерних объектов всех объектов класса TCountry.

filter

where

Позволяет использовать для отбора условия, заданные доменами, использованными в решении на платформе. Имя или идентификатор домена указывается в атрибуте name. Условие отбора этого домена будет интерпретировано с учетом значений, переданных в дочернем элементе context. Для каждого из этих значений должны быть указаны его имя, домен и значение.

Пример

1<query class="TCountry">
2  <item part="what" name="Name"/>
3  <item part="what" name="Description"/>
4  <item part="where" name = "TRegion of UnivCountry domain" special="filter>
5      <context>
6        <UnivCountry domain="4565848">67991</UnivCountry>
7      </context>
8  </item>
9</query>

Получить значения свойств Name, Description объектов класса TCountry, подходящих под условие отбора домена "TRegion of UnivCountry domain", используя значение "67991" вместо идентификатора UnivCountry.
Условие отбора домена "TRegion of UnivCountry domain":
((Self.Parent = UnivCountry) or (Self = UnivCountry))

uplink

what
where

Используется для отбора данных в контексте выбранных родительских объектов. Связь отбираемых объектов с выборкой связанных родительских объектов будет установлена по свойству, переданному атрибутом name. В атрибуте value может быть передан идентификатор одного объекта, список идентификаторов объектов через ";" или идентификатор буфера, в который предварительного сохранен список объектов.

Пример

1<query class="TCountry">
2  <item part="where" name="Parent" value="14750" special="uplink"/>
3  <item part="what" name="Name"/>
4  <item part="what" name="Description"/>
5</query>

Получить значения свойств Name, Description объектов класса TCountry, у которых значение свойства Parent равно "14750" (или входит в состав объектов, сохраненных в буфере с идентификатором "14750").

root

where

Будут отобраны только объекты, не имеющие родителя, после наложения других условий отбора.

Пример

1<query class="TCountry">
2  <item part="what" name="Name"/>
3  <item part="what" name="Description"/>
4  <item part="where" special="root"/>
5</query>

Получить значения свойств Name, Description "корневых" (не имеющих родителя) объектов класса TCountry.

desc

order

Используется для сортировки "по убыванию" для элементов с атрибутом part ="order". Без указания атрибута special будет выполнена сортировка "по возрастанию".

Пример

1<item part="order" name="LastName"/>
2<item part="order" name="BirthDate" special="desc"/>

count

what
having

Используется для запросов с группировкой, в элементах, у которых part = "what" или "having" для получения количества объектов в группе.

Пример

1<item part="what" name="Region"/>
2<item part="what" name="ID" special="count"/>
3<item part="group" name="Region"/>
4<item part="having" name="ID" value=">3" special="count"/>

Сгруппировать результат запроса по значению свойства "Region", для каждой группы вернуть значение свойства "Region" и количество записей в группе, отобрав при этом только такие группы, количество объектов в которых больше 3-х.

sum

what
having

Используется для запросов с группировкой, в элементах, у которых part = "what" или "having" для получения суммы значений свойства, имя которого передано атрибутом name.

Пример

1<item part="what" name="Region"/>
2<item part="what" name="PayedSum" special="sum"/>
3<item part="group" name="Region"/>

Сгруппировать результат запроса по значению свойства "Region", для каждой группы вернуть значение свойства "Region" и сумму значений свойства "PayedSum" для всех объектов группы.

min

what
having

Используется для запросов с группировкой, в элементах, у которых part = "what" или "having" для получения минимального значения свойства, имя которого передано атрибутом name.

Пример

1<item part="what" name="Region"/>
2<item part="what" name="BirthDate" special="min"/>
3<item part="group" name="Region"/>

Сгруппировать результат запроса по значению свойства "Region", для каждой группы вернуть значение свойства "Region" и минимальное значение свойства "BirthDate" среди всех объектов группы.

max

what
having

Используется для запросов с группировкой, в элементах, у которых part = "what" или "having" для получения максимального значения свойства, имя которого передано атрибутом name.

Пример

1<item part="what" name="Region"/>
2<item part="what" name="BirthDate" special="max"/>
3<item part="group" name="Region"/>

Сгруппировать результат запроса по значению свойства "Region", для каждой группы вернуть значение свойства "Region" и максимальное значение свойства "BirthDate" среди всех объектов группы.

avg

what
having

Используется для запросов с группировкой, в элементах, у которых part = "what" или "having" для получения среднего значения свойства, имя которого передано атрибутом name.

Пример

1<item part="what" name="Region"
2<item part="what" name="PayedSum" special="avg"/>
3<item part="group" name="Region"/>

Сгруппировать результат запроса по значению свойства "Region", для каждой группы вернуть значение свойства "Region" и среднее значение свойства "PayedSum" среди всех объектов группы.

masterLink

where

Позволят наложить отбор на объекты класса ("подчиненный" класс) в контексте выбранных объектов класса-мастера или класса, связанного с исходным по другому свойству ("главный" класс). В атрибуте name в этом случае передаются имена свойства "главного" класса и свойства "подчиненного" класса, по которым эти классы связаны. Имена свойств указываются следующим образом:

Если одним из этих свойств является идентификатор (ID), то имя этого свойства не указывается (это свойство используется по умолчанию)
Если оба свойства отличаются от ID, то их имена указываются через разделитель ";", например, "Master;Person"
Если только свойство "подчиненного" класса отличается от ID, то указывается только имя этого свойства, например, "Person"
Если только свойство "главного" отличается от ID, то вместо свойства-подчиненного указывается *, например, "Master;*"

В свойстве value передается идентификатор буфера, содержащего список выбранных объектов "главного" класса.

Пример

1<query class="TContact">
2  <item part="what" name="ContactInfo"/>
3  <item part="what" name="ContactType" special="name"/>
4  <item part="where" name="Person" value="246889" special="masterLink"/>
5</query>

Получить значения свойств ContactInfo, ContactType (Имя) объектов класса TContact, для объектов, список которых сохранен в буфере с идентификатором "246889", связанным с классом TContact по свойству Person.

selectedOnly

where

Позволят наложить отбор по списку идентификаторов объектов класса, ранее сохраненных в буфере.

Пример

1<query class="TPerson">
2  <item part="what" name="LastName"/>
3  <item part="what" name="FirstName"/>
4  <item part="where" value="246889" special="selectedOnly"/>
5</query>

Получить значения свойств LastName, FirstName объектов класса TPerson, список которых сохранен в буфере с идентификатором "246889".

distinct

what

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

Пример

1<query class="TPerson">
2  <item part="what" name="FirstName"/>
3  <item part="what" special="distinct"/>
4</query>

Получить набор уникальных значений свойства FirstName класса TPerson.

1<query class="TPerson">
2  <item part="what" name="FirstName"/>
3  <item part="what" name="MiddleName"/>
4  <item part="what" special="distinct"/>
5</query>

Получить набор уникальных сочетаний значений свойств FirstName и MiddleName класса TPerson.

view

where

Позволяет при выполнении запроса наложить отбор, используемый для определенного представления. Имя (или идентификатор) представления указывается в атрибуте name.

Пример

1<query class="TPerson">
2  <item part="where" name="Persons older 25" special="view"/>
3  <item part="what" name="FirstName"/>
4  <item part="what" name="LastName"/>
5</query>

Получить значения свойств FirstName, LastName объектов класса TPerson, соответствующих условиям отбора представления Persons older 25.

caseInsensitive

where

Позволяет наложить отбор на значение свойства строкового типа без учета регистра. Без использования special поиск ведется с учетом регистра.

Пример

1<query class="TPerson">
2  <item part="what" name="FirstName"/>
3  <item part="what" name="LastName"/>
4  <item part="where" name="FirstName" value="АНДРЕЙ" special="caseInsensitive"/>
5</query>

Получить значения свойств FirstName, LastName объектов класса TPerson, с отбором по значению свойства FirstName без учета регистра символов. TPerson.

string

where

Позволят явно приводить к строковому типу значения свойства, переданного атрибутом name.

Пример

1<query class="TCountry">
2  <item part="what" name="Name"/>
3  <item part="what" name="Description"/>
4  <item part="where" name="Code" value="00002" special="string"/>
5</query>

Получить значения свойств Name, Description объектов класса TCountry, со значением свойства Code, равным "00002".

listed

where

Позволяет выполнять отбор по списку объектов, входящих в список, сохраненный в системе как объект класса TObjectList ("Списки"), идентификатор которого нужно передать в качестве значения атрибута value.

Пример

1<query class="TCountry">
2  <item part="what" name="Name"/>
3  <item part="what" name="Description"/>
4  <item part="where" name="ID" value="5245654" special="listed"/>
5</query>

Получить значения свойств Name, Description объектов класса TCountry, входящих в список, сохраненный как объект класса TObjectList с идентификатором "5245654".

name

what
where

Для свойств-ссылок на объекты позволяет получить Имя объекта, переданного атрибутом name. В полученном ответе соответствующий элемент будет иметь имя ИмяСвойства-N.

Пример

1<query class="TCountry">
2  <item part="what" name="Name"/>
3  <item part="what" name="Description"/>
4  <item part="what" name="Parent"/>
5  <item part="what" name="Parent" special="name"/>
6</query>

Для всех объектов класса TCountry получить значения свойств Name, Description, Parent, а также Имя объекта Parent.

description

what
where

Для свойств-ссылок на объекты позволяет получить Наименование объекта, переданного атрибутом name. В полученном ответе соответствующий элемент будет иметь имя ИмяСвойства-D.

Пример

1<query class="TCountry">
2  <item part="what" name="Name"/>
3  <item part="what" name="Description"/>
4  <item part="what" name="Parent"/>
5  <item part="what" name="Parent" special="description"/>
6</query>

Для всех объектов класса TCountry получить значения свойств Name, Description, Parent, а также Наименование объекта Parent.

function

what
where

Позволяет использовать значения, полученные в результате вызова функций, как в элементах с атрибутом part ="what", так и в элементах с атрибутом part ="where". Имя функции должно быть передано в атрибуте value в формате Имя класса.Имя функции. Если функция имеет параметры, то для их передачи необходимо добавить дочерний элемент context, со своими дочерними элементами для каждого из параметров в формате <ИмяПараметра>Значение параметра</ИмяПараметра>. Если функция является "методом объекта", параметр "ID" добавлять не нужно, он будет использован автоматически. В элементах с атрибутом part ="what" значение атрибута name может быть любым, оно не будет использовано при выполнении запроса, но станет именем элемента данных в получаемом ответе.

Пример

01<item part="what" name="InitAndLast" value="TPerson.GetInitAndLast" special="22"/>
02<item part="what" name="ContactList" value="TPerson.GetContactList" special="22">
03  <context>
04    <ContactType>63474</ContactType>
05  </context>
06</item>
07<item part="where" name="TWorker.IsSuperior" value="1" special = "function">
08  <context>
09    <OtherWorker>625186</OtherWorker>
10    <Department></Department>
11  </context>
12</item>

Получить результат выполнения функции GetInitAndLast класса TPerson (функция не имеет параметров), получить результат выполнения функции GetContactList класса TPerson с параметром ContactType = 625186. Отобрать только те объекты, для которых результат выполнения функции IsSuperior класса TWorker равен "1". Функция IsSuperior вызывается со значением 625186 параметра OtherWorker и пустым значением параметра Department.

countdistinct

what
having

Позволяет получить количество уникальных значений свойства.

Пример

1<query class="TPerson">
2  <item part="what" name="FirstName" special="countdistinct"/>
3</query>

Получить количество уникальных значений свойства FirstName класса TPerson.

boolean

what
where

Позволят приводить к "логическому" типу значения свойства, переданного атрибутом name. Приведение выполняется по следующему принципу:

значение Null преобразуется в пустое значение в ответе
значение "0" остается значением "0" в ответе
любое непустое значение преобразуется в значение "1" в ответе

Такая возможность позволяет, например, более эффективно (без получения самих значений) определять пустоту/непустоту значений типа "большой объект".

Пример

1<query class="TCountry">
2  <item part="what" name="Name"/>
3  <item part="what" name="Description"/>
4  <item part="what" name="Code" special="boolean"/>
5</query>

Получить значения свойств Name, Description, а также значение свойства Code, преобразованное к "логическому" всех объектов класса TCountry.

exact

where

При использовании значения "exact" (25) атрибута special значение, переданное в атрибуте value, будет использовано "как есть" - без преобразования типов, без трактовки символов "*", "?" как маски и т.п.

Пример

1<query class="TCountry">
2  <item part="what" name="Name"/>
3  <item part="what" name="Description"/>
4  <item part="where" name="Code" value = "002*25?" special="exact"/>
5</query>

Получить значения свойств Name, Description объектов класса TCountry со значением свойства Code, равным "002*25?".

searchindex

where

Позволяет использовать индексы полнотекстового поиска при отборах. Поиск по выполняться по всем полям класса, значение атрибута name будет проигнорировано.

Пример

1<query class="TMailMessage">
2  <item part="what" name="Theme"/>
3  <item part="what" name="Body"/>
4  <item part="what" name="Created"/>
5  <item part="where" value="приглашаем *на семинар *Современные" special="searchindex">
6</query>

Получить значения свойств Theme, Body, Created объектов класса TMailMessage, среди значений свойств которых будет найдена указанная строка, с использованием индекса полнотекстового поиска.

optimization

where

Позволяет использовать имеющиеся подсказки оптимизатору при выполнении запроса.

Пример

1<query class="TPerson">
2  <item part="what" name="FirstName"/>
3  <item part="what" name="LastName"/>
4  <item part="what" value="ORARefreshOnFetch=true;APPRefreshOnFetch=true" special="optimization">
5</query>

Получить значения свойств FirstName, LastName объектов класса TPerson, используя при выполнении запроса подсказки оптимизатору.