AllianceBlock for Developers: Crash Course AllianceBlock Query Language (ABQL)

5 min readApr 6, 2021

With the release of the AllianceBlock Data Tunnel comes the introduction of the AllianceBlock Query Language: ABQL. ABQL is a JSON based query language. If you are familiar with other JSON based query languages, you will definitely recognize some similarities and you should be able to master ABQL rather quickly.

Please note that ABQL, together with the release of the Data Tunnel is in MVP stage, which means that the features and functionality of ABQL will still grow and expand.

Introduction to JSON

If you are already familiar with JSON, please skip ahead to the next section: "Getting Started with ABQL".

JSON (JavaScript Object Notation) is a lightweight data format that is nowadays used as the major data format between most applications, especially RESTful APIs. It's especially useful because it's so compact compared to for example XML. JSON is able to contain nested data and arrays in order to support the most complicated data schemes.

A valid JSON starting in its most simple way and then growing in complexity to show the potential of JSON could look like this:

From simple to more complicated, an overview of what's possible with JSON

Accessing this data through applications usually goes something like this:

Pseudo code used to access data from a JSON object

Importance of JSON in the Data Tunnel

In order to accommodate application developers, (automated) integrations with a wide array of systems, human readability, ease of transport, and seamless integration with existing tooling we choose to have the output format of the Data Tunnel datasets in JSON. JSON (compatible) data formats are also a common data format used in NoSQL databases, therefore it doesn't make sense to introduce entirely new data formats.

ABQL and JSON

As the output format itself is based on JSON, the query language used to retrieve the output format in the first place is also JSON based: ABQL.

Knowing how JSON data is constructed is fundamental to understand ABQL.

To get a deeper understanding of working with JSON (through JavaScript), follow this article.

Getting started with ABQL

As highlighted in the previous chapter, ABQL is always valid JSON. So if you are already comfortable with the JSON format, you should have no problem figuring out how to write valid ABQL after going through the below examples.

Basic examples to get data quickly

ABQL only needs to have specified what is really needed.

If you want all data to be returned, you simply execute the following query (an empty JSON object):

You basically tell the interpreter that you do not want to limit the output to anything, so all data will be returned. Can be compared to: "SELECT * FROM TableName"

If you want only some data to be returned, you can limit your selection easily using the "limit" property:

Select 10 first records, can be compared to "SELECT * FROM TableName LIMIT 10"

Working with the Data Schema

Any data returned by the Data Tunnel, whether it's unfiltered or not, will return with the full data schema directly next to the data itself. This is done to make integration and interpretation as easy and straightforward as possible.

Very high over, there are two root properties returned in each dataset result:

Through the "schema" property you can view the definition of the dataset. In other words, this property contains the description of each data field, including their datatypes:

Through the "results" property you can view the data itself. The data in the "data" property will always be valid to the schema provided in the "schema" property. Meaning, if you ran a query that aggregates all data to a single "count" property, the returned schema will be adjusted to reflect to only that "count" property, defined as an integer. Each result is wrapped in an array, even if its count is only 1.

Concrete examples

Select only 3 columns from all records:

Select data from a nested object and rename the column name to a more friendly one:

Select the sum of the amounts and name it total:

Working with conditions

Some examples use operators (like "$gt"), please see the next chapter for more details on operators.

A simple condition, finding records whose property "year" equals 2015:

A range (bigger than 2000, less than or equal to 2010):

An "Or" condition:

Ordering data

Ordering data can be done on multiple fields (in an array). Use ASC for ascending order or DESC for descending order.

Query operators ($<operator>)

Operators are used mainly in conditions to build ranges, exclusions or inclusions. The following operators are currently supported:

$eq (equal)
$neq (not equal)
$gt (greather than)
$lt (less than)
$gte (greater than or equal to)
$lte (less than or equal to)
$or (or)
$and (and)
$nlt (not less than)
$ngt (not greater than)

A more advanced example

Get the current stock bought, subtracting everything that was sold from everything that was bought:

Getting additional help

Got stuck running or building a query? Don't hesitate to reach out on our Discord Channel in the #development channel!

About AllianceBlock

AllianceBlock is building the first globally compliant decentralized capital market. The AllianceBlock Protocol is a decentralized, blockchain-agnostic layer 2 that automates the process of converting any digital or crypto asset into a bankable product.

Incubated by three of Europe’s most prestigious incubators: Station F, L39, and Kickstart Innovation in Zurich, and led by a heavily experienced team of ex-JP Morgan, Barclays, BNP Paribas, Goldman Sachs investment bankers, and quants, AllianceBlock is on the path to disrupt the $100 trillion securities market with its state-of-the-art and globally compliant decentralized capital market.