Query Language

Hyperledger Composer Query Language

Queries in Hyperledger Composer are written in a bespoke query language. Queries are defined in a single query file called (queries.qry) within a business network definition.

Query Syntax

All queries must contain the description and statement properties.

Description

The description property is a string which describes the function of the query. It must be included but can contain anything.

Statement

The statement property contains the defining rules of the query, and can have the following operators:

  • SELECT is a mandatory operator, and by default defines the registry and asset or participant type that is to be returned.
  • FROM is an optional operator which defines a different registry to query.
  • WHERE is an optional operator which defines the conditions to be applied to the registry data.
  • AND is an optional operator which defines additional conditions.
  • OR is an optional operator which defines alternative conditions.
  • CONTAINS is an optional operator that defines conditions for array values
  • ORDER BY is an optional operator which defines the sorting or results.

Example Query

This query returns all drivers from the default registry whose age is less than the supplied parameter or whose firstName is "Dan", as long as their lastName is not "Selman".

In practical terms, this query returns all drivers who do not have the lastName "Selman", as long as they are under a defined age, or have the firstName Dan, and orders the results by lastName ascending and firstName ascending.

query Q20{
    description: "Select all drivers younger than the supplied age parameter or who are named Dan and whose lastName is not Selman, ordered from A-Z by firstName"
    statement:
        SELECT org.example.Driver
            WHERE ((age < _$ageParam OR firstName == 'Dan') AND (lastName != 'Selman'))
                ORDER BY [lastName ASC, firstName ASC]
}

Parameters in queries

Queries can be written with undefined parameters that must be supplied when running the query. For example, the following query returns all drivers where the age property is greater than the supplied parameter:

query Q17 {
    description: "Select all drivers aged older than PARAM"
    statement:
        SELECT org.example.Driver
            WHERE (_$ageParam < age)
}

Sample Contains queries

The CONTAINS filter is used to search a array field in a node. The below query returns all the drivers who earned the punctual and steady-driving badges. Considering that the badges is of array type in driver participant.

query Q18 {
    description: "Select all drivers who has the following interests"
    statement:
        SELECT org.example.Driver
            WHERE (badges CONTAINS ['punctual', 'steady-driving'])
}

What next?