In this section, we will discover how to rewrite your BQLv1 in BQLv2

BQLv1 URLs to BQLv2

If you have an API call to the URL /v1/analyses/my-username/my-website/20210801/urls?area=current&previous_crawl=20210715 , the analysis slugs from the URL will define the collection that the BQLv2 is querying.

Example:

{
  "fields": [
    "url",
    "http_code",
    "previous.http_code"
  ],
  "filters": {
    "field": "indexable.is_indexable",
    "predicate": "eq",
    "value": true
  }
}

Becomes, to /v1/projects/my-username/my-website/query:

{
  "collections": [
    "crawl.20210801",
    "crawl.20210715"
  ],
  "query": {
    "dimensions": [
      "crawl.20210801.url",
      "crawl.20210801.http_code",
      "crawl.20210715.http_code"
    ],
    "metrics": [],
    "filters": {
      "field": "crawl.20210801.indexable.is_indexable",
      "predicate": "eq",
      "value": true
    }
  }
}

• Any fields from BQLv1 become dimensions
• The BQLv2 fields need to be aliased (in dimensions and filters)
• The previous prefix becomes the prefix of the compared crawl

BQLv1 Aggregation to BQLv2

If you have an API call to the URL /v1/analyses/my-username/my-website/20210801/urls/aggs?area=current&previous_crawl=20210715, which does an aggregation of crawl data, the analysis slugs from the URL will define the collection that the BQLv2 is querying.

Example:

[
  {
    "aggs": [
      {
        "metrics": [
          "count"
        ],
        "group_by": [
          {
            "distinct": {
              "field": "segments.pagetype.depth_1",
              "order": {
                "value": "asc"
              },
              "size": 300
            }
          }
        ]
      }
    ]
  }
]

Becomes, to /v1/projects/my-username/my-website/query:

{
  "collections": [
    "crawl.20210801"
  ],
  "query": {
    "dimensions": [
      "crawl.20210801.segments.pagetype.depth_1"
    ],
    "metrics": [
      "crawl.20210801.count_urls_crawl"
    ],
    "sort": [0]
  }
}

• the metrics in BQLv1 are translated to BQLv2 metrics (but using different fields)
• the BQLv1 group_by becomes the dimensions
• sorted using the BQLv2 sort key, instead of defining it inside the group_by

Areas

BQLv1 defines an area, to define the scope that is queried. One can query the current, new or disappeared area. These concepts do not exist in BQLv2.
Instead, they can be reproduced by smartly in BQLv2 through the right filters.

Examples, for a current analysis 20210801, and a compared crawl 20210715:

New area

The URLs must exist on the current crawl, and missing from the compared crawl:

{
  "and": [
    {
      "field": "crawl.20210801.url_exists_crawl",
      "value": true
    },
    {
      "field": "crawl.20210715.url_exists_crawl",
      "value": false
    }
  ]
}

Disappeared area

The URLs must be missing from the current crawl, and present on the compared crawl:

{
  "and": [
    {
      "field": "crawl.20210801.url_exists_crawl",
      "value": false
    },
    {
      "field": "crawl.20210715.url_exists_crawl",
      "value": true
    }
  ]
}