You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@paimon.apache.org by "JingsongLi (via GitHub)" <gi...@apache.org> on 2026/03/29 06:01:25 UTC
[PR] feat: Introduce docs for paimon-rust [paimon-rust]
JingsongLi opened a new pull request, #157:
URL: https://github.com/apache/paimon-rust/pull/157
<!--
Thank you very much for contributing to Paimon Rust - we are happy that you want to help us improve it. To help the community review your contribution in the best possible way, please go through the checklist below, which will get the contribution into a shape in which it can be best reviewed.
## Contribution Checklist
- Make sure that the pull request corresponds to a [GitHub issue](https://github.com/apache/paimon-rust/issues). Exceptions are made for typos in documentation or comments, which need no issue.
- Fill out the template below to describe the changes contributed by the pull request. That will give reviewers the context they need to do the review.
- Make sure that the change passes the automated tests, i.e., `cargo test` passes.
- Each pull request should address only one issue, not mix up code from multiple issues.
**(The sections below can be removed for hotfixes or typos)**
-->
### Purpose
<!-- Linking this pull request to the issue -->
Introduce docs.
<!-- What is the purpose of the change -->
### Brief change log
<!-- Please describe the changes made in this pull request and explain how they address the issue -->
### Tests
<!-- List unit tests or integration cases to verify this change -->
### API and Format
<!-- Does this change affect API or storage format -->
### Documentation
<!-- Does this change introduce a new feature or require documentation updates -->
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@paimon.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Introduce docs for paimon-rust [paimon-rust]
Posted by "JingsongLi (via GitHub)" <gi...@apache.org>.
JingsongLi commented on code in PR #157:
URL: https://github.com/apache/paimon-rust/pull/157#discussion_r3005954672
##########
.asf.yaml:
##########
@@ -46,3 +46,8 @@ notifications:
commits: commits@paimon.apache.org
issues: issues@paimon.apache.org
pullrequests: issues@paimon.apache.org
+
+protected_branches:
+ main:
+ required_pull_request_reviews:
+ required_approving_review_count: 0
Review Comment:
Just test review override.
This setting makes merging cumbersome, as two committers must participate in order to merge the code.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@paimon.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Introduce docs for paimon-rust [paimon-rust]
Posted by "luoyuxia (via GitHub)" <gi...@apache.org>.
luoyuxia commented on code in PR #157:
URL: https://github.com/apache/paimon-rust/pull/157#discussion_r3005799838
##########
docs/src/getting-started.md:
##########
@@ -0,0 +1,178 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Getting Started
+
+## Installation
+
+Add `paimon` to your `Cargo.toml`:
+
+```toml
+[dependencies]
+paimon = "0.0.0"
+tokio = { version = "1", features = ["full"] }
+```
+
+By default, the `storage-fs` (local filesystem) and `storage-memory` (in-memory) backends are enabled. To use additional storage backends, enable the corresponding feature flags:
+
+```toml
+[dependencies]
+paimon = { version = "0.0.0", features = ["storage-s3"] }
+```
+
+Available storage features:
+
+| Feature | Backend |
+|------------------|------------------|
+| `storage-fs` | Local filesystem |
+| `storage-memory` | In-memory |
+| `storage-s3` | Amazon S3 |
+| `storage-oss` | Alibaba Cloud OSS|
+| `storage-all` | All of the above |
+
+## Catalog Management
+
+`FileSystemCatalog` manages databases and tables stored on a local (or remote) filesystem.
+
+### Create a Catalog
+
+```rust
+use paimon::FileSystemCatalog;
+
+let catalog = FileSystemCatalog::new("/tmp/paimon-warehouse")?;
+```
+
+### Manage Databases
+
+```rust
+use paimon::Catalog; // import the trait
+use std::collections::HashMap;
+
+// Create a database
+catalog.create_database("my_db", false, HashMap::new()).await?;
+
+// List databases
+let databases = catalog.list_databases().await?;
+
+// Drop a database (cascade = true to drop all tables inside)
+catalog.drop_database("my_db", false, true).await?;
+```
+
+### Manage Tables
+
+```rust
+use paimon::catalog::Identifier;
+use paimon::spec::{DataType, IntType, VarCharType, Schema};
+
+// Define a schema
+let schema = Schema::builder()
+ .column("id", DataType::Int(IntType::new()))
+ .column("name", DataType::VarChar(VarCharType::string_type()))
+ .build()?;
+
+// Create a table
+let identifier = Identifier::new("my_db", "my_table");
+catalog.create_table(&identifier, schema, false).await?;
+
+// List tables in a database
+let tables = catalog.list_tables("my_db").await?;
+
+// Get a table handle
+let table = catalog.get_table(&identifier).await?;
+```
+
+## Reading a Table
+
+Paimon Rust uses a scan-then-read pattern: first scan the table to produce splits, then read data from those splits as Arrow `RecordBatch` streams.
+
+```rust
+use futures::StreamExt;
+
+// Get a table from the catalog
+let table = catalog.get_table(&Identifier::new("my_db", "my_table")).await?;
+
+// Create a read builder
+let read_builder = table.new_read_builder();
+
+// Step 1: Scan — produces a Plan containing DataSplits
+let scan = read_builder.new_scan();
+let plan = scan.plan().await?;
+
+// Step 2: Read — consumes splits and returns Arrow RecordBatches
+let reader = read_builder.new_read()?;
+let mut stream = reader.to_arrow(plan.splits())?;
+
+while let Some(batch) = stream.next().await {
+ let batch = batch?;
+ println!("Got batch with {} rows", batch.num_rows());
Review Comment:
nit: may be print the record batch
```
println!("RecordBatch: {batch:#?}");
```
##########
docs/mkdocs.yml:
##########
@@ -0,0 +1,65 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+site_name: Apache Paimon Rust
+site_description: The Rust implementation of Apache Paimon
+site_url: https://paimon.apache.org/paimon-rust/
Review Comment:
seem it's not available now.
Another question is do we need a separate website to hold the docs just like cpp client `https://alibaba.github.io/paimon-cpp/index.html`
##########
docs/src/releases.md:
##########
@@ -0,0 +1,43 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Releases
+
+## Release Policy
+
+Apache Paimon Rust follows [Semantic Versioning](https://semver.org/). All releases are published to [crates.io](https://crates.io/crates/paimon).
+
+## Upcoming
+
+### 0.1.0 (In Development)
+
+The first release of Apache Paimon Rust. Track progress at the [0.1.0 milestone](https://github.com/apache/paimon-rust/issues/3).
+
+Planned features:
+
+- Paimon table format reader
+- Local filesystem and S3 storage backends
+- REST Catalog client
+- Apache DataFusion integration
+- Partitioned table support
+- C FFI bindings
Review Comment:
Also add go bindings?
##########
docs/src/releases.md:
##########
@@ -0,0 +1,43 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Releases
+
+## Release Policy
+
+Apache Paimon Rust follows [Semantic Versioning](https://semver.org/). All releases are published to [crates.io](https://crates.io/crates/paimon).
+
+## Upcoming
+
+### 0.1.0 (In Development)
+
+The first release of Apache Paimon Rust. Track progress at the [0.1.0 milestone](https://github.com/apache/paimon-rust/issues/3).
+
+Planned features:
+
+- Paimon table format reader
+- Local filesystem and S3 storage backends
Review Comment:
we also support oss
##########
docs/src/index.md:
##########
@@ -0,0 +1,48 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Apache Paimon Rust
+
+The Rust implementation of [Apache Paimon](https://paimon.apache.org/) — a streaming data lake platform with high-speed data ingestion, changelog tracking, and efficient real-time analytics.
+
+## Overview
+
+Apache Paimon Rust provides native Rust libraries for reading and writing Paimon tables, enabling high-performance data lake access from the Rust ecosystem.
+
+Key features:
+
+- Native Rust reader for Paimon table format
+- Support for local filesystem and S3 storage backends
Review Comment:
dito: we also support oss
##########
docs/src/architecture.md:
##########
@@ -0,0 +1,60 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Architecture
+
+## Overview
+
+Apache Paimon Rust is organized as a Cargo workspace with multiple crates, each responsible for a distinct layer of functionality.
+
+## Crate Structure
+
+### `crates/paimon` — Core Library
+
+The core crate implements the Paimon table format, including:
+
+- **Catalog** — REST Catalog client for discovering and managing databases and tables
Review Comment:
```suggestion
- **Catalog** — Catalog client for discovering and managing databases and tables
```
Since not only rest catalog, but also filesystem catalog
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@paimon.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Introduce docs for paimon-rust [paimon-rust]
Posted by "QuakeWang (via GitHub)" <gi...@apache.org>.
QuakeWang commented on code in PR #157:
URL: https://github.com/apache/paimon-rust/pull/157#discussion_r3005893050
##########
.asf.yaml:
##########
@@ -46,3 +46,8 @@ notifications:
commits: commits@paimon.apache.org
issues: issues@paimon.apache.org
pullrequests: issues@paimon.apache.org
+
+protected_branches:
+ main:
+ required_pull_request_reviews:
+ required_approving_review_count: 0
Review Comment:
```suggestion
required_approving_review_count: 1
```
I think this value is at least 1. Please verify this is the intended value before merging.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@paimon.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Introduce docs for paimon-rust [paimon-rust]
Posted by "JingsongLi (via GitHub)" <gi...@apache.org>.
JingsongLi closed pull request #157: feat: Introduce docs for paimon-rust
URL: https://github.com/apache/paimon-rust/pull/157
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@paimon.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Introduce docs for paimon-rust [paimon-rust]
Posted by "XiaoHongbo-Hope (via GitHub)" <gi...@apache.org>.
XiaoHongbo-Hope merged PR #157:
URL: https://github.com/apache/paimon-rust/pull/157
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@paimon.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Introduce docs for paimon-rust [paimon-rust]
Posted by "JingsongLi (via GitHub)" <gi...@apache.org>.
JingsongLi commented on code in PR #157:
URL: https://github.com/apache/paimon-rust/pull/157#discussion_r3005954672
##########
.asf.yaml:
##########
@@ -46,3 +46,8 @@ notifications:
commits: commits@paimon.apache.org
issues: issues@paimon.apache.org
pullrequests: issues@paimon.apache.org
+
+protected_branches:
+ main:
+ required_pull_request_reviews:
+ required_approving_review_count: 0
Review Comment:
Just test review override.
This setting makes merging cumbersome, as two Commitors must participate in order to merge the code.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@paimon.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Introduce docs for paimon-rust [paimon-rust]
Posted by "XiaoHongbo-Hope (via GitHub)" <gi...@apache.org>.
XiaoHongbo-Hope commented on PR #157:
URL: https://github.com/apache/paimon-rust/pull/157#issuecomment-4151839401
+1
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@paimon.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Introduce docs for paimon-rust [paimon-rust]
Posted by "QuakeWang (via GitHub)" <gi...@apache.org>.
QuakeWang commented on code in PR #157:
URL: https://github.com/apache/paimon-rust/pull/157#discussion_r3005794811
##########
docs/src/contributing.md:
##########
@@ -0,0 +1,62 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Contributing
+
+Apache Paimon Rust welcomes contributions from everyone. See the full [Contributing Guide](https://github.com/apache/paimon-rust/blob/main/CONTRIBUTING.md) for detailed instructions.
+
+## Quick Start
+
+1. Fork the [repository](https://github.com/apache/paimon-rust)
+2. Clone your fork: `git clone https://github.com/<your-username>/paimon-rust.git`
+3. Create a feature branch: `git checkout -b feature/my-feature`
+4. Make your changes and add tests
+5. Run checks locally before submitting
+6. Open a Pull Request
+
+## Development Setup
+
+```bash
+# Ensure you have the correct Rust toolchain
+rustup show
+
+# Build the project
+cargo build
+
+# Run all tests
+cargo test
+
+# Format code
+cargo fmt
+
+# Lint
+cargo clippy
Review Comment:
The project CI runs `cargo clippy --all-targets --workspace -- -D warnings`. Running `cargo clippy` locally without `-D warnings` may pass while CI fails, creating a confusing contributor experience. Please align this with the actual CI command.
##########
docs/README.md:
##########
@@ -0,0 +1,55 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Documentation
+
+This directory contains the source files for the Apache Paimon Rust documentation site, built with [MkDocs](https://www.mkdocs.org/) and the [Material for MkDocs](https://squidfun.github.io/mkdocs-material/) theme.
Review Comment:
```suggestion
This directory contains the source files for the Apache Paimon Rust documentation site, built with [MkDocs](https://www.mkdocs.org/) and the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme.
```
##########
docs/src/getting-started.md:
##########
@@ -0,0 +1,178 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Getting Started
+
+## Installation
+
+Add `paimon` to your `Cargo.toml`:
+
+```toml
+[dependencies]
+paimon = "0.0.0"
+tokio = { version = "1", features = ["full"] }
+```
+
+By default, the `storage-fs` (local filesystem) and `storage-memory` (in-memory) backends are enabled. To use additional storage backends, enable the corresponding feature flags:
+
+```toml
+[dependencies]
+paimon = { version = "0.0.0", features = ["storage-s3"] }
+```
+
+Available storage features:
+
+| Feature | Backend |
+|------------------|------------------|
+| `storage-fs` | Local filesystem |
+| `storage-memory` | In-memory |
+| `storage-s3` | Amazon S3 |
+| `storage-oss` | Alibaba Cloud OSS|
+| `storage-all` | All of the above |
+
+## Catalog Management
+
+`FileSystemCatalog` manages databases and tables stored on a local (or remote) filesystem.
+
+### Create a Catalog
+
+```rust
+use paimon::FileSystemCatalog;
+
+let catalog = FileSystemCatalog::new("/tmp/paimon-warehouse")?;
+```
+
+### Manage Databases
+
+```rust
+use paimon::Catalog; // import the trait
+use std::collections::HashMap;
+
+// Create a database
+catalog.create_database("my_db", false, HashMap::new()).await?;
+
+// List databases
+let databases = catalog.list_databases().await?;
+
+// Drop a database (cascade = true to drop all tables inside)
+catalog.drop_database("my_db", false, true).await?;
+```
+
+### Manage Tables
+
+```rust
+use paimon::catalog::Identifier;
+use paimon::spec::{DataType, IntType, VarCharType, Schema};
+
+// Define a schema
+let schema = Schema::builder()
+ .column("id", DataType::Int(IntType::new()))
+ .column("name", DataType::VarChar(VarCharType::string_type()))
+ .build()?;
+
+// Create a table
+let identifier = Identifier::new("my_db", "my_table");
+catalog.create_table(&identifier, schema, false).await?;
+
+// List tables in a database
+let tables = catalog.list_tables("my_db").await?;
+
+// Get a table handle
+let table = catalog.get_table(&identifier).await?;
+```
+
+## Reading a Table
+
+Paimon Rust uses a scan-then-read pattern: first scan the table to produce splits, then read data from those splits as Arrow `RecordBatch` streams.
+
+```rust
+use futures::StreamExt;
+
+// Get a table from the catalog
+let table = catalog.get_table(&Identifier::new("my_db", "my_table")).await?;
+
+// Create a read builder
+let read_builder = table.new_read_builder();
+
+// Step 1: Scan — produces a Plan containing DataSplits
+let scan = read_builder.new_scan();
+let plan = scan.plan().await?;
+
+// Step 2: Read — consumes splits and returns Arrow RecordBatches
+let reader = read_builder.new_read()?;
+let mut stream = reader.to_arrow(plan.splits())?;
+
+while let Some(batch) = stream.next().await {
+ let batch = batch?;
+ println!("Got batch with {} rows", batch.num_rows());
+}
+```
+
+## DataFusion Integration
+
+Query Paimon tables using SQL with [Apache DataFusion](https://datafusion.apache.org/). Add the integration crate:
+
+```toml
+[dependencies]
+paimon = "0.0.0"
+paimon-datafusion = "0.0.0"
+datafusion = "46"
Review Comment:
```suggestion
datafusion = "52"
```
The DataFusion version here is out of date. The integration crate currently depends on 52.3.0 — using "46" will cause API incompatibility at compile time. Please update to datafusion = "52".
##########
docs/src/getting-started.md:
##########
@@ -0,0 +1,178 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# Getting Started
+
+## Installation
+
+Add `paimon` to your `Cargo.toml`:
+
+```toml
+[dependencies]
+paimon = "0.0.0"
+tokio = { version = "1", features = ["full"] }
+```
+
+By default, the `storage-fs` (local filesystem) and `storage-memory` (in-memory) backends are enabled. To use additional storage backends, enable the corresponding feature flags:
+
+```toml
+[dependencies]
+paimon = { version = "0.0.0", features = ["storage-s3"] }
+```
+
+Available storage features:
+
+| Feature | Backend |
+|------------------|------------------|
+| `storage-fs` | Local filesystem |
+| `storage-memory` | In-memory |
+| `storage-s3` | Amazon S3 |
+| `storage-oss` | Alibaba Cloud OSS|
+| `storage-all` | All of the above |
+
+## Catalog Management
+
+`FileSystemCatalog` manages databases and tables stored on a local (or remote) filesystem.
+
+### Create a Catalog
+
+```rust
+use paimon::FileSystemCatalog;
+
+let catalog = FileSystemCatalog::new("/tmp/paimon-warehouse")?;
+```
+
+### Manage Databases
+
+```rust
+use paimon::Catalog; // import the trait
+use std::collections::HashMap;
+
+// Create a database
+catalog.create_database("my_db", false, HashMap::new()).await?;
+
+// List databases
+let databases = catalog.list_databases().await?;
+
+// Drop a database (cascade = true to drop all tables inside)
+catalog.drop_database("my_db", false, true).await?;
+```
+
+### Manage Tables
+
+```rust
+use paimon::catalog::Identifier;
+use paimon::spec::{DataType, IntType, VarCharType, Schema};
+
+// Define a schema
+let schema = Schema::builder()
+ .column("id", DataType::Int(IntType::new()))
+ .column("name", DataType::VarChar(VarCharType::string_type()))
+ .build()?;
+
+// Create a table
+let identifier = Identifier::new("my_db", "my_table");
+catalog.create_table(&identifier, schema, false).await?;
+
+// List tables in a database
+let tables = catalog.list_tables("my_db").await?;
+
+// Get a table handle
+let table = catalog.get_table(&identifier).await?;
+```
+
+## Reading a Table
+
+Paimon Rust uses a scan-then-read pattern: first scan the table to produce splits, then read data from those splits as Arrow `RecordBatch` streams.
+
+```rust
+use futures::StreamExt;
+
+// Get a table from the catalog
+let table = catalog.get_table(&Identifier::new("my_db", "my_table")).await?;
+
+// Create a read builder
+let read_builder = table.new_read_builder();
+
+// Step 1: Scan — produces a Plan containing DataSplits
+let scan = read_builder.new_scan();
Review Comment:
This example will not compile. `new_scan()` borrows `read_builder` immutably and the returned `TableScan<'a>` keeps that borrow alive as long as `scan` is in scope. Calling `read_builder.new_read()` on line 119 while `scan` still holds the borrow will be rejected by the borrow checker. Split the two phases into separate scopes:
```rust
// Scan phase — borrow ends when this block exits
let plan = {
let scan = read_builder.new_scan();
scan.plan().await?
};
// Read phase
let reader = read_builder.new_read()?;
let mut stream = reader.to_arrow(plan.splits())?;
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@paimon.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] feat: Introduce docs for paimon-rust [paimon-rust]
Posted by "JingsongLi (via GitHub)" <gi...@apache.org>.
JingsongLi commented on code in PR #157:
URL: https://github.com/apache/paimon-rust/pull/157#discussion_r3005804082
##########
docs/mkdocs.yml:
##########
@@ -0,0 +1,65 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+site_name: Apache Paimon Rust
+site_description: The Rust implementation of Apache Paimon
+site_url: https://paimon.apache.org/paimon-rust/
Review Comment:
I will add this in paimon-web project.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@paimon.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org