Queries
A query is a question asked once, with its answer kept at a page in the app, drawn as a chart or a table. Ask the assistant in Slack or Telegram, or add --save to a CLI command; the reply carries the link.
A query is a snapshot. Its page shows the answer as it was when the question was asked, with the time it was taken. Refresh asks the question again. A number that should stay current is a metric.
Create one
From the assistant
Ask to see, chart, plot, open, export or download something, or ask for a table you can open. The assistant answers in a sentence or a short table and adds the link.
| Ask | Drawn as |
|---|---|
| ”Chart swap volume by pool for the last week” | Stacked bars, one colour per pool |
| ”Show me transactions per day on our markets this month” | Bars |
| ”Plot wstETH’s share price over the last 30 days” | Line |
| ”Chart inflows against outflows for the treasury” | In and out |
| ”A table of our markets ranked by TVL” | Table |
| ”List the biggest deposits this week” | Table |
An answer that is a series over time, or longer than a chat message carries, is kept at a page without being asked.
From the CLI
Add --save to query, to events … --event, or to history. The command prints the answer as it does without the flag, then the link.
contract-dev query transfers --group DZap --days 30 --by day,token --sum "{USD}" --save stacked --title "Volume by token"
contract-dev query transactions --group "Wildcat markets" --days 30 --by day --count --save
contract-dev query contracts --group "Wildcat markets" --sort "{TVL}" --save table
contract-dev events --group "Uniswap v3" --event Swap --read "t0=token0()" --fixed t0 --read "t1=token1()" --fixed t1 \
--by contract --by day --sum "max(usd(abs(amount0), t0), usd(abs(amount1), t1))" --window 7d --save stacked
contract-dev history "Lido wstETH" --event Transfer --window 90d --by week --save bars| Flag | Does |
|---|---|
--save | Keeps the answer; the rows pick how it is drawn. |
--save bars|stacked|diverging|line|table | Keeps it drawn this way. Refused, with the reason, when the rows cannot carry it. |
--title "…" | Names the page. Made from the question when left out. |
--draw <column> | The column a chart draws when the rows carry several, such as a read beside TVL. |
--of timeline|contracts|wallets | history only: which of its tables to keep. The timeline by default. |
What a chart needs
| Form | Needs |
|---|---|
| Bars | Rows grouped by day or week (--by day with --count or --sum), one series. |
| Stacked bars | Rows grouped by day or week and one more column (--by day,token). |
| In and out | Rows grouped by day and direction (--by day,direction), or a value that goes below zero. |
| Line | A value read over time: --series on a contracts query, or a metric’s readings. |
| Table | Any answer. |
A value over time is read with --series:
contract-dev query contracts --group Vaults --read "raw=convertToAssets(1000000000000000000)" --read "sp=raw / 10^18" \
--series 30d --every 1d --save line --draw sp--series 30d reads every contract in scope at each step back over 30 days; --every sets the step (1h, 6h, 1d, 1w), chosen for the window when left out. at on a read takes one figure as it was then: --read "bal7=balanceOf(0x…) in asset() at 7d".
The page
A query opens at /queries/<id>.
| Control | Does |
|---|---|
| Drawn as | Switches between bars, stacked bars, in and out, line and table. A form the rows cannot carry is refused, with the reason. |
| Refresh | Asks the question again and replaces the answer. |
| CSV | Downloads every row. |
| Prints the page. | |
| Delete | Removes the query. Asking the question again makes a new one. |
Under the chart, every row, sortable by any column. The rail shows the dataset, scope and window, when the answer was taken, who asked and from where, and the CLI line that asks the same question again.
A page holds up to 5,000 rows. The assistant reads back the first 25 and links the rest.
The list
Queries (/queries, or ⌘K → Queries) lists every saved query in the workspace: title, how it is drawn, dataset, rows, who asked, when. A query saved from Slack or the CLI appears within seconds.
CLI
contract-dev queries # list
contract-dev queries show <id|title> # what was asked, as of when, the rows
contract-dev queries csv <id|title> # the rows as CSV
contract-dev queries refresh <id|title> # ask it again now
contract-dev queries rename <id|title> "<title>"
contract-dev queries as <id|title> <bars|stacked|diverging|line|table>
contract-dev queries delete <id|title>A query is named by its id or its title. Add --json for the full answer.