From f8197d13ec5bb7ad5728876e578e994706d4de5c Mon Sep 17 00:00:00 2001 From: Xuanwo Date: Fri, 27 Feb 2026 12:34:36 +0800 Subject: [PATCH] docs: update file versioning matrix for 2.2 rollout --- docs/src/format/file/versioning.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/src/format/file/versioning.md b/docs/src/format/file/versioning.md index 13fbdd89724..67684c95be9 100644 --- a/docs/src/format/file/versioning.md +++ b/docs/src/format/file/versioning.md @@ -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.|