Skip to Content
We are live but in Staging 🎉
TablesOverview

Tables

K3’s table primitive is an HTAP store — transactional writes coalesced into analytical reads on Delta Lake. Every bucket gets an auto-enabled table engine; you go straight from CreateTable to inserting rows and running SQL.

The on-disk format is Delta Lake — open, standard, and time-travel-capable. The SQL surface is DuckDB-flavored — anything DuckDB parses, K3 can plan.

What you can do

  • Create tables with composite primary keys, partitioning, and JSON columns
  • Run full SQL — INSERT / MERGE / UPDATE / DELETE / SELECT / CREATE TABLE / CTAS / DROP TABLE / ALTER TABLE ADD COLUMN — through one planner-driven Execute RPC
  • Control freshness per read — EVENTUAL (Delta-only, OLAP-optimized) / STRONG (read-your-writes) / OLTP_ONLY
  • Auto-extract rows from objects — create a pipeline-bound table tied to a Scriptum analytics template; rows materialize as documents land in the bucket (see Pipelines)
  • Maintenance ops — Optimize (compact files), Vacuum (expire old versions), Compact (force log drain), Restore (time-travel), History (commit log)

Two creation modes

Equal weight, picked at create time:

ModeRPCWhen to use
ManualCreateTableYou know the schema. Define columns / partitions / merge keys; K3 creates the Delta table eagerly. SQL-first workflow — pure Execute/Insert/Merge/Query thereafter.
Pipeline-boundCreateTablePipelineUnstructured documents land in the bucket; you want them auto-extracted. Pick a warehouse-compatible Scriptum template; K3 persists the table, the pipeline binding, and an auto-generated ingest rule. Schema materializes lazily on first ingest.

Engine

Every bucket gets a table engine auto-enabled on CreateBucket. The engine is per-bucket; all tables in the bucket share it. You won’t touch the engine RPCs for normal usage — they exist for advanced scenarios (custom settings, disable + re-enable, troubleshooting). See API Reference → Engine.

In this section

  • Quickstart — first table, first INSERT, first query — 5 minutes
  • Core Concepts — proto-grounded types: Engine, Table, Column, QueryStrategy, WriteStrategy, Freshness, HistoryEntry
  • SQL Compatibility — DuckDB dialect, types, statement shapes, refusals, JSON ops
  • API Reference — full gRPC + HTTP — Tables · Data · Execute · Maintenance · Templates · Engine
  • CLI Guide — dodil k3 table · engine commands
  • Recipes — manual table, pipeline-bound table, time-travel + restore, CTAS / materialize

See also

  • Object Storage — where every table’s Delta artifacts live, in your bucket
  • Pipelines — the bridge from unstructured uploads to structured rows
  • Conventions — auth, headers, error envelope
Replay & RetryQuickstart