All relevant transactions and states are stored in the vault of the Corda node. Often it is required for the CorDapp to access this vault for various activities. To serve this purpose, Corda has been architected from the ground up to encourage the use of industry standard and proven query frameworks and libraries for accessing the vault.
Thus, it provides a number of flexible query mechanisms that could be used:
- Vault Query API
- Using a JDBC session
- Using JPA/JQL queries
- Custom third-party data access frameworks such as Spring Data
Corda comes with Vault Query API that could satisfy the majority of your query requirements. This blog will focus on how to use Vault Query in your CorDapp to perform custom queries based on custom attributes of your contract state.
To perform custom queries based on a custom attribute in your state, firstly the state must implement QueryableState with your custom mapped schema. This way the database (and Corda) will know what you will be querying by. The Vault Query API can be used with the QueryCriteria interface for advanced filtering. The QueryCriteria interface provides a flexible mechanism to specify different filtering criteria, including and/or composition and a rich set of operators.These operators include binary logic, comparison, equality, likeness, nullability, collection-based, as well as standard SQL aggregate functions.
The QueryCriteria has four implementations serving different purposes based on your state type: VaultQueryCriteria, FungibleAssetQueryCriteria, LinearStateQueryCriteria and VaultCustomQueryCriteria. More details about these implementations could be found in the Writing vault queries article. Of this the VaultCustomQueryCriteria comes in handy for custom queries. The VaultCustomQueryCriteria provides the means to specify one or many arbitrary expressions on attributes defined by a custom contract state that implements its own schema. Again, to use this, your state must implement QueryableState.
For example, the below sample queries the vault for InsuranceState states with a given policyNumber. First, we get the Field object for the relevant field in the state. Then, we build the CriteriaExpression that specifies what values for the field are acceptable.
The complete code for this CorDapp can be found in GitHub. To learn more, make sure to visit corda.net and join our developer community Developer Portal, where you’ll have a direct line to R3’s Devrel Team and other developers building on Corda.
Thanks for reading and happy coding 🙂
