API Reference

Complete API reference for the Fluss C++ client.

Result

Field / Method	Type	Description
error_code	int32_t	0 for success, non-zero for errors
error_message	std::string	Human-readable error description
Ok()	bool	Returns true if operation succeeded (error_code == 0)

Configuration

Field	Type	Default	Description
bootstrap_servers	std::string	"127.0.0.1:9123"	Coordinator server address
writer_request_max_size	int32_t	10485760 (10 MB)	Maximum request size in bytes
writer_acks	std::string	"all"	Acknowledgment setting ("all", "0", "1", or "-1")
writer_retries	int32_t	INT32_MAX	Number of retries on failure
writer_batch_size	int32_t	2097152 (2 MB)	Batch size for writes in bytes. Upper bound when dynamic sizing is on; fixed batch size when off
writer_dynamic_batch_size_enabled	bool	true	Enable per-table dynamic batch sizing: target grows 10% above 80% fill, shrinks 5% below 50%
writer_dynamic_batch_size_min	int32_t	262144 (256 KB)	Lower bound for the dynamic batch size estimator (ignored when disabled)
writer_batch_timeout_ms	int64_t	100	Maximum time in ms to wait for a writer batch to fill up before sending
writer_bucket_no_key_assigner	std::string	"sticky"	Bucket assignment strategy for tables without bucket keys: "sticky" or "round_robin"
scanner_remote_log_prefetch_num	size_t	4	Number of remote log segments to prefetch
remote_file_download_thread_num	size_t	3	Number of threads for remote log downloads
scanner_remote_log_read_concurrency	size_t	4	Streaming read concurrency within a remote log file
scanner_log_max_poll_records	size_t	500	Maximum number of records returned in a single Poll()
scanner_log_fetch_max_bytes	int32_t	16777216 (16 MB)	Maximum bytes per fetch response for LogScanner
scanner_log_fetch_min_bytes	int32_t	1	Minimum bytes the server must accumulate before returning a fetch response
scanner_log_fetch_wait_max_time_ms	int32_t	500	Maximum time (ms) the server may wait to satisfy min-bytes
scanner_log_fetch_max_bytes_for_bucket	int32_t	1048576 (1 MB)	Maximum bytes per fetch response per bucket for LogScanner
connect_timeout_ms	uint64_t	120000	TCP connect timeout in milliseconds
security_protocol	std::string	"PLAINTEXT"	"PLAINTEXT" (default) or "sasl" for SASL auth
security_sasl_mechanism	std::string	"PLAIN"	SASL mechanism (only "PLAIN" is supported)
security_sasl_username	std::string	(empty)	SASL username (required when protocol is "sasl")
security_sasl_password	std::string	(empty)	SASL password (required when protocol is "sasl")

Connection

Method	Description
static Create(const Configuration& config, Connection& out) -> Result	Create a connection to a Fluss cluster
GetAdmin(Admin& out) -> Result	Get the admin interface
GetTable(const TablePath& table_path, Table& out) -> Result	Get a table for read/write operations
Available() -> bool	Check if the connection is valid and initialized

Admin

Database Operations

Method	Description
CreateDatabase(const std::string& database_name, const DatabaseDescriptor& descriptor, bool ignore_if_exists) -> Result	Create a database
DropDatabase(const std::string& name, bool ignore_if_not_exists, bool cascade) -> Result	Drop a database
ListDatabases(std::vector<std::string>& out) -> Result	List all databases
DatabaseExists(const std::string& name, bool& out) -> Result	Check if a database exists
GetDatabaseInfo(const std::string& name, DatabaseInfo& out) -> Result	Get database metadata

Table Operations

Method	Description
CreateTable(const TablePath& path, const TableDescriptor& descriptor, bool ignore_if_exists) -> Result	Create a table
DropTable(const TablePath& path, bool ignore_if_not_exists) -> Result	Drop a table
GetTableInfo(const TablePath& path, TableInfo& out) -> Result	Get table metadata
ListTables(const std::string& database_name, std::vector<std::string>& out) -> Result	List tables in a database
TableExists(const TablePath& path, bool& out) -> Result	Check if a table exists

Partition Operations

