Skip to main content
Interana Docs

BAQL syntax and usage

Interana provides a flexible query language to use within an external query API call. This article describes how to format BAQL syntax. It includes a table comparing and contrasting some types of queries with analogies in SQL, as well as some example BAQL queries.

BAQL syntax

Use BAQL inside a call to the Interana external query API.

A complete API call containing BAQL is formatted as follows:

{"bql": "select count(*) from foreverMusic"}

A sample request with BAQL looks like this:

curl 'https://11.2.34.141/v1/query' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Token san+aslnasw50293sjlfhgnoOvWW/sQH09y0' \
    -d '{"bql": "select count(*) from foreverMusic"}' --verbose
> POST /v1/query HTTP/2
> Host: 11.2.34.141
> User-Agent: curl/7.54.0
> Accept: */*
> Content-type: application/json
> Authorization: Token san+aslnasw50293sjlfhgnoOvWW/sQH09y0
> Content-Length: 32

For more information on using the external query API, see Use the Interana external query API.

This article focuses on the syntax within the double quotes.

BAQL building blocks

Like other database query languages, BAQL statements consist of a sequence of clauses, which can in turn consist of expressions. BAQL clauses must be assembled in a specific order to form a valid statement. For example, consider the following statement:

select count (* where page = "Error") from my_table group by ROUND(length,10) between 6 months ago and now

The entire BAQL statement consists of several clauses and an expression.

The clauses in the example are:

  • select count (* where page="Error")
  • from my_table
  • group by artist
  • between 6 months ago and now

The expressions in the example are:

  • ROUND(length,10)
  • ROUND(length,10) + 1 is another valid expression
  • page = "Error"
  • page like ".*error.*"
  • length - another_length
  • length / 100 * 100


To build a BAQL query, start by choosing aggregations and the target of the aggregations (that is, the things you want to aggregate over).

Every BAQL query must contain the required clauses, as follows:

  • aggregation
  • table
  • time range (if none is supplied, the query defaults to the time range "beginning of time to now")

Other clauses are optional, for example:

  • Filter on aggregation
  • Group by clause

BAQL is case sensitive.

BAQL equivalents of Interana UI queries

The following table shows common Interana queries and their equivalents in BAQL. The table begins with a straightforward count of events, the default query in most datasets, and each line in the table further refines the query.

Interana sentence-model UI

BAQL statement

Concept

Show count of events

select count (*) from my_table

 

Show count of events
Filtered to events with page that matches Error

select count (* where page=”Error”) from my_table

 

Filter

Show count of events Filtered to events with page that matches Error
Split by artist

select count (* where page=”Error”) from my_table group by artist

Split by

Show count of events Filtered to events with page that matches Error ​​​​Split by artist
6 months ago until now

select count (* where page=”Error”) from my_table group by artist between 6 months ago and now

Relative time

Show count of events Filtered to events with page that matches Error
Split by ROUND(length,10) 6 months ago until now

select count (* where page="Error") from my_table group by
ROUND(length,10) between 6 months ago and now

Math

Time

Relative time

The following query defines a relative time window:

select count(* where action="hate") from fashion between beginning_of_time and now
Trailing time windows

The following query counts the number of events for each 2 day window every day between 2019-01-01 and 2019-01-15:

select count(*) from my_table for every day over 2 days between 2019-01-01 and 2019-01-15

In the current version of Interana, a trailing window must be a multiple of the resolution. For example, a trailing window cannot be 7 days if the resolution is 3 days. This also means that a trailing window cannot be smaller than the resolution.

Actor property examples

The following query returns the number of users who had an event between 2019-01-08 and 2019-01-15 but not in the previous week (2019-01-01 to 2019-01-18):

with prev_week_activity as Actor<user>(
  count(*) over 1 week offset -1 week
)
select count_unique(user where prev_week_activity = 0) from my_table between 2019-01-08 and 2019-01-15

The following query defines two actor properties, user_age and years_voting, the former as an aggregation and the latter as a formula:

with user_age as Actor<user>(
  max(age) between beginning_of_time and now
),
years_voting as Actor<user>(
  user_age - 18
)
select ...
  • Was this article helpful?