lance-format

Lance v13 リファレンス

Lance はマルチモーダル AI 向けのオープンなカラムナ形式です。「ランダムアクセスでは Parquet より 100 倍高速なカラムナデータ形式」です。単一の形式ではなく、相互運用する仕様群で構成されます。ファイル形式、テーブル形式、インデックス形式、カタログ仕様、名前空間クライアント仕様があります。lance-format/lance の Rust ワークスペースでは、これらすべてに加え、Python（pylance）および Java バインディングも実装しています。

このスキルが対象とするのは v13.0.0-beta.4（lance-format/lance の git タグ）で、現在の開発最前線です。安定版の固定バージョンは v12.0.0 で、2026-09-17 にリリースされました。main ではなくタグに固定してください。Lance は数日ごとにベータタグをリリースしており、next 形式のエンコーディングは変更される可能性があります。以下にバージョンの一覧を示します。

リファレンスは 3 層構成です。タスクに必要なものを読み込んでください。

• 詳細リファレンス - 具体的なスキーマ、パラメーター、proto、または制約を確認できます。トピックごとに分かれています。

  references/ 内のファイル	対象	セクション
  format-file.md	Lance の概要、26 個のクレート、ファイル形式、データ型	1-4
  format-table.md	データセットのレイアウト、マニフェスト、フラグメント、スキーマの進化、バージョン管理／タグ／ブランチ、行 ID、トランザクション + OCC、MemWAL	5-10
  indexes.md	ベクトル／スカラー／FTS／地理インデックス、分散ビルド	11-12
  ops.md	オブジェクトストア、機能マトリックス、ソースマップ	13, 15, 16
  changelog-v7-v13.md	v7 から v13 までの全変更点	14

  「section N」と記された相互参照は、references/lance-reference.md で確認できます。

• references/performance.md - パフォーマンスに関するすべてのガイダンスです。パート A では公式文書を案内し、上流でまだ文書化されていないソース由来の変更点を補足します。パート B では、現場で検証されたリモートストレージの運用方法を説明します。パフォーマンス、チューニング、保守コスト、または「なぜ遅いのか」という質問には、こちらを読み込んでください。

• references/docs/ - 公式ドキュメント（対象タグの docs/src）を一字一句そのまま複製したものです。すべてのガイド、クイックスタート、形式仕様が未編集のまま含まれています。公式文書の全文が必要な場合に読み込んでください。ディレクトリの構成は以下のとおりです。

references/maintenance.md では、このスキルを新しい上流タグに合わせて更新する方法を説明しています。

Lance と LanceDB

この2つは別物であり、混同すると誤った回答につながります。

• Lance - フォーマットおよびエンジンです。lance-format/lance リポジトリ、lance /lance-* Rust クレート、pylance が該当します。データセット、ファイル／テーブルフォーマット、インデックス、コミット、 スキャンを提供します。DuckDB、Polars、Ray、Spark、PyTorch、DataFusion、または独自の Rust／Python コードから直接利用できます。このスキルの対象は Lance です。
• LanceDB - Lance 上に構築された、別個のデータベース 製品（lancedb/lancedb）です。 クエリビルダー API、埋め込みレジストリ、API としてのリランカー、複数言語 SDK の 同等性、マネージドの Cloud／Enterprise ティアを追加します。ここでは扱いません。

より広いエコシステム（別リポジトリ、独自のバージョン系列で、いずれもここでは扱いません）：Flink ストリーミング 書き込み（lance-flink）、pglance による PostgreSQL の読み取り、Cypher グラフエンジン（lance-graph）、データセット ブラウザー（lance-data-viewer）、エージェント型コンテキスト管理（lance-context）、および Hive、Polaris、Gravitino、Unity Catalog、AWS Glue 用の ネームスペースカタログです。 正規のドキュメントサイトは lance.org です。言語別に生成された SDK ドキュメントは、Python 用の lance-format.github.io/lance-python-doc と、Java 用の javadoc.io にあります。対応する lance-format.github.io/lance-java-doc のパスは 404 になります。

Cargo.toml で lance クレートにリンクしている場合は、Lance を直接使っています。このスキルを利用してください。 LanceDB の内部についても、その下のストレージレイヤーは Lance なので、フォーマット自体については引き続きこのスキルが 基準になります。

ラッパーによってフォーマットの機能が隠れることがあります。 LanceDB の create_table では安定した行 ID を有効にできません。 それができるのは pylance の write_dataset(enable_stable_row_ids=True) だけです。フォーマットレベルの機能が設計上 重要な場合は、基盤となるフォーマットで解決できると決めつける前に、ラッパーがその機能を公開しているか確認してください。 公開していない場合は、pylance を直接利用してください。

クレートのワークスペース

rust/ の下に26のクレートディレクトリがあります。lance が公開エントリーポイントです。Dataset、スキャナー、 インデックス、コミットを扱います。それ以外（lance-table、lance-file、lance-encoding、lance-index、 lance-io、lance-core、lance-datafusion、lance-linalg、lance-namespace* など）は、その下のレイヤーです。Edition 2024、MSRV 1.91.0、arrow 58、datafusion 54 です。Python バインディングには 3.10 以降が必要です。役割、バージョン、すべてのワークスペース依存関係を記載した完全な 表は、references/format-file.md のセクション2にあります。