Method	Description
CreatePartition(const TablePath& path, const std::unordered_map<std::string, std::string>& partition_spec, bool ignore_if_exists) -> Result	Create a partition
DropPartition(const TablePath& path, const std::unordered_map<std::string, std::string>& partition_spec, bool ignore_if_not_exists) -> Result	Drop a partition
ListPartitionInfos(const TablePath& path, std::vector<PartitionInfo>& out) -> Result	List partition metadata

Offset Operations

Method	Description
ListOffsets(const TablePath& path, const std::vector<int32_t>& bucket_ids, const OffsetSpec& query, std::unordered_map<int32_t, int64_t>& out) -> Result	Get offsets for buckets
ListPartitionOffsets(const TablePath& path, const std::string& partition_name, const std::vector<int32_t>& bucket_ids, const OffsetSpec& query, std::unordered_map<int32_t, int64_t>& out) -> Result	Get offsets for a partition's buckets

Lake Operations

Method	Description
GetLatestLakeSnapshot(const TablePath& path, LakeSnapshot& out) -> Result	Get the latest lake snapshot

Cluster Operations

Method	Description
GetServerNodes(std::vector<ServerNode>& out) -> Result	Get all alive server nodes (coordinator + tablets)

ServerNode

Field	Type	Description
id	int32_t	Server node ID
host	std::string	Hostname of the server
port	uint32_t	Port number
server_type	std::string	Server type ("CoordinatorServer", "TabletServer", or "Unknown")
uid	std::string	Unique identifier (e.g. "cs-0", "ts-1")

"Unknown" is used when the client has not yet determined the endpoint type, such as bootstrap endpoints.

Table

Method	Description
NewRow() -> GenericRow	Create a schema-aware row for this table
NewAppend() -> TableAppend	Create an append builder for log tables
NewUpsert() -> TableUpsert	Create an upsert builder for PK tables
NewLookup() -> TableLookup	Create a lookup builder for PK tables
NewPrefixLookup(std::vector<std::string> cols, PrefixLookuper& out) -> Result	Create a prefix (bucket-key) lookuper
NewScan() -> TableScan	Create a scan builder
GetTableInfo() -> TableInfo	Get table metadata
GetArrowSchema(std::shared_ptr<arrow::Schema>& out) -> Result	The Arrow schema AppendArrowBatch expects
GetTablePath() -> TablePath	Get the table path
HasPrimaryKey() -> bool	Check if the table has a primary key

TableAppend

Method	Description
CreateWriter(AppendWriter& out) -> Result	Create an append writer

TableUpsert

Method	Description
PartialUpdateByIndex(std::vector<size_t> column_indices) -> TableUpsert&	Configure partial update by column indices
PartialUpdateByName(std::vector<std::string> column_names) -> TableUpsert&	Configure partial update by column names
CreateWriter(UpsertWriter& out) -> Result	Create an upsert writer

TableLookup

Method	Description
CreateLookuper(Lookuper& out) -> Result	Create a lookuper for point lookups

TableScan

Method	Description
ProjectByIndex(std::vector<size_t> column_indices) -> TableScan&	Project columns by index
ProjectByName(std::vector<std::string> column_names) -> TableScan&	Project columns by name
Limit(int32_t row_number) -> TableScan&	Set a positive row limit (enables CreateBucketBatchScanner; rejected by log scanners)
CreateLogScanner(LogScanner& out) -> Result	Create a record-based log scanner; on a primary-key table, subscribes to its CDC changelog (per-record change_type)
CreateRecordBatchLogScanner(LogScanner& out) -> Result	Create an Arrow RecordBatch-based log scanner (log tables only — no per-record change types)
CreateBucketBatchScanner(const TableBucket& bucket, BatchScanner& out) -> Result	Bounded scan of one bucket (requires Limit)

AppendWriter

Method	Description
Append(const GenericRow& row) -> Result	Append a row (fire-and-forget)
Append(const GenericRow& row, WriteResult& out) -> Result	Append a row with write acknowledgment
Flush() -> Result	Flush all pending writes

UpsertWriter

Method	Description
Upsert(const GenericRow& row) -> Result	Upsert a row (fire-and-forget)
Upsert(const GenericRow& row, WriteResult& out) -> Result	Upsert a row with write acknowledgment
Delete(const GenericRow& row) -> Result	Delete a row by primary key (fire-and-forget)
Delete(const GenericRow& row, WriteResult& out) -> Result	Delete a row with write acknowledgment
Flush() -> Result	Flush all pending operations

