Skip to content

docs: update file versioning matrix for 2.2 rollout #6033

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Xuanwo merged 1 commit into from
Feb 27, 2026
Merged

docs: update file versioning matrix for 2.2 rollout #6033

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 13 additions & 9 deletions docs/src/format/file/versioning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,22 @@ major number is changed when the file format itself is modified while the minor
strategy is modified. Newer versions will typically have better performance and compression but may not be readable
by older versions of Lance.

In addition, the latest version of the file format (next) is unstable and should not be used for production use cases.
In addition, the `next` alias points to an unstable format version and should not be used for production use cases.
Breaking changes could be made to unstable encodings and that would mean that files written with these encodings are
no longer readable by any newer versions of Lance. The `next` version should only be used for experimentation and
benchmarking upcoming features.

The `stable` and `next` aliases are resolved by the specific Lance release you are using. During a format rollout
(for example, 2.2), prefer explicit version pinning for deterministic behavior across environments.

The following values are supported:

| Version | Minimal Lance Version | Maximum Lance Version | Description |
| -------------- | --------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| 0.1 | Any | 0.34 (write) | This is the initial Lance format. It is no longer writable. |
| 2.0 | 0.16.0 | Any | Rework of the Lance file format that removed row groups and introduced null support for lists, fixed size lists, and primitives |
| 2.1 (unstable) | None | Any | Enhances integer and string compression, adds support for nulls in struct fields, and improves random access performance with nested fields. |
| legacy | N/A | N/A | Alias for 0.1 |
| stable | N/A | N/A | Alias for the latest stable version (currently 2.0) |
| next | N/A | N/A | Alias for the latest unstable version (currently 2.1) |
| Version | Minimal Lance Version | Maximum Lance Version | Description |
| -------------- | --------------------- | --------------------- | ----------- |
| 0.1 | Any | 0.34 (write) | This is the initial Lance format. It is no longer writable. |
| 2.0 | 0.16.0 | Any | Rework of the Lance file format that removed row groups and introduced null support for lists, fixed size lists, and primitives |
| 2.1 | 0.38.1 | Any | Enhances integer and string compression, adds support for nulls in struct fields, and improves random access performance with nested fields. |
| 2.2 (unstable) | None | Any | Adds support for newer nested type/encoding capabilities (including map support) and 2.2-era storage features. |
| legacy | N/A | N/A | Alias for 0.1 |
| stable | N/A | N/A | Alias for the latest stable version in the Lance release you are running. |
| next | N/A | N/A | Alias for the latest unstable version in the Lance release you are running.|