Uso e sintaxe do filtro de lista

Este guia descreve a sintaxe de filtro de lista e como filtrar vários de tipos de recursos.

Alguns métodos da API podem aceitar um filtro para limitar os recursos retornados na resposta.

Resumo

Esta seção fornece uma visão geral rápida da estrutura da sintaxe do filtro da lista.

• Um filtro é uma string que contém um expression. Um expression é um booleano combinação de comparações:

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

• Um comparison corresponde a um campo de recurso com um valor. Você pode usar todos operadores de comparação comuns.

  comparison = name OP value
  OP = "<=" | "<" | ">=" | ">"  | "!=" | "=" | ":"
  

  O operador has, dois-pontos (:), pode ser usado em strings e campos. Consulte a seção Tem operador para ver mais detalhes.

• É possível usar os seguintes tipos de valores em filtros:

  • Numbers
  • Strings
  • Expressões entre parênteses

  value = number| string | "*" | "(" expression ")"
  

• As strings podem representar o seguinte:

  • Texto arbitrário
  • Booleanos
  • Valores de tipo enumerado
  • Carimbos de data/hora

Expressões booleanas

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

As operações são feitas na seguinte ordem:

1. NOT
2. OR
3. AND

Por exemplo, as seguintes expressões são equivalentes:

a OR NOT b AND NOT c OR d

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

É possível omitir o operador AND entre comparações. Por exemplo, os seguintes e os filtros são os mesmos:

c=d AND e=f

c=d e=f

É possível usar o hífen (-) como alternativa para NOT. Não pode haver um espaço entre o hífen (-) e a comparação a seguir. Por exemplo, o filtros a seguir são iguais:

NOT e=f

-e=f

Comparações

Nesta seção, descrevemos comparações de "name OP value" da seguinte maneira:

comparison = name OP value

onde

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

O lado esquerdo de uma comparação é o nome do caminho de um campo de recurso da API. O nome consiste em uma série de identificadores de recursos conectados por ponto (.). Cada identificador de campo é seguido pelo próximo nível de nomes desse campo. Para exemplo, considere um recurso com um campo complexo item que tem outro um campo complexo tool, que tem um campo chamado shape. Em um filtro para este você se referiria a uma forma com o nome item.tool.shape.

O lado direito é normalmente um valor escalar que é convertido na e comparados com ele. Veja os tipos de valor literal para mais detalhes.

O lado direito de uma comparação também pode ser expresso como um booleano entre parênteses de valores literais e/ou expressões booleanas que contêm apenas valores literais (precedidos com ou sem NOT). O nome do lado esquerdo e o operador de comparação são aplicados a cada um dos valores. Por exemplo, o filtros a seguir são iguais:

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

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

Aqui está outro exemplo mais complexo de duas funções filtros:

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")

Tipos de literal de valor

O valor do lado direito de um operador de comparação pode ser categorizado em "Número" e Literais de string.

Número

Esta seção descreve a representação de literais numéricos.

String

Esta seção descreve os tipos que você pode gravar como um literal de string na a sintaxe de filtro.

Operadores de comparação

Veja os operadores de comparação:

• Menor ou igual a: "<="
• Menor que: "<"
• Maior ou igual a: ">="
• Maior que: ">"
• Diferente de: "!="
• Igual a: "="
• Tem: ":"

Esses operadores se aplicam aos valores Double, Integer, Boolean, Enum e Timestamp tipos

Tem operador

É possível usar o operador HAS (:) para operações especiais nos :

Substrings

Quando o operador HAS é usado para comparar valores em uma coluna de strings com um string, o operador atuará como uma operação de substring. Por exemplo: name:"abcd" retorna todas as instâncias em que name é uma string contendo "abcd"

Verificação da existência

Quando você usa o operador HAS com o caractere especial *, O operador HAS verifica se há valores não nulos. Por exemplo: name:* retorna todas as instâncias em que name não é nulo, ausente ou indefinido.

.

Quando você usa o operador HAS com valores não strings, ele se comporta da mesma forma que o operador EQUALS (=). Por exemplo, isCompleted:true se comporta na da mesma forma que isCompleted = true.

Campos repetidos

É possível usar o operador HAS (:) para filtrar um recurso de API repetido , desde que as seguintes condições sejam verdadeiras:

1. Há apenas um componente repetido no caminho do identificador de campo.
2. O último identificador do caminho do campo é do tipo escalar.

Não é possível filtrar campos repetidos aninhados.

Veja um exemplo:

item tem um campo colors, que contém valores de string como "red", "blue" e "yellow".

• item.colors:("red") retorna todos os itens que têm o valor "red" no colors.
• item.colors:("red" "yellow") retorna todos os itens que têm "red" e "yellow" no campo colors.
• item.colors:("red" OR "yellow") retorna todos os itens que têm "red" ou "yellow" no campo colors.

item também tem um campo tools repetido que é um objeto complexo com um escalar campo shape, cujos valores podem ser "square" ou "round".

• item.tools.shape:("square") retorna todos os itens que têm formato de "square". ferramentas de visualização.
• item.tools.shape:("square" "round") retorna todos os itens que têm um Ferramenta no formato "square" e outra no formato "round".
• item.tools.shape:("square" OR "round") retorna todos os itens que têm um Ferramenta de forma "square" ou uma ferramenta de forma "round".

.

Campos aninhados não preenchidos

Campos aninhados são subcampos de campos de nível raiz, por exemplo, shape em item.tools.shape é um campo aninhado de items.tools.

O padrão dos campos no nível raiz é "false". Os campos aninhados não são preenchidos por padrão.

Objetos com campos aninhados não preenchidos não são retornados por valores (!=).

Veja um exemplo:

item.tools tem um tipo enumerado size cujo valor pode ser definido como "SMALL", "MEDIUM" ou "LARGE".

Se você tiver os seguintes itens:

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

Uma chamada para items.list com o filtro negativo "tools.size != SMALL" retorna o seguinte:

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

Como item.tools.size não foi definido para item3, o filtro negativo não foi retornar o objeto item3.

Exemplos