How to query Hyperledger Fabric chaincode

Querying Hyperledger Fabric chaincode reads ledger state through a peer without submitting a transaction to the ordering service. Use it after a smart contract is committed to a channel, after an invoke updates an asset, or when checking the current world-state value before an application test.

The peer CLI sends the proposal to the active peer identity in the shell environment. peer chaincode query returns the endorsed result of the chaincode function call and prints that result locally, so it proves the selected peer can execute the read path but does not create a block or change ledger state.

The Fabric test network provides channel mychannel and the asset-transfer sample chaincode basic. For another network, use its channel name, chaincode name, peer address, MSP path, and TLS root certificate path before reading production data.

1. Change to the Fabric test network directory.

   $ cd fabric-samples/test-network

   The channel and chaincode must already exist. The default sample setup creates mychannel and deploys the basic chaincode before a query can return ledger state.
   Related: How to deploy Hyperledger Fabric chaincode

2. Add the Fabric binaries and sample config directory to the current shell.

   $ export PATH="$PWD/../bin:$PATH"
   $ export FABRIC_CFG_PATH="$PWD/../config"

3. Set the Org1 peer identity for the query.

   $ export CORE_PEER_TLS_ENABLED=true
   $ export CORE_PEER_LOCALMSPID=Org1MSP
   $ export CORE_PEER_MSPCONFIGPATH="$PWD/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp"
   $ export CORE_PEER_TLS_ROOTCERT_FILE="$PWD/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt"
   $ export CORE_PEER_ADDRESS=localhost:7051

   The active CORE_PEER_ADDRESS selects the peer for simple test-network queries. Use --peerAddresses and --tlsRootCertFiles when a connection profile or script targets peers explicitly.

4. Confirm that the chaincode definition is committed on the channel.

   $ peer lifecycle chaincode querycommitted --channelID mychannel --name basic
   Committed chaincode definition for chaincode 'basic' on channel 'mychannel':
   Version: 1.0, Sequence: 1, Endorsement Plugin: escc, Validation Plugin: vscc

   If this command reports that the chaincode is not found, deploy or commit the chaincode before querying ledger state.

5. Query all sample assets from the chaincode.

   $ peer chaincode query -C mychannel -n basic -c '{"Args":["GetAllAssets"]}'
   [{"Key":"asset1","Record":{"ID":"asset1","color":"blue","size":5,"owner":"Tomoko","appraisedValue":300}},
   {"Key":"asset2","Record":{"ID":"asset2","color":"red","size":5,"owner":"Brad","appraisedValue":400}},
   ##### snipped #####
   {"Key":"asset6","Record":{"ID":"asset6","color":"white","size":15,"owner":"Michel","appraisedValue":800}}]

   peer chaincode query contacts the peer and prints the chaincode response. It does not need an orderer endpoint because no ledger update is submitted.

6. Query one asset by ID when checking a specific value.

   $ peer chaincode query -C mychannel -n basic -c '{"Args":["ReadAsset","asset1"]}'
   {"ID":"asset1","color":"blue","size":5,"owner":"Tomoko","appraisedValue":300}

   The constructor JSON can also use Function plus Args, such as {"Function":"ReadAsset","Args":["asset1"]}, when that shape is easier to generate from a script.

7. Treat endorsement failures as query failures, not empty success results.

   $ peer chaincode query -C mychannel -n basic -c '{"Args":["ReadAsset","asset70"]}'
   Error: endorsement failure during query. response: status:500 message:"The asset asset70 does not exist"

   A chaincode error means the peer endorsed an error response from the smart contract. Check the asset key, function name, active channel, and peer identity before retrying.