Skip to Content
We are live but in Staging 🎉
TablesCLI GuideOverview

Tables — CLI Guide

Two dodil k3 command groups cover the Tables domain:

  • dodil k3 table — table lifecycle + SQL + data mutations + maintenance. Most of your time is here.
  • dodil k3 engine — per-bucket engine lifecycle. Engine is auto-enabled on CreateBucket — you rarely touch these.

For navigation, this guide splits the table subcommands into three pages by concern:

PageSubcommandsMaps to API
dodil k3 table — lifecyclecreate · list · get · describe · deleteTables
dodil k3 table — dataquery · insert · merge · update · delete-rowsData + Execute
dodil k3 table — maintenanceoptimize · vacuum · compactMaintenance
dodil k3 engineenable · get · disableEngine

For install, auth, output format, and global flags see CLI Basics. For the underlying API contracts see Tables — API Reference.

Quick session

# 0. (Engine is already enabled — every bucket gets one on CreateBucket.)
#    Skip straight to creating a table.
 
dodil k3 table create events --bucket kb-prod \
  --columns-json '[
    {"name":"id","type":"COLUMN_TYPE_LONG","nullable":false},
    {"name":"user_id","type":"COLUMN_TYPE_STRING","nullable":false},
    {"name":"event_type","type":"COLUMN_TYPE_STRING","nullable":false},
    {"name":"payload","type":"COLUMN_TYPE_JSON","nullable":true}
  ]' \
  --partition-column event_type \
  --merge-key id --merge-key user_id
 
# 1. Insert
dodil k3 table insert events --bucket kb-prod \
  --row '{"id":1,"user_id":"u-101","event_type":"click","payload":{"page":"/pricing"}}' \
  --row '{"id":2,"user_id":"u-102","event_type":"purchase","payload":{"sku":"A-12"}}'
 
# 2. Query (eventual freshness)
dodil k3 table query "SELECT event_type, COUNT(*) AS n FROM events GROUP BY event_type" \
  --bucket kb-prod
 
# 3. Upsert with MERGE semantics
dodil k3 table merge events --bucket kb-prod \
  --match-column id --match-column user_id \
  --row '{"id":1,"user_id":"u-101","event_type":"click_pricing","payload":{"page":"/pricing","variant":"B"}}'
 
# 4. Drain write log to Delta + bin-pack
dodil k3 table compact events --bucket kb-prod
dodil k3 table optimize events --bucket kb-prod

See the Quickstart for the same flow with prose annotations.

CLI surface vs API surface

The CLI covers the most-common operations. Anything missing has a direct HTTP equivalent in the API Reference.

DomainAPI coverageCLI coverageUse API directly for
EngineEnableEngine · GetEngine · DisableEnginefull— ✅ complete
Table lifecycleCreateTable · CreateTablePipeline · ListTables · GetTable · DeleteTable · AlterTable · DescribeTable · ListPartitionscreate (manual + pipeline) · list · get · describe · deleteAlterTable (ADD COLUMN), ListPartitions — use curl against /:bucket/tables/:name/{schema,partitions}
DataQuery · Insert · Merge · Update · DeleteRowsfullQuery.freshness selector — CLI hardcodes default (eventual)
SQL plannerExecute (full DuckDB SQL) · Materializepartial — table query runs reads via the same dispatcherDDL via Execute (CREATE / ALTER / DROP / CTAS), Materialize, write SQL strings via Execute
MaintenanceOptimize · Vacuum · Compact · Restore · Historyoptimize · vacuum · compactRestore, History — use API
Templates (warehouse-compatible)ListTemplatestable templates — org-scoped (no -b needed); --category / --search / --label server-side filters— ✅ complete

Global flags worth knowing

All dodil k3 table and dodil k3 engine subcommands take:

FlagShortRequiredDescription
--bucket-byes (persistent on the group)Bucket the engine / table lives in
--output-onotable (default) · json — pick json for piping into jq

For the full set of global flags (--api-endpoint, --token, --org, --timeout, etc.) see CLI Basics → Global Flags.

See also

Enginedodil k3 table