Skip to content

Docs: Add format v3 implementation status - #18062

Open
manuzhang wants to merge 7 commits into
apache:mainfrom
manuzhang:codex/docs-v3-status
Open

manuzhang wants to merge 7 commits into
apache:mainfrom
manuzhang:codex/docs-v3-status

Conversation

@manuzhang

@manuzhang manuzhang commented Sep 11, 2026 •

Copy link
Copy Markdown
Member

Summary

  • add V3 capability coverage and refresh data type and operation status across all five libraries
  • define Data Types Y as schema support plus both value reads and writes in a supported data file format; mark Java and PyIceberg geometry/geography N because schema recognition alone is insufficient
  • present version-dependent data types, table metadata, and table operations in table-format tabs, combining identical ranges as V1 - V2 and V1 - V3
  • retain Table Spec subtitles at their original heading levels
  • use the default theme template, tab behavior, and automatically generated heading anchors
  • show PyIceberg's V3 SQL/Glue/Hive create/update limitations in separate catalog tabs
  • correct released Go transform/DV-read/manifest-rewrite status, PyIceberg delete planning/reading and location updates, Rust HMS updates, and C++ SQL catalog support
  • audit against the published library releases listed below rather than unreleased branch heads

Closes #17308.

Audit scope

Published releases audited, with review findings rechecked on 2026-09-22:

  • Java 1.11.0: 6976e020b8
  • PyIceberg 0.12.0: 75396614a5
  • Rust 0.10.1: 04ae06bdb1
  • Go 0.6.0: 350ae7270d
  • C++ 0.3.0: 0284683f7e

Testing

  • git diff --check
  • make -C site lint
  • .venv/bin/python3 -m mkdocs build
  • local browser review of heading hierarchy and ten tab groups; rebuilt HTML checks confirm default theme configuration and generated heading anchors without custom spans, IDs, or support footnotes
  • local mocked-HTTP diagnostics for PyIceberg V3 REST create and seven metadata-maintenance operations (client request paths, not live catalog integration tests)
  • PyIceberg 0.12.0 value-level checks with PyArrow 23.0.1: nanosecond timestamps (with/without timezone) and unknown nulls round-trip through write_file and ArrowScan; geometry/geography inputs fail schema compatibility with both GeoArrow extensions and binary fallback

AI Disclosure

  • Model: GPT-5
  • Platform/Tool: Codex
  • Human Oversight: partially reviewed
  • Prompt Summary: Audit Apache Iceberg implementation status against published releases, correct verified review findings, and preserve tabbed Table Spec tables with consolidated identical version ranges and original heading levels using default theme behavior.

@github-actions github-actions Bot added the docs label Sep 11, 2026
Consolidate versioned operation tables, track v3-specific capabilities, and refresh implementation status across language libraries.

Generated-by: Codex

Co-authored-by: Codex <codex@openai.com>
@manuzhang
manuzhang marked this pull request as draft September 12, 2026 14:46
Present version-independent capabilities in a shared table and use open-ended version notation where features continue beyond their introduction.\n\nGenerated-by: Codex
Record the released library versions used by the status page and remove capability claims that depend on unreleased commits.\n\nGenerated-by: Codex
Identify data types by the format version that introduced them while preserving the existing libraries introduction.\n\nGenerated-by: Codex
Place the shared Spec column explanation before the first status table that uses it.\n\nGenerated-by: Codex
@manuzhang
manuzhang marked this pull request as ready for review September 20, 2026 02:52
@RussellSpitzer

Copy link
Copy Markdown
Member

I think it's definitely good to add this information but i'm not quite sure about the format. Did we just not to copy the compatibility section for V3? Having multiple roles for support based on the version seems a little harder to read imho.

@manuzhang

Copy link
Copy Markdown
Member Author

Did we just not to copy the compatibility section for V3? Having multiple roles for support based on the version seems a little harder to read imho.

I think it will be easier to compare between versions. With more versions incoming, it's hard to maintain them copying almost identical table every time.

Comment thread site/docs/status.md Outdated
| uuid | V1+ | Y | Y | Y | Y | N |
| fixed | V1+ | Y | Y | Y | Y | Y |
| binary | V1+ | Y | Y | Y | Y | Y |
| variant | V3+ | Y | Y | N | Y | N |

@nssalian nssalian Sep 21, 2026 •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this isn't right. variant is only supported in java, rust, go. python is pending. c++ is pending as well, that's rightly marked here

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for catching this. I will do another round of review.

@manuzhang
manuzhang marked this pull request as draft September 21, 2026 02:02
Comment thread site/docs/status.md

## Table Maintenance Operations

### Table Spec V1

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems easier to read for a user. We could combine like the PR does but keeping it this way (per version) tells a user what to expect in each version rather than infer from one Spec version column. Combining does make it leaner but I don't know if that really matters, I'd lean on simplicity.

Correct type support for PyIceberg, Go, and C++, and mark C++ V3 metadata and row-lineage writes according to the 0.3.0 release.

Generated-by: Codex

Co-authored-by: Codex <codex@openai.com>
@manuzhang
manuzhang force-pushed the codex/docs-v3-status branch 5 times, most recently from f1c6d5e to 1ef76e3 Compare September 21, 2026 15:35
@manuzhang
manuzhang marked this pull request as ready for review September 21, 2026 15:37
@manuzhang

Copy link
Copy Markdown
Member Author

@RussellSpitzer @nssalian I'm using tabbed table now. Each Table Spec gets its own tab or one merged tab if their contents are identical.

Comment thread site/overrides/status.html Outdated

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: is there a way to not override the template? Curious why need extra logic here

@manuzhang
manuzhang force-pushed the codex/docs-v3-status branch 3 times, most recently from 58cea0a to b7de469 Compare September 22, 2026 13:19
Correct released-library status and distinguish REST-dependent V3 metadata maintenance from local catalog writes. Require schema and value read/write support for Data Types Y, and mark schema-only geospatial support N. Preserve combined-version tabs and original heading levels with default theme behavior.

Generated-by: Codex

Co-authored-by: Codex <codex@openai.com>

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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: Implementation Status page missing Table Spec V3 breakdown

4 participants