Sintaxe de filtro

Alguns endpoints da API aceitam um parâmetro where, que aplica um filtro ao conjunto de resultados.

As seções a seguir trazem alguns exemplos de uso de filtros e uma referência completa de sintaxe.

Exemplos

O campo "foo" é igual a 3:

{ "field": "foo", "is": ["eq", 3] }

Para campos do tipo objeto, use a notação por ponto para se referir a campos aninhados. O campo "bar", aninhado no campo "foo", é igual a 3:

{ "field": "foo.bar", "is": ["eq", 3] }

O campo inteiro "foo" é igual a 3 e o campo inteiro "bar" é menor que 10:

{
    "and": [
        { "field": "foo", "is": ["eq", 3] },
        { "field": "bar", "is": ["lt", 10] }
    ]
}

Ou o valor em maiúsculas do campo de string "foo" é igual a "AHREFS", ou todos os elementos de string no campo de array "bar" têm o prefixo "Ahrefs" e o sufixo "seo".

{
  "or": [
    {
      "field": "foo",
      "modifier": "uppercase",
      "is": ["eq", "AHREFS"]
    },
    {
      "field": "bar",
      "list_is": {
        "and": [
          ["prefix", "Ahrefs"],
          ["suffix", "seo"],
        ]
      }
    }
  ]
}

Referência da linguagem

A sintaxe de filtro é descrita pela gramática a seguir, expressa em notação no estilo BNF.

Um termo entre colchetes angulares \< e > representa um símbolo. Um símbolo seguido de + representa um array não vazio que contém o símbolo. Um ? antes de um campo de objeto indica que o campo é opcional.

Os dois símbolos terminais são definidos da seguinte forma:

• \<field_alias> Um alias de campo de filtro. Consulte a documentação do endpoint específico para ver a lista de aliases válidos. Observe que os parâmetros select e where podem aceitar aliases diferentes.
• \<value> Um valor JSON. Ele deve corresponder ao tipo do campo (ou ao modificador do campo, se presente).

Os padrões permitidos em expressões de filtro com regex variam de acordo com a ferramenta.

• Keywords Explorer: Apenas * como operador curinga.
• Site Explorer: sintaxe RE2.

\<bool_filter> ::= { "and" : \<bool_filter>+ }
              |   { "or" : \<bool_filter>+ }
              |   { "not" : \<bool_filter> }
              |   \<expr>

\<expr> ::= {
             "field" : \<field_alias>,
             ? "is": \<condition>,
             ? "list_is": \<list_condition>
           }

\<condition> ::= [ "eq", \<value> ]
            |   [ "neq", \<value> ]
            |   [ "gt", \<value> ]
            |   [ "gte", \<value> ]
            |   [ "lt", \<value> ]
            |   [ "lte", \<value> ]
            |   [ "substring", \<value> ]
            |   [ "isubstring", \<value> ]
            |   [ "phrase_match", \<value> ]
            |   [ "iphrase_match", \<value> ]
            |   [ "prefix", \<value> ]
            |   [ "suffix", \<value> ]
            |   [ "regex", \<value> ]
            |   "empty"
            |   "is_null"

\<condition_bool_filter> ::= { "and" : \<condition_bool_filter>+ }
                        |   { "or" : \<condition_bool_filter>+ }
                        |   { "not" : \<condition_bool_filter> }
                        |   \<condition>

\<list_condition> ::= { "any" : \<condition_bool_filter> }
                 |   { "all" : \<condition_bool_filter> }