This is an automated email from the ASF dual-hosted git repository.
yuxia pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fluss-rust.git
The following commit(s) were added to refs/heads/main by this push:
new 6740719 [doc] Update fluss-rust readme markdown (#415)
6740719 is described below
commit 6740719c30203e7f9a8b6e482a4e8454dce50238
Author: yuxia Luo <[email protected]>
AuthorDate: Fri Mar 20 16:20:58 2026 +0800
[doc] Update fluss-rust readme markdown (#415)
---
Cargo.toml | 4 +-
bindings/python/pyproject.toml | 2 +-
crates/fluss/Cargo.toml | 8 +-
crates/fluss/README.md | 110 +++++++++++++++++++++++----
website/docs/user-guide/rust/installation.md | 4 +-
5 files changed, 104 insertions(+), 24 deletions(-)
diff --git a/Cargo.toml b/Cargo.toml
index 77d7140..cd473e7 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -18,9 +18,8 @@
[workspace.package]
authors = ["Apache Fluss <[email protected]>"]
categories = ["api-bindings", "database"]
-description = "The rust implementation of fluss"
edition = "2024"
-homepage = "https://fluss.apache.org/";
+homepage = "https://clients.fluss.apache.org/";
license = "Apache-2.0"
repository = "https://github.com/apache/fluss-rust";
rust-version = "1.85"
@@ -36,7 +35,6 @@ fluss = { package = "fluss-rs", version = "0.1.0", path =
"crates/fluss", featur
tokio = { version = "1.44.2", features = ["full"] }
clap = { version = "4.5.37", features = ["derive"] }
arrow = { version = "57.0.0", features = ["ipc_compression"] }
-
bigdecimal = "0.4"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
diff --git a/bindings/python/pyproject.toml b/bindings/python/pyproject.toml
index 1664597..ce4c436 100644
--- a/bindings/python/pyproject.toml
+++ b/bindings/python/pyproject.toml
@@ -42,7 +42,7 @@ dependencies = [
]
[project.urls]
-Homepage = "https://clients.fluss.apache.org/";
+Homepage = "https://clients.fluss.apache.org/user-guide/rust/installation/";
Repository = "https://github.com/apache/fluss-rust";
[project.optional-dependencies]
diff --git a/crates/fluss/Cargo.toml b/crates/fluss/Cargo.toml
index c0ba6f8..7b68e51 100644
--- a/crates/fluss/Cargo.toml
+++ b/crates/fluss/Cargo.toml
@@ -22,10 +22,12 @@ rust-version = { workspace = true }
version = { workspace = true }
name = "fluss-rs"
authors = { workspace = true }
-description = { workspace = true }
-homepage = { workspace = true }
+description = "The official rust client of Apache Fluss (Incubating)"
+homepage = "https://clients.fluss.apache.org/user-guide/rust/installation/";
repository = { workspace = true }
keywords = { workspace = true }
+categories = { workspace = true }
+documentation = "https://docs.rs/fluss-rs";
[lib]
name = "fluss"
@@ -81,4 +83,4 @@ testcontainers = "0.25.0"
test-env-helpers = "0.2.2"
[build-dependencies]
-prost-build = { version = "0.14" }
+prost-build = "0.14"
diff --git a/crates/fluss/README.md b/crates/fluss/README.md
index aad8de9..b37a75d 100644
--- a/crates/fluss/README.md
+++ b/crates/fluss/README.md
@@ -1,25 +1,105 @@
-# Apache Fluss™ Rust Client (Incubating)
+# Apache Fluss (Incubating) Official Rust Client
-Rust client library for [Apache Fluss™](https://fluss.apache.org/). This crate
provides the core client used by the fluss-rust workspace and by the Python and
C++ bindings.
+Official Rust client library for [Apache Fluss
(Incubating)](https://fluss.apache.org/).
-# Todo: move how to use to the first, and how to build to the last,
https://github.com/apache/opendal/blob/main/core/README.md
-# is a good reference
+[](https://crates.io/crates/fluss-rs)
+[](https://docs.rs/fluss-rs/)
-## Requirements
+## Usage
-- Rust (see [rust-toolchain.toml](../../rust-toolchain.toml) at repo root)
-- protobuf (for build)
+The following example shows both **primary key (KV) tables** and **log
tables** in one flow: connect, create a KV table (upsert + lookup), then create
a log table (append + scan).
-## Build
+```rust
+use fluss::client::EARLIEST_OFFSET;
+use fluss::client::FlussConnection;
+use fluss::config::Config;
+use fluss::error::Result;
+use fluss::metadata::{DataTypes, Schema, TableDescriptor, TablePath};
+use fluss::row::{GenericRow, InternalRow};
+use std::time::Duration;
-From the repository root:
+#[tokio::main]
+async fn main() -> Result<()> {
+ let mut config = Config::default();
+ config.bootstrap_servers = "127.0.0.1:9123".to_string();
+ let connection = FlussConnection::new(config).await?;
+ let admin = connection.get_admin().await?;
-```bash
-cargo build -p fluss-rs
+ // ---- Primary key (KV) table: upsert and lookup ----
+ let kv_path = TablePath::new("fluss", "users");
+ let mut kv_schema = Schema::builder()
+ .column("id", DataTypes::int())
+ .column("name", DataTypes::string())
+ .column("age", DataTypes::bigint())
+ .primary_key(vec!["id"]);
+ let kv_descriptor = TableDescriptor::builder()
+ .schema(kv_schema.build()?)
+ .build()?;
+ admin.create_table(&kv_path, &kv_descriptor, false).await?;
+
+ let kv_table = connection.get_table(&kv_path).await?;
+ let upsert_writer = kv_table.new_upsert()?.create_writer()?;
+ let mut row = GenericRow::new(3);
+ row.set_field(0, 1i32);
+ row.set_field(1, "Alice");
+ row.set_field(2, 30i64);
+ upsert_writer.upsert(&row)?;
+ upsert_writer.flush().await?;
+
+ let mut lookuper = kv_table.new_lookup()?.create_lookuper()?;
+ let mut key = GenericRow::new(1);
+ key.set_field(0, 1i32);
+ let result = lookuper.lookup(&key).await?;
+ if let Some(r) = result.get_single_row()? {
+ println!("KV lookup: id={}, name={}, age={}",
+ r.get_int(0)?, r.get_string(1)?, r.get_long(2)?);
+ }
+
+ // ---- Log table: append and scan ----
+ let log_path = TablePath::new("fluss", "events");
+ let log_schema = Schema::builder()
+ .column("ts", DataTypes::bigint())
+ .column("message", DataTypes::string())
+ .build()?;
+ let log_descriptor = TableDescriptor::builder()
+ .schema(log_schema)
+ .build()?;
+ admin.create_table(&log_path, &log_descriptor, false).await?;
+
+ let log_table = connection.get_table(&log_path).await?;
+ let append_writer = log_table.new_append()?.create_writer()?;
+ let mut event = GenericRow::new(2);
+ event.set_field(0, 1700000000i64);
+ event.set_field(1, "hello");
+ append_writer.append(&event)?;
+ append_writer.flush().await?;
+
+ let scanner = log_table.new_scan().create_log_scanner()?;
+ scanner.subscribe(0, EARLIEST_OFFSET).await?;
+ let scan_records = scanner.poll(Duration::from_secs(1)).await?;
+ for record in scan_records {
+ let r = record.row();
+ println!("Log scan: ts={}, message={}", r.get_long(0)?,
r.get_string(1)?);
+ }
+
+ Ok(())
+}
```
-## Quick start and examples
+## Storage Support
+
+The Fluss client reads remote data by accessing Fluss’s **remote files** (e.g.
log segments and snapshots) directly. The following **remote file systems** are
supported; enable the matching feature(s) for your deployment:
+
+| Storage Backend | Feature Flag | Status | Description |
+|----------------|--------------|--------|-------------|
+| Local Filesystem | `storage-fs` | ✅ Stable | Local filesystem storage |
+| Amazon S3 | `storage-s3` | ✅ Stable | Amazon S3 storage |
+| Alibaba Cloud OSS | `storage-oss` | ✅ Stable | Alibaba Cloud Object Storage
Service |
-## TODO
-- [ ] Expand API documentation and usage examples in this README.
-- [ ] Add more examples for table, log scan, and write flows.
+You can enable all storage backends at once using the `storage-all` feature
flag.
+
+Example usage in Cargo.toml:
+```toml
+[dependencies]
+fluss-rs = { version = "0.x.x", features = ["storage-s3", "storage-fs"] }
+```
diff --git a/website/docs/user-guide/rust/installation.md
b/website/docs/user-guide/rust/installation.md
index e698783..540d4a1 100644
--- a/website/docs/user-guide/rust/installation.md
+++ b/website/docs/user-guide/rust/installation.md
@@ -7,7 +7,7 @@ The Fluss Rust client is published to
[crates.io](https://crates.io/crates/fluss
```toml
[dependencies]
-fluss-rs = "0.1"
+fluss-rs = "0.1.0"
tokio = { version = "1", features = ["full"] }
```
@@ -16,7 +16,7 @@ tokio = { version = "1", features = ["full"] }
```toml
[dependencies]
# Default: memory and filesystem storage
-fluss-rs = "0.1"
+fluss-rs = "0.1.0"
# With S3 storage support
fluss-rs = { version = "0.1", features = ["storage-s3"] }
