query

#Query

Объект с набором методов, позволяющих сформировать расширенный запрос к сервису МойСклад на выборку сущностей.

• Создание запроса

  • createQuery

• Формирование запроса

  • select
    • выборка по значению
    • выборка AND
    • выборка OR
    • выборка по условию
  • filter
  • uuids

• Параметры запроса

  • skip → start
  • start
  • limit → count
  • count
  • page
  • orderBy → sort
  • sort
  • sortMode
  • fileContent
  • showArchived

##Создание запроса ###client.createQuery([queryObj] [, options]) Создание экземпляра запроса

var query = require('moysklad-client').createQuery();

####Parameters

Наименование	Тип	Описание
queryObj	Object	Объект запроса
options	Object	Параметры запроса

Пример создания запроса с параметрами:

var query = client.createQuery({ applicable: true }, { sortBy: 'moment' });

перейти к заголовку

##Формирование запроса

• select
  • выборка по значению
  • выборка AND
  • выборка OR
  • выборка по условию
• filter
• uuids

перейти к заголовку

###query.select(obj [, ...]) Основной метод для составления сложных запросов. Синтаксис запросов совместим с популярной объектной БД MongoDb (за исключением ряда методов).

query.select({ applicable: true });

####Parameters

Наименование	Тип	Описание
obj	Object или Query	Object или другой Query запрос, определяющий условия которым должны соответствовать запрашиваемые документы. Может быть передано несколько объектов, в этом случае условия запросов будут скобинированы в текущий запрос.

####Составление объекта запроса

ВЫБОРКА ПО ЗНАЧЕНИЮ ПОЛЯ

Пример простого объекта запроса для выборки проведенных сущностей

{ applicable: true }

Если фильтруемое поле внутри другого объекта, то возможна вложенаня структура запроса

{ 
    requisite: {
        inn: '143383217826'
    } 
}

это касается и связанных сущностей

{ 
    state: {
        name: 'Оформлен'
    } 
}

можно использовать такую запись

{ 
    'state.name': 'Оформлен'
}

к примеру, cледующие три варианта запроса идентичны

{ 
    stateUuid: 'f27e91ac-01ae-11e4-ab96-002590a28eca' 
}

{ 
    'state.uuid': 'f27e91ac-01ae-11e4-ab96-002590a28eca' 
}

{ 
    state: { 
        uuid: 'f27e91ac-01ae-11e4-ab96-002590a28eca' 
    }
}

перейти к заголовку

ВЫБОРКА ПО НЕСКОЛЬКИМ ПОЛЯМ (AND)

Ниже приведен AND запрос соответствующий всем проведенным документам в статусе "Оформлен"

{ 
    applicable: true,
    'state.name': 'Оформлен'
}

ВЫБОРКА ПО СПИСКУ ЗНАЧЕНИЙ (OR)

Для записи OR запросов есть несколько вариантов:

Ниже приведены примеры запросов соответствующих всем документам в статусе "Оформлен" или "Принят"

1. Оператор $in

   {'state.name': {$in: ['Оформлен', 'Принят']}}

2. Метод client.anyOf

   {'state.name': client.anyOf('Оформлен', 'Принят')} 

   {'state.name': client.anyOf(['Оформлен', 'Принят'])} 

   вместо client.anyOf можно использовать client.$in

3. Самый простой способ - указать массив значений

   {'state.name': ['Оформлен', 'Принят']}

перейти к заголовку

ВЫБОРКА ПО УСЛОВИЮ

Условные операторы <, <=, >, >= по понятным причинам не могут быть непосредственно использованы при составлении объекта запроса, но могут быть заменены соответствующими альтернативами. Когда поле должно соответствовать накладываемому условию, значение должно быть обернуто в специальный объект или метод:

Оператор	Запись 1	Запись 2	Запись 3
<	{$lt:value}	query.$lt(value)	query.lessThan(value)
<=	{$lte:value}	query.$lte(value)	query.lessThanOrEqualTo(value)
>	{$gt:value}	query.$gt(value)	query.greaterThen(value)
>=	{$gte:value}	query.$gte(value)	query.greaterThanOrEqualTo(value)
между	{$gt:value1, $lt:value2}	query.$bt(value1, value2)	query.between(value1, value2)

• Оператор != не поддерживается API МойСклад.
• В качестве значений фильтра может быть использована дата в формате moment.js.

Пример объекта запроса с использованием условных операторов:

var moysklad = require('moysklad-client')
  , moment   = require('moment');

var client   = moysklad.createClient();

var query    = moysklad.createQuery({
    archived: false,
    'state.name': client.anyOf('Активный', 'VIP'),
    created: {
        $gt: new Date(2013, 0, 1), 
        $lt: moment().add('month', -1)
    }
});

####Return this - текущий запрос для цепочки вызовов

перейти к заголовку

###query.filter(key, value) Добавляет к запросу условие фильтрации value по одному из свойств key. Удобно использовать как краткую запись query.select, если необходимо задать лишь один параметр, либо при задании полей фильтра в цикле.

query.filter('state.name', 'Активный');

Правила задания свойства и значения аналогичны query.select

####Return this - текущий запрос для цепочки вызовов

перейти к заголовку

###query.uuids(value) Позволяет выбрать сущности по списку идентификаторов.

query.uuid([
    '47896027-0e6b-11e2-c959-3c4a97f3a0a7',
    '50c93f7f-d638-467a-92d5-a64f8126ad64'
]);

аналог записи

query
    .select({
        uuid: [ '47896027-0e6b-11e2-c959-3c4a97f3a0a7',
                '50c93f7f-d638-467a-92d5-a64f8126ad64' ]
    })
    .showArchived(true);

####Parameters

Наименование	Тип	Описание
value	Array или String	Идентификатор или массив идентификаторов сущностей для выборки

####Return this - текущий запрос для цепочки вызовов

перейти к заголовку

##Параметры запроса

• skip → start
• start
• limit → count
• count
• page
• orderBy → sort
• sort
• sortMode
• fileContent
• showArchived

перейти к заголовку

###query.skip → query.start Альтернативная запись метода query.start

перейти к заголовку

###query.start(num) Задает смещение с начала коллекции выборки.

query.start(100);

Вызов метода без параметров вернет текущее значение start

####Return this - текущий запрос для цепочки вызовов или Number - текущее значение (при вызове метода без параметров)

перейти к заголовку

###query.limit → query.count Альтернативная запись метода query.count

###query.count(num) Задает кол-во элементов для включения в выборку.

query.count(10);

Максимальное значение count не может быть больше 1000.

####Return this - текущий запрос для цепочки вызовов или Number - текущее значение (при вызове метода без параметров)

перейти к заголовку

###query.page(num, size) Задает выборку для элементов соответствующих странице num при размере страницы size. Упрощенная запись комбинации методов start и count.

query.page(5, 30);

аналогично записи

query.start((5 - 1) * 30).count(30);

Максимальное значение size не может быть больше 1000.

перейти к заголовку

###query.orderBy → query.sort Альтернативная запись метода query.sort

###query.sort(name [, sortMode]) Указание поля сущности по которому будет проведена сортировка при выборке объектов.

query.sort('moment');

сортировку можно проводить по вложенным полям

query.sort('targetAgent.name', 'desc');

По умолчанию объекты упорядочиваются по идентификатору.

Направление сортировки можно указать отдельно методом query.sortMode.

Наименование	Тип	Описание
name	String	наименование поля по которому проводится сортировка
sortMode	String	опциональный параметр, определяющий направление сортировки: asc - по возрастанию (по умолчанию), desc - по убыванию

####Return this - текущий запрос для цепочки вызовов или String - текущее значение sort (при вызове метода без параметров)

перейти к заголовку

###query.sortMode(mode) Задает направление сортировки выбираемых объектов. Применяется совместно с методом query.sort.

query.sort('moment').sortMode('desc');

аналогично записи

query.sort('moment', 'desc');

Вызов метода без параметров вернет текущее значение start

####Return this - текущий запрос для цепочки вызовов или String - текущее значение (при вызове метода без параметров)

перейти к заголовку

###query.fileContent(bool) Указывает на необходимость включать в тело запрашиваемой сущности содержимое прикрепленных файлов (документов, изображений).

query.fileContent(true);

Значение по умолчанию false

####Return this - текущий запрос для цепочки вызовов или Boolean - текущее значение (при вызове метода без параметров)

перейти к заголовку

###query.showArchived(bool) Указывает на необходимость включать в выборку сущности находящиеся в архиве.

query.showArchived(true);

Значение по умолчанию false

####Return this - текущий запрос для цепочки вызовов или Boolean - текущее значение (при вызове метода без параметров)

перейти к заголовку