WriteResult

Method	Description
Wait() -> Result	Wait for server acknowledgment of the write

Lookuper

Method	Description
Lookup(const GenericRow& pk_row, LookupResult& out) -> Result	Lookup a row by primary key

PrefixLookuper

Performs prefix (bucket-key) lookups, returning all rows whose primary key starts with the given prefix. Obtained from Table::NewPrefixLookup(). See the Prefix Lookup example.

Method	Description
PrefixLookup(const GenericRow& prefix_row, PrefixLookupResult& out) -> Result	Look up all rows matching the prefix columns

LogScanner

Method	Description
Subscribe(int32_t bucket_id, int64_t offset) -> Result	Subscribe to a single bucket at an offset
Subscribe(const std::vector<BucketSubscription>& bucket_offsets) -> Result	Subscribe to multiple buckets
SubscribePartitionBuckets(int64_t partition_id, int32_t bucket_id, int64_t start_offset) -> Result	Subscribe to a single partition bucket
SubscribePartitionBuckets(const std::vector<PartitionBucketSubscription>& subscriptions) -> Result	Subscribe to multiple partition buckets
Unsubscribe(int32_t bucket_id) -> Result	Unsubscribe from a non-partitioned bucket
UnsubscribePartition(int64_t partition_id, int32_t bucket_id) -> Result	Unsubscribe from a partition bucket
Poll(int64_t timeout_ms, ScanRecords& out) -> Result	Poll individual records
PollRecordBatch(int64_t timeout_ms, ArrowRecordBatches& out) -> Result	Poll Arrow RecordBatches

BatchScanner

One-shot bounded scan of a single bucket. Obtained from TableScan::CreateBucketBatchScanner(). The scan runs on the first call below, yields its single batch once, then is spent.

Method	Description
NextBatch(ArrowRecordBatches& out) -> Result	Run the scan; returns the batch once, then empty
CollectAllBatches(ArrowRecordBatches& out) -> Result	Drain the scanner into all of its batches

GenericRow

GenericRow is a write-only row used for append, upsert, delete, and lookup key construction. For reading field values from scan or lookup results, see RowView and LookupResult.

Index-Based Setters

Method	Description
SetNull(size_t idx)	Set field to null
SetBool(size_t idx, bool value)	Set boolean value
SetInt32(size_t idx, int32_t value)	Set 32-bit integer
SetInt64(size_t idx, int64_t value)	Set 64-bit integer
SetFloat32(size_t idx, float value)	Set 32-bit float
SetFloat64(size_t idx, double value)	Set 64-bit float
SetString(size_t idx, const std::string& value)	Set string value
SetBytes(size_t idx, const std::vector<uint8_t>& value)	Set binary data
SetDate(size_t idx, const Date& value)	Set date value
SetTime(size_t idx, const Time& value)	Set time value
SetTimestampNtz(size_t idx, const Timestamp& value)	Set timestamp without timezone
SetTimestampLtz(size_t idx, const Timestamp& value)	Set timestamp with timezone
SetDecimal(size_t idx, const std::string& value)	Set decimal from string
SetArray(size_t idx, ArrayWriter&& writer)	Set array value (consumes the writer)
SetMap(size_t idx, MapWriter&& writer)	Set map value (consumes the writer)
SetRow(size_t idx, GenericRow&& nested)	Set ROW value from a nested row (consumes it)

Name-Based Setters

When using table.NewRow(), the Set() method auto-routes to the correct type based on the schema:

Method	Description
Set(const std::string& name, std::nullptr_t)	Set field to null by column name
Set(const std::string& name, bool value)	Set boolean by column name
Set(const std::string& name, int32_t value)	Set integer by column name
Set(const std::string& name, int64_t value)	Set big integer by column name
Set(const std::string& name, float value)	Set float by column name
Set(const std::string& name, double value)	Set double by column name
Set(const std::string& name, const std::string& value)	Set string/decimal by column name
Set(const std::string& name, const Date& value)	Set date by column name
Set(const std::string& name, const Time& value)	Set time by column name
Set(const std::string& name, const Timestamp& value)	Set timestamp by column name
Set(const std::string& name, ArrayWriter&& writer)	Set array value by column name
Set(const std::string& name, MapWriter&& writer)	Set map value by column name
Set(const std::string& name, GenericRow&& nested)	Set ROW value by column name

