Syntaxe de filtrage

Certains endpoints d’API acceptent un paramètre where, qui applique un filtre à l’ensemble des résultats.

Les sections suivantes donnent des exemples d’utilisation des filtres ainsi qu’une référence complète de la syntaxe.

Exemples

Le champ « foo » est égal à 3 :

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

Pour les champs de type objet, utilisez la notation par points pour faire référence aux champs imbriqués. Le champ « bar », imbriqué sous le champ « foo », est égal à 3 :

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

Le champ entier « foo » est égal à 3 et le champ entier « bar » est inférieur à 10 :

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

Soit la valeur en majuscules du champ de chaîne « foo » est égale à « AHREFS », soit tous les éléments de type chaîne du champ tableau « bar » ont le préfixe « Ahrefs » et le suffixe « seo ».

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

Référence du langage

La syntaxe de filtrage est décrite par la grammaire suivante, exprimée en notation de style BNF.

Un terme encadré par des chevrons \< et > désigne un symbole. Un symbole suivi d’un + désigne un tableau non vide contenant ce symbole. Un ? précédant un champ d’objet indique que le champ est facultatif.

Les deux symboles terminaux sont définis comme suit :

• \<field_alias> Un alias de champ de filtre. Consultez la documentation de l’endpoint concerné pour obtenir la liste des alias valides. Notez que les paramètres select et where peuvent accepter des alias différents.
• \<value> Une valeur JSON. Elle doit correspondre au type du champ (ou au type du modificateur du champ, s’il y en a un).

Les motifs autorisés dans les expressions de filtre regex diffèrent selon l'outil.

• Keywords Explorer : uniquement * comme opérateur générique.
• Site Explorer : syntaxe 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> }