Skip to main content

Table Client

GitHub source:

The table entry point is cli.Table(client.TablePath{...}).

What This Client Is For​

TableClient is the main surface for:

  • table metadata lookups
  • routed read/write RPCs
  • row-oriented helper methods
  • snapshot scan flows

In practice, most application code spends its time here after Dial(...).

Common Pattern​

table := cli.Table(client.TablePath{
	DatabaseName: "fluss",
	TableName:    "orders",
})

Metadata​

  • Info(...)
  • Schema(...)

These are commonly the first calls before row construction, writer bootstrap, decode helpers, or snapshot planning.

Raw Data Operations​

  • AppendLog(...)
  • UpsertKV(...)
  • Lookup(...)
  • PrefixLookup(...)
  • FetchLog(...)
  • FetchLogWithOptions(...)
  • LimitScan(...)

These methods map more directly to the underlying routed RPC behavior.

Use them when you need:

  • explicit bucket targeting
  • explicit request fields such as fetch options
  • raw record batches or lower-level results

Key request/result types include:

  • BucketRecordBatch
  • LookupBucketRequest
  • FetchBucketRequest
  • FetchLogOptions
  • FetchedBucket
  • LimitScanResult

Writer Helpers​

  • NewAppendWriter(...)
  • NewUpsertWriter(...)
  • BootstrapRowWriter(...)

These are the best entry points when you want more ergonomic, reusable write flows rather than manually building raw batches.

Row-Oriented Log Helpers​

  • AppendIndexedRow(...)
  • AppendIndexedRowAuto(...)
  • AppendArrowRows(...)
  • AppendArrowRowsAuto(...)
  • AppendArrowRecord(...)
  • AppendArrowRecordAuto(...)
  • AppendArrowChangelogRows(...)

These helpers are the easiest way to teach log-table usage in docs because they work from public row/schema concepts instead of raw byte payloads.

Primary-Key Helpers​

  • UpsertRow(...)
  • UpsertRowAuto(...)
  • PartialUpdateRow(...)
  • PartialUpdateRowAuto(...)
  • DeleteRow(...)
  • DeleteRowAuto(...)
  • LookupRows(...)
  • LookupRow(...)

These are the most approachable primary-key operations for application code.

The Auto forms are especially useful when routing can be derived from table metadata.

Scan Helpers​

  • ScanRows(...)
  • ScanIndexedRows(...)
  • SnapshotScanRows(...)

Important distinction:

  • ScanRows(...) and ScanIndexedRows(...) work through the current KV scan path
  • SnapshotScanRows(...) is the snapshot-driven local-reader path documented separately in the deep dives

Choosing Between Raw and Helper APIs​

Prefer helper-style APIs when you want:

  • row-based construction
  • metadata-driven routing
  • simpler app-facing code

Prefer raw APIs when you want:

  • explicit bucket/request control
  • direct record-batch handling
  • lower-level protocol-shaped behavior

Important Result Shapes​

Common returned types include:

  • ProduceResult
  • PutResult
  • PartialWriteError
  • FetchedBucket
  • LimitScanResult

Guidance​

Where both raw and helper-style APIs exist, the docs should generally teach the helper-style path first and use the raw path only when it provides important control or protocol-level visibility.