So just to add into this growing list of IBM posts, in this article I will give you a step by step comprehensive run through on how to create effective Blockchain queries using IBM Hyperledger for your business.
Importance of Blockchain queries
Creating effective and working blockchain queries has wide importance when it comes to application developers. Here querying resources, such as transaction data and assets in blocks on a blockchain, can be a potentially time consuming and a very circuitous task.
So when it comes to creating business blockchain queries, you may encounter the following questions or rather doubts in your mind.
How should I compose an effective business query that can be understood smoothly by the blockchain?
How do I get the results?
How do I consume the results?
Many people consider the sets of diverse and disparate nature of data in varying formats, transforming and then extracting results and showcase them in a presentable way as a burden.
This is where IMB Hyperledger comes into play in making your task of submitting and then handling query results simple and clean.
IBM Hyperledger Composition
Hyperledger Composer is based on Hyperledger Fabric v1.0, but prior to Hyperledger Fabric v1.0, queries required IDs generated by Hyperledger Fabric.
Now with Hyperledger Composer’s rich query capability and Hyperledger Fabric v1.0, you can query resources using any attribute or variable parameters. By using queries with parameters, you don’t have to construct complex ad hoc queries, and you can construct template queries, setting the parameters for each use.
Common Blockchain queries
Consider these logical queries, for example:
“Show me the list of commodities created by Trader A.”
“Show me the list of commodities of type EURONEXT created by Trader B in the last week.”
“Show me the history of changes to the ledger for a particular Commodity instance, by a particular Trader, and for a specified time window.”
Translation of these queries into “Blockchain Speak”
Using Hyperledger Composer’s rich Query feature allows you to compose powerful queries like the one’s mentioned above. This unique Query feature bridges the gap, Hence you will no longer have to build the syntax, parse, convert, and validate the query. You won’t even have to build up its types, and the results you get back from a Hyperledger Fabric blockchain. Even also would not have to worry about ensuring a consistent format for your Blockchain.
Another big plus is that, Hyperledger Composer’s Query language eliminates these hassles, thus making it further easy to define queries, in simple notation. This efficiently enables your application to take actions based on business-defined criteria. Once this is done, you can then easily consume the queries directly in your application. This can also be done via the generated query REST APIs.
I would strongly recommend you to grab the monthly roundup that will allow you to use the best free tools, training, and community resources to help you put blockchain to work and achieve the best results.
The Hyperledger Composer Query language is powerful enough to return efficient results using a blockchain resource’s attributes. To explain how it is basically done, we will take an existing trade-network sample deployed using Hyperledger Composer as an example and show how to use rich queries with a REST server. The trade-network sample simply shows the transfer of ownership of commodities between two different traders.
Through this same procedure, we will also show you how to perform operations on result sets, such as updating or removing assets using a transaction processor.
I would strongly recommend you to work through this tutorial as per the steps and software listed below. Please do not skip any step in between. You will also require a working knowledge of JSON and basic query definitions.
Once you have gone through the tutorial, you can easily use Hyperledger Composer to build your network and try out your own queries.
Prerequisites and Software requirements
Hyperledger Composer development tools. We will show you how to install them in the next section.
Hyperledger Composer command line (composer-cli)
Hyperledger Composer REST server (composer-rest-server)
A running Hyperledger Fabric runtime (v1 GA edition). We will give you the guidelines for downloading and starting the Hyperledger Fabric environment in the next section.
Set up the Hyperledger Composer runtime with CouchDB
Install the Hyperledger Composer development tools (as a non-root user)
To install composer-cli, run the following command:
npm install -g composer-cli
The composer-cli contains all the command-line operations for developing business networks.
To install composer-rest-server, run the following command:
npm install -g composer-rest-server
The Hyperledger Composer Loopback Connector is used by the Hyperledger Composer REST server to generate the REST Explorer web page containing the REST APIs that have been generated for the model AFTER the connection to a business network, extraction of the models and schema for the network.
A CouchDB image and CouchDB configuration need to be set up and enabled in order to use rich queries. Both the sets of optimizations have been done in the Hyperledger Composer v0.11+ with the Hyperledger Fabric V1 runtime.
Now, you can enable CouchDB for each peer or a specific peer, and also set the peer to depend on it. Once the CouchDB is enabled, a CouchDB instance is configured for the peer.
A docker-compose.yml file with the appropriate configuration looks something like this:
Add a query to a business network
Queries are JSON objects defined in a query file (.qry) in the business network definition and the Hyperledger Composer Query language quite suitably follows the CouchDB Mango query language standards. These queries can be used to return the following resources:
We will be using some of the most simple queries defined in the Hyperledger Composer trade-network sample in this tutorial, which you can download from GitHub.
Every single query uses a simple syntax, defined by the initial query keyword, which is followed by the query name. For example, selectCommoditiesByOwner.
The description field must be having a human-readable and meaningful description of the query’s function. The statement field contains the SELECT attribute, which further defines the registry or set of resources to query. Next it also contains the WHERE attribute, which defines the conditions that must be fulfilled to return resources.
Open an existing business network, and create a queries.qry file.
In this file, you can describe multiple queries.
I have shown an example query below. This query will return all commodities where the owner attribute matches the _$owner variable parameter.
When a transaction is submitted, the Historian feature in Hyperledger Composer maintains a history of ledger updates that have occurred in a business network.
The HistorianRecord is instantly updated and a registry of transactions is built up over time that includes the transaction inputs for a particular transaction as well. Along with this, the participants and identities involved in submitting those transactions are also registered into the historian record.
Two additional transactions are added to the queries.qry file to demonstrate the Historian feature in Hyperledger Composer:
Listing 1. Example query with additional transactions
description: "Select commodity all historians"
SELECT org.hyperledger.composer.system.HistorianRecord FROM
WHERE (transactionType == 'AddAsset' OR transactionType ==
'UpdateAsset' OR transactionType == 'RemoveAsset')
description: "Find commodity historians after a specified time"
SELECT org.hyperledger.composer.system.HistorianRecord FROM
HistorianRegistry WHERE (transactionTimestamp > _$justnow)
Step 3: You can now cut and paste these two queries into the queries.qry file. DO NOT FORGET to save the file.
Deploy the business network to Hyperledger Fabric
The business network you now have should include the queries.qry file. Please deploy the business network with the following command if you have a local instance of Hyperledger Fabric:
PLEASE NOTE: You should update the business network if you have already deployed the trade-network.bna, with this command:See the Hyperledger Composer Command Line documentation for more details.You can also choose to pass a full path to the trade-network.bna; DO KEEP IN MIND that the hlfv1 is the connection profile name to the Hyperledger Fabric runtime.
The id dan[at]email.com in the Participant registry has a URI prefix of resource:org.acme.trading.Trader# to the participant in question. This URI prefix is the one which the fully qualified relationship refers.Please keep in mind that the Fabric was modeled as such in the trade-network model that the owner attribute has a relationship to a Participant instance.
Create a trade transaction
If I am asked to explain a trade transaction, then I would put it as, a transaction defined to change the ownership of a Commodity. As mentioned earlier, all transactions are recorded in the Historian registry for this commodities-trading business network.
The historian registry maintains a history or record of transactions, their types, and the changes/deltas added by a particular transaction.
The listing 8 shows all Historian records of transactions after the specified date time in the Historian registry this query finds. Both system transactions and user-defined transactions are included in the transaction.
From what I have heard and from what I have experienced myself, it becomes easy to perform complex and powerful queries on assets and transactions with the help of the rich Query language built into Hyperledger Composer.
The Hyperledger Composer Query language provides great flexibility for querying any attributes easily and without it, you would have to construct ad hoc queries in your code without this native Query language and then work to make sense of the results returned.
With the help of this step by step tutorial, I have attempted to show you:
How to define queries in Hyperledger Composer
How to deploy or update a business network to Hyperledger Fabric with CouchDB enabled
How to set up a REST server and use that to query your business network.
Recommended steps (Additional)
Now that we are through with the major set up, here is a list of steps that I would recommend you, so you can strengthen your skills with the Hyperledger Composer.
Saurabh Mukhekar is a Tech Blogger from Pune, India. He is also thinker, maker, life long learner, hybrid developer, edupreneur, mover & shaker. He’s captain planet of BlogSaays and seemingly best described in rhyme. Follow Him On Facebook