CQL

Appearance

Getting the same rows twice ​

The same query at the same blocks returns the same rows; what changes between runs is the block latest points at.

That one sentence is the whole promise, and this page is about its edges: what a re-run does, what a chain reorganisation does, when the rows can legitimately change, and how to insist on a fresh read.

What is fixed at run time ​

When you press Run, CQL pins the head of every chain in the query — the block number and its hash — and answers the entire run against those pins. Every call, every storage read and every log fetch is at a block whose hash was recorded, so the rows describe one consistent state.

Two consequences follow. A query written against numbered blocks — at 26_000_000, or the month of stETH share rates at at 25_800_000..26_000_000 every 7200 in Sample a long range — asks for exactly the same blocks every time and returns exactly the same rows. And a query written against latest — the quick start's at latest-21600..latest every 7200 — asks a different question each run, because the head has moved; its last row is the head itself, and every 7 200 blocks the oldest sample leaves the window as a new one enters. The rows differ for that reason and no other.

Running it again ​

Press Run on a query you have already run and CQL hands back the result it already has for those pins, without going to the chain. That is what makes flipping between two saved queries instant.

Force re-run (⌘⇧⏎) discards that and reads everything again at a fresh pin. Use it when you suspect the chain has moved on since the last run, or when an ABI you uploaded to your library has changed and you want the calls decoded with the new one.

Reorganisations ​

Above the finalized block a chain can reorganise, replacing the block a run read with another. CQL notices — every block above finalized is read by hash — and does one of two things. If it happens once, it re-pins, re-reads only the rows whose blocks changed, and reports CQL4900 in the run's diagnostics. If it happens twice in one run, the run fails with CQL4002 and the advice to query finalized, which cannot move.

at finalized-21600..finalized every 7200 is the way to write the three-day series so that its rows will never change.

When the same blocks give different rows ​

Three things can change the rows without the blocks changing, and each is visible in the run:

  • A proxy was upgraded, so an interval of the range is now decoded with a different ABI. stETH is a proxy, so this can happen to it; the Contract tab and CQL3904 show which implementation each interval borrowed from.
  • Your library changed. A query that says with { abi: 'lido' } reads whatever lido is now.
  • A contract got verified after you saw CQL3008 and pressed Check again.

See also ​