Tables
Create, show and manage tables. A table is a state table (one row per thing, such as a loan or a withdrawal request, alive while the thing is, its columns read live) or an activity table (one row per event, or another table’s rows, optionally grouped and ranked). See Tables.
Requires contract-dev login. tables is accepted as well as table.
table list
Every table, hidden ones too, with each one’s description: the activity tables, then each state table’s rule for a row, the events it watches, when a row finishes, and its rows active and finished.
contract-dev table list [--group <group>] [--contract <ref>]--group or --contract lists the state tables on that scope alone. table with no subcommand lists too.
table show <table>
An activity table’s rows, asked now: 25 unless --limit says, --json for every one. While its rows are still being read, it says so and shows none.
contract-dev table show <table> [--limit <n>] [--json]A state table: findings and endings per period, rows per status, how long rows take, column totals, the biggest and newest rows, the busiest contracts.
contract-dev table show <table> [--by day|week|month] [--since YYYY-MM-DD] [--among active|done|all]
[--column <key|label>] [--contract <ref>] [--limit <n>]
contract-dev table show <table> --row <id>| Flag | Description |
|---|---|
--by | How findings and endings are counted: day, week or month (UTC). |
--since YYYY-MM-DD | Start the timeline on this UTC day. |
--among | Which rows the totals and the biggest rows cover: active (default), done or all. |
--column <key|label> | The column the biggest rows are ranked by. Without it no rows are ranked. |
--contract <ref> | Only the rows in this contract of the table’s scope. |
--limit <n> | The biggest and newest rows to list. Default 5, at most 25. |
--row <id> | One row: its values, its statuses, its watched events and its own events since it was found. |
contract-dev table show "Withdrawal requests" --by week --among done
contract-dev table show "Withdrawal requests" --row 1042table "<name>" reads as table show "<name>". To filter, rank or fold a table’s rows, use query table. There is no export command: --json prints every row.
table create "<name>"
--on says what the table is on and --each what a row is.
--on | What the table is on |
|---|---|
A name or 0x… address | A contract or wallet. |
tag:<group> | Every member of a group. |
workspace | Every watched contract. |
table:"<other>" | Another table’s rows, its own --where carried in. A table that groups its rows with --by cannot be built on. |
| Table | Made with |
|---|---|
| Activity, from events | --each <Event> alone, or with a plain --column <name>, --status or a --by measure: one row per event, or per group. |
| Activity, built on another table | --on table:"<other>": that table’s rows, or a metric’s records. |
| State | --each <Event> with --id, --finished, --formula, a read --column "<Label>=<view>(…)", or --count or --sum without --by: one row per thing the event announces. |
A table is made from events, or built on a table that is. Transactions, transfers, wallets and contracts are asked with query, not kept as a table.
Every table takes --description "<sentence>": a sentence or two on what it shows, beside it on the Tables page and at the top of its page.
Activity tables
contract-dev table create "<name>" --on <what> --each <Event> [--each …]
[--field "<name>=<expr>[ on <Event>]"]… [--read "<name>=<call>"]… [--pair "<Event> [on <field>]"]…
[--keep <param>[,<param>…] | --keep all] [--days <n>] [--detail <name>]… [--description "<sentence>"] [query flags]
contract-dev table create "<name>" --on table:"<other>" [query flags]| Flag | Description |
|---|---|
--each <Event> | An event kept as rows. Repeat for several. |
--field "<name>=<expr>[ on <Event>]" | A figure on each row: usd(amount, token) in dollars on the event’s day, amount(raw, token) in whole tokens, a read as of its transaction, or a paired event’s field as Event.field. on <Event> makes it that event’s alone, when events name the same thing differently. |
--read "<name>=<call>" | A view read as of each event’s transaction. |
--pair "<Event> [on <field>]" | Another event of the same transaction, its fields read as Event.field. |
--keep <param>,… / --keep all | Event parameters kept on every row beyond the ones the fields read. |
--days <n> | How far back the rows reach. |
--detail <name> | A column each row opens onto, one line per item of a list field: a batch swap’s swaps. |
The table shows its --field columns.
The query flags are query’s: --where keeps rows, --by with --measure, --sum, --count or --distinct groups them, --having, --breakdown, --sort, --limit and --top rank and cut them. The question is asked again while the table is open, so a grouped table’s figures move with its window.
# Every swap over $10k
contract-dev table create "Big swaps" --on tag:pools --each Swap --read "t0=token0()" \
--field "dollars=usd(abs(amount0), t0)" --where "dollars > 10000"
# The top ten traders by volume, last 7 days
contract-dev table create "Top traders, 7d" --on tag:pools --each Swap --read "t0=token0()" \
--field "dollars=usd(abs(amount0), t0)" --days 7 --by wallet --measure volume="sum(dollars)" --measure swaps=count \
--top 10
# A ranking built on the swaps table
contract-dev table create "Whales" --on table:"Big swaps" --by wallet --count --top 10--value, --aggregate, --unit, --split and --line are refused here: they make a metric, with metric define.
State tables
One row per thing the --each event announces, identified by one of its fields. A row is alive until its finishing rule holds; a finished row keeps its final values and stops being read. Its history is read now and kept up to date.
contract-dev table create "<name>" --on <what> --each <Event> [--id <field>] [--id-shown date|number]
[--column "<Label>=<view>(<args>)[.<output>][; on 0x…][; token <token>][; show usd][; decimals <n>]"]…
[--formula "<Label>=<expr>[; call <name>=<call>]…[; token <token>][; show usd]"]…
[--status "<Label>: <Opt>=<rule>; <Opt>=<rule>; <Opt>"]…
[--count "<Event>[:label] [on <field>]"]…
[--sum "<Event>.<field>[:label] [on <field>] [token <token> [show usd] | decimals <n>]"]…
[--event "<Event>.<field>"]… [--finished "<rule>"] [--closes <Event>] [--closes-on <field>]
[--hidden] [--description "<sentence>"]| Flag | Description |
|---|---|
--each <Event> | The event that announces a row. |
--id <field> | The event’s field that is the row’s id, when several could be. |
--id-shown date|number | Show a number id as a date (an expiry, a deadline). It is a number unless you say so. |
--column "<Label>=<view>(<args>)" | A view read live on each open row. id() stands for the row’s id and {Label} for a cell of the row. After the call: .output for one of several outputs, ; on 0x… to read another contract, ; token <token>, ; show usd, ; decimals <n>. |
--formula "…" | A calculated column over the row’s other columns, with calls of its own if needed. Repeat for more. |
--status "…" | A status column. Its options are tried in order and the first whose rule holds wins; an option with no rule is Otherwise and comes last. Repeat for more. |
--count "…" | A column counting an event per row, matched on the row’s id. |
--sum "…" | A column summing one of an event’s fields per row, matched on the row’s id. |
--event "<Event>.<field>" | An event a rule names, with the field that holds the row id. |
--finished "<rule>" | When a row is finished. |
--closes <Event> | Shorthand for a pinned Stage column with one option, Closed, on that event; a row is finished once it is. --closes-on <field> names its id field. |
; on 0x… / ; on {Column} / ; on id() | After a --column call: where the read goes when not the row’s own contract. One contract for every row, an address the row itself holds (each pool’s own hook), or the row’s id where that is an address. |
last <window> | At the end of a --count or --sum: a window back from now (24h, 7d, 30d) in place of the whole history. |
from table:"<table>" | With last: add up a table of events’ rows per row of this table, --sum '<column>:<Label> from table:"Swaps" last 7d'. The link is the field the events table says holds this table’s rows (where "id in Pools"), or on <field>. |
--row-name "<template>" | What a row is called, over the table’s own columns in braces: "{Token 0}/{Token 1}" names a pool by its pair. The name stands in the table in place of the id. |
--detail "<Column>, <Column>…" | Columns shown on a row’s own page and not in the table. Every column is made the same way; this only says where it shows. |
--hidden | Make a table to answer a question: it stays off the Tables page and is removed 7 days after it was last read. |
Every number column keeps its value per row and day. A row’s page charts them and lists the row’s own rows from each table of events that points at its table. A formula reads an earlier value with ago({Deposits}, 7d), and table show <table> --row <id|name> --last 30d reads a row’s columns over time (--series for every day). A column over a window has its whole past; a read, an event total and a formula have days from when the table started keeping them.
Nothing is matched by name. When an event has more than one field that could hold the row id, say which: on <field> on --count and --sum, --event "<Event>.<field>" for an event a rule names, --closes-on for --closes.
contract-dev table create "Loans" --on tag:markets --each LoanOpened --id loanId \
--column "Owed=accountDebt(id())" --finished "seen(LoanClosed)"
contract-dev table create "Withdrawal rounds" --on tag:"Wildcat markets" --each WithdrawalBatchCreated --id-shown date \
--sum "WithdrawalQueued.normalizedAmount:Requested on expiry token asset()" \
--sum "WithdrawalBatchPayment.normalizedAmountPaid:Paid on expiry token asset()" \
--event WithdrawalBatchExpired.expiry \
--formula "Outstanding=max({Requested} - {Paid}, 0); token asset(); show usd" \
--status "Stage: Expired=latest(WithdrawalBatchExpired); Paying=seen(WithdrawalBatchPayment); Queued" \
--status "Health: Overdue={Stage} == \"Expired\" and timeIn({Stage}) > 24h; At risk={Outstanding} > 100000; Healthy" \
--finished "{Stage} == \"Expired\" and {Outstanding} == 0"Rules
Rules are expressions over the row: columns as {Label}; events by name with seen(E), at(E), latest(E); inList(), now(), found(), timeIn({Status}); and, or, not, comparisons, arithmetic, and durations like 24h or 7d; price(T), usd(raw, T) and amount(raw, T) for dollars at the current price.
{Outstanding} > 100000 and not seen(WithdrawalBatchClosed)
{Stage} == "Expired" and timeIn({Stage}) > 24hA formula folds an event’s field by name over the row’s events: sum(Event.field), count(Event), min, max, first, last.
Amounts
Nothing is assumed about what a number is. An amount is a token amount only when it ends with token <token>: the token’s 0x address, self (the contract itself), or a view each contract answers with the token’s address, like asset(). Its decimals then scale it, and show usd puts it in dollars at the current price. A formula already in token units takes the same: --formula "Outstanding={Requested} - {Paid}; token asset(); show usd"; its own calls then count in that token too, unless one states decimals <n>. Without a token a number is shown as the chain holds it; decimals <n> scales a plain number.
table update <table>
Rename or describe a table, add status or formula columns or replace their rules (by label), set when its rows finish, or put a hidden table on the Tables page or take one off. An activity table takes --name and --description only.
contract-dev table update <table> [--name "<name>"] [--description "<sentence>"] [--status "<Label>: …"]… [--formula "<Label>=<expr>"]…
[--token "<Label>=<token> [show usd]"]… [--event "<Event>.<field>"]… [--finished "<rule>" | --never-finishes]
[--show | --hide]| Flag | Description |
|---|---|
--name "<name>" | Rename it. |
--description "<sentence>" | Describe it. --description "" removes the description. |
--status, --formula | Add a column, or replace the rules of the one with that label. |
--token "<Label>=<token> [show usd]" | Set or change a column’s token. Nothing after = clears it. |
--event "<Event>.<field>" | An event a rule names, with the field that holds the row id. |
--finished "<rule>" / --never-finishes | When rows finish, or never. |
--show / --hide | Put a hidden table on the Tables page, or take one off. |
contract-dev table update "Withdrawal requests" --formula "Outstanding={Requested} - {Paid}"
contract-dev table update "Withdrawal rounds" --showtable delete <table>
Remove a table by name or id. A state table’s rows, their readings and the alerts on its columns go with it. An activity table made from events takes the rows it kept with it.
contract-dev table delete "Withdrawal rounds"A number over a table’s rows is a metric: metric define --on table:"<table>". An alert on every open row is notify add alert --on table:"<table>" --column ….