Skip to main content

Update calls

Beginner
Concept

To interact with a canister's methods, there are two primary types of calls that can be used: update calls and query calls.

Update calls can make modifications to a canister's state, while query calls cannot. Update calls are executed on all nodes of the subnet that the canister is deployed on since the result of the call must go through consensus. This makes them slower than query calls. They can be synchronous or asynchronous.

Update calls do not go through consensus on the local development environment.

A query method can be called as both an update or a query, whereas update methods can only be called as an update.

Update callsQuery calls
Slow (1-2s)Fast (200-400ms)
Can modify stateCan't modify state
Goes through consensusDoes not go through consensus
Executed on all nodes of a subnetExecuted on a single node
Cost cyclesFree

See the reference on ingress messages for a more technical discussion of this topic.

Making update calls with dfx​

To make an update call to a canister, use the dfx canister call command with the --update flag:

  • dfx canister call --update <canister-name> <method_name> : Make an update call to a canister deployed locally. The local development environment must be running to deploy and call a canister locally. Start it with dfx start --background.

  • dfx canister call --update <canister-name> <method_name> --network=playground: Make an update call to a canister deployed on the playground. Making update calls to canisters deployed on the playground is free, but canisters are temporary and will be removed after 20 minutes.

  • dfx canister call --update <canister-name> <method_name> --network=ic: Make an update call to a canister deployed on the mainnet. Update calls will cost cycles.

Making update calls from within canisters​

  // This query method returns the currently persisted greeting with the given name.
  public query func greet(name : Text) : async Text {
    return greeting # name # "!";
  };