Filtersyntax

Einige API-Endpunkte akzeptieren einen Parameter where, der einen Filter auf die Ergebnismenge anwendet.

Die folgenden Abschnitte enthalten einige Beispiele für die Filterverwendung sowie eine vollständige Syntaxreferenz.

Beispiele

Feld "foo" ist gleich 3:

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

Für Felder vom Typ Object verwende die Punktnotation, um auf verschachtelte Felder zu verweisen. Feld "bar", verschachtelt unter Feld "foo", ist gleich 3:

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

Das Integer-Feld "foo" ist gleich 3 und das Integer-Feld "bar" ist kleiner als 10:

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

Entweder ist der in Großbuchstaben umgewandelte Wert des String-Felds "foo" gleich "AHREFS", oder alle String-Elemente im Array-Feld "bar" haben das Präfix "Ahrefs" und das Suffix "seo".

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

Sprachreferenz

Die Filtersyntax wird durch die folgende Grammatik beschrieben, ausgedrückt in einer Notation im BNF-Stil.

Ein in spitzen Klammern \< und > eingeschlossener Begriff bezeichnet ein Symbol. Ein Symbol, gefolgt von einem +, bezeichnet ein nicht leeres Array, das dieses Symbol enthält. Ein ? vor einem Object-Feld zeigt an, dass das Feld optional ist.

Die beiden terminalen Symbole sind wie folgt definiert:

• \<field_alias> Ein Alias für ein Filterfeld. Eine Liste gültiger Aliase findest du in der Dokumentation des jeweiligen Endpunkts. Beachte, dass die Parameter select und where unterschiedliche Aliase akzeptieren können.
• \<value> Ein JSON-Wert. Er sollte dem Typ des Felds entsprechen (oder dem Typ des Modifiers des Felds, falls einer vorhanden ist).

Zulässige Muster in Regex-Filterausdrücken unterscheiden sich je nach Tool.

• Keywords Explorer: Nur * als Platzhalteroperator.
• Site Explorer: RE2-Syntax.

\<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> }