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

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

Некоторые методы 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}

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

1. NOT
2. OR
3. 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")

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

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

Число

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

Нить

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

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

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

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

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

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

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

Подстроки

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

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

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

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

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

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

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

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

Вот пример:

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. По умолчанию вложенные поля не заполняются.

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

Вот пример:

item.tools имеет перечисление size , значение которого может быть установлено как "SMALL" , "MEDIUM" или "LARGE" .

Если у вас есть следующие предметы:

{
  "name": "item1",
  "tools": {
    "size": "MEDIUM"
  }
},
{
  "name": "item2",
  "tools": {
    "size": "LARGE"
  }
},
{
  "name": "item3"
}

Вызов items.list с отрицательным фильтром "tools.size != SMALL" возвращает следующее:

{
  "items": [
    {
      "name": "item1",
      "tools": {
        "size": "MEDIUM"
      }
    },
    {
      "name": "item2",
      "tools": {
        "size": "LARGE"
      }
    }
  ]
}

Поскольку item.tools.size не был установлен для item3 , отрицательный фильтр не возвращает объект item3 .

Примеры