Reads

rpc Query(QueryRequest) returns (QueryResponse);
 
message QueryRequest {
  string db_id = 1;
  string sql = 2;
  map<string, Value> params = 3;       // @name placeholders — never interpolate
  map<string, Type> param_types = 4;   // NUMERIC / TIMESTAMP / DATE / JSON binds
  uint32 limit = 5;                    // 0 = server default
  optional string min_ulid = 6;        // read-your-writes watermark
  ResultEncoding result_encoding = 7;  // TYPED (default) | ARROW
  uint32 knn_ef_search = 8;            // pgvector: SET hnsw.ef_search
  uint32 knn_probes = 9;               // pgvector: SET ivfflat.probes
  bool knn_exact_scan = 10;            // pgvector: exact re-rank
  bool knn_eventual = 11;              // pgvector: allow an eventual index read
}
 
message QueryResponse {
  RowSet rows = 1;                     // EMPTY when the result spooled — read manifest
  ServedBy served_by = 2;
  string max_wal_ulid = 3;             // watermark this read observed
  repeated string warnings = 4;
  ResultManifest manifest = 5;         // set above the inline size threshold
  map<string, string> table_watermarks = 6;  // one token per table read
}

{
  "db_id": "kb-prod",
  "sql": "SELECT * FROM events WHERE user_id = @uid LIMIT 100",
  "params": { "uid": { "string_value": "u-101" } }
}

FAILED_PRECONDITION: strong read aborted: the WAL overlay truncated at N entries,
so the result would be incomplete — compaction is catching up; retry shortly

rpc QueryStream(QueryRequest) returns (stream QueryStreamResponse);
 
message QueryStreamResponse {
  RowSet chunk = 1;
  bool last = 2;                       // final frame
  ServedBy served_by = 3;
  repeated string warnings = 4;
}

rpc GetRow(GetRowRequest) returns (GetRowResponse);
 
message GetRowRequest {
  string db_id = 1;
  string table = 2;
  RowSet key = 3;                      // the PK columns, typed, one row
  repeated string columns = 4;         // projection (empty = all)
  optional int64 as_of_version = 5;    // time travel: a pure historical snapshot
  optional string min_ulid = 6;
  ResultEncoding result_encoding = 7;
}
 
message GetRowResponse {
  bool found = 1;
  RowSet row = 2;                      // absent when not found
  ServedBy served_by = 3;
  string max_wal_ulid = 4;
  int64 version = 5;                   // the table version this read observed
}

rpc BatchGetRows(BatchGetRowsRequest) returns (BatchGetRowsResponse);
 
message BatchGetRowsRequest {
  string db_id = 1;
  string table = 2;
  RowSet keys = 3;                     // one row per key
  repeated string columns = 4;
  optional int64 as_of_version = 5;
  ResultEncoding result_encoding = 6;
}
 
message BatchGetRowsResponse {
  RowSet rows = 1;
  int64 version = 2;
  RowSet unprocessed_keys = 3;         // not attempted this call — retry exactly these
}

enum ServedBy {
  SERVED_BY_UNSPECIFIED = 0;
  SERVED_BY_HOT         = 1;   // served from a reader's RAM
  SERVED_BY_WARM        = 2;   // served from a reader's local disk
  SERVED_BY_MERGED      = 3;   // recent writes merged over the table snapshot
  SERVED_BY_WAREHOUSE   = 4;   // table snapshot scan, nothing pending
  SERVED_BY_WAL         = 5;   // pending writes only (internal)
  SERVED_BY_HOT_SHARDED = 6;   // sharded in-memory fan-out
}