RowView

Read-only row view for scan results. Provides zero-copy access to string and bytes data. RowView shares ownership of the underlying scan data via reference counting, so it can safely outlive the ScanRecords that produced it.

string_view Lifetime

GetString() returns std::string_view that borrows from the underlying data. The string_view is valid as long as any RowView (or ScanRecord) referencing the same poll result is alive. Copy to std::string if you need the value after all references are gone.

Index-Based Getters

Method	Description
FieldCount() -> size_t	Get the number of fields
GetType(size_t idx) -> TypeId	Get the type at index
IsNull(size_t idx) -> bool	Check if field is null
GetBool(size_t idx) -> bool	Get boolean value at index
GetInt32(size_t idx) -> int32_t	Get 32-bit integer at index
GetInt64(size_t idx) -> int64_t	Get 64-bit integer at index
GetFloat32(size_t idx) -> float	Get 32-bit float at index
GetFloat64(size_t idx) -> double	Get 64-bit float at index
GetString(size_t idx) -> std::string_view	Get string at index (zero-copy)
GetBytes(size_t idx) -> std::pair<const uint8_t*, size_t>	Get binary data at index (zero-copy)
GetDate(size_t idx) -> Date	Get date at index
GetTime(size_t idx) -> Time	Get time at index
GetTimestamp(size_t idx) -> Timestamp	Get timestamp at index
IsDecimal(size_t idx) -> bool	Check if field is a decimal type
GetDecimalString(size_t idx) -> std::string	Get decimal as string at index

Complex Getters (ARRAY / MAP / ROW)

Method	Description
GetValue(size_t idx) -> Value	Get a complex column as a recursive Value handle
GetValue(const std::string& name) -> Value	Same, by column name

Navigate the returned Value with At / KeyAt / ValueAt / Field and read leaves with its Get*() methods.

Name-Based Getters

Method	Description
IsNull(const std::string& name) -> bool	Check if field is null by name
GetBool(const std::string& name) -> bool	Get boolean by column name
GetInt32(const std::string& name) -> int32_t	Get 32-bit integer by column name
GetInt64(const std::string& name) -> int64_t	Get 64-bit integer by column name
GetFloat32(const std::string& name) -> float	Get 32-bit float by column name
GetFloat64(const std::string& name) -> double	Get 64-bit float by column name
GetString(const std::string& name) -> std::string_view	Get string by column name
GetBytes(const std::string& name) -> std::pair<const uint8_t*, size_t>	Get binary data by column name
GetDate(const std::string& name) -> Date	Get date by column name
GetTime(const std::string& name) -> Time	Get time by column name
GetTimestamp(const std::string& name) -> Timestamp	Get timestamp by column name
GetDecimalString(const std::string& name) -> std::string	Get decimal as string by column name

ScanRecord

ScanRecord is a value type that can be freely copied, stored, and accumulated across multiple Poll() calls. It shares ownership of the underlying scan data via reference counting.

Field	Type	Description
offset	int64_t	Record offset in the log
timestamp	int64_t	Record timestamp
change_type	ChangeType	Change type (AppendOnly, Insert, UpdateBefore, UpdateAfter, Delete)
row	RowView	Row data (value type, shares ownership via reference counting)

ScanRecords

Flat Access

Method	Description
Count() -> size_t	Total number of records across all buckets
IsEmpty() -> bool	Check if empty
begin() / end()	Iterator support for range-based for loops

Flat iteration over all records (regardless of bucket):

for (const auto& rec : records) {
    std::cout << "offset=" << rec.offset << std::endl;
}

Per-Bucket Access

Method	Description
BucketCount() -> size_t	Number of distinct buckets
Buckets() -> std::vector<TableBucket>	List of distinct buckets
Records(const TableBucket& bucket) -> BucketRecords	Records for a specific bucket (empty if bucket not present)
BucketAt(size_t idx) -> BucketRecords	Records by bucket index (0-based, O(1))

BucketRecords

A bundle of scan records belonging to a single bucket. Obtained from ScanRecords::Records() or ScanRecords::BucketAt(). BucketRecords is a value type — it shares ownership of the underlying scan data via reference counting, so it can safely outlive the ScanRecords that produced it.

