バージョンと ref
バージョンは固めたメタデータと記録、ref はバージョンを指す名前です。DuckLake のスナップショットや Git のコミットとの関係も説明します。
バージョン
バージョンは、固めた DuckLake メタデータ 1 つと、それがどうできたかの記録です。自分のフォルダに置かれ、一度書いたら変わりません。
versions/019a3c4e-7b21-7f3a-9c55-2f0d8e1a4b6c/
version.json 記録: 親、作者、メッセージ、チェックサム
metadata.db 固めたメタデータ
tables.json テーブル・データファイル・ビュー・宣言の一覧
記録には次のことを書きます。
id: バージョン ID。UUIDv7 なので作った順に並び、2 人の書き手が同じ ID を作ることはありませんseq: 人に見せる番号。親のseqに 1 を足した数ですparents: 積んだ元のバージョン。最初のバージョンでは空ですauthor、message、created_atmetadata: メタデータファイルの大きさと sha256。読み手は取得したものを確かめられますtables:tables.jsonの大きさと sha256ducklake: メタデータの DuckLake 形式と、固めたときのスナップショット
ID は、Git のコミットと違って中身のハッシュではありません。同じメタデータでも、DuckDB のリリースが違うと別のバイト列になるので、中身のハッシュは安定しません。中身は metadata の sha256 で確かめます。
項目の一覧は、仕様のバージョンにあります。
スナップショットとバージョン
DuckLake は書き込みのたびにスナップショットを作ります。INSERT、CREATE TABLE、ALTER をそれぞれのトランザクションで流すたびに 1 つです。1 日の作業で数百になることもあります。バージョンは、作業ができたと判断したときに作り、その時点の最後のスナップショットを取ります。
スナップショットとバージョンの関係は、作業ブランチのコミットと、それを squash して main に入れたコミットの関係と同じです。スナップショットは commit_message や commit_extra_info と一緒にメタデータの中に残るので、細かい履歴は失われません。version.json には、親から足したスナップショットの範囲だけを書き、中身は写しません。
ref
ref は、バージョン ID と改行だけを書いたファイルです。読み手は ID を知らなくても、ref からバージョンを見つけられます。
refs/heads/main 019a3c4e-7b21-7f3a-9c55-2f0d8e1a4b6c
refs/tags/2025-final 019a2f10-0c4d-7e88-a1b2-55c0d9e3f7aa
HEAD ref: refs/heads/main
| 種類 | パス | 動くか |
|---|---|---|
| ブランチ | refs/heads/<name> |
前へだけ動く |
| タグ | refs/tags/<name> |
動かない |
| リクエスト | refs/requests/<number> |
ホストが決める |
| HEAD | HEAD |
めったに動かない |
読み手がほかを指定しなければ、main を読みます。Git と同じく、HEAD が main を指します。タグは、読み手が頼れるバージョンを固定します。たとえばある年の確定値です。refs/requests/ はホストのためのものです。承認待ちのバージョンを、main に載せずにここで持てます。
リポジトリの中で変わるファイルは ref だけです。ほかのファイルは一度しか書きません。
ブランチを動かす
ブランチは前へだけ動きます。新しいバージョンが main になれるのは、いま main が指すバージョンの子孫であるときです。子孫とは、parents をたどるとそのバージョンに着くバージョンです。Git でいう fast-forward です。
main → A
Alice が A をクローンし、B(親 A)をコミットして push: main → B
Bob も A をクローンしていて、C(親 A)をコミットして push: 断られる
C は B の上に積まれていないので、Bob の push は断られます。受け付けると、誰も決めていないのに B が main の履歴から消えてしまいます。Bob は B をクローンし、変更をやり直します。新しいバージョンの上でのやり直しは、たいてい同じ SQL を実行し直すだけで済みます。
マージ
時間のかかる作業は自分のブランチで進め、できあがったら main にマージします。
main → A → B
\
feature C
main で fdl merge refs/heads/feature を実行すると M(親 B、C)ができる: main → M
マージは、テーブルごとに B、C、両者の共通の祖先 A の 3 つのバージョンを比較します。片方のブランチだけが変えたテーブルは、そのブランチの内容を取り込みます。両方が同じテーブルを変えたときは、3 つのバージョンで宣言した primary_key で行を照合し、片方だけが変えたセルを取り込みます。両方が違う値に変えたセルは衝突になり、バージョンは作りません。主キーの無いテーブルは行の多重集合としてマージし、片方だけが追加・削除した行を取り込みます。主キーが 3 つのバージョンで違うテーブルは衝突になります。マージのために付けた行番号は主キーになりません。どの行が同じ行かを示さないためです。マージを参照してください。
バージョンを取り消すためにブランチを後ろへ戻すのは、明示的に指示したときだけできます。取り消したバージョンも、リポジトリと履歴には残ります。
履歴
fdl log は、ref が指すバージョンから最初のバージョンまで、最初の親をたどります。
3 019a4b… 2026-11-01T09:00:00Z alice
Correct the 2026 figures
2 019a3c… 2026-10-15T09:00:00Z bob
Add 2026
1 019a2f… 2026-10-01T09:00:00Z alice
First towns
保持期間を過ぎたバージョンも履歴に残ります。記録はそのままで、メタデータだけがありません。保持期間を参照してください。