Skip to content

[doc](s3) Fix the wrong property name for path-style access - #4485

Open
wy471x wants to merge 4 commits into
apache:masterfrom
wy471x:docs/fix-s3-path-style-property
Open

wy471x wants to merge 4 commits into
apache:masterfrom
wy471x:docs/fix-s3-path-style-property

Conversation

@wy471x

@wy471x wy471x commented Oct 23, 2026

Copy link
Copy Markdown

Versions

  • dev
  • 4.x
  • 3.x
  • 2.1 or older (not covered by version/language sync gate)

Languages

  • Chinese
  • English

Docs Checklist

  • Checked by AI
  • Test Cases Built
  • Updated required version and language counterparts, or explained why not
  • If only one language changed, confirmed whether source/translation counterparts need sync

What's wrong

Fixes apache/doris#69137

The documentation says path-style access is enabled with s3.use_path_style, which is not a recognized property name in Doris, so users following the docs cannot switch to path-style access (for example when they access MinIO, SeaweedFS or other S3-compatible services).

In the FE property definitions the accepted names are:

  • use_path_style — canonical name, accepted by every S3-compatible dialect.
  • s3.path-style-access — accepted alias for the S3 / Iceberg-style spelling.
  • <service>.use_path_style (oss., obs., minio., cos., ozone., gs.) — accepted for the matching service.

s3.use_path_style does not exist in any of them.

What changed

  • lakehouse/storages/s3.md: the parameter table now lists use_path_style (with s3.path-style-access as the alias), plus a short note that s3.use_path_style is invalid and that S3-compatible services accept their own prefixed spelling.
  • lakehouse/storages/aliyun-oss.md, huawei-obs.md, minio.md: the legacy/alias column listed s3.use_path_style; it now lists use_path_style.
  • lakehouse/storages/seaweedfs.md: SeaweedFS requires path-style access, but the parameter table, the example CREATE CATALOG snippet and the usage recommendations all used s3.use_path_style; they now use use_path_style.
  • Applied to dev (docs/) and 4.x (versioned_docs/version-4.x/), in both English and zh-CN. 3.x / 2.1 are frozen snapshots outside the version sync gate and are intentionally left untouched.

Validation

  • Checked the property names against the Doris FE sources: S3FileSystemProperties declares @ConnectorProperty(names = {USE_PATH_STYLE, "s3.path-style-access"}) where USE_PATH_STYLE = "use_path_style", and OssFileSystemProperties / ObsFileSystemProperties / MinioFileSystemProperties / OzoneFileSystemProperties declare their own <service>.use_path_style plus use_path_style and s3.path-style-access. No FE/external-table/StorageVault property parser accepts s3.use_path_style (grep -rn "s3\.use_path_style" over the Doris repository returns no match).
  • No remaining s3.use_path_style occurrences in the touched trees except the intentional "is not valid" note.
  • Markdown-only change: no navigation, sidebar, slug or link changes, so no redirect or sidebar updates are needed. Tables stay aligned and render identically in the versioned and localized copies.

`use_path_style` is the property that enables path-style access for S3 in
Doris, and `s3.path-style-access` is accepted as its alias. The docs listed
`s3.use_path_style`, which is not a recognized property name and therefore
had no effect, so users following the docs could not switch to path-style
access.

- Update the S3 parameter table and add a note on the valid spellings.
- Fix the legacy/alias column of the OSS, OBS and MinIO parameter tables.
- Fix the SeaweedFS examples, which require path-style access.

Fixes apache/doris#69137

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Doc] 官方文档中 S3 路径风格访问参数错误 (s3.use_path_style)

1 participant