Execute — API Reference

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

The canonical SQL surface. Send a DuckDB SQL string; K3’s planner parses it, picks the right dispatch strategy (keyed/non-keyed write, eventual/strong/federated read, DDL, CTAS), and runs it. Every shape Data RPCs cover is reachable here, plus everything they don’t (JOINs, CTEs, window functions, CTAS, ALTER TABLE).

Request / response

rpc Execute(ExecuteRequest) returns (ExecuteResponse);
 
message ExecuteRequest {
  string bucket = 1;
  string sql = 2;                             // DuckDB-flavored SQL
  Freshness freshness = 3;                    // Read-freshness override — ignored for write/DDL
}
 
// Response is a oneof — the variant matches the SQL kind.
message ExecuteResponse {
  oneof result {
    ExecuteQueryResult query = 1;
    ExecuteWriteResult write = 2;
    ExecuteDdlResult ddl = 3;
  }
}
 
message ExecuteQueryResult {
  repeated string columns = 1;
  repeated string rows = 2;                   // JSON-encoded rows
  int64 row_count = 3;
  ServedBy served_by = 4;                     // WAREHOUSE | MERGED | OLTP
  QueryStrategy strategy = 5;
  string strategy_reason = 7;                 // e.g. "table is not partitioned"
  repeated string warnings = 6;
}
 
message ExecuteWriteResult {
  int64 rows_written = 1;
  WriteStrategy strategy = 2;
  bool noop = 3;                              // true when keys list resolved to zero rows
  bool pending_drain = 4;                     // true when write went through the write log
  string target_table = 5;
  repeated string warnings = 6;
}
 
message ExecuteDdlResult {
  string op = 1;                              // "create_table" | "create_table_as_select" | "alter_table" | "drop_table"
  string target_table = 2;
  optional int64 version = 3;                 // present for CREATE/ALTER; absent for DROP
}

Generic Execute invocation via grpcurl:

grpcurl \
  -H "Authorization: Bearer $DODIL_TOKEN" \
  -d '{
    "bucket": "kb-prod",
    "sql": "SELECT 1"
  }' \
  $K3_GRPC \
  dodil.k3.tables.v1.TableService/Execute

SQL constraints: one statement per call. No BEGIN/COMMIT/ROLLBACK. The planner refuses both — see Refusals.

For the dialect itself (types, JSON ops, statement shapes), see SQL Compatibility.

Sub-pages — by SQL shape

• DDL — CREATE TABLE (with PRIMARY KEY + PARTITIONED BY), CTAS (type inference), ALTER TABLE ADD COLUMN, DROP TABLE. Start here — define the table before you query or write to it.
• SELECT — read strategies (UNARY_WAREHOUSE, UNARY_MERGED_STRONG, FEDERATED_AGGREGATE / SCAN / TO_SINGLE), JSON column reads, joins / CTEs / windows.
• INSERT — keyed (KEYED_INSERT_SINGLE / BULK / FROM_SELECT) and non-keyed (NON_KEYED_INSERT, NON_KEYED_INSERT_FROM_SELECT).
• UPDATE — keyed (KEYED_UPDATE, KEYED_RANGE, KEYED_FROM_SUBQUERY) and non-keyed (with WAL-bypass warning and the two safe patterns).
• DELETE — keyed (KEYED_DELETE, KEYED_RANGE_DELETE, KEYED_DELETE_FROM_SUBQUERY) and non-keyed.
• MERGE — MERGE_ROWS / MERGE_QUERY / MERGE_TABLE, WHEN MATCHED THEN DELETE, pre/post-drain semantics.
• Materialize — structured SELECT INTO-style RPC; same dispatcher as CTAS with separate inputs for source / SQL / target / partitioning / mode.

Freshness — read-side request control

For SELECT plans, you control freshness via ExecuteRequest.freshness; the planner picks the strategy based on table size + partitioning + the query shape.

QueryStrategy — read-side observability

Returned on ExecuteQueryResult.strategy. Full per-strategy walkthrough on SELECT.

WriteStrategy — write-side observability

Returned on ExecuteWriteResult.strategy. The planner classifies the SQL into one of 16 variants based on: (1) does the table have merge_keys, (2) does the predicate match all merge_keys, (3) is the SQL shape INSERT / UPDATE / DELETE / MERGE.

Keyed strategies route through the write log → compactor MERGE on next drain. Safe for concurrent writes; visible immediately under freshness=STRONG.

Non-keyed strategies ⚠️ go directly to Delta, bypassing the write log. If pending log entries for the same rows haven’t compacted yet, the next drain may overwrite the Delta-side change. See UPDATE → Non-keyed safe patterns.

ServedBy

Returned on ExecuteQueryResult.served_by to make it obvious which engine answered.

What you can put in an Execute SQL string

Refusals

The following are valid DuckDB SQL but K3 refuses them:

When the response says noop

ExecuteWriteResult.noop = true means the planner picked a strategy but the keys list resolved to zero rows — no dispatch happened. Common cases:

• KEYED_RANGE / KEYED_RANGE_DELETE whose range matched no existing PKs
• KEYED_FROM_SUBQUERY where the subquery returned empty

Read it as a clean “no rows affected” — same outcome as a SELECT with zero matches.

See also

• Data — typed shortcuts for Query / Insert / Merge / Update / DeleteRows
• Tables — table lifecycle + DescribeTable (post-drain row classification)
• Maintenance → Compact — force write-log drain before non-keyed writes
• Core Concepts → WriteStrategy + QueryStrategy — full enum reference
• SQL Compatibility — DuckDB dialect specifics (types, JSON ops, refusals)
• Recipes → Manual table + CTAS / Materialize — runnable end-to-end flows