CQL

Appearance

Errors and diagnostics ​

CQL refuses a query it cannot run and tells you why, in a message that names the place in the text and what to do instead.

There is one shape of message, four bands of code, and a short list of the ones you will actually meet. After this page the full table is a lookup, not a read.

How one reads ​

CQL2004 · error · Column `from` is a reserved word; write it in backticks, qualify it as `t.from`,
or rename it with `by sender = t.from`   (line 4, column 9)

Every diagnostic has a code you can search this handbook for, a severity, a message in plain words, and a position the editor underlines. Most messages end with the fix. Where CQL can guess what you meant — a misspelled operator, a wrongly cased address — it offers the correction in a hint underneath.

Three severities ​

  • error — the query does not run. Fix it and run again.
  • warning — the query runs, but something in it is probably not what you meant. CQL2901, for example: comparing an address with a bare 0x… literal ignores the chain, and this query spans two.
  • info — a fact about the run worth knowing: the range was sampled, the ABI was borrowed from a proxy's implementation (as stETH's is on every run), a value was rounded. These arrive with the rows, not instead of them.

Four bands ​

The first digit says when the problem was found.

BandFoundAbout
CQL1xxxas you typethe text: a missing semicolon, an odd hex digit, an invalid checksum
CQL2xxxas you typemeaning: unknown names, mismatched types, a function the ABI lacks
CQL3xxxbefore the runthe chain and the caps: a block beyond the head, a missing ABI, too many rows
CQL4xxxduring the runthings only the data can reveal: a node that stopped answering, a timeout, a cap crossed

The first two bands appear in the editor before you press Run. The third appears a moment later, once CQL has looked at the chain. Only the fourth costs you a run.

The ones you will meet ​

  • CQL1016 · Unexpected …; expected … — a syntax slip, most often the missing ; after a let.
  • CQL1006 · Address checksum is invalid — mixed-case address with a typo. The hint gives the corrected spelling; or write it all in lowercase. stETH's address is mixed-case, so paste it rather than retype it.
  • CQL2002 · … is not a column, source alias or let binding — a name CQL does not know. Usually the alias is wrong (s when the source says as t).
  • CQL2004 · Column … is a reserved word — you wrote from bare. Qualify it (t.from), backtick it (`from`), or rename it (by sender = t.from).
  • CQL2010 · Function … not found in the ABI — the ABI CQL found for the contract has no such function: s.stEthPerToken() on stETH, say, when that function belongs to wstETH. Open the Contract tab to see what it does have.
  • CQL2050 · Expression needs a name — project { t.value * 2 } has no obvious column name. Write { doubled: t.value * 2 }.
  • CQL3001 · … is beyond the pinned head — a block number in the future.
  • CQL3008 · … has no ABI — nobody has verified the contract. Check again, use .call(), or upload the ABI. Finding a contract's ABI.
  • CQL3014 / CQL3016 — the query is too large. Narrow, sample or summarize; Long ranges and limits.
  • CQL3901 · No at given; using … — an event source with no range read the default window. Informational; add at if you wanted a different one.
  • CQL4006 · Run exceeded the … timeout — narrow the query or sample more coarsely.

When a run is refused for credits ​

Runs are paid for in credits. Before a run starts, the run bar shows roughly what it will cost — ~0.201 credits — and that much is set aside from your balance when you press Run. When the run ends it is charged what it actually used, and the rest goes back; a run that failed through no fault of the query, such as a node that stopped answering, is not charged at all. What a run uses can come to more than was set aside — the figure is an estimate, not a cap — and then the difference is charged too, even if that takes your balance below zero; a run answered from a result that already exists is charged a small read fee straight away instead, and one that joins the same query while it is already running sets aside only that fee. The run bar says what each run cost once it has finished, and so does Recent.

If your balance does not cover what a run would set aside, the run is refused before anything happens:

CQL0402 · Insufficient credits: this run needs 1.084744 credits and the balance is 0.491119

CQL0402 is not about the query, so it has no position in the text, and pressing Run again will not help: the balance has to grow first. The usage page, linked beside the message and from your balance at the top of the page, shows the balance, what is set aside for runs still going, and every charge with the reason for it.

See also ​