[lucasfang]

Purpose

Linked issue: close #466

Correct statements the implementation contradicts and bring the feature, build-switch, plugin-target and system-table lists up to date. The substantive errors: compaction.rst documented compaction.file-size, an option that has never existed, and parquet.enable-dictionary, renamed to parquet.enable.dictionary in #263; primary_key_global_index.rst stated commit message v12, raised to 13 in #247; write.rst said object-store paths require REST catalog commit mode, although table.cpp also accepts WithCatalog(). The stale lists: README now covers primary-key commit and all seven registered formats instead of three, building.rst gains PAIMON_ENABLE_MOSAIC, PAIMON_ENABLE_VORTEX and PAIMON_ENABLE_NETWORK_TESTS, build_system.rst gains four plugin targets, basic_concepts.rst gains Vortex, which removes its contradiction with data_types.rst, and system_tables.rst goes from 4 documented suffixes to all 15. The coverage gaps: api/catalog.rst adds Table, Database and CatalogOptions, catalog.rst documents the Table::NewScan, NewRead, NewWrite and NewCommit entry points added in #434 as equivalent to the Create() calls, and code-style.md adds the missing hooks, clang-tidy check groups and testing utilities. The code examples: the MapSharedShreddingAccessBuilder comment in an installed public header called builder->AddKey() on the Result<std::unique_ptr<...>> that Create() returns and dropped the Status from AddKey, blob_defs.h qualified its own constants as Blob:: where no such members exist, the credential provider example in catalog.rst called make_shared<MyCredentialProvider>(path, options) against a class declaring no such constructor, and manifest_entry_cache.rst built an LruCache whose header lives in src/ and is never installed. Two more compiled on their own but broke at the use their own comment documents: variant.h assigned builder.Build("v") to auto field and then told the reader to pass it to SetReadSchema, which rejects a Result, and the SetReadSchema example in read_context.h discarded the [[nodiscard]] arrow::Status returned by arrow::ExportSchema. That one now follows examples/read_write_demo.cpp, the user-facing precedent, because the internal PAIMON_RETURN_NOT_OK_FROM_ARROW macro is not installed.

Tests

Comment and prose only, so no unit or integration test applies. Verified locally: pre-commit run --files over the sixteen changed files passes, including Sphinx Lint, codespell, clang-format and trailing-whitespace, and git diff --check is clean. Every correction was taken from the source rather than assumed: option names from defs.cpp and parquet_format_defs.h, the compaction threshold from CoreOptions::GetCompactionFileSize(), the commit-message version range from CommitMessageSerializer::Deserialize, the object-store commit modes from the guard in table.cpp, plugin targets from each add_paimon_lib call together with the add_subdirectory guards that establish which of them build unconditionally, system-table semantics from the class comments in metadata_system_tables.h and global_system_tables.h, and the testing-utility entries from the implementations themselves. The cross-reference and doxygen-target checks over docs/source/ still resolve; the doxygen target count rises from 89 to 92 with the three added classes. All five C++ examples were extracted into translation units and built with g++ -std=c++17 -fsyntax-only before and after the fix, and each pair behaves as intended: the pre-fix version fails with the mismatch its fix targets and the fixed version compiles cleanly. The failures are base operand of '->' has non-pointer type 'Result<unique_ptr<MapSharedShreddingAccessBuilder>>', 'kExtensionTypeKey' is not a member of 'paimon::Blob', no matching function for call to 'MyCredentialProvider::MyCredentialProvider(...)', cannot convert 'Result<unique_ptr<ArrowSchema>>' to 'unique_ptr<ArrowSchema>', and ignoring returned value of type 'arrow::Status', declared with attribute 'nodiscard'. Two of them need the harness to state the defect: the variant.h example compiles on its own, so its unit also performs the SetReadSchema call the comment prescribes, and discarding a [[nodiscard]] value is only a warning, so the read_context.h unit adds -Werror=unused-result. The LruCache fix is prose about header availability, so it was checked against the install rules instead: CMakeLists.txt installs only include/, and ScanContextBuilder::WithCache takes the public Cache interface.

API and Format

No. Comments and prose only: no declaration, signature, symbol or behavior changes anywhere. Three installed public headers are touched — include/paimon/data/shredding/map_shared_shredding_schema_utils.h, include/paimon/data/variant.h and include/paimon/read_context.h — and only inside their /// examples, so the generated API documentation changes while the ABI and the source compatibility of MapSharedShreddingAccessBuilder, VariantAccessBuilder and ReadContextBuilder do not. No storage format or protocol is affected. Two statements now record the current facts rather than change them: CommitMessageSerializer writes version 13 and reads versions 3 through 13, and an object-store commit accepts either CommitContextBuilder::WithCatalog() or UseRESTCatalogCommit(), the two being mutually exclusive.

Documentation

This change is itself the documentation work; it introduces no new feature. Sixteen files: twelve documentation ones — README.md, docs/code-style.md, docs/source/basic_concepts.rst, docs/source/build_system.rst, docs/source/building.rst, docs/source/api/catalog.rst and, under docs/source/user_guide/, catalog.rst, compaction.rst, manifest_entry_cache.rst, primary_key_global_index.rst, system_tables.rst and write.rst — plus comment-only example fixes in four headers, include/paimon/data/shredding/map_shared_shredding_schema_utils.h, include/paimon/data/variant.h, include/paimon/read_context.h and src/paimon/common/data/blob_defs.h. Two known gaps are deliberately left out because they need new prose rather than corrections: the realtime module has 16 exported types with no user guide or API page, and roughly thirty further exported classes that the user guide explains at length have no API reference page.

Generative AI tooling

Generated-by: Qoder

[lxy-9602]

It seems that sys.catalog_options has requires_catalog=false. With the corresponding option enabled, we might be able to load directly via path.

[lxy-9602]

Changelog support is already in place for both the write path and the commit path.
It’s just that the overwrite commit flow will ignore the changelog file and print a warning.

[lszskye]

Vortex here

[lxy-9602]

How about removing Vortex support first?

[SteNicholas]

@lucasfang, I left two comments for documentation correctness issues. PTAL.

[SteNicholas]

Require version management for object-store commits. WithCatalog() alone does not enable object-store commits. IsCatalogCommit() requires a catalog implementing VersionManagedCatalog and advertising SupportsVersionManagement(); FileSystemCatalog falls back to rename-based commits and remains rejected on object-store paths. Please qualify this guidance to require a version-managed catalog, such as REST, so users do not follow a configuration that still fails.

[SteNicholas]

Document the public API limitation for global tables. Loading through a catalog does not currently provide the advertised read path. FileSystemCatalog::GetTable(Identifier("sys", "tables")) reaches TableSchemaExists(), which rejects system tables. TableScan::Create() and TableRead::Create() also call LoadFromPath(), which leaves the catalog null even when WithCatalog() was supplied. Listing and schema lookup work, but reading sys.all_table_options, sys.tables, and sys.partitions through the public API does not. Please document that limitation instead of presenting catalog loading as a working alternative.

[zjw1111]

after #447 merged, docs maybe need check again