Sintaxis de filtros

Algunos endpoints de la API aceptan un parámetro where, que aplica un filtro al conjunto de resultados.

Las secciones siguientes ofrecen algunos ejemplos de uso de filtros y una referencia completa de la sintaxis.

Ejemplos

El campo "foo" es igual a 3:

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

Para los campos de tipo objeto, usa la notación con puntos para referirte a campos anidados. El campo "bar", anidado dentro del campo "foo", es igual a 3:

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

El campo entero "foo" es igual a 3 y el campo entero "bar" es menor que 10:

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

O bien el valor en mayúsculas del campo de cadena "foo" es igual a "AHREFS", o bien todos los elementos de cadena del campo de matriz "bar" tienen el prefijo "Ahrefs" y el sufijo "seo".

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

Referencia del lenguaje

La sintaxis de filtros se describe mediante la siguiente gramática, expresada en notación de estilo BNF.

Un término entre corchetes angulares \< y > denota un símbolo. Un símbolo seguido de un + denota una matriz no vacía que contiene el símbolo. Un ? delante de un campo de objeto indica que el campo es opcional.

Los dos símbolos terminales se definen de la siguiente manera:

• \<field_alias> Un alias de campo de filtro. Consulta la documentación del endpoint correspondiente para ver la lista de alias válidos. Ten en cuenta que los parámetros select y where pueden aceptar alias diferentes.
• \<value> Un valor JSON. Debe coincidir con el tipo del campo (o con el del modificador del campo, si hay alguno).

Los patrones permitidos en las expresiones de filtro regex varían según la herramienta.

• Keywords Explorer: Solo * como operador comodín.
• Site Explorer: sintaxis 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> }