Skip to main content

Primary-Key Tables

Primary-key flows are one of the strongest documented parts of the current SDK.

The dev and E2E harnesses already exercise:

  • upsert
  • lookup
  • partial update
  • delete
  • limit scan
  • prefix lookup
  • snapshot batch scan

Upsert​

row, err := client.NewRow(kvSchema, int64(5001), "Ada Lovelace", "gold")
if err != nil {
	log.Fatal(err)
}

result, err := kvClient.UpsertRowAuto(ctx, row, nil)
if err != nil {
	log.Fatal(err)
}

Lookup​

rows, err := kvClient.LookupRows(ctx, 0, kvSchema, []client.Row{row}, []int{0})
if err != nil {
	log.Fatal(err)
}

There is also a single-row helper:

row, err := kvClient.LookupRow(ctx, 0, kvSchema, keyRow, []int{0})

Partial Update​

Partial update is explicit about target columns:

row, err := client.NewRow(kvSchema, int64(5001), nil, "platinum")
if err != nil {
	log.Fatal(err)
}

result, err := kvClient.PartialUpdateRowAuto(ctx, row, []int32{0, 2})
if err != nil {
	log.Fatal(err)
}

The helper validates that key columns are still included where needed.

Delete​

result, err := kvClient.DeleteRowAuto(ctx, keyRow, nil)
if err != nil {
	log.Fatal(err)
}

Limit Scan and Prefix Lookup​

These are currently validated in the canonical E2E harness and belong in the “supported and tested” category, not just “API exists”.

Snapshot Batch Scan​

The canonical E2E harness also validates the current snapshot batch-scan path.

Real example:

schema := client.NewSchema(
	client.Int64Type(),
	client.StringType(),
	client.StringType(),
)

snapshotID, err := waitForLatestKVSnapshot(ctx, cli, env.kvTable, 0)
if err != nil {
	log.Fatal(err)
}

rows, err := cli.Table(env.kvTable).SnapshotScanRows(ctx, schema, client.SnapshotScanOptions{
	BucketID:   0,
	SnapshotID: &snapshotID,
})
if err != nil {
	log.Fatal(err)
}

This flow is already public and real, but it deserves careful framing:

  • it is validated in the canonical RustFS/Paimon demo path
  • it fetches remote or local snapshot files into a local temporary directory first
  • it then opens the local snapshot through a read-only rockyardkv path
  • it supports schema-id-aware remapping for older snapshot rows

For the internal flow details, continue to:

Format Note​

The current real-cluster validation path follows Fluss COMPACTED KV semantics for the primary-key flows covered by the demos.