lance より下のものに依存している場合、v11 で動作しなくなります - PR #8020-#8026 で lance-encoding::version が再エクスポートなしで削除されました（LanceFileVersion と ConcreteFileVersion はどちらも 現在 lance-file::version にあります）。また、lance_io::encodings と previous 名前空間が削除され、 現在の各フォーマットに独自の versions/v2_{0,1,2,3} モジュールが設けられました。セクション2.1を参照してください。

トランザクションコードも移動しました（#8053/#8054/#8056）。rust/lance/src/dataset/transaction.rs は 削除され、代わりに rust/lance-table/src/transaction/ モジュールツリー（builder、 conflicts、operation、proto、manifest_build、validate、index_maintenance、 row_version、update_map）が導入されました。lance::dataset::transaction の shim は引き続き Operation、Transaction、TransactionBuilder、RewriteGroup、UpdateMap などを再エクスポートするため、一般的な インターフェースは変わりません。ただし、shim に含まれないシンボルや古いパスへの参照は、 新しいパスに変更する必要があります。

ファイル形式のバージョン

ファイル形式には、単一のメジャー・マイナーバージョンが設定されています。data_storage_version はデータセットの作成時に設定されますが、v12.0.0 以降は、データセットの作成後に固定されなくなりました。これは書き込み先を指定しなかった場合のデフォルトであり、データセットに含まれるデータの概要ではありません。「作成と上書きではこのデフォルトが設定されます。追加、更新、マージ挿入、コンパクションでは変更されません。」既存の V2 データセットでは、ほかのファイルを書き換えずに、操作ごとに "2.0"、"2.1"、"2.2"、"2.3" を指定できます（#8582-#8585）。そのため、1 つのデータセットに複数の厳密な V2 バージョンのデータファイルを格納できます。**V1 と V2 は引き続き混在できません。**セクション 3 を参照してください。

バージョン	ステータス	備考
0.1 (legacy)	読み取り専用	元の形式。書き込みには使用できません
2.0	安定版	行グループを削除。リスト／FSL／プリミティブ型の null をサポート
2.1	以前のデフォルト	適応型の構造エンコーディング。整数／文字列の圧縮を改善。struct フィールドの null に対応。ネストされたデータへのランダムアクセスを改善。Lance 5.0.0 から v12.0.0-beta.15 までデフォルトでした
2.2	現在のデフォルト（stable）	Map 型、Blob v2、VariablePackedStruct、より大きなミニブロック。Map と Blob v2 に必要
2.3	不安定版（next）	現在の next エイリアスの対象（列挙型の V2_3）。スパースな構造ページが導入され、2.3 の書き込み側ではレップ／デフ予算に基づくヒューリスティックにより自動選択されるようになりました

現在、stable は 2.1 ではなく 2.2 を参照します（#8657、beta.15）。また、列挙型の #[default] は 2.2 であるため、明示的な data_storage_version を指定せずに作成されたデータセットは 2.2 として書き込まれます。この変更は DataStorageFormat::default() -> stable_file_version() を通じて新しいデータセットの作成に反映され、Python の write_dataset もデフォルトで stable を経由するため、これを引き継ぎます。ドキュメントにはこの変更が反映されていません。format/file/versioning.md には、stable は「デフォルトバージョンのエイリアス」としか書かれていないため、ここではコードが正となります。next は 2.3 を参照します。ビルド間で動作を再現可能にするには、番号を明示的に指定してください。

コードで不安定版とされているのは 2.3 のみです。2.2 はこれまで不安定版とされたことはなく、現在はデフォルトで使われます。リリースのセレクター（LanceFileVersion）は、永続化される識別子（ConcreteFileVersion）とは異なる型です。詳細とスパースな構造ページの自動選択ルールについては、references/format-file.md のセクション 3.1 と 3.6 を参照してください。

バージョンの変遷

メジャーバージョンを上げるのは人ではなくボットです。ci/publish_beta.sh は、リリースの起点以降にある PR のいずれかに GitHub の breaking-change ラベルが付いている場合、MAJOR+1 を新たな起点にします。判定マーカーは ラベル であり、Conventional Commits の ! ではありません。そのため、メジャーバージョンが上がるのは「ラベル付きの破壊的変更が取り込まれた」という意味であり、再設計を示すものではありません。また、ラベルのない ! では何も上がりません。この処理は 4 系統連続 で発生しており、そのため v9.1.0、v10.1.0、v11.1.0、v12.1.0 はいずれもリリースされませんでした。12.1 系統が最も分かりやすい例です。main に chore: bump main to 12.1.0-beta.0 コミットが入り、その4コミット後にボットが起点を13に変更しました。そのため、release-root/12.1.0-beta.N と release-root/13.0.0-beta.N は 同じベースコミット（c3c9632a2）であり、v12.1.0-beta.* タグは存在しません。

最近の3系統では、最終版が リリースされています。v10.0.0（2026-08-08）、v11.0.0（2026-08-30）、v12.0.0（2026-09-17）です。いずれも main の祖先ではない 安定化ブランチ上にあります。これは Lance の最終版では通常のことであり、非公式リリースという意味ではありません。

メジャー	破壊的変更のテーマ
v13（現行、v13.0.0-beta.4）	WriteParams に file_writer_options が追加されました（#9192 - メジャーバージョンの起点を変更した、ラベル付き PR）。遅延ページメタデータ初期化により StructuralFieldScheduler のシグネチャとメタデータ キャッシュキーの形式 が変更されました（#7465）。json_extract／json_get は JSON インデックスにルーティングされなくなりました（#9101）。差分は以下を参照
v12（v12.0.0、2026-09-17）	WrappingObjectStore の実装者は wrap_paginated の追加が必要です（デフォルト実装なし）。MemWAL の ShardManifestStore は名称が変更され、対象が限定されました。lance-namespace はレスポンスオブジェクトを返すようになりました。外部ストアに前バージョンを条件とする公開機能が追加されました。ネームスペースのマージインサートキーがリストになりました。呼び出し側が提供する Writer／open_part のフローが削除されました（#9072）。ラベルなしながら、より大きな変更として、stable が 2.2 になり、IVF_RQ のデフォルトが 5-bit になりました。新たに追加されたフォーマット機能：データファイルのバージョン混在。差分は以下を参照
v11（v11.0.0、2026-08-30）	フラグメント ID がデータセットの存続期間全体で単調増加する上限値になりました。lance-file／lance-encoding が内部で大幅に再編されました。v7 以来初めてマニフェストの機能フラグが追加されましたが、最終版の前に 再割り当て されました。新たに追加：カバリングインデックス、merge_insert の write_mode、行アドレスによる事前フィルタリング。差分は以下を参照
v10	Blob API で null 選択が保持されるようになりました。キャッシュキーが不透明な BLAKE3 ダイジェストになりました（ウォームキャッシュも永続キャッシュもすべてコールドミスし、従来形式へのフォールバックはありません）。非同期の create_remapper。MemWAL の generation は SSTable に、merge は compaction に名称変更されました（ワイヤ互換性あり、シンボル互換性なし）
v9.1（未リリース、v10 に改称）	FTS／inverted の作成で block_size パラメーターを指定するようになりました。新たに追加：データオーバーレイファイル（ベースファイルを書き換えずにセル単位で更新。未安定で、環境変数による有効化が必要）、疎な構造ページ、lance-index-core
v9	Python 3.9 のサポートが終了しました。インデックス付きカラムをキャストする場合、alter_columns は即座に失敗するようになりました。FM-Index の proto 名変更により、既存の FM インデックスが読み取れなくなりました。FTS／inverted のデフォルトがオンディスク形式 v2 になりました
v8	すべてのインデックス構築が、セグメントベースの単一のライフサイクルに統合されました。新たに追加：lance-derive、FM-Index、マルチビット IVF_RQ、公開された approx_mode、TOS と GooseFS のオブジェクトストア
v7	MemWAL、ブランチ、geo／RTree インデックス、lance-select クレート、ICU FTS

v12.0.0 が安定版として固定するバージョン であり、GitHub Releases で Latest として表示されています。crates.io には 最終版のみ が登録されています（最新は lance 12.0.0 で、13.x はありません）。PyPI の pylance も同様に 12.0.0 です。そのため、ベータ版を固定するには git 依存関係が必要です。ベータ版の wheel は代わりに fury.io から、新しい名称の組織（https://pypi.fury.io/lance-format）で公開されており、現在は pylance-13.0.0b1 から b4 まで登録されています。

すべての PR 引用を含むタグごとの差分一覧：references/changelog-v7-v13.md。

v11 の差分

v10.0.0-beta.7 から最終版の v11.0.0 までに357件のコミットがあり、breaking-change ラベル付きの PR は16件（beta.16 までに14件、最終版で #8407 と #8535）でした。ほとんどの構造上の不変条件は維持されました。26個のクレート、16個のトランザクション操作、CommitConfig.num_retries は 20、arrow 58／datafusion 54、MSRV 1.91.0、Edition 2024、Python 3.10+ で、これらはすべて v13.0.0-beta.4 でも維持されています。

references/changelog-v7-v13.md に変更点の全容があります。すべての PR 引用、v7 以降のタグごとの内訳、Python／Java の API、そして各修正が必要になった条件を記載しています。「何が変わったか／自分の環境に影響があるか」という質問には、こちらを参照してください。以下では、特に影響の大きいものだけを説明します。

v11 で影響する5つの変更：

• フラグメント ID はデータセットの存続期間を通じた最大値を基準に割り当てられます（#8206）― API だけでなく、フォーマット上の不変条件です。上書きしても ID は0から再開されなくなり、削除ファイルを含む上書きフラグメントは拒否され、重複 ID を生成するコミットも拒否されます。そのため、Lance 0.16 以前で書き込まれたデータセットは引き続き読み取れる場合がありますが、コミットはできなくなります。上書き後の dataset.get_fragment(0) では、マニフェストから ID を読み取る必要があります。セクション5では、v0.10 より前の未ソートのマニフェストにおける解決時の危険性も取り上げています。この問題により、フラグメントで絞り込んだインデックスが誤ったフラグメントを対象にすることがあります。
• ファイルバージョンの型とリーダー／ライターの構成が変更されました（#8020-#8026）― lance-encoding::version は再エクスポートなしで削除されました。LanceFileVersion は PartialOrd／Ord を失ったため（#8027、#8028）、v >= LanceFileVersion::Next はコンパイルできなくなりました。FileWriter は列挙型になり、すべてのコンストラクターが削除されました。これらの変更の大半は、コンパイル時に静かにエラーになります。セクション3.6を参照してください。
• トランザクションコードが lance-table に移動しました（#8053/#8054/#8056）― 上記のクレートワークスペースに関する注記を参照してください。一般的な API は lance::dataset::transaction のシムでカバーされます。
• Operation::Project／Merge に preserves_nullability が追加されました（#8347）― null 可能性を狭める場合は、この値を設定してはいけません。また、このような射影は、並行する値の書き込みと競合するようになりました。これにより、alter_columns と競合する書き込みが、狭められたスキーマでは読み取れない null 値を挿入する可能性があった実際の問題が解消されました。セクション9.2を参照してください。
• 外部マニフェストのプロトコルが変更されました（#8499）― オブジェクトストレージが正となり、外部ストアの put-if-not-exists は予約として扱われ、保存された ETag は無視する必要があります。ETag を保持したままにすると、リーダーが正常なマニフェストを Manifest e_tag mismatch として拒否します。セクション9を参照してください。

マニフェストの機能フラグが変更され、最終版の前にビット128が再割り当てされました。 v11 では v7 以降初めて新しいビットが追加され、FLAG_UNKNOWN は128から256に移動しました。しかし、追加されたビット FLAG_MEM_WAL_INDEX_CATCHUP はその後廃止され（#8680）、v11.0.0 のリリース前に、空いたビットは FLAG_COVERED_INDEX_METADATA = 128 に割り当てられました（#8535）。最終版と v12 には、インデックスキャッチアップフラグも require_index_catchup proto フィールドもありません。index_catchup に存在しないシャードは、常に不明を意味するようになりました。リーダーとライターの両方がビット128に対応している必要があり、対応していない場合はテーブルを拒否する必要があります。セクション7を参照してください。

v11.0.0-beta.4 から beta.17 のいずれかには固定しないでください。 これらのビルドでは、ビット128をサポート対象の MemWAL フラグとして扱うため、カバリングインデックスのデータセットを拒否せずに開いてしまいます。誤った隣接要素が返され、エラーも発生しません。この問題は、ビットを引き継ぐフラグにそのまま引き継がれます。 カバリングインデックスはv11で新たに導入されたフォーマット機能です（#8535）。v13で再定義されました（#8856）。 IndexMetadata.covering_fields（protoフィールド11）は、インデックスが値を「保持する」列を指定します。そのため、これらの列のみを射影するクエリは、ベーステーブルを参照せずに回答できます。これはもはやfieldsの末尾に付加する列ではありません。「インデックスが出力する順序で、fieldsのサブセットでなければなりません。列が保持されるのは、ここに指定されている場合に限ります」。インデックスのキーにもなっている列も含まれます。また、fields[0]は引き続きキー列です。インデックスの無効化範囲は広いままです。「更新された列がfieldsに含まれるインデックスはすべて対象です。列がキーになっているか、単に保持されているだけかは問いません」。

「まだインデックスビルダーが保持値を書き込まない」という状況は変わりました。V3 IVF補助ファイルは列を物理的に保持できます。また、「リーダーは位置ではなく除外によって保持列を特定します。補助ファイルのスキーマに含まれる列のうち、量子化器の内部列ではないものはすべて保持列です」。これらの列は、新しいcovering_field_idsメタデータキーによってソースフィールドに対応付けられます。カバレッジはインデックス単位ではなく、セグメント単位になりました。「1つの論理インデックスでも、一部のセグメントだけ値を保持し、ほかのセグメントでは保持しないことがあります」。VectorQueryProto.covering_projection（フィールド15）がクエリ側のタグとして予約されており、未設定、設定済みで空、設定済みで空でない、という3つの異なる意味があります。セクション11。

ビット8はv12.0.0の正式版で使用されました。 FLAG_MIXED_DATA_FILE_VERSIONS = 1 << 8（256）は、FLAG_UNKNOWNと同じ値であることが固定された予約値ではなくなりました。アサーションはFLAG_MIXED_DATA_FILE_VERSIONS < FLAG_UNKNOWNに緩和され、FLAG_UNKNOWNは1 << 8から1 << 9（512）に移動し、ビルドは混在バージョンのデータセットを読み書きするようになりました。引き続きSTICKY_PAIRED_FLAGSに含まれています。また、片方だけが設定されたマニフェストはハードエラーになりました。「混在するデータファイルバージョンのリーダー機能ビットとライター機能ビットの一方しかマニフェストに設定されていないため、セマンティクスが未定義です」。セクション7。

ビット1024については、ドキュメントとコードの内容が異なります。コードを信頼してください。 FLAG_FRAGMENT_REUSE_INDEX = 1 << 10はrust/lance-table/src/feature_flags.rs:69で宣言されており、v13.0.0-beta.4時点では、ツリー全体でこの宣言が唯一の出現箇所です。これはFLAG_UNKNOWN（512）よりも大きく、サポート対象の集合はFLAG_UNKNOWN - 1として計算されるため、これを設定したマニフェストは拒否されます。一方、仕様ページではリーダーが「はい」、ライターが「はい」とされ、未知の境界値は2048になっています。ドキュメントは最終的に意図されている状態を説明していますが、コードでは定数が予約されただけです。現時点でタグ付きFRIを対象にビルドする場合、動作ではなく説明文を前提にビルドすることになります。

LANCE_*環境変数が2つ追加されました（AMX関連の作業によるもの、#8540）。LANCE_DISABLE_AMX（実行時のキルスイッチ）とLANCE_AMX_FP16_CC（ビルド時のコンパイラー上書き設定）です。grep時の注意点：LANCE_AMX_CFG_*とLANCE_AMX_TILE_COUNTはamx_fp16.c内のCマクロであり、環境変数ではありません。また、LANCE_FACTORはBALANCE_FACTORの一部です。単純なLANCE_*のgrepでは、実際には存在しない4つの環境変数としてすべて報告されます。

差分全体を読まずに把握しておきたい変更点： FTSにドキュメント境界の軸（DocumentGranularity、#7788）が追加されました。list_elementモードは3つ目のトリガーとなり、FTSのオンディスクフォーマットv3が必要です。20 MiBを超えるトランザクションはマニフェストの外部にスピルするようになりました（#7881）。MemWALの追いつき処理は宣言型ではなく導出型になりました（#8481）。トランザクションのprotoフィールド9はフィールド10に置き換えられ、非推奨になりました（#7432）。コンパクションに行数・バイト数の上限とフラグメント除外が追加されました（#8235、#8532）。merge_insertにwrite_modeが追加されました（#8423）。また、Pythonのコミット競合はOSErrorのサブクラスであるlance.commit.CommitConflictErrorになったため、既存のハンドラーも引き続き機能します（#8563）。引用付きの一覧はreferences/changelog-v7-v13.mdにあります。 アドレスドメインインデックスが、コンパクション済みのフラグメントを誤って対象として示さなくなりました（v11、beta.16以前）。以前はリライト時に、ZoneMapも含めて、すべてのインデックスのfragment_bitmapを新しいフラグメントIDに進めていました。しかし、ZoneMapに格納されたアドレスは、リライトによって削除されたフラグメントを指しています。Rewriteパスではresults_are_row_addrs()に応じて処理を分岐するようになりました。アドレスドメインインデックスにはdrop_rewritten_fragmentsとフルスキャンへのフォールバックを適用し、古いアドレスを使う代わりに、正確さを保ちながら速度を落とします。修復されるのは新しいコンパクションのみです。v10以前にすでに破損したインデックスは再作成が必要で、通常のメンテナンスでは自然に修復されません。更新後のfragment_bitmapによって、増分フォールドも何も行わなくなるためです。セクション11を参照してください。

正確性に関する修正は、アップグレードだけで十分かどうかで分かれています。 ほとんどは読み取りパスのみの修正で、アップグレードすれば修復されます。次の修正は該当しません。データの書き換えまたは修復が必要です：#8382、#8669、#8509、#7703、#8539、#8459、#8378、#8482、#8834（HNSWの再構築が必要です。永続化されたグラフには、グラフに含まれていないIDへのエッジが含まれている可能性があり、失われた再現率は回復しません）、#8101（NULL許容の主キーにより、merge_insertを繰り返すたびに行が気づかないうちに重複していました。既存の重複は手動で削除する必要があります）、#8511、#8427、#8513、#8839、#8904。それぞれの条件はreferences/changelog-v7-v13.mdに記載されています。

v12の差分

release-root/12.0.0-beta.Nから最終版のv12.0.0までに225件のコミットがあり、breaking-changeラベル付きのPRは7件です。beta.15で公開されていた5件に加え、最終版までの間に**#9072と#9101**が追加されました。新しいインデックス型も新しいクレートもなく、上記の構造上の不変条件はすべて引き続き有効です。ラベルは最低限を示すもので、すべてを網羅するものではありません。この系列で特に大きな動作変更が2件ありますが、どちらも従来のコミットメッセージに!が付いている一方、ラベルは付いていないため、ボットはカウントしませんでした。stableから2.2への移行（前述の#8657）と、IVF_RQの5ビットのデフォルト値（後述）です。

• WrappingObjectStore の実装者は wrap_paginated を追加する必要があります (#8606) - 「意図的にデフォルトはありません。ここを誤ると、速度がひそかに失われるか、ラッパーがひそかに失われますが、どちらも表面化しません。」ラッパーを通じたリスト処理のプッシュダウンを維持するには Some を返し、諦めて inner 経由にフォールバックするには None を返します。1つのラッパーが諦めると、チェーン全体でプッシュダウンが無効になります。オブジェクトストアをラップするものは、更新するまでコンパイルに失敗します。
• 新しいページ分割リスト処理：ObjectStore::read_dir_page (#8606) - プレフィックス直下の子を1ページ分と、不透明な再開トークンを返します。注意点：「1ページは1リクエストなので、ページに含まれる子の数が limit で要求した数より少なくても、続きがある場合があります」ページの件数が少なくなった時点で終わりとせず、トークンが None になるまで処理してください。
• MemWAL の ShardManifestStore の名称を変更し、公開範囲を縮小 (#8640) - read_latest は latest に、read_latest_uncached は refresh_latest に変更され、write は crate 内限定になりました（commit_update、claim_epoch、または initialize_shard 経由で使用してください）。既存の commit_update クロージャーを変更する必要はありません。セクション10。
• lance-namespace を 0.8.5 から 0.11.1 に更新 (#8903) - 4つの LanceNamespace メソッドが、値だけでなくレスポンスオブジェクトを返すようになりました。count_table_rows は CountTableRowsResponse、query_table は QueryTableResponse、namespace_exists と table_exists はそれぞれ専用のレスポンス型を返します。呼び出し側では値を取り出す必要があり、トレイトを実装している場合は同じシグネチャへの更新が必要です。
• 外部マニフェストストアに、先行バージョン条件付きの公開機能を追加 (#8800) - put_if_predecessor は、先行バージョンにライターが確認したものと同じ ID が含まれている場合に限り、バージョンを予約します。また commit_after は PrerequisiteFailed で失敗し、「競合にはなりません」。コンパイルを壊す変更はトレイトメソッドではなく、新しい ManifestLocation.identity フィールドです（トレイトメソッドにはすべてデフォルト実装があります）。組み込みストアでこれを実装しているものはありません。セクション9。
• 名前空間のマージ挿入キーをリストに変更 (#8915) - on は Option<String> から Option<Vec<String>> に変わり、キーの列数によって NULL の意味が変わります。単一列キーでは NULL は NULL と等しいものとして扱われ、複合キーでは SQL の等価性が使われます。「この場合、NULL キーは何にも一致しません。バイト列が完全に同じ NULL にさえ一致しません」。

lance-namespace の固定バージョンは1つではなくなりました。 #8915 で Rust クライアントが 0.12.0 に、#8979 で Java も 0.12.0 に更新されました。一方、生成モデルが on を単独の文字列として送信するため、Python のみ >=0.11.1,<0.12 のままです。3つすべてに同じバージョンを指定せず、言語ごとにバージョンを記載してください。この分岐はすでに一度変更されているため、以前の組み合わせを引き継がず、必ず再確認してください。

IVF_RQ のデフォルトが、1次元あたり1ビットから5ビットに変更 (#8936) - デフォルト設定ではインデックスサイズが約 4.4倍 に増加します（上流の 1 億行 x 768d の例では、約10.8 GiBから約47.3 GiB）。検索モード Fast は「インデックスに追加のビットが格納されていても、1ビットの符号コードのみを使用する」ため、追加分を使わずにストレージだけを消費します。オプトアウトするには、num_bits=1 を明示的に設定してください。ただし、マルチビットの距離推定と一部の再現率を犠牲にします。サイズ計算式は references/indexes.md を参照してください。

列スライスのスティッチング（#8660）は beta.9 で取り消されました (#8926) - 「#8923 の呼び出し側管理による置き換えの開発中にリリースすべきではありません」。rust/lance-file/src/concat.rs は beta.15 で再び存在しますが、取り消されたスティッチングではなく、#8923 の呼び出し側が管理するデータファイルパーツを保持しています。

proto に2つの追加がありました。 MemWAL の SsTable に in_memory_bytes、physical_rows、primary_key_bytes が追加されました（フィールド3～5、#8981）。すべてオプションで、存在しない場合にゼロとして読み取ってはなりません。FilteredReadOptions には materialization_readahead_bytes と batch_size_bytes が追加されました（13、14）。protos/AGENTS.md の新しいルールでは、実行プランのスキーマは「永続化された Lance 形式ではなく、ワイヤープロトコルの契約」であるため、これは形式の変更ではありません。transaction.proto／ann.proto／index.proto に変更はありません。 新規追加、非破壊的な変更： プロバイダー固有の一括コピーとディープクローンの同時実行数上限（セクション 13）；Python の ObjectStoreProvider 登録（#8522）；パック済み BLOB ライターの BinaryView（#8700）；呼び出し元が管理するデータファイルパーツ（#8923）；特定のバージョンの クリーンアップ（#8617）；LanceDataset.slice()（#8059）と、6 つの追加 LanceFragment.scanner オプション（#8429）；Python のインデックス再トレーニングを復元（#8786）；名前空間管理のクローンを非推奨化し、シムに変更（#8964）。名前空間による最新バージョンの解決で、_versions/ プレフィックス全体を列挙しなくなりました（#8679）。約 34 万バージョンのテーブルでは、これは約 344 回のリストページ、つまり「純粋な I/O 待ちが約 25 秒」に相当し、すべてのオープン処理で発生していました。

アップグレードだけでなく、再ビルドまたは書き換えが必要な修正： #8779（NGRAM インデックスの再ビルド）、#8510（均一に並べ替えたフラグメントから圧縮されたデータの書き換え）、#8984（復活したインデックスの再削除）、#8837（1 行あたり約 2.7KB 未満の MemWAL シャードの修復。再オープンできません）。PR ごとの条件の全文と、アップグレードで修復されるはるかに長いリストは、references/changelog-v7-v13.md にあります。

混在するデータファイルバージョンが実装されました — もはや「6 件中 1 件」ではありません。#8581〜#8584 は v12.0.0 でリリースされ（検証、操作ごとの V2 書き込み先、データセット操作全体への伝播、圧縮先の指定）、#8585 で v13 系のバインディングから利用できるようになりました。これに伴い proto も変更されました。DataStorageFormat.version は現在「データファイル書き込み時に使用するデフォルトのフォーマットバージョン」であり、この機能が設定されると「各 DataFile のバージョンがデコード時の正規の値」になります。

進行中で、未リリース — リリース済みとして扱わないでください： 汎用ブロックの v5 圧縮は、マージ済み PR が 10 件中 1 件のままです（#8324。#8325〜#8333 はすべて未オープンです）。次に予定されている大きな依存関係の破壊的変更は #8997「arrow 59、DataFusion 55、pyo3 0.29 へのアップグレード」です。v13.0.0-beta.4 時点でまだオープンのため、引き続き arrow 58 / datafusion 54 が使われています。この変更は、未対応の PyO3 アドバイザリ 2 件（RUSTSEC-2026-0176/0177）にも影響します。rustls は RUSTSEC-2026-0285 への対応として、別途 0.23.45 に修正されました（#9212）。

v13 の差分

release-root/13.0.0-beta.N から v13.0.0-beta.4 までの66 件のコミットと、breaking-change ラベル付き PR 2 件です。新しいクレートも新しいインデックスタイプもありません。26 クレート、16 個のトランザクション操作、CommitConfig.num_retries の値 20、arrow 58 / datafusion 54、MSRV 1.91.0、Edition 2024、Python 3.10 以降はすべて変わりません。

この期間では、! とラベルの関係が逆転しました。 conventional commit の ! が付いたコミット 3 件（#7465、#9192、#9101）には、すべて breaking-change ラベルも付いています。ラベルは上限ではなく下限として扱う方針を維持してください。ただし、この期間はその食い違いを示す新たな証拠ではなく、反例です。

• WriteParams に file_writer_options が追加されました (#9192) — メジャーバージョンを引き上げた、ラベル付きの唯一の PR です。FileWriterOptions { data_cache_bytes, max_page_bytes, keep_original_array } が、Rust、Python、Java のデータセット書き込み API から利用できるようになりました。max_page_bytes がゼロの場合、エンコーダーの構築後に問題が発生するのではなく、その前に拒否されます。構造体リテラルで WriteParams を構築しているコードはコンパイルに失敗します。
• ページメタデータが遅延初期化され、メタデータキャッシュキーの形式が変わりました (#7465)。 StructuralFieldScheduler::initialize は requested_ranges を受け取るようになり、ページスケジューラーの initialize は init_ranges() と init_from_buffers(buffers, io) に分割されました。外部の実装はコンパイルに失敗します。公開 API の DecodeBatchScheduler::try_new のシグネチャは維持されています。範囲対応のエントリーポイントはクレート内限定の try_new_with_ranges です。コンパイルエラーなしで影響する点は、キャッシュが列単位の FieldDataCacheKey からページ単位の PageDataCacheKey { column_index, page_index, view_tag } に変わったことです。そのため、このアップグレードでは、ウォームキャッシュも永続化されたメタデータキャッシュもすべてコールドミスになります。その効果は明確で、「コールド状態でのポイント読み取り／範囲読み取りにおけるメタデータ IO は、列の総ページ数に依存しません」。
• json_extract と json_get は JSON インデックスにルーティングされなくなりました (#9101)。インデックスを使うのは、型指定された 4 つのアクセサー（json_get_int / _float / _bool / _string）のみです。それ以外はすべて全件スキャンにフォールバックします。これにより、「引用符付きキーを検索して何も一致しなかった」というキーの不一致、Utf8 リテラルによって Int64 の B ツリーがパニックする問題、「引用符付けは順序を保持しない（ab < ab! なのに "ab" > "ab!"）」ことによる不正な範囲という、実際に発生していた 3 つの誤答バグが修正されます。コストは通知されません。以前はインデックスが使われていた json_extract のワークロードも、エラーや実行計画の警告なしにスキャンへ切り替わります。これらの述語は型指定されたアクセサーに書き換えてください。

Fragment Reuse Index にバージョン管理されたディスク上の契約が追加されました (#9136)。InlineContent のフィールド 1 は versions から legacy_versions に改名され、index_version >= 1 の場合に使われる、タグ付きの transitions リストがフィールド 2 に追加されました。マッピングは OrderedCompaction または StablePartition のいずれか一方になりました。stable partition は「ソース行の相対的な順序を各宛先内で維持しながら、ソース行を宛先フラグメントに割り当てます」。これにより、FRI は再クラスタリング後も既存のインデックスを再利用できます。これは v0 のモデルにはなかった 2 つ目のユースケースです。物理形式は、不変の行マップ Lance ファイルで、uint16 ラベルと LSPC マジックのカウント行列を使います。重要なルールが 2 つあります。安定した行 ID とタグ付き FRI は併用できません（「書き込み側は、それらに対して index_version >= 1 を公開してはなりません」）。また、クリーンアップでは「古いアドレスの変換にまだ必要な中間トランジションを保持しなければなりません」。アップストリームでは従来の主張も修正され、「FRI は重複する書き換え間の競合を解消しません」とされています。セクション 11。

新規追加、非破壊的変更： Dataset::frag_reuse_index() が公開され (#9112)、パフォーマンスガイドに記載されました。FileFragment::write_overlay は実際の OverlayWriter を返すようになりました (#8761、引き続き環境変数で有効化)。hf_enable_resolve_cache を備えた hf:// オブジェクトストア (#9236)、Python の lance.bitmap.Bitmap、deep_clone() (#9181)、base_paths() (#9191)、update_columns(with_offsets=True) (#8891)、Java の DataStorageVersion、FileWriteOptions、ScanOptions.indexSegments が追加されました。また、名前空間のテーブル一覧取得が、ついに read_dir_page によって上限付きになりました (#9165)。inline_optimization_enabled は true から false に変更されました (#9180)。アップストリームは、エントリー数 1M で書き込みの p50 が 49% 減少した測定結果を根拠として挙げています。

パフォーマンスに関する質問

パフォーマンスに関する内容（スキャンや検索の遅さ、リモート／オブジェクトストレージのコスト、インデックスのメンテナンスコスト、メモリのサイジング、バージョンの肥大化、ベンチマークなど）については、まず references/performance.md を読み込んでください。Part A では、公式ガイダンスと、ソースから導き出された未文書化の変更を案内しています。Part B では、S3 互換ストレージで実地検証された方法を紹介しています。基本原則は リモート呼び出しを最小限にする ことです。コミット、スキャン、往復処理を減らすことが、桁違いの改善につながります。公式の 「Tuning remote scans」 セクション（v11 で導入され、v12 でも変更なし）では、クロスリージョンまたはパブリックインターネット経由のアクセスにおける出発点が示されています。クラウドのデフォルトである同時リクエスト数 64 は過剰なため、LANCE_IO_THREADS=8、 fragment_readahead=1、batch_readahead=2、io_buffer_size=64MB を設定します。これは、呼び出し量をすでに最小限にした後に行う、妥当な次の手段です。

AMX-FP16（#8540、beta.16）は、速度だけでなく 結果 に影響する v11 のパフォーマンス変更です。有効になる条件では、IVF のパーティション割り当てが 近似ではなく正確 になるため、再現率が向上する とともに、以前のビルドとは割り当て結果が異なります。有効になる条件は形状によって決まり（float16 + dot、dimension >= 32、num_centroids >= 32）、それ以外では従来の経路が使われます。LANCE_DISABLE_AMX=1 で無効にできますが、その場合は割り当ても近似経路に戻ります。そのため、これを設定して構築したインデックスは、設定せずに構築したインデックスと同等ではありません。

リモート処理のチューニングを始める前に知っておきたいキャッシュに関する事実が 2 つあります。Lance には常駐データキャッシュがありません（Session が保持するのはインデックスとメタデータのキャッシュだけで、デコード済みの値は保持しないため、ポイント読み取りを繰り返すたびにオブジェクトストレージの IO が再発生します）。また、DatasetBuilder::with_session を介して共有した 1 つの Arc<Session> を、複数のデータセットで利用できます。初回の検索が遅い主な原因はインデックスのページ読み込みです。対策には prewarm_index を使ってください。#7465 ではメタデータキャッシュのキーの形式が変更されるため、v13 にアップグレードした後の初回実行では、キャッシュがウォーム状態または永続化済みであっても、ページ読み込みが再度発生します。詳細とビルド時の要件については references/performance.md を参照してください。

タイムトラベルはアーカイブの仕組みではありません。 バージョン履歴は無料で保持できるように見えますが、デフォルトのクリーンアップでは 7 日より古いものはすべて削除され、クリーンアップは通常の最適化処理の一部です。そのため、古いバージョンを永続的な記録として扱う設計では、最初のメンテナンス処理で履歴が失われます。アーカイブが必要な場合は、明示的に用意してください。

公式ドキュメントのミラー

references/docs/ は、追跡対象のタグにある lance-format/lance の docs/src をそのままミラーしたもので、Markdown ファイル 45 件と図 4 点をすべて直接閲覧できます。

ディレクトリ	ファイル数	内容
guide/	14	CRUD、パフォーマンス、オブジェクトストア、分散書き込みとインデックス作成、JSON、トークナイザー、データ型、データの進化、blob、配列、タグ／ブランチ、移行、オブザーバビリティ
quickstart/	4	最初のデータセット、ベクトル検索、全文検索、バージョン管理
format/	1	仕様スタックの概要
format/file/	3	コンテナー仕様、構造エンコーディングと圧縮、フォーマットのバージョン
format/table/	9	レイアウト、スキーマ、トランザクション（競合解決マトリックス）、バージョン管理、行 ID の系譜、ブランチ／タグ、MemWAL、データオーバーレイファイル
format/index/	1 + 4 svg	インデックスのライフサイクル、フラグメントのカバレッジ、コンパクションとの相互作用
format/index/scalar/	9	fts、fmindex、ngram、btree、bitmap、bloom_filter、label_list（array_has_any/all）、zonemap、rtree
format/index/vector/	1	IVF／PQ／SQ／RQ／HNSW の概念とストレージレイアウト
format/index/system/	2	フラグメント再利用インデックス、MemWAL システムインデックス
integrations/	1	Lance 上の DataFusion SQL（JSON 関数を含む）

ミラーされていないもの： docs/src/images/（PNG／GIF アセット）は含まれていないため、ミラーされたページ内の画像リンクは解決されません。本文はそれだけで完結しており、4 点の .drawio.svg 図はミラーされています。また、設計上、community/、examples/、integrations/{index,pytorch,tensorflow}.md と、ランディング用のスタブおよびコントリビューター向けファイル（format/AGENTS.md、format/CLAUDE.md）も含まれていません。

ドキュメントの階層全体がこのリポジトリには存在しないため、ミラーすることも、クローンから一覧を作成することもできません。docs/make-full-website.sh は、ビルド時に独自のバージョン系列を持つ 6 つの兄弟リポジトリから、format/catalog、format/namespace、および integrations/{duckdb,huggingface,spark,ray,trino,context} セクションを組み立てます。チェックイン済みの integrations/index.md では spark/、duckdb、trino がローカルにあるかのようにリンクされていますが、これらのパスはツリー内に存在しません。Lance Context と HuggingFace 統合のドキュメントは、ビルド済みサイトにのみ存在するナビゲーションセクション全体です。これらについては、このミラーではなく lance.org を参照してください。同様に、Protobuf メッセージ本文はビルド時に protos/ から mkdocs_protobuf によって展開されるため、ミラーされた仕様ページでは、サイト上にレンダリング済みのスキーマが表示される箇所に %%% proto.message.X %%% のプレースホルダーが表示されます。