In this section you will discover queries, one of two primary objects handled by modules. At the end of the section is a code example that puts queries into practice in your checkers blockchain.
A query is a request for information, made by end-users of an application through an interface, and processed by a full node. Available information includes:
- Information about the network.
- Information about the application itself.
- Information about the application state.
Queries do not require consensus to be processed as they do not trigger state transitions. Therefore queries can be handled entirely independently by a full node.
Visit the detailed Cosmos SDK documentation (opens new window) for a clear overview of the query lifecycle and learn how a query is created, handled, and responded to.
# Code example
If you have used Ignite CLI so far, it has already created queries for you to get one stored game or a list of them. However, you still do not have a way to check whether a move works or is valid. It would be wasteful to send a transaction with an invalid move, it is better to catch such a mistake before submitting a transaction. So you are going to create a query to discover whether a move is valid.
Ignite CLI can again help with a simple command:
This creates the following query objects:
It also creates a function that should look familiar:
Now you must fill in the gaps under
TODO. Simply put:
Is the game finished? You should add a
Is it an expected player?
Is it the player's turn?
Attempt the move in memory without committing any new state:
If all checks are passed, return the OK status:
The player's move will be tested against the latest validated state of the blockchain. It does not test against the intermediate state being calculated as transactions are delivered, nor does it test against the potential state that would result from delivering the transactions still in the transaction pool.
A player can test their move only after the opponent's move is included in a previous block. These types of edge-case scenarios are not common in your checkers game, and you can expect little to no effect on the user experience.
This is not an exhaustive list of potential queries. Some examples of other possible queries would be to get a player's open games, or to get a list of games that are timing out soon. It depends on the needs of your application and how much functionality you willingly provide.
If you would like to get started on building your own checkers game you can go straight to the main exercise in Run Your Own Cosmos Chain, either natively with SDK v0.50 or with Ignite CLI to start from scratch.
More precisely, you can jump to:
To summarize, this section has explored:
- Queries, one of two primary objects handled by a module in the Cosmos SDK, which inspect a module's state and are always read-only.
- How a query is a request for information (which could be about the network, about an application, or about the application's state) that is made by end-users of an application through an interface.
- How queries do not require consensus to be processed as they do not trigger state transitions, meaning they can be handled entirely independently by a full node.