Method	Description
Size() -> size_t	Number of records in this bucket
Empty() -> bool	Check if empty
Bucket() -> const TableBucket&	Get the bucket
operator[](size_t idx) -> ScanRecord	Access record by index within this bucket
begin() / end()	Iterator support for range-based for loops

TableBucket

Field / Method	Description
table_id -> int64_t	Table ID
bucket_id -> int32_t	Bucket ID
partition_id -> std::optional<int64_t>	Partition ID (empty if non-partitioned)
operator==(const TableBucket&) -> bool	Equality comparison

LookupResult

Read-only result for lookup operations. Provides zero-copy access to field values.

Metadata

Method	Description
Found() -> bool	Whether a matching row was found
FieldCount() -> size_t	Get the number of fields

Index-Based Getters

Method	Description
GetType(size_t idx) -> TypeId	Get the type at index
IsNull(size_t idx) -> bool	Check if field is null
GetBool(size_t idx) -> bool	Get boolean value at index
GetInt32(size_t idx) -> int32_t	Get 32-bit integer at index
GetInt64(size_t idx) -> int64_t	Get 64-bit integer at index
GetFloat32(size_t idx) -> float	Get 32-bit float at index
GetFloat64(size_t idx) -> double	Get 64-bit float at index
GetString(size_t idx) -> std::string_view	Get string at index (zero-copy)
GetBytes(size_t idx) -> std::pair<const uint8_t*, size_t>	Get binary data at index (zero-copy)
GetDate(size_t idx) -> Date	Get date at index
GetTime(size_t idx) -> Time	Get time at index
GetTimestamp(size_t idx) -> Timestamp	Get timestamp at index
IsDecimal(size_t idx) -> bool	Check if field is a decimal type
GetDecimalString(size_t idx) -> std::string	Get decimal as string at index

Complex Getters (ARRAY / MAP / ROW)

GetValue(size_t idx) -> Value and GetValue(const std::string& name) -> Value, same as on RowView. Navigate the returned Value.

Name-Based Getters

Method	Description
IsNull(const std::string& name) -> bool	Check if field is null by name
GetBool(const std::string& name) -> bool	Get boolean by column name
GetInt32(const std::string& name) -> int32_t	Get 32-bit integer by column name
GetInt64(const std::string& name) -> int64_t	Get 64-bit integer by column name
GetFloat32(const std::string& name) -> float	Get 32-bit float by column name
GetFloat64(const std::string& name) -> double	Get 64-bit float by column name
GetString(const std::string& name) -> std::string_view	Get string by column name
GetBytes(const std::string& name) -> std::pair<const uint8_t*, size_t>	Get binary data by column name
GetDate(const std::string& name) -> Date	Get date by column name
GetTime(const std::string& name) -> Time	Get time by column name
GetTimestamp(const std::string& name) -> Timestamp	Get timestamp by column name
GetDecimalString(const std::string& name) -> std::string	Get decimal as string by column name

PrefixLookupResult

Read-only result of a prefix lookup — zero or more matched rows. Each row is a PrefixRowView exposing the same scalar getters as RowView (index- and name-based) plus GetValue(...) for complex (ARRAY / MAP / ROW) columns.

Method	Description
Size() -> size_t	Number of matched rows
IsEmpty() -> bool	Whether the result has no rows
GetRow(size_t index) -> PrefixRowView	Get the row at index (throws if out of range)

ArrowRecordBatch

Method	Description
GetArrowRecordBatch() -> std::shared_ptr<arrow::RecordBatch>	Get the underlying Arrow RecordBatch
Available() -> bool	Check if the batch is valid
NumRows() -> int64_t	Number of rows in the batch
GetTableId() -> int64_t	Table ID
GetPartitionId() -> int64_t	Partition ID
GetBucketId() -> int32_t	Bucket ID
GetBaseOffset() -> int64_t	First record offset
GetLastOffset() -> int64_t	Last record offset

ArrowRecordBatches

Method	Description
Size() -> size_t	Number of batches
Empty() -> bool	Check if empty
operator[](size_t idx)	Access batch by index
begin() / end()	Iterator support for range-based for loops

Schema

Method	Description
NewBuilder() -> Schema::Builder	Create a new schema builder
FromArrow(std::shared_ptr<arrow::Schema> schema, std::vector<std::string> primary_keys = {}) -> Schema	Build a schema from an existing Arrow schema (escape hatch; prefer DataType::Map / DataType::Row)

