Sintassi dei filtri

Alcuni endpoint API accettano un parametro where, che applica un filtro all’insieme dei risultati.

Le sezioni seguenti forniscono alcuni esempi di utilizzo dei filtri e un riferimento completo della sintassi.

Esempi

Il campo "foo" è uguale a 3:

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

Per i campi di tipo oggetto, usa la notazione con punto per fare riferimento ai campi annidati. Il campo "bar", annidato nel campo "foo", è uguale a 3:

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

Il campo intero "foo" è uguale a 3 e il campo intero "bar" è minore di 10:

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

O il valore in maiuscolo del campo stringa "foo" è uguale a "AHREFS", oppure tutti gli elementi stringa nel campo array "bar" hanno il prefisso "Ahrefs" e il suffisso "seo".

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

Riferimento al linguaggio

La sintassi dei filtri è descritta dalla seguente grammatica, espressa in notazione in stile BNF.

Un termine racchiuso tra parentesi angolari \< e > indica un simbolo. Un simbolo seguito da un + indica un array non vuoto contenente il simbolo. Un ? che precede un campo di un oggetto indica che il campo è facoltativo.

I due simboli terminali sono definiti come segue:

• \<field_alias> Un alias di campo per i filtri. Consulta la documentazione dello specifico endpoint per l’elenco degli alias validi. Tieni presente che i parametri select e where possono accettare alias diversi.
• \<value> Un valore JSON. Dovrebbe corrispondere al tipo del campo (o al tipo del modificatore del campo, se presente).

I pattern consentiti nelle espressioni di filtro regex variano in base allo strumento.

• Keywords Explorer: solo * come operatore jolly.
• Site Explorer: sintassi 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> }