You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@fluss.apache.org by "xx789633 (via GitHub)" <gi...@apache.org> on 2025/08/25 10:08:19 UTC
[PR] [lake/lance] add documentation for Lance connector [fluss]
xx789633 opened a new pull request, #1587:
URL: https://github.com/apache/fluss/pull/1587
<!--
*Thank you very much for contributing to Fluss - we are happy that you want to help us improve Fluss. 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/alibaba/fluss/issues). Exceptions are made for typos in JavaDoc or documentation files, which need no issue.
- Name the pull request in the format "[component] Title of the pull request", where *[component]* should be replaced by the name of the component being changed. Typically, this corresponds to the component label assigned to the issue (e.g., [kv], [log], [client], [flink]). Skip *[component]* if you are unsure about which is the best component.
- 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., `mvn clean verify` 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 -->
Linked issue: close #1568
--
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@fluss.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [lake/lance] add documentation for Lance connector [fluss]
Posted by "leonardBang (via GitHub)" <gi...@apache.org>.
leonardBang commented on code in PR #1587:
URL: https://github.com/apache/fluss/pull/1587#discussion_r2329918501
##########
website/docs/streaming-lakehouse/integrate-data-lakes/lance.md:
##########
@@ -0,0 +1,124 @@
+---
+title: Lance
+sidebar_position: 3
+---
+
+# Lance
+
+[Lance](https://lancedb.github.io/lance/) is a modern table format optimized for machine learning and AI applications.
+To integrate Fluss with Lance, you must enable lakehouse storage and configure Lance as the lakehouse storage. For more details, see [Enable Lakehouse Storage](maintenance/tiered-storage/lakehouse-storage.md#enable-lakehouse-storage).
+
+## Configure Lance as LakeHouse Storage
+
+### Configure Lance in Cluster Configurations
+
+To configure Lance as the lakehouse storage, you must configure the following configurations in `server.yaml`:
+```yaml
+# Lance configuration
+datalake.format: lance
+
+# Currently only local file system and object stores such as AWS S3 (and compatible stores) are supported as storage backends for Lance
+# To use S3 as Lance storage backend, you need to specify the following properties
+datalake.lance.warehouse: s3://<bucket>
+datalake.lance.endpoint: <endpoint>
+datalake.lance.allow_http: true
+datalake.lance.access_key_id: <access_key_id>
+datalake.lance.secret_access_key: <secret_access_key>
+
+# Use local file system as Lance storage backend, you only need to specify the following property
+# datalake.lance.warehouse: /tmp/lance
+```
+
+When a table is created or altered with the option `'table.datalake.enabled' = 'true'`, Fluss will automatically create a corresponding Lance table with path `<warehouse_path>/<database_name>/<table_name>.lance`.
+The schema of the Lance table matches that of the Fluss table.
+
+```sql title="Flink SQL"
+USE CATALOG fluss_catalog;
+
+CREATE TABLE fluss_order_with_lake (
+ `order_id` BIGINT,
+ `item_id` BIGINT,
+ `amount` INT,
+ `address` STRING
+) WITH (
+ 'table.datalake.enabled' = 'true',
+ 'table.datalake.freshness' = '30s'
+);
+```
+
+### Start Tiering Service to Lance
+Then, you must start the datalake tiering service to tier Fluss's data to Lance. For guidance, you can refer to [Start The Datalake Tiering Service
+](maintenance/tiered-storage/lakehouse-storage.md#start-the-datalake-tiering-service). Although the example uses Paimon, the process is also applicable to Lance.
+
+But in [Prepare required jars](maintenance/tiered-storage/lakehouse-storage.md#prepare-required-jars) step, you should follow this guidance:
+- Put [fluss-flink connector jar](/downloads) into `${FLINK_HOME}/lib`, you should choose a connector version matching your Flink version. If you're using Flink 1.20, please use [fluss-flink-1.20-$FLUSS_VERSION$.jar](https://repo1.maven.org/maven2/org/apache/fluss/fluss-flink-1.20/$FLUSS_VERSION$/fluss-flink-1.20-$FLUSS_VERSION$.jar)
+- If you are using [Amazon S3](http://aws.amazon.com/s3/), [Aliyun OSS](https://www.aliyun.com/product/oss) or [HDFS(Hadoop Distributed File System)](https://hadoop.apache.org/docs/stable/) as Fluss's [remote storage](maintenance/tiered-storage/remote-storage.md),
+ you should download the corresponding [Fluss filesystem jar](/downloads#filesystem-jars) and also put it into `${FLINK_HOME}/lib`
+- Put [fluss-lake-lance jar](https://repo1.maven.org/maven2/org/apache/fluss/fluss-lake-lance/$FLUSS_VERSION$/fluss-lake-lance-$FLUSS_VERSION$.jar) into `${FLINK_HOME}/lib`
+
+Additionally, when following the [Start Datalake Tiering Service](maintenance/tiered-storage/lakehouse-storage.md#start-datalake-tiering-service) guide, make sure to use Lance-specific configurations as parameters when starting the Flink tiering job:
+```shell
+<FLINK_HOME>/bin/flink run /path/to/fluss-flink-tiering-$FLUSS_VERSION$.jar \
+ --fluss.bootstrap.servers localhost:9123 \
+ --datalake.format lance \
+ --datalake.lance.warehouse s3://<bucket> \
+ --datalake.lance.endpoint <endpoint> \
+ --datalake.lance.allow_http true \
+ --datalake.lance.secret_access_key <secret_access_key> \
+ --datalake.lance.access_key_id <access_key_id>
+```
+
+> **NOTE**: Fluss v0.8 only supports tiering log tables to Lance.
+
+Then, the datalake tiering service continuously tiers data from Fluss to Lance. The parameter `table.datalake.freshness` controls the frequency that Fluss writes data to Lance tables. By default, the data freshness is 3 minutes.
+
+You can also specify Lance table properties when creating a datalake-enabled Fluss table by using the `lance.` prefix within the Fluss table properties clause.
+
+```sql title="Flink SQL"
+CREATE TABLE fluss_order_with_lake (
+ `order_id` BIGINT,
+ `item_id` BIGINT,
+ `amount` INT,
+ `address` STRING
+ ) WITH (
+ 'table.datalake.enabled' = 'true',
+ 'table.datalake.freshness' = '30s',
+ 'lance.max_row_per_file' = '512'
+);
+```
+
+For example, you can specify the property `max_row_per_file` to control the writing behavior when Fluss tiers data to Lance.
+
+## Reading with Lance ecosystem tools
+
+Since the data tiered to Lance from Fluss is stored as a standard Lance table, you can use any tool that supports Lance to read it. Below is an example using [pylance](https://pypi.org/project/pylance/):
+
+```python title="Lance Python"
+import lance
+ds = lance.dataset("<warehouse_path>/<database_name>/<table_name>.lance")
+```
+
+## Data Type Mapping
+
+Lance internally stores data in Arrow format.
+When integrating with Lance, Fluss automatically converts between Fluss data types and Lance data types.
+The following table shows the mapping between [Fluss data types](table-design/data-types.md) and Lance data types:
+
+| Fluss Data Type | Lance Data Type |
+|-------------------------------|-----------------|
+| BOOLEAN | BOOLEAN |
+| TINYINT | Int8 |
+| SMALLINT | Int16 |
+| INT | Int32 |
+| BIGINT | Int64 |
+| FLOAT | Float32 |
+| DOUBLE | Float64 |
+| DECIMAL | Decimal128 |
+| STRING | Utf8 |
+| CHAR | Utf8 |
+| DATE | Date |
+| TIME | TIME |
+| TIMESTAMP | TIMESTAMP |
+| TIMESTAMP WITH LOCAL TIMEZONE | TIMESTAMP |
Review Comment:
```suggestion
| TIME | Time |
| TIMESTAMP | Timestamp |
| TIMESTAMP WITH LOCAL TIMEZONE | Timestamp |
```
##########
website/docs/streaming-lakehouse/integrate-data-lakes/lance.md:
##########
@@ -0,0 +1,124 @@
+---
+title: Lance
+sidebar_position: 3
+---
+
+# Lance
+
+[Lance](https://lancedb.github.io/lance/) is a modern table format optimized for machine learning and AI applications.
+To integrate Fluss with Lance, you must enable lakehouse storage and configure Lance as the lakehouse storage. For more details, see [Enable Lakehouse Storage](maintenance/tiered-storage/lakehouse-storage.md#enable-lakehouse-storage).
+
+## Configure Lance as LakeHouse Storage
+
+### Configure Lance in Cluster Configurations
+
+To configure Lance as the lakehouse storage, you must configure the following configurations in `server.yaml`:
+```yaml
+# Lance configuration
+datalake.format: lance
+
+# Currently only local file system and object stores such as AWS S3 (and compatible stores) are supported as storage backends for Lance
+# To use S3 as Lance storage backend, you need to specify the following properties
+datalake.lance.warehouse: s3://<bucket>
+datalake.lance.endpoint: <endpoint>
+datalake.lance.allow_http: true
+datalake.lance.access_key_id: <access_key_id>
+datalake.lance.secret_access_key: <secret_access_key>
+
+# Use local file system as Lance storage backend, you only need to specify the following property
+# datalake.lance.warehouse: /tmp/lance
+```
+
+When a table is created or altered with the option `'table.datalake.enabled' = 'true'`, Fluss will automatically create a corresponding Lance table with path `<warehouse_path>/<database_name>/<table_name>.lance`.
+The schema of the Lance table matches that of the Fluss table.
+
+```sql title="Flink SQL"
+USE CATALOG fluss_catalog;
+
+CREATE TABLE fluss_order_with_lake (
+ `order_id` BIGINT,
+ `item_id` BIGINT,
+ `amount` INT,
+ `address` STRING
+) WITH (
+ 'table.datalake.enabled' = 'true',
+ 'table.datalake.freshness' = '30s'
+);
+```
+
+### Start Tiering Service to Lance
+Then, you must start the datalake tiering service to tier Fluss's data to Lance. For guidance, you can refer to [Start The Datalake Tiering Service
+](maintenance/tiered-storage/lakehouse-storage.md#start-the-datalake-tiering-service). Although the example uses Paimon, the process is also applicable to Lance.
+
+But in [Prepare required jars](maintenance/tiered-storage/lakehouse-storage.md#prepare-required-jars) step, you should follow this guidance:
+- Put [fluss-flink connector jar](/downloads) into `${FLINK_HOME}/lib`, you should choose a connector version matching your Flink version. If you're using Flink 1.20, please use [fluss-flink-1.20-$FLUSS_VERSION$.jar](https://repo1.maven.org/maven2/org/apache/fluss/fluss-flink-1.20/$FLUSS_VERSION$/fluss-flink-1.20-$FLUSS_VERSION$.jar)
+- If you are using [Amazon S3](http://aws.amazon.com/s3/), [Aliyun OSS](https://www.aliyun.com/product/oss) or [HDFS(Hadoop Distributed File System)](https://hadoop.apache.org/docs/stable/) as Fluss's [remote storage](maintenance/tiered-storage/remote-storage.md),
+ you should download the corresponding [Fluss filesystem jar](/downloads#filesystem-jars) and also put it into `${FLINK_HOME}/lib`
+- Put [fluss-lake-lance jar](https://repo1.maven.org/maven2/org/apache/fluss/fluss-lake-lance/$FLUSS_VERSION$/fluss-lake-lance-$FLUSS_VERSION$.jar) into `${FLINK_HOME}/lib`
+
+Additionally, when following the [Start Datalake Tiering Service](maintenance/tiered-storage/lakehouse-storage.md#start-datalake-tiering-service) guide, make sure to use Lance-specific configurations as parameters when starting the Flink tiering job:
+```shell
+<FLINK_HOME>/bin/flink run /path/to/fluss-flink-tiering-$FLUSS_VERSION$.jar \
+ --fluss.bootstrap.servers localhost:9123 \
+ --datalake.format lance \
+ --datalake.lance.warehouse s3://<bucket> \
+ --datalake.lance.endpoint <endpoint> \
+ --datalake.lance.allow_http true \
+ --datalake.lance.secret_access_key <secret_access_key> \
+ --datalake.lance.access_key_id <access_key_id>
+```
+
+> **NOTE**: Fluss v0.8 only supports tiering log tables to Lance.
+
+Then, the datalake tiering service continuously tiers data from Fluss to Lance. The parameter `table.datalake.freshness` controls the frequency that Fluss writes data to Lance tables. By default, the data freshness is 3 minutes.
+
+You can also specify Lance table properties when creating a datalake-enabled Fluss table by using the `lance.` prefix within the Fluss table properties clause.
+
+```sql title="Flink SQL"
+CREATE TABLE fluss_order_with_lake (
+ `order_id` BIGINT,
+ `item_id` BIGINT,
+ `amount` INT,
+ `address` STRING
+ ) WITH (
+ 'table.datalake.enabled' = 'true',
+ 'table.datalake.freshness' = '30s',
+ 'lance.max_row_per_file' = '512'
+);
+```
+
+For example, you can specify the property `max_row_per_file` to control the writing behavior when Fluss tiers data to Lance.
+
+## Reading with Lance ecosystem tools
+
+Since the data tiered to Lance from Fluss is stored as a standard Lance table, you can use any tool that supports Lance to read it. Below is an example using [pylance](https://pypi.org/project/pylance/):
+
+```python title="Lance Python"
+import lance
+ds = lance.dataset("<warehouse_path>/<database_name>/<table_name>.lance")
+```
+
+## Data Type Mapping
+
+Lance internally stores data in Arrow format.
+When integrating with Lance, Fluss automatically converts between Fluss data types and Lance data types.
+The following table shows the mapping between [Fluss data types](table-design/data-types.md) and Lance data types:
+
+| Fluss Data Type | Lance Data Type |
+|-------------------------------|-----------------|
+| BOOLEAN | BOOLEAN |
+| TINYINT | Int8 |
+| SMALLINT | Int16 |
+| INT | Int32 |
+| BIGINT | Int64 |
+| FLOAT | Float32 |
+| DOUBLE | Float64 |
+| DECIMAL | Decimal128 |
+| STRING | Utf8 |
+| CHAR | Utf8 |
+| DATE | Date |
+| TIME | TIME |
+| TIMESTAMP | TIMESTAMP |
+| TIMESTAMP WITH LOCAL TIMEZONE | TIMESTAMP |
+| BINARY | FixedSizeBinary |
+| BYTES | BINARY |
Review Comment:
```suggestion
| BYTES | Binary |
```
##########
website/docs/streaming-lakehouse/integrate-data-lakes/lance.md:
##########
@@ -0,0 +1,124 @@
+---
+title: Lance
+sidebar_position: 3
+---
+
+# Lance
+
+[Lance](https://lancedb.github.io/lance/) is a modern table format optimized for machine learning and AI applications.
+To integrate Fluss with Lance, you must enable lakehouse storage and configure Lance as the lakehouse storage. For more details, see [Enable Lakehouse Storage](maintenance/tiered-storage/lakehouse-storage.md#enable-lakehouse-storage).
+
+## Configure Lance as LakeHouse Storage
+
+### Configure Lance in Cluster Configurations
+
+To configure Lance as the lakehouse storage, you must configure the following configurations in `server.yaml`:
+```yaml
+# Lance configuration
+datalake.format: lance
+
+# Currently only local file system and object stores such as AWS S3 (and compatible stores) are supported as storage backends for Lance
+# To use S3 as Lance storage backend, you need to specify the following properties
+datalake.lance.warehouse: s3://<bucket>
+datalake.lance.endpoint: <endpoint>
+datalake.lance.allow_http: true
+datalake.lance.access_key_id: <access_key_id>
+datalake.lance.secret_access_key: <secret_access_key>
+
+# Use local file system as Lance storage backend, you only need to specify the following property
+# datalake.lance.warehouse: /tmp/lance
+```
+
+When a table is created or altered with the option `'table.datalake.enabled' = 'true'`, Fluss will automatically create a corresponding Lance table with path `<warehouse_path>/<database_name>/<table_name>.lance`.
+The schema of the Lance table matches that of the Fluss table.
+
+```sql title="Flink SQL"
+USE CATALOG fluss_catalog;
+
+CREATE TABLE fluss_order_with_lake (
+ `order_id` BIGINT,
+ `item_id` BIGINT,
+ `amount` INT,
+ `address` STRING
+) WITH (
+ 'table.datalake.enabled' = 'true',
+ 'table.datalake.freshness' = '30s'
+);
+```
+
+### Start Tiering Service to Lance
+Then, you must start the datalake tiering service to tier Fluss's data to Lance. For guidance, you can refer to [Start The Datalake Tiering Service
+](maintenance/tiered-storage/lakehouse-storage.md#start-the-datalake-tiering-service). Although the example uses Paimon, the process is also applicable to Lance.
+
+But in [Prepare required jars](maintenance/tiered-storage/lakehouse-storage.md#prepare-required-jars) step, you should follow this guidance:
+- Put [fluss-flink connector jar](/downloads) into `${FLINK_HOME}/lib`, you should choose a connector version matching your Flink version. If you're using Flink 1.20, please use [fluss-flink-1.20-$FLUSS_VERSION$.jar](https://repo1.maven.org/maven2/org/apache/fluss/fluss-flink-1.20/$FLUSS_VERSION$/fluss-flink-1.20-$FLUSS_VERSION$.jar)
+- If you are using [Amazon S3](http://aws.amazon.com/s3/), [Aliyun OSS](https://www.aliyun.com/product/oss) or [HDFS(Hadoop Distributed File System)](https://hadoop.apache.org/docs/stable/) as Fluss's [remote storage](maintenance/tiered-storage/remote-storage.md),
+ you should download the corresponding [Fluss filesystem jar](/downloads#filesystem-jars) and also put it into `${FLINK_HOME}/lib`
+- Put [fluss-lake-lance jar](https://repo1.maven.org/maven2/org/apache/fluss/fluss-lake-lance/$FLUSS_VERSION$/fluss-lake-lance-$FLUSS_VERSION$.jar) into `${FLINK_HOME}/lib`
+
+Additionally, when following the [Start Datalake Tiering Service](maintenance/tiered-storage/lakehouse-storage.md#start-datalake-tiering-service) guide, make sure to use Lance-specific configurations as parameters when starting the Flink tiering job:
+```shell
+<FLINK_HOME>/bin/flink run /path/to/fluss-flink-tiering-$FLUSS_VERSION$.jar \
+ --fluss.bootstrap.servers localhost:9123 \
+ --datalake.format lance \
+ --datalake.lance.warehouse s3://<bucket> \
+ --datalake.lance.endpoint <endpoint> \
+ --datalake.lance.allow_http true \
+ --datalake.lance.secret_access_key <secret_access_key> \
+ --datalake.lance.access_key_id <access_key_id>
+```
+
+> **NOTE**: Fluss v0.8 only supports tiering log tables to Lance.
+
+Then, the datalake tiering service continuously tiers data from Fluss to Lance. The parameter `table.datalake.freshness` controls the frequency that Fluss writes data to Lance tables. By default, the data freshness is 3 minutes.
+
+You can also specify Lance table properties when creating a datalake-enabled Fluss table by using the `lance.` prefix within the Fluss table properties clause.
+
+```sql title="Flink SQL"
+CREATE TABLE fluss_order_with_lake (
+ `order_id` BIGINT,
+ `item_id` BIGINT,
+ `amount` INT,
+ `address` STRING
+ ) WITH (
+ 'table.datalake.enabled' = 'true',
+ 'table.datalake.freshness' = '30s',
+ 'lance.max_row_per_file' = '512'
+);
+```
+
+For example, you can specify the property `max_row_per_file` to control the writing behavior when Fluss tiers data to Lance.
+
+## Reading with Lance ecosystem tools
+
+Since the data tiered to Lance from Fluss is stored as a standard Lance table, you can use any tool that supports Lance to read it. Below is an example using [pylance](https://pypi.org/project/pylance/):
+
+```python title="Lance Python"
+import lance
+ds = lance.dataset("<warehouse_path>/<database_name>/<table_name>.lance")
+```
+
+## Data Type Mapping
+
+Lance internally stores data in Arrow format.
+When integrating with Lance, Fluss automatically converts between Fluss data types and Lance data types.
+The following table shows the mapping between [Fluss data types](table-design/data-types.md) and Lance data types:
+
+| Fluss Data Type | Lance Data Type |
+|-------------------------------|-----------------|
+| BOOLEAN | BOOLEAN |
Review Comment:
```suggestion
| BOOLEAN | Bool |
```
--
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@fluss.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [lake/lance] add documentation for Lance connector [fluss]
Posted by "xx789633 (via GitHub)" <gi...@apache.org>.
xx789633 commented on code in PR #1587:
URL: https://github.com/apache/fluss/pull/1587#discussion_r2329509557
##########
website/docs/streaming-lakehouse/integrate-data-lakes/lance.md:
##########
@@ -0,0 +1,98 @@
+---
+title: Lance
+sidebar_position: 1
Review Comment:
done
##########
website/docs/streaming-lakehouse/integrate-data-lakes/lance.md:
##########
@@ -0,0 +1,98 @@
+---
Review Comment:
done
--
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@fluss.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [lake/lance] add documentation for Lance connector [fluss]
Posted by "xx789633 (via GitHub)" <gi...@apache.org>.
xx789633 commented on PR #1587:
URL: https://github.com/apache/fluss/pull/1587#issuecomment-3265917734
Thanks for the suggestions @leonardBang @luoyuxia . All merged.
--
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@fluss.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [lake/lance] add documentation for Lance connector [fluss]
Posted by "luoyuxia (via GitHub)" <gi...@apache.org>.
luoyuxia commented on code in PR #1587:
URL: https://github.com/apache/fluss/pull/1587#discussion_r2329452136
##########
website/docs/streaming-lakehouse/integrate-data-lakes/lance.md:
##########
@@ -0,0 +1,98 @@
+---
+title: Lance
+sidebar_position: 1
Review Comment:
use `sidebar_position: 3`
`sidebar_position: 1` is for paimon, `sidebar_position: 2` is for iceberg which will be added.
##########
website/docs/streaming-lakehouse/integrate-data-lakes/lance.md:
##########
@@ -0,0 +1,98 @@
+---
Review Comment:
```Currently, Fluss supports [Paimon as Lakehouse Storage](http://localhost:3000/docs/streaming-lakehouse/integrate-data-lakes/paimon/), more kinds of data lake formats are on the roadmap.```
We shoud adjust the statement in page `streaming-lakehouse/overview/` since lance is supported now.
##########
website/docs/streaming-lakehouse/integrate-data-lakes/lance.md:
##########
@@ -0,0 +1,98 @@
+---
+title: Lance
+sidebar_position: 1
+---
+
+# Lance
+
+[Lance](https://lancedb.github.io/lance/) is a modern table format optimized for machine learning and AI applications.
+To integrate Fluss with Lance, you must enable lakehouse storage and configure Lance as the lakehouse storage. For more details, see [Enable Lakehouse Storage](maintenance/tiered-storage/lakehouse-storage.md#enable-lakehouse-storage).
Review Comment:
I'm wondering is it possible to guide how to start the Tiering Service to lance. Although it refers to (maintenance/tiered-storage/lakehouse-storage.md#enable-lakehouse-storage). But it's used Paimon as the example, not every step is suitable to lance. I think add an seperate page to guide how to start the Tiering Service to lance is much benefit to users
##########
website/docs/streaming-lakehouse/integrate-data-lakes/lance.md:
##########
@@ -0,0 +1,98 @@
+---
+title: Lance
+sidebar_position: 1
+---
+
+# Lance
+
+[Lance](https://lancedb.github.io/lance/) is a modern table format optimized for machine learning and AI applications.
+To integrate Fluss with Lance, you must enable lakehouse storage and configure Lance as the lakehouse storage. For more details, see [Enable Lakehouse Storage](maintenance/tiered-storage/lakehouse-storage.md#enable-lakehouse-storage).
+
+## Introduction
+
+To configure Lance as the lakehouse storage, you must configure the following configurations in `server.yaml`:
+```yaml
+# Lance configuration
+datalake.format: lance
+
+datalake.lance.warehouse: /tmp/lance
+
+# To use S3 as Lance storage backend, you need to specify the following properties
Review Comment:
IIUC, now, only s3 and local filesystem is supported, right? Please add a note for this.
--
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@fluss.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [lake/lance] add documentation for Lance connector [fluss]
Posted by "luoyuxia (via GitHub)" <gi...@apache.org>.
luoyuxia commented on PR #1587:
URL: https://github.com/apache/fluss/pull/1587#issuecomment-3265424299
@xx789633 Hi, I append a new commit to make step up tiering service for lance more clear. PTAL
--
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@fluss.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [lake/lance] add documentation for Lance connector [fluss]
Posted by "leonardBang (via GitHub)" <gi...@apache.org>.
leonardBang commented on code in PR #1587:
URL: https://github.com/apache/fluss/pull/1587#discussion_r2329916362
##########
website/docs/streaming-lakehouse/integrate-data-lakes/lance.md:
##########
@@ -0,0 +1,124 @@
+---
+title: Lance
+sidebar_position: 3
+---
+
+# Lance
+
+[Lance](https://lancedb.github.io/lance/) is a modern table format optimized for machine learning and AI applications.
+To integrate Fluss with Lance, you must enable lakehouse storage and configure Lance as the lakehouse storage. For more details, see [Enable Lakehouse Storage](maintenance/tiered-storage/lakehouse-storage.md#enable-lakehouse-storage).
+
+## Configure Lance as LakeHouse Storage
+
+### Configure Lance in Cluster Configurations
+
+To configure Lance as the lakehouse storage, you must configure the following configurations in `server.yaml`:
+```yaml
+# Lance configuration
+datalake.format: lance
+
+# Currently only local file system and object stores such as AWS S3 (and compatible stores) are supported as storage backends for Lance
+# To use S3 as Lance storage backend, you need to specify the following properties
+datalake.lance.warehouse: s3://<bucket>
+datalake.lance.endpoint: <endpoint>
+datalake.lance.allow_http: true
+datalake.lance.access_key_id: <access_key_id>
+datalake.lance.secret_access_key: <secret_access_key>
+
+# Use local file system as Lance storage backend, you only need to specify the following property
+# datalake.lance.warehouse: /tmp/lance
+```
+
+When a table is created or altered with the option `'table.datalake.enabled' = 'true'`, Fluss will automatically create a corresponding Lance table with path `<warehouse_path>/<database_name>/<table_name>.lance`.
+The schema of the Lance table matches that of the Fluss table.
+
+```sql title="Flink SQL"
+USE CATALOG fluss_catalog;
+
+CREATE TABLE fluss_order_with_lake (
+ `order_id` BIGINT,
+ `item_id` BIGINT,
+ `amount` INT,
+ `address` STRING
+) WITH (
+ 'table.datalake.enabled' = 'true',
+ 'table.datalake.freshness' = '30s'
+);
+```
+
+### Start Tiering Service to Lance
+Then, you must start the datalake tiering service to tier Fluss's data to Lance. For guidance, you can refer to [Start The Datalake Tiering Service
+](maintenance/tiered-storage/lakehouse-storage.md#start-the-datalake-tiering-service). Although the example uses Paimon, the process is also applicable to Lance.
+
+But in [Prepare required jars](maintenance/tiered-storage/lakehouse-storage.md#prepare-required-jars) step, you should follow this guidance:
+- Put [fluss-flink connector jar](/downloads) into `${FLINK_HOME}/lib`, you should choose a connector version matching your Flink version. If you're using Flink 1.20, please use [fluss-flink-1.20-$FLUSS_VERSION$.jar](https://repo1.maven.org/maven2/org/apache/fluss/fluss-flink-1.20/$FLUSS_VERSION$/fluss-flink-1.20-$FLUSS_VERSION$.jar)
+- If you are using [Amazon S3](http://aws.amazon.com/s3/), [Aliyun OSS](https://www.aliyun.com/product/oss) or [HDFS(Hadoop Distributed File System)](https://hadoop.apache.org/docs/stable/) as Fluss's [remote storage](maintenance/tiered-storage/remote-storage.md),
+ you should download the corresponding [Fluss filesystem jar](/downloads#filesystem-jars) and also put it into `${FLINK_HOME}/lib`
+- Put [fluss-lake-lance jar](https://repo1.maven.org/maven2/org/apache/fluss/fluss-lake-lance/$FLUSS_VERSION$/fluss-lake-lance-$FLUSS_VERSION$.jar) into `${FLINK_HOME}/lib`
+
+Additionally, when following the [Start Datalake Tiering Service](maintenance/tiered-storage/lakehouse-storage.md#start-datalake-tiering-service) guide, make sure to use Lance-specific configurations as parameters when starting the Flink tiering job:
+```shell
+<FLINK_HOME>/bin/flink run /path/to/fluss-flink-tiering-$FLUSS_VERSION$.jar \
+ --fluss.bootstrap.servers localhost:9123 \
+ --datalake.format lance \
+ --datalake.lance.warehouse s3://<bucket> \
+ --datalake.lance.endpoint <endpoint> \
+ --datalake.lance.allow_http true \
+ --datalake.lance.secret_access_key <secret_access_key> \
+ --datalake.lance.access_key_id <access_key_id>
+```
+
+> **NOTE**: Fluss v0.8 only supports tiering log tables to Lance.
+
+Then, the datalake tiering service continuously tiers data from Fluss to Lance. The parameter `table.datalake.freshness` controls the frequency that Fluss writes data to Lance tables. By default, the data freshness is 3 minutes.
+
+You can also specify Lance table properties when creating a datalake-enabled Fluss table by using the `lance.` prefix within the Fluss table properties clause.
+
+```sql title="Flink SQL"
+CREATE TABLE fluss_order_with_lake (
+ `order_id` BIGINT,
+ `item_id` BIGINT,
+ `amount` INT,
+ `address` STRING
+ ) WITH (
+ 'table.datalake.enabled' = 'true',
+ 'table.datalake.freshness' = '30s',
+ 'lance.max_row_per_file' = '512'
+);
+```
+
+For example, you can specify the property `max_row_per_file` to control the writing behavior when Fluss tiers data to Lance.
+
+## Reading with Lance ecosystem tools
+
+Since the data tiered to Lance from Fluss is stored as a standard Lance table, you can use any tool that supports Lance to read it. Below is an example using [pylance](https://pypi.org/project/pylance/):
+
+```python title="Lance Python"
+import lance
+ds = lance.dataset("<warehouse_path>/<database_name>/<table_name>.lance")
+```
+
+## Data Type Mapping
+
+Lance internally stores data in Arrow format.
+When integrating with Lance, Fluss automatically converts between Fluss data types and Lance data types.
+The following table shows the mapping between [Fluss data types](table-design/data-types.md) and Lance data types:
+
+| Fluss Data Type | Lance Data Type |
+|-------------------------------|-----------------|
+| BOOLEAN | BOOLEAN |
Review Comment:
```suggestion
| BOOLEAN | Bool |
```
##########
website/docs/streaming-lakehouse/integrate-data-lakes/lance.md:
##########
@@ -0,0 +1,124 @@
+---
+title: Lance
+sidebar_position: 3
+---
+
+# Lance
+
+[Lance](https://lancedb.github.io/lance/) is a modern table format optimized for machine learning and AI applications.
+To integrate Fluss with Lance, you must enable lakehouse storage and configure Lance as the lakehouse storage. For more details, see [Enable Lakehouse Storage](maintenance/tiered-storage/lakehouse-storage.md#enable-lakehouse-storage).
+
+## Configure Lance as LakeHouse Storage
+
+### Configure Lance in Cluster Configurations
+
+To configure Lance as the lakehouse storage, you must configure the following configurations in `server.yaml`:
+```yaml
+# Lance configuration
+datalake.format: lance
+
+# Currently only local file system and object stores such as AWS S3 (and compatible stores) are supported as storage backends for Lance
+# To use S3 as Lance storage backend, you need to specify the following properties
+datalake.lance.warehouse: s3://<bucket>
+datalake.lance.endpoint: <endpoint>
+datalake.lance.allow_http: true
+datalake.lance.access_key_id: <access_key_id>
+datalake.lance.secret_access_key: <secret_access_key>
+
+# Use local file system as Lance storage backend, you only need to specify the following property
+# datalake.lance.warehouse: /tmp/lance
+```
+
+When a table is created or altered with the option `'table.datalake.enabled' = 'true'`, Fluss will automatically create a corresponding Lance table with path `<warehouse_path>/<database_name>/<table_name>.lance`.
+The schema of the Lance table matches that of the Fluss table.
+
+```sql title="Flink SQL"
+USE CATALOG fluss_catalog;
+
+CREATE TABLE fluss_order_with_lake (
+ `order_id` BIGINT,
+ `item_id` BIGINT,
+ `amount` INT,
+ `address` STRING
+) WITH (
+ 'table.datalake.enabled' = 'true',
+ 'table.datalake.freshness' = '30s'
+);
+```
+
+### Start Tiering Service to Lance
+Then, you must start the datalake tiering service to tier Fluss's data to Lance. For guidance, you can refer to [Start The Datalake Tiering Service
+](maintenance/tiered-storage/lakehouse-storage.md#start-the-datalake-tiering-service). Although the example uses Paimon, the process is also applicable to Lance.
+
+But in [Prepare required jars](maintenance/tiered-storage/lakehouse-storage.md#prepare-required-jars) step, you should follow this guidance:
+- Put [fluss-flink connector jar](/downloads) into `${FLINK_HOME}/lib`, you should choose a connector version matching your Flink version. If you're using Flink 1.20, please use [fluss-flink-1.20-$FLUSS_VERSION$.jar](https://repo1.maven.org/maven2/org/apache/fluss/fluss-flink-1.20/$FLUSS_VERSION$/fluss-flink-1.20-$FLUSS_VERSION$.jar)
+- If you are using [Amazon S3](http://aws.amazon.com/s3/), [Aliyun OSS](https://www.aliyun.com/product/oss) or [HDFS(Hadoop Distributed File System)](https://hadoop.apache.org/docs/stable/) as Fluss's [remote storage](maintenance/tiered-storage/remote-storage.md),
+ you should download the corresponding [Fluss filesystem jar](/downloads#filesystem-jars) and also put it into `${FLINK_HOME}/lib`
+- Put [fluss-lake-lance jar](https://repo1.maven.org/maven2/org/apache/fluss/fluss-lake-lance/$FLUSS_VERSION$/fluss-lake-lance-$FLUSS_VERSION$.jar) into `${FLINK_HOME}/lib`
+
+Additionally, when following the [Start Datalake Tiering Service](maintenance/tiered-storage/lakehouse-storage.md#start-datalake-tiering-service) guide, make sure to use Lance-specific configurations as parameters when starting the Flink tiering job:
+```shell
+<FLINK_HOME>/bin/flink run /path/to/fluss-flink-tiering-$FLUSS_VERSION$.jar \
+ --fluss.bootstrap.servers localhost:9123 \
+ --datalake.format lance \
+ --datalake.lance.warehouse s3://<bucket> \
+ --datalake.lance.endpoint <endpoint> \
+ --datalake.lance.allow_http true \
+ --datalake.lance.secret_access_key <secret_access_key> \
+ --datalake.lance.access_key_id <access_key_id>
+```
+
+> **NOTE**: Fluss v0.8 only supports tiering log tables to Lance.
+
+Then, the datalake tiering service continuously tiers data from Fluss to Lance. The parameter `table.datalake.freshness` controls the frequency that Fluss writes data to Lance tables. By default, the data freshness is 3 minutes.
+
+You can also specify Lance table properties when creating a datalake-enabled Fluss table by using the `lance.` prefix within the Fluss table properties clause.
+
+```sql title="Flink SQL"
+CREATE TABLE fluss_order_with_lake (
+ `order_id` BIGINT,
+ `item_id` BIGINT,
+ `amount` INT,
+ `address` STRING
+ ) WITH (
+ 'table.datalake.enabled' = 'true',
+ 'table.datalake.freshness' = '30s',
+ 'lance.max_row_per_file' = '512'
+);
+```
+
+For example, you can specify the property `max_row_per_file` to control the writing behavior when Fluss tiers data to Lance.
+
+## Reading with Lance ecosystem tools
+
+Since the data tiered to Lance from Fluss is stored as a standard Lance table, you can use any tool that supports Lance to read it. Below is an example using [pylance](https://pypi.org/project/pylance/):
+
+```python title="Lance Python"
+import lance
+ds = lance.dataset("<warehouse_path>/<database_name>/<table_name>.lance")
+```
+
+## Data Type Mapping
+
+Lance internally stores data in Arrow format.
+When integrating with Lance, Fluss automatically converts between Fluss data types and Lance data types.
+The following table shows the mapping between [Fluss data types](table-design/data-types.md) and Lance data types:
+
+| Fluss Data Type | Lance Data Type |
+|-------------------------------|-----------------|
+| BOOLEAN | BOOLEAN |
Review Comment:
```suggestion
| BOOLEAN | Bool |
```
--
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@fluss.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [lake/lance] add documentation for Lance connector [fluss]
Posted by "luoyuxia (via GitHub)" <gi...@apache.org>.
luoyuxia merged PR #1587:
URL: https://github.com/apache/fluss/pull/1587
--
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@fluss.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [lake/lance] add documentation for Lance connector [fluss]
Posted by "xx789633 (via GitHub)" <gi...@apache.org>.
xx789633 commented on code in PR #1587:
URL: https://github.com/apache/fluss/pull/1587#discussion_r2329510182
##########
website/docs/streaming-lakehouse/integrate-data-lakes/lance.md:
##########
@@ -0,0 +1,98 @@
+---
+title: Lance
+sidebar_position: 1
+---
+
+# Lance
+
+[Lance](https://lancedb.github.io/lance/) is a modern table format optimized for machine learning and AI applications.
+To integrate Fluss with Lance, you must enable lakehouse storage and configure Lance as the lakehouse storage. For more details, see [Enable Lakehouse Storage](maintenance/tiered-storage/lakehouse-storage.md#enable-lakehouse-storage).
+
+## Introduction
+
+To configure Lance as the lakehouse storage, you must configure the following configurations in `server.yaml`:
+```yaml
+# Lance configuration
+datalake.format: lance
+
+datalake.lance.warehouse: /tmp/lance
+
+# To use S3 as Lance storage backend, you need to specify the following properties
Review Comment:
done
--
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@fluss.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] [lake/lance] add documentation for Lance connector [fluss]
Posted by "xx789633 (via GitHub)" <gi...@apache.org>.
xx789633 commented on PR #1587:
URL: https://github.com/apache/fluss/pull/1587#issuecomment-3265458981
Thanks for the improvements. Looks good to me.
--
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@fluss.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org