Schema::Builder

Method	Description
AddColumn(const std::string& name, const DataType& type) -> Builder&	Add a column
SetPrimaryKeys(const std::vector<std::string>& keys) -> Builder&	Set primary key columns
SetAutoIncrementColumn(std::string column) -> Builder&	Set the auto increment column. Must be an INT or BIGINT column of a primary-key table, and not a primary-key column itself.
Build() -> Schema	Build the schema

TableDescriptor

Method	Description
NewBuilder() -> TableDescriptor::Builder	Create a new table descriptor builder

TableDescriptor::Builder

Method	Description
SetSchema(const Schema& schema) -> Builder&	Set the table schema
SetPartitionKeys(const std::vector<std::string>& keys) -> Builder&	Set partition key columns
SetBucketCount(int32_t count) -> Builder&	Set the number of buckets
SetBucketKeys(const std::vector<std::string>& keys) -> Builder&	Set bucket key columns
SetProperty(const std::string& key, const std::string& value) -> Builder&	Set a table property
SetCustomProperty(const std::string& key, const std::string& value) -> Builder&	Set a custom property
SetComment(const std::string& comment) -> Builder&	Set a table comment
Build() -> TableDescriptor	Build the table descriptor

DataType

Factory Methods

Method	Description
DataType::Boolean()	Boolean type
DataType::TinyInt()	8-bit signed integer
DataType::SmallInt()	16-bit signed integer
DataType::Int()	32-bit signed integer
DataType::BigInt()	64-bit signed integer
DataType::Float()	32-bit floating point
DataType::Double()	64-bit floating point
DataType::String()	UTF-8 string
DataType::Bytes()	Binary data
DataType::Date()	Date (days since epoch)
DataType::Time()	Time (milliseconds since midnight)
DataType::Timestamp(int precision)	Timestamp without timezone
DataType::TimestampLtz(int precision)	Timestamp with timezone
DataType::Decimal(int precision, int scale)	Decimal with precision and scale
DataType::Array(DataType element)	Array of the given element type
DataType::Map(DataType key, DataType value)	Map of key/value types (either may be complex)
DataType::Row(std::vector<std::pair<std::string, DataType>> fields)	Row of named fields (types may be complex)

MAP / ROW (and arrays nesting them) compose to any depth; the binding lowers them to Arrow internally when the table is created or a writer is built.

Accessors

Method	Description
id() -> TypeId	Get the type ID
precision() -> int	Get precision (for Decimal/Timestamp types)
scale() -> int	Get scale (for Decimal type)
nullable() -> bool	Returns true if this type is nullable (default), false if NOT NULL
element_type() -> const DataType*	Get element type (for Array type, nullptr otherwise)
key_type() / value_type() -> const DataType*	MAP key / value types (nullptr otherwise)
field_count() -> size_t	ROW field count (0 otherwise)
field_name(size_t i) -> const std::string&	ROW field name at i
field_type(size_t i) -> const DataType*	ROW field type at i
NotNull() -> DataType	Returns a copy of this type with nullable set to false

ArrayWriter

Write-only builder for array column values. Constructed with a fixed size and element type, then populated element-by-element. Move-only — consumed by GenericRow::SetArray() or ArrayWriter::SetArray() for nested arrays. For arrays whose element is a ROW / MAP, construct from an Arrow element type (arrow::struct_(...) / arrow::map(...)).

Method	Description
ArrayWriter(size_t size, DataType element_type)	Create an array writer; element may be complex (DataType::Map/Row)
ArrayWriter(size_t size, std::shared_ptr<arrow::DataType> element_type)	Arrow escape hatch for the element type
SetNull(size_t idx)	Set element to null
SetBool(size_t idx, bool value)	Set boolean element
SetInt32(size_t idx, int32_t value)	Set 32-bit integer element
SetInt64(size_t idx, int64_t value)	Set 64-bit integer element
SetFloat32(size_t idx, float value)	Set 32-bit float element
SetFloat64(size_t idx, double value)	Set 64-bit float element
SetString(size_t idx, const std::string& value)	Set string element
SetBytes(size_t idx, const std::vector<uint8_t>& value)	Set binary element
SetDate(size_t idx, const Date& value)	Set date element
SetTime(size_t idx, const Time& value)	Set time element
SetTimestampNtz(size_t idx, const Timestamp& value)	Set timestamp without timezone element
SetTimestampLtz(size_t idx, const Timestamp& value)	Set timestamp with timezone element
SetDecimal(size_t idx, const std::string& value)	Set decimal element from string
SetArray(size_t idx, ArrayWriter&& nested)	Set nested array element (consumes nested)
SetRow(size_t idx, GenericRow&& row)	Set ROW element (consumes the row)
SetMap(size_t idx, MapWriter&& map)	Set MAP element (consumes the map)

