Predicate Filters

The most common filter is the Predicate filter, which is used to filter on a specific field against a specific value.

"filters": {
  "field": "url",
  "predicate": "eq",
  "value": "example.com/a"
}

See the Predicates page for the list of predicate filters.

The field can contain a plain field slug or any function that can also be used as a dimension. For instance:

"filters": {
  "field": {
    "function": "div",
    "args": ["crawl.20210102.http_code", 100]
  },
  "predicate": "eq",
  "value": 2
}

This filter will return rows when the HTTP code is 200 because the result of the function is equal to 2.

One way to compare two fields is to use the equality function in the predicate so the function returns true and filters on rows where the result is true:

"filters": {
  "field": {
    "function": "eq",
    "args": [
      "crawl.20210102.http_code",
      "crawl.20201201.http_code"
    ]
  },
  "predicate": "eq",
  "value": true
}

Find all available functions on the Functions page.

Boolean Filters

BQL supports the boolean filters and and or to compound filters, which can be nested. For example:

"filters": {
  "or": [
    {
      "field": "url",
      "predicate": "contains",
      "value": "mobile"
    },
    {
      "and": [
        {
          "field": "protocol",
          "predicate": "eq",
          "value": "http"
        },
        {
          "field": "host",
          "predicate": "eq",
          "value": "m.example.com"
        }
      ]
    }
  ]
}

Negative Filters

To negate a filter and exclude rows that match this condition, encapsulate the nested filter in a not:

"filters": {
  "not": {
    "field": "url",
    "predicate": "eq",
    "value": "example.com/a"
  }
}