---
title: バージョンと ref
description: バージョンは固めたメタデータと記録、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_at`
- `metadata`: メタデータファイルの大きさと sha256。読み手は取得したものを確かめられます
- `tables`: `tables.json` の大きさと sha256
- `ducklake`: メタデータの DuckLake 形式と、固めたときのスナップショット

ID は、Git のコミットと違って中身のハッシュではありません。同じメタデータでも、DuckDB のリリースが違うと別のバイト列になるので、中身のハッシュは安定しません。中身は `metadata` の sha256 で確かめます。

項目の一覧は、仕様の[バージョン](/ja/spec/versions)にあります。

## スナップショットとバージョン

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 つのバージョンで違うテーブルは衝突になります。マージのために付けた行番号は主キーになりません。どの行が同じ行かを示さないためです。[マージ](/ja/spec/writing#マージ)を参照してください。

バージョンを取り消すためにブランチを後ろへ戻すのは、明示的に指示したときだけできます。取り消したバージョンも、リポジトリと履歴には残ります。

## 履歴

`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
```

保持期間を過ぎたバージョンも履歴に残ります。記録はそのままで、メタデータだけがありません。[保持期間](/ja/internals/inside-a-repository#保持期間を過ぎたバージョン)を参照してください。
