Skip to content

[doc](lance) Document OSS support for the Lance catalog - #4094

Open
FANNG1 wants to merge 2 commits into
apache:masterfrom
FANNG1:lance-oss-catalog-docs
Open

[doc](lance) Document OSS support for the Lance catalog#4094
FANNG1 wants to merge 2 commits into
apache:masterfrom
FANNG1:lance-oss-catalog-docs

Conversation

@FANNG1

@FANNG1 FANNG1 commented Aug 28, 2026

Copy link
Copy Markdown
Contributor

Summary

Documents the Alibaba Cloud OSS support added by apache/doris#67157 (issue apache/doris#67131). The Lance catalog page currently tells users that a warehouse can only be a local path, file:// or s3://, so OSS looks unsupported.

Requested by @zhangstar333 in apache/doris#67157.

Changes

Both versioned_docs/version-4.x/.../lance-catalog.mdx and the zh-CN copy:

  • warehouse now lists oss:// among the accepted forms.
  • New Use Alibaba Cloud OSS section next to the existing S3 one, with a CREATE CATALOG example, the qualified oss://bucket.oss-<region>.aliyuncs.com/path form Doris reduces to the bucket, the bucket requirement, and a note on oss.session_token.
  • REST catalog section now names the OSS properties usable as defaults, states that namespace-vended credentials take precedence over the catalog's own, and shows a catalog created with no access key at all.
  • Documents that a namespace may vend the options as either oss_endpoint / oss_access_key_id / oss_secret_access_key / oss_region / oss_security_token or the bare OSS-native endpoint / access_key_id / access_key_secret / region / security_token, and that vending one option under both spellings with different values is an error.

Verification

The examples were run against a real OSS bucket on a Doris cluster built from apache/doris#67157, not written from the code alone:

  • the filesystem example exactly as written — without fs.oss.support, which the doc does not mention — creates the catalog and scans correctly;
  • the qualified oss://bucket.<endpoint>/path warehouse also scans, and oss:/path is rejected at CREATE CATALOG;
  • the no-credential REST example was exercised against a real Apache Gravitino 1.3.0 lance-rest service, which vends the bare OSS-native spellings;
  • the conflicting-spelling error was reproduced.

Scope

Every statement on the page was exercised against a live bucket, including oss.session_token: an STS triple obtained through AssumeRole scans the table, and the same temporary key pair without the token fails to initialize the catalog with OSS's own InvalidAccessKeyId / "The Security Token may be lost to specify that it is a STS Access Id". That negative control is what shows the token is carried through to the BE rather than the scan succeeding by some other route.

A path-style addressing note was written and then removed: Alibaba Cloud OSS uses virtual-hosted addressing and its public endpoints no longer accept path-style requests, so there was no configuration to confirm it against.

apache/doris#67157 lets a Lance catalog reach Alibaba Cloud OSS, but the
page still listed only local, file:// and s3:// warehouses.

Add an OSS section beside the existing S3 one, note the qualified
oss://bucket.oss-<region>.aliyuncs.com/path form and the bucket
requirement, and name the OSS properties a REST catalog can use as
defaults. Also state that namespace-vended credentials take precedence
over the catalog's own, and that Doris accepts both the oss_ prefixed and
the bare OSS-native spellings of the vended options - the shape a real
Lance REST namespace hands back.

Both the English and zh-CN copies are updated.
Alibaba Cloud OSS uses virtual-hosted addressing and the public endpoints
no longer accept path-style requests, so there is no configuration this
note usefully applies to and none that could be exercised to confirm it.
Documenting the switch would only invite readers to try a setting whose
behaviour is unverified.
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.

1 participant