Skip to Content
We are live but in Staging 🎉
TablesAPI ReferenceOverview

Tables — API Reference

Package: dodil.k3.tables.v1 · Service: TableService

The Tables surface is 21 RPCs across six functional groups. Two universal entry points worth knowing about up front:

  • Execute — send a DuckDB SQL string, K3’s planner routes it through the right write or read strategy. The canonical SQL surface — every DDL / DML / SELECT shape goes here.
  • Data shortcuts — Query / Insert / Merge / Update / DeleteRows are typed RPCs that the planner routes through the same strategies as Execute. Use these when you’d rather pass typed JSON rows + predicates than assemble SQL strings.

Both share the same dispatch logic — pick whichever is ergonomically nicer for your caller.

Sections

PageRPCsTopic
TablesCreateTable · CreateTablePipeline · ListTables · GetTable · DeleteTable · AlterTable · DescribeTable · ListPartitionsTable lifecycle — both manual and pipeline-generated modes
DataQuery · Insert · Merge · Update · DeleteRowsStructured row operations (no SQL strings)
Execute (SQL)Execute · MaterializePlanner-driven SQL — every DDL / DML / read shape with examples
MaintenanceOptimize · Vacuum · Compact · Restore · HistoryFile compaction, version cleanup, time travel, commit log
TemplatesListTemplatesBrowse Scriptum templates filtered to warehouse-compatible ones
EngineEnableEngine · GetEngine · DisableEnginePer-bucket engine lifecycle — auto-enabled on CreateBucket, rarely touched

Wire conventions

HTTP request bodyHTTP query / pathgRPC
Field namescamelCase (pbjson)snake_case (e.g. table_name, before_version)as in .proto
Enumswire-name strings ("FRESHNESS_STRONG", "WRITE_STRATEGY_KEYED_UPDATE")—enum
int64JSON stringsstringsint64
All fieldsalways emitted (no defaults dropped)——

Endpoint roots

EndpointUse
https://k3.dev.dodil.io (staging) · https://k3.dodil.io (prod)HTTP
k3-grpc.dev.dodil.io:443 (staging) · k3-grpc.dodil.io:443 (prod)gRPC

Auth: bearer JWT in Authorization. See Conventions.

Truthful response shape

Write responses (InsertResponse / MergeResponse / UpdateResponse / DeleteRowsResponse / ExecuteWriteResult) return:

  • rows_written — count of writes the table accepted at response time. For keyed writes this is the write-log append count; for non-keyed writes it’s the direct Delta row count.
  • pending_drain — true when the write landed in the write log and waits on the compactor to materialize into Delta. false when the write went directly to Delta.
  • version — Delta version after the write. 0 when the write is still pending drain (Delta unchanged until next compaction).

Per-row insert/update/delete classification is not knowable synchronously for write-log routes — that breakdown emerges after the compactor MERGE and is exposed via DescribeTable’s last_drain_* fields.

See also

SQL CompatibilityOverview