MapWriter

Write-only builder for map column values. Construct with the key/value types, then for each entry set the key and value and call Commit(). Keys cannot be null; an unset value defaults to null. Move-only — consumed by GenericRow::SetMap(), ArrayWriter::SetMap(), and MapWriter::SetValueMap(). For a key/value that is itself a ROW / MAP / ARRAY, construct from Arrow types and use the SetValue{Row,Map,Array} setters.

Method	Description
MapWriter(size_t capacity, DataType key_type, DataType value_type)	Create a map writer; key/value may be complex (DataType::Map/Row/Array)
MapWriter(size_t capacity, std::shared_ptr<arrow::DataType> key_type, std::shared_ptr<arrow::DataType> value_type)	Arrow escape hatch for key/value types
SetKey{Bool,Int32,Int64,Float32,Float64,String,Bytes,Date,Time,Timestamp,Decimal}(...)	Stage the entry key (NTZ vs LTZ chosen from the declared key type)
SetValueNull()	Stage a null entry value
SetValue{Bool,Int32,Int64,Float32,Float64,String,Bytes,Date,Time,Timestamp,Decimal}(...)	Stage the entry value (NTZ vs LTZ from the declared value type)
SetValueRow(GenericRow&&) / SetValueMap(MapWriter&&) / SetValueArray(ArrayWriter&&)	Stage a compound entry value (consumes the writer)
Commit()	Append the staged key/value as one map entry

Value

Read-only handle for a complex (ARRAY / MAP / ROW) column value, obtained from RowView::GetValue(), LookupResult::GetValue(), or PrefixRowView::GetValue(). Navigate to children with At / KeyAt / ValueAt / Field (each returns a child Value); read a leaf with the Get*() methods. A typed read on a null or wrong-typed value throws. Move-only; owns a Rust handle released on destruction.

Leaf reads

Method	Description
Type() -> TypeId	Type of this value
IsNull() -> bool	Whether this value is null
GetBool() -> bool	Read a boolean leaf
GetInt32() -> int32_t	Read a 32-bit integer leaf
GetInt64() -> int64_t	Read a 64-bit integer leaf
GetFloat32() -> float	Read a 32-bit float leaf
GetFloat64() -> double	Read a 64-bit float leaf
GetString() -> std::string	Read a string leaf
GetBytes() -> std::vector<uint8_t>	Read a binary leaf
GetDate() -> Date	Read a date leaf
GetTime() -> Time	Read a time leaf
GetTimestamp() -> Timestamp	Read a timestamp leaf
GetDecimalString() -> std::string	Read a decimal leaf as string

Navigation

Method	Description
Size() -> size_t	Element count (ARRAY) / entries (MAP)
FieldCount() -> size_t	Field count (ROW)
At(size_t i) -> Value	ARRAY element i
KeyAt(size_t i) -> Value	MAP key at entry i
ValueAt(size_t i) -> Value	MAP value at entry i
Field(size_t i) -> Value	ROW field i
Field(const std::string& name) -> Value	ROW field by name

TablePath

Method / Field	Description
TablePath(const std::string& database, const std::string& table)	Create a table path
database_name -> std::string	Database name
table_name -> std::string	Table name
ToString() -> std::string	String representation

TableInfo

Field	Type	Description
table_id	int64_t	Table ID
schema_id	int32_t	Schema ID
table_path	TablePath	Table path
created_time	int64_t	Creation timestamp
modified_time	int64_t	Last modification timestamp
primary_keys	std::vector<std::string>	Primary key columns
bucket_keys	std::vector<std::string>	Bucket key columns
partition_keys	std::vector<std::string>	Partition key columns
num_buckets	int32_t	Number of buckets
has_primary_key	bool	Whether the table has a primary key
is_partitioned	bool	Whether the table is partitioned
properties	std::unordered_map<std::string, std::string>	Table properties
custom_properties	std::unordered_map<std::string, std::string>	Custom properties
comment	std::string	Table comment
schema	Schema	Table schema

Temporal Types

Date

Method	Description
Date::FromDays(int32_t days)	Create from days since epoch
Date::FromYMD(int year, int month, int day)	Create from year, month, day
Year() -> int	Get year
Month() -> int	Get month
Day() -> int	Get day

Time

Method	Description
Time::FromMillis(int32_t millis)	Create from milliseconds since midnight
Time::FromHMS(int hour, int minute, int second)	Create from hour, minute, second
Hour() -> int	Get hour
Minute() -> int	Get minute
Second() -> int	Get second
Millis() -> int64_t	Get sub-second millisecond component (0-999)

Timestamp

Method	Description
Timestamp::FromMillis(int64_t millis)	Create from milliseconds since epoch
Timestamp::FromMillisNanos(int64_t millis, int32_t nanos)	Create from milliseconds and nanoseconds
Timestamp::FromTimePoint(std::chrono::system_clock::time_point tp)	Create from a time point

PartitionInfo

Field	Type	Description
partition_id	int64_t	Partition ID
partition_name	std::string	Partition name

DatabaseDescriptor

Field	Type	Description
comment	std::string	Database comment
properties	std::unordered_map<std::string, std::string>	Custom properties

DatabaseInfo

Field	Type	Description
database_name	std::string	Database name
comment	std::string	Database comment
properties	std::unordered_map<std::string, std::string>	Custom properties
created_time	int64_t	Creation timestamp
modified_time	int64_t	Last modification timestamp

LakeSnapshot

Field	Type	Description
snapshot_id	int64_t	Snapshot ID
bucket_offsets	std::vector<BucketOffset>	All bucket offsets

BucketOffset

Field	Type	Description
table_id	int64_t	Table ID
partition_id	int64_t	Partition ID
bucket_id	int32_t	Bucket ID
offset	int64_t	Offset value

OffsetSpec

Method	Description
OffsetSpec::Earliest()	Query for the earliest available offset
OffsetSpec::Latest()	Query for the latest offset
OffsetSpec::Timestamp(int64_t timestamp_ms)	Query offset at a specific timestamp

Constants

Constant	Value	Description
fluss::EARLIEST_OFFSET	-2	Start reading from the earliest available offset

To start reading from the latest offset (only new records), resolve the current offset via ListOffsets before subscribing:

std::unordered_map<int32_t, int64_t> offsets;
admin.ListOffsets(table_path, {0}, fluss::OffsetSpec::Latest(), offsets);
scanner.Subscribe(0, offsets[0]);

Enums

ChangeType

Value	Short String	Description
AppendOnly	+A	Append-only record
Insert	+I	Inserted row
UpdateBefore	-U	Previous value of an updated row
UpdateAfter	+U	New value of an updated row
Delete	-D	Deleted row

You may refer to the following example to convert ChangeType enum to its short string representation.

inline const char* ChangeTypeShortString(ChangeType ct) {
    switch (ct) {
        case ChangeType::AppendOnly: return "+A";
        case ChangeType::Insert: return "+I";
        case ChangeType::UpdateBefore: return "-U";
        case ChangeType::UpdateAfter: return "+U";
        case ChangeType::Delete: return "-D";
    }
    throw std::invalid_argument("Unknown ChangeType");
}

TypeId

Value	Description
Boolean	Boolean type
TinyInt	8-bit signed integer
SmallInt	16-bit signed integer
Int	32-bit signed integer
BigInt	64-bit signed integer
Float	32-bit floating point
Double	64-bit floating point
String	UTF-8 string
Bytes	Binary data
Date	Date
Time	Time
Timestamp	Timestamp without timezone
TimestampLtz	Timestamp with timezone
Decimal	Decimal
Array	Array of elements
Map	Map of key/value pairs
Row	Row (struct) of fields

ChangeType

Value	Description
AppendOnly	Append-only record (log tables)
Insert	Inserted row (PK tables)
UpdateBefore	Row value before an update (PK tables)
UpdateAfter	Row value after an update (PK tables)
Delete	Deleted row (PK tables)

OffsetSpec

Value	Description
Earliest	Earliest available offset
Latest	Latest offset
Timestamp	Offset at a specific timestamp