Migrating from BQLv1 to BQLv2
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 becomedimensions
- The BQLv2 fields need to be aliased (in
dimensions
andfilters
) - 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 BQLv2metrics
(but using different fields) - the BQLv1
group_by
becomes thedimensions
- sorted using the BQLv2
sort
key, instead of defining it inside thegroup_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
}
]
}
Updated about 3 years ago