This is an automated email from the ASF dual-hosted git repository.
morningman pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new 7ba916c84f5d [docs] Add OSS access scenarios and direct file query
example (#4625)
7ba916c84f5d is described below
commit 7ba916c84f5d7a0cd68ddd55ab9fcd849ec085d1
Author: Mingyu Chen (Rayner) <[email protected]>
AuthorDate: Fri Nov 13 08:04:04 2026 +0800
[docs] Add OSS access scenarios and direct file query example (#4625)
The OSS connection reference lists properties without explaining where
users should supply them. Add a scenario table covering direct file
queries, import, Hive catalogs, and export, with links to full workflows
and a small CSV query example that requires no Doris table.
Keep the example and explanations consistent in English and Chinese dev,
4.x, and 3.x. Fixes #3197.
Validation: checked S3 TVF parsing, CSV schema handling, and OSS/S3
property aliases against Doris source; all new relative links resolve
and the SQL matches across all six pages; front matter and MDX checks
plus `git diff --check` passed. The example's expected rows follow from
the supplied two-row CSV; no live OSS request was run. Existing page
paths and headings are preserved.
Co-authored-by: morningman <[email protected]>
---
docs/lakehouse/storages/aliyun-oss.md | 48 ++++++++++++++++++++++
.../current/lakehouse/storages/aliyun-oss.md | 48 ++++++++++++++++++++++
.../version-3.x/lakehouse/storages/aliyun-oss.md | 48 ++++++++++++++++++++++
.../version-4.x/lakehouse/storages/aliyun-oss.md | 48 ++++++++++++++++++++++
.../version-3.x/lakehouse/storages/aliyun-oss.md | 48 ++++++++++++++++++++++
.../version-4.x/lakehouse/storages/aliyun-oss.md | 48 ++++++++++++++++++++++
6 files changed, 288 insertions(+)
diff --git a/docs/lakehouse/storages/aliyun-oss.md
b/docs/lakehouse/storages/aliyun-oss.md
index 78972622fa70..565d924f1184 100644
--- a/docs/lakehouse/storages/aliyun-oss.md
+++ b/docs/lakehouse/storages/aliyun-oss.md
@@ -14,6 +14,54 @@ This document describes the parameters required to access
Alibaba Cloud OSS, whi
- Export properties
- Outfile properties
+## When to Configure OSS Access
+
+These properties configure access to files in OSS. Set them on the operation
that reads or writes those files:
+
+| Scenario | Where to configure access | Example |
+| --- | --- | --- |
+| Query a CSV, Parquet, or ORC file directly | In the `S3(...)` table-valued
function | Query example below |
+| Import OSS files into an existing Doris table | In `S3(...)` for `INSERT
INTO ... SELECT`, or in the `WITH S3` clause of Broker Load | [OSS data
import](../../data-operate/import/data-source/aliyun-oss.md) |
+| Query Hive tables whose data is stored in OSS | In the catalog properties
when running `CREATE CATALOG` | [Hive Catalog](../catalogs/hive-catalog) |
+| Export query results to OSS | In the properties of the export command |
[SELECT INTO OUTFILE](../../data-operate/export/outfile.md) |
+
+For example, upload a UTF-8 file `users.csv` to your OSS bucket, without a
header row:
+
+```text
+1,Alice
+2,Bob
+```
+
+Ensure the Doris FE and BE nodes can reach the OSS endpoint and that the
supplied credentials can read the object. Replace the bucket, object path, and
credentials below. This query reads the file directly; it does not require
creating a Doris table. It uses the S3-compatible `s3.*` property names.
+
+```sql
+SELECT id, name
+FROM S3(
+ "uri" = "s3://your-bucket/users.csv",
+ "format" = "csv",
+ "s3.endpoint" = "oss-cn-beijing.aliyuncs.com",
+ "s3.region" = "cn-beijing",
+ "s3.access_key" = "<your-access-key>",
+ "s3.secret_key" = "<your-secret-key>",
+ "column_separator" = ",",
+ "csv_schema" = "id:int;name:string"
+)
+ORDER BY id;
+```
+
+Expected result for the file above:
+
+```text
++------+-------+
+| id | name |
++------+-------+
+| 1 | Alice |
+| 2 | Bob |
++------+-------+
+```
+
+To persist the data in Doris, create a target table and use `INSERT INTO ...
SELECT` as shown in the OSS data-import guide linked above. For other
operations, place the connection properties in the corresponding catalog, load,
or export statement.
+
## OSS
Doris uses S3 Client to access Alibaba Cloud OSS through S3-compatible
protocol.
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/storages/aliyun-oss.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/storages/aliyun-oss.md
index cf7e49bf2b48..f0dee55d7318 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/storages/aliyun-oss.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/storages/aliyun-oss.md
@@ -14,6 +14,54 @@
- Export 属性
- Outfile 属性
+## 何时配置 OSS 访问参数
+
+这些参数用于访问 OSS 中的文件，应配置在实际读写文件的操作中：
+
+| 场景 | 配置位置 | 示例 |
+| --- | --- | --- |
+| 直接查询 CSV、Parquet 或 ORC 文件 | `S3(...)` 表值函数中 | 见下方查询示例 |
+| 将 OSS 文件导入已有的 Doris 表 | `INSERT INTO ... SELECT` 中的 `S3(...)`，或 Broker Load
的 `WITH S3` 子句中 | [OSS
数据导入](../../data-operate/import/data-source/aliyun-oss.md) |
+| 查询数据存储在 OSS 的 Hive 表 | `CREATE CATALOG` 的 Catalog 属性中 | [Hive
Catalog](../catalogs/hive-catalog) |
+| 将查询结果导出到 OSS | 导出语句的属性中 | [SELECT INTO
OUTFILE](../../data-operate/export/outfile.md) |
+
+例如，将不含表头的 UTF-8 文件 `users.csv` 上传到 OSS bucket：
+
+```text
+1,Alice
+2,Bob
+```
+
+确保 Doris FE、BE 节点可以访问 OSS endpoint，且所提供的凭据有该对象的读取权限。替换下方的
bucket、对象路径和凭据。此查询直接读取文件，无需先创建 Doris 表；示例使用兼容 S3 的 `s3.*` 参数名。
+
+```sql
+SELECT id, name
+FROM S3(
+ "uri" = "s3://your-bucket/users.csv",
+ "format" = "csv",
+ "s3.endpoint" = "oss-cn-beijing.aliyuncs.com",
+ "s3.region" = "cn-beijing",
+ "s3.access_key" = "<your-access-key>",
+ "s3.secret_key" = "<your-secret-key>",
+ "column_separator" = ",",
+ "csv_schema" = "id:int;name:string"
+)
+ORDER BY id;
+```
+
+上述文件的预期结果：
+
+```text
++------+-------+
+| id | name |
++------+-------+
+| 1 | Alice |
+| 2 | Bob |
++------+-------+
+```
+
+如需将数据保存到 Doris，请先建目标表，再按上方 OSS 数据导入指南使用 `INSERT INTO ... SELECT`。其他场景则在对应的
Catalog、导入或导出语句中设置连接属性。
+
## OSS
Doris 使用 S3 Client，通过 S3 兼容协议访问阿里云 OSS。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/lakehouse/storages/aliyun-oss.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/lakehouse/storages/aliyun-oss.md
index 1cf65f7c1b04..72b12b33fca6 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/lakehouse/storages/aliyun-oss.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/lakehouse/storages/aliyun-oss.md
@@ -14,6 +14,54 @@
- Export 属性
- Outfile 属性
+## 何时配置 OSS 访问参数
+
+这些参数用于访问 OSS 中的文件，应配置在实际读写文件的操作中：
+
+| 场景 | 配置位置 | 示例 |
+| --- | --- | --- |
+| 直接查询 CSV、Parquet 或 ORC 文件 | `S3(...)` 表值函数中 | 见下方查询示例 |
+| 将 OSS 文件导入已有的 Doris 表 | `INSERT INTO ... SELECT` 中的 `S3(...)`，或 Broker Load
的 `WITH S3` 子句中 | [OSS
数据导入](../../data-operate/import/data-source/aliyun-oss.md) |
+| 查询数据存储在 OSS 的 Hive 表 | `CREATE CATALOG` 的 Catalog 属性中 | [Hive
Catalog](../catalogs/hive-catalog) |
+| 将查询结果导出到 OSS | 导出语句的属性中 | [SELECT INTO
OUTFILE](../../data-operate/export/outfile.md) |
+
+例如，将不含表头的 UTF-8 文件 `users.csv` 上传到 OSS bucket：
+
+```text
+1,Alice
+2,Bob
+```
+
+确保 Doris FE、BE 节点可以访问 OSS endpoint，且所提供的凭据有该对象的读取权限。替换下方的
bucket、对象路径和凭据。此查询直接读取文件，无需先创建 Doris 表；示例使用兼容 S3 的 `s3.*` 参数名。
+
+```sql
+SELECT id, name
+FROM S3(
+ "uri" = "s3://your-bucket/users.csv",
+ "format" = "csv",
+ "s3.endpoint" = "oss-cn-beijing.aliyuncs.com",
+ "s3.region" = "cn-beijing",
+ "s3.access_key" = "<your-access-key>",
+ "s3.secret_key" = "<your-secret-key>",
+ "column_separator" = ",",
+ "csv_schema" = "id:int;name:string"
+)
+ORDER BY id;
+```
+
+上述文件的预期结果：
+
+```text
++------+-------+
+| id | name |
++------+-------+
+| 1 | Alice |
+| 2 | Bob |
++------+-------+
+```
+
+如需将数据保存到 Doris，请先建目标表，再按上方 OSS 数据导入指南使用 `INSERT INTO ... SELECT`。其他场景则在对应的
Catalog、导入或导出语句中设置连接属性。
+
## OSS
Doris 使用 S3 Client，通过 S3 兼容协议访问阿里云 OSS。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/storages/aliyun-oss.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/storages/aliyun-oss.md
index cf7e49bf2b48..f0dee55d7318 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/storages/aliyun-oss.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/storages/aliyun-oss.md
@@ -14,6 +14,54 @@
- Export 属性
- Outfile 属性
+## 何时配置 OSS 访问参数
+
+这些参数用于访问 OSS 中的文件，应配置在实际读写文件的操作中：
+
+| 场景 | 配置位置 | 示例 |
+| --- | --- | --- |
+| 直接查询 CSV、Parquet 或 ORC 文件 | `S3(...)` 表值函数中 | 见下方查询示例 |
+| 将 OSS 文件导入已有的 Doris 表 | `INSERT INTO ... SELECT` 中的 `S3(...)`，或 Broker Load
的 `WITH S3` 子句中 | [OSS
数据导入](../../data-operate/import/data-source/aliyun-oss.md) |
+| 查询数据存储在 OSS 的 Hive 表 | `CREATE CATALOG` 的 Catalog 属性中 | [Hive
Catalog](../catalogs/hive-catalog) |
+| 将查询结果导出到 OSS | 导出语句的属性中 | [SELECT INTO
OUTFILE](../../data-operate/export/outfile.md) |
+
+例如，将不含表头的 UTF-8 文件 `users.csv` 上传到 OSS bucket：
+
+```text
+1,Alice
+2,Bob
+```
+
+确保 Doris FE、BE 节点可以访问 OSS endpoint，且所提供的凭据有该对象的读取权限。替换下方的
bucket、对象路径和凭据。此查询直接读取文件，无需先创建 Doris 表；示例使用兼容 S3 的 `s3.*` 参数名。
+
+```sql
+SELECT id, name
+FROM S3(
+ "uri" = "s3://your-bucket/users.csv",
+ "format" = "csv",
+ "s3.endpoint" = "oss-cn-beijing.aliyuncs.com",
+ "s3.region" = "cn-beijing",
+ "s3.access_key" = "<your-access-key>",
+ "s3.secret_key" = "<your-secret-key>",
+ "column_separator" = ",",
+ "csv_schema" = "id:int;name:string"
+)
+ORDER BY id;
+```
+
+上述文件的预期结果：
+
+```text
++------+-------+
+| id | name |
++------+-------+
+| 1 | Alice |
+| 2 | Bob |
++------+-------+
+```
+
+如需将数据保存到 Doris，请先建目标表，再按上方 OSS 数据导入指南使用 `INSERT INTO ... SELECT`。其他场景则在对应的
Catalog、导入或导出语句中设置连接属性。
+
## OSS
Doris 使用 S3 Client，通过 S3 兼容协议访问阿里云 OSS。
diff --git a/versioned_docs/version-3.x/lakehouse/storages/aliyun-oss.md
b/versioned_docs/version-3.x/lakehouse/storages/aliyun-oss.md
index a7d2059984a2..5a24fef04a88 100644
--- a/versioned_docs/version-3.x/lakehouse/storages/aliyun-oss.md
+++ b/versioned_docs/version-3.x/lakehouse/storages/aliyun-oss.md
@@ -14,6 +14,54 @@ This document describes the parameters required to access
Alibaba Cloud OSS, whi
- Export properties
- Outfile properties
+## When to Configure OSS Access
+
+These properties configure access to files in OSS. Set them on the operation
that reads or writes those files:
+
+| Scenario | Where to configure access | Example |
+| --- | --- | --- |
+| Query a CSV, Parquet, or ORC file directly | In the `S3(...)` table-valued
function | Query example below |
+| Import OSS files into an existing Doris table | In `S3(...)` for `INSERT
INTO ... SELECT`, or in the `WITH S3` clause of Broker Load | [OSS data
import](../../data-operate/import/data-source/aliyun-oss.md) |
+| Query Hive tables whose data is stored in OSS | In the catalog properties
when running `CREATE CATALOG` | [Hive Catalog](../catalogs/hive-catalog) |
+| Export query results to OSS | In the properties of the export command |
[SELECT INTO OUTFILE](../../data-operate/export/outfile.md) |
+
+For example, upload a UTF-8 file `users.csv` to your OSS bucket, without a
header row:
+
+```text
+1,Alice
+2,Bob
+```
+
+Ensure the Doris FE and BE nodes can reach the OSS endpoint and that the
supplied credentials can read the object. Replace the bucket, object path, and
credentials below. This query reads the file directly; it does not require
creating a Doris table. It uses the S3-compatible `s3.*` property names.
+
+```sql
+SELECT id, name
+FROM S3(
+ "uri" = "s3://your-bucket/users.csv",
+ "format" = "csv",
+ "s3.endpoint" = "oss-cn-beijing.aliyuncs.com",
+ "s3.region" = "cn-beijing",
+ "s3.access_key" = "<your-access-key>",
+ "s3.secret_key" = "<your-secret-key>",
+ "column_separator" = ",",
+ "csv_schema" = "id:int;name:string"
+)
+ORDER BY id;
+```
+
+Expected result for the file above:
+
+```text
++------+-------+
+| id | name |
++------+-------+
+| 1 | Alice |
+| 2 | Bob |
++------+-------+
+```
+
+To persist the data in Doris, create a target table and use `INSERT INTO ...
SELECT` as shown in the OSS data-import guide linked above. For other
operations, place the connection properties in the corresponding catalog, load,
or export statement.
+
## OSS
Doris uses S3 Client to access Alibaba Cloud OSS through S3-compatible
protocol.
diff --git a/versioned_docs/version-4.x/lakehouse/storages/aliyun-oss.md
b/versioned_docs/version-4.x/lakehouse/storages/aliyun-oss.md
index 78972622fa70..565d924f1184 100644
--- a/versioned_docs/version-4.x/lakehouse/storages/aliyun-oss.md
+++ b/versioned_docs/version-4.x/lakehouse/storages/aliyun-oss.md
@@ -14,6 +14,54 @@ This document describes the parameters required to access
Alibaba Cloud OSS, whi
- Export properties
- Outfile properties
+## When to Configure OSS Access
+
+These properties configure access to files in OSS. Set them on the operation
that reads or writes those files:
+
+| Scenario | Where to configure access | Example |
+| --- | --- | --- |
+| Query a CSV, Parquet, or ORC file directly | In the `S3(...)` table-valued
function | Query example below |
+| Import OSS files into an existing Doris table | In `S3(...)` for `INSERT
INTO ... SELECT`, or in the `WITH S3` clause of Broker Load | [OSS data
import](../../data-operate/import/data-source/aliyun-oss.md) |
+| Query Hive tables whose data is stored in OSS | In the catalog properties
when running `CREATE CATALOG` | [Hive Catalog](../catalogs/hive-catalog) |
+| Export query results to OSS | In the properties of the export command |
[SELECT INTO OUTFILE](../../data-operate/export/outfile.md) |
+
+For example, upload a UTF-8 file `users.csv` to your OSS bucket, without a
header row:
+
+```text
+1,Alice
+2,Bob
+```
+
+Ensure the Doris FE and BE nodes can reach the OSS endpoint and that the
supplied credentials can read the object. Replace the bucket, object path, and
credentials below. This query reads the file directly; it does not require
creating a Doris table. It uses the S3-compatible `s3.*` property names.
+
+```sql
+SELECT id, name
+FROM S3(
+ "uri" = "s3://your-bucket/users.csv",
+ "format" = "csv",
+ "s3.endpoint" = "oss-cn-beijing.aliyuncs.com",
+ "s3.region" = "cn-beijing",
+ "s3.access_key" = "<your-access-key>",
+ "s3.secret_key" = "<your-secret-key>",
+ "column_separator" = ",",
+ "csv_schema" = "id:int;name:string"
+)
+ORDER BY id;
+```
+
+Expected result for the file above:
+
+```text
++------+-------+
+| id | name |
++------+-------+
+| 1 | Alice |
+| 2 | Bob |
++------+-------+
+```
+
+To persist the data in Doris, create a target table and use `INSERT INTO ...
SELECT` as shown in the OSS data-import guide linked above. For other
operations, place the connection properties in the corresponding catalog, load,
or export statement.
+
## OSS
Doris uses S3 Client to access Alibaba Cloud OSS through S3-compatible
protocol.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
