Internet Computer

What is the difference between query and update calls, and how does an engine scale?

All help topics

Update calls change a canister's state and run on every node after consensus; query calls only read, run on a single node and answer faster.

Update calls
  • Every replica executes the call, in the same order, once consensus has placed it in a block. The result is agreed by the subnet and signed by it.
  • Their changes are kept. Use updates for anything that writes, and for reads whose answer must be trustworthy.
  • They take longer than queries, because they wait for consensus.
Query calls
  • One replica answers from its own copy of the state, and nothing the query changes is kept.
  • The answer is signed only by the node that served it. If a client acts on the result (a balance, a permission, a price), call the method as an update instead, or have the canister certify the data so the client can verify it.
How this shapes an engine's capacity
  • Reads scale with nodes. Any node can serve a query, so query throughput grows with the number of nodes times each node's capacity.
  • Writes scale with node class. Every node processes every update, so more nodes don't add write throughput. For more, move to a larger node class.
  • Memory is per node. Every node holds a full copy of your data, so four nodes with 100 GiB each give the engine 100 GiB, not 400 GiB. More memory also means a larger class.
  • More nodes buy fault tolerance: more of them can fail before the engine stops.
  • Split heavy work across canisters. Each canister handles one message at a time, so spreading load over several canisters can raise throughput.

An engine's CPU figure is the average utilization across its live nodes, not a sum. Sustained high CPU under write-heavy work means the nodes are near their limit, and the fix is a larger node class, not more nodes.

Learn more
Still stuck? Contact support