Эта страница переведена с помощью Cloud Translation API.

Синтаксис и использование фильтра списка

В этом руководстве описывается синтаксис фильтра списка и способы фильтрации различных типов ресурсов.

Некоторые методы API могут принимать фильтр для ограничения ресурсов, возвращаемых в ответе.

Краткое содержание

В этом разделе представлен краткий обзор синтаксической структуры фильтра списка.

Фильтр — это строка, содержащая expression . expression представляет собой булевую комбинацию сравнений:
```
expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison }
expression = ( expression )
```
comparison сопоставляет поле ресурса со значением. Вы можете использовать все распространенные операторы сравнения.
```
comparison = name OP value
OP = "<=" | "<" | ">=" | ">"  | "!=" | "=" | ":"
```
Оператор has , двоеточие ( : ), можно использовать для строк и повторяющихся полей. Подробности смотрите в разделе Оператор Has .
В фильтрах можно использовать следующие типы значений:
- Числа
- Струны
- Выражения в скобках
```
value = number| string | "*" | "(" expression ")"
```
Строки могут представлять следующее:
- Произвольный текст
- логические значения
- Перечисляемые значения
- Временные метки

Логические выражения

expression = ["NOT"|"-"] comparison {["AND" | "OR"] ["NOT"|"-"] comparison}

Операции производятся в следующем порядке:

NOT
OR
AND

Например, следующие выражения эквивалентны:

a OR NOT b AND NOT c OR d

(a OR (NOT b)) AND ((NOT c) OR d)

Вы можете опустить оператор AND между сравнениями. Например, следующие фильтры одинаковы:

c=d AND e=f

c=d e=f

Вы можете использовать дефис ( - ) в качестве альтернативы NOT . Между дефисом ( - ) и следующим сравнением не может быть пробела. Например, следующие фильтры одинаковы:

NOT e=f

-e=f

Сравнения

В этом разделе описываются сравнения "name OP value" например:

comparison = name OP value

где

OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
name = identifier { "." identifier }
identifier = unquoted_text
value = number | string | "*" | "(" expression ")"

Левая часть сравнения — это путь к полю ресурса API. Имя состоит из серии идентификаторов ресурсов, соединенных точкой ( . ). За каждым идентификатором поля следует следующий уровень имен для этого поля. Например, рассмотрим ресурс, имеющий item сложного поля, который имеет другой tool сложного поля с полем с именем shape . В фильтре для этого ресурса вы должны ссылаться на форму с именем item.tool.shape .

Правая часть обычно представляет собой скалярное значение, которое преобразуется в тип поля и сравнивается с ним. Дополнительные сведения см. в разделе «Типы литералов значений» .

Правая часть сравнения также может быть выражена как заключенная в круглые скобки булева комбинация литеральных значений и/или логических выражений, содержащая только литеральные значения (с предшествующим NOT или без него). Левое имя и оператор сравнения применяются к каждому значению. Например, следующие фильтры одинаковы:

deal.name = ("test 1" OR "test 2")

deal.name = "test 1" OR deal.name = "test 2"

Вот еще один, более сложный пример двух эквивалентных фильтров:

deal.name = ("test 1" OR "test 2" AND (NOT "test3" OR "test4"))

(deal.name = "test 1" OR deal.name = "test 2") AND ( (NOT deal.name = "test3") OR deal.name = "test4")

Типы литералов значений

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

Число

В этом разделе описывается представление числовых литералов.

Тип	Определение	Примеры
Двойной	Любое число, содержащее десятичную точку со знаком («-») или без него, считается двойным.	1234,567 -789.0123
Целое число	Любое число, не имеющее десятичной точки, со знаком («-») или без него, рассматривается как целое число.	1234 -789

Нить

В этом разделе описаны типы, которые можно записать в виде строкового литерала в синтаксисе фильтра.

Тип	Определение	Примеры
логическое значение	`TRUE` или `FALSE` в любом регистре букв.	`TRUE` `True` `"true"`
Перечисление	Имя литерала перечисляемого типа. Перечисления чувствительны к регистру.	`FINALIZED` — это не то же самое, что `Finalized`
Нить	Любая строка, содержащая текст в кодировке UTF-8 или 7-битный текст ASCII. Встроенные кавычки необходимо отделять обратной косой чертой. Строки без кавычек с пробелами обрабатываются как неявное «И» среди всех слов после разделения строки пробелами.	`name = "test \"double quotes\""` `name=(ABC DEF)` эквивалентно `name=ABC AND name=DEF`
Временная метка	Строка в стандартном формате ISO8601.	`"2014-10-02T15:01:23.045Z"`

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

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

Меньше или равно: "<="
Меньше: "<"
Больше или равно: ">="
Больше чем: ">"
Не равно: "!="
Равно: "="
Имеет: ":"

Эти операторы применяются к типам значений Double, Integer, Boolean, Enum и Timestamp.

Имеет оператор

Вы можете использовать оператор HAS ( : ) для специальных операций над следующими полями:

Подстроки

Когда оператор HAS используется для сравнения значений строкового столбца со строкой, этот оператор действует как операция над строкой. Например, name:"abcd" возвращает все экземпляры, где name — это строка, содержащая "abcd" .

Проверка существования

Когда вы используете оператор HAS со специальным символом * , оператор HAS проверяет наличие ненулевых значений. Например, name:* возвращает все экземпляры, где name не равно NULL, отсутствует или не определено.

Когда вы используете оператор HAS с нестроковыми значениями, он ведет себя так же, как оператор EQUALS ( = ). Например, isCompleted:true ведет себя так же, как isCompleted = true .

Повторяющиеся поля

Вы можете использовать оператор HAS ( : ) для фильтрации повторяющегося поля ресурса API, если выполняются следующие условия:

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

Фильтрация по вложенным повторяющимся полям не поддерживается.

Вот пример:

item имеет поле colors , которое содержит строковые значения, такие как "red" , "blue" и "yellow" .

item.colors:("red") возвращает все элементы, имеющие значение "red" в поле colors .
item.colors:("red" "yellow") возвращает все элементы, у которых в поле colors есть как "red" так и "yellow" .
item.colors:("red" OR "yellow") возвращает все элементы, у которых в поле colors указано "red" или "yellow" .

item также имеет повторяющееся поле tools , которое представляет собой сложный объект со скалярной shape поля, значения которого могут быть "square" или "round" .

item.tools.shape:("square") возвращает все элементы, имеющие инструменты "square" формы.
item.tools.shape:("square" "round") возвращает все элементы, у которых есть инструмент как "square" так и "round" формы.
item.tools.shape:("square" OR "round") возвращает все элементы, у которых есть инструмент "square" или "round" формы.

Незаполненные вложенные поля

Вложенные поля — это подполя полей корневого уровня, например shape в item.tools.shape — это вложенное поле items.tools .

Поля корневого уровня по умолчанию имеют значение false. По умолчанию вложенные поля не заполняются.

Объекты с незаполненными вложенными полями не возвращаются отрицательными фильтрами ( != ).