---
title: 書く
description: クローン、コミット、push。作業メタデータ、書き込みの順番、push が断られるとき。
---

## 作業メタデータ

書き手は作業メタデータに書きます。データセットの外にある、SQLite の DuckLake メタデータです。手元のパソコンでもホストのコンテナでも、作業メタデータは 1 種類です。

- `DATA_INLINING_ROW_LIMIT 0` で ATTACH し、すべての行をデータファイルに書かなければならない
- データパスはデータセットのデータフォルダ（`<root><data_dir>`）。新しいデータファイルはデータセットに書かれる。HTTP 越しのデータセットだけは例外で、新しいデータファイルは書き手のマシンのフォルダに書き、push がそれを上げる（[HTTP での push](/ja/spec/http#書き方)）
- `ducklake_expire_snapshots` と `ducklake_cleanup_old_files` を流してはいけない

## 段階

| 段階 | すること |
| --- | --- |
| クローン | ブランチのバージョンのメタデータから作業メタデータを作り、そのバージョンを覚える。最初のバージョンの前は空のものを作る |
| コミット | 作業メタデータの最後のスナップショットを新しいバージョンに固める。親は覚えておいたバージョン。親の[宣言](/ja/spec/versions#宣言)に書き手のツールが加えた変更を合わせて、`tables.json` を書く |
| push | データファイルを確かめ、テーブルごとに profile を測り（任意）、メタデータ、`tables.json`・profile、`version.json` の順にアップロードし、条件付きで ref を動かす |

書き手は、Git が `git push` までコミットを手元に置くのと同じく、コミットしたバージョンを手元に置いてあとで push してかまいません。push までデータセットは変わりません。例外は作業メタデータがデータセットに書いたデータファイルで、どのバージョンもまだ参照していないので、push しないままなら猶予期間のあとに削除されます。

クローンでは、DuckLake の管理用の表を、固めたメタデータから SQLite へそのまま写します。固めるときはその逆で、最後のスナップショットとそれが読む行だけを残します。どちらもデータファイルは書き換えません。

固めるとき、書き手は次のことをしなければなりません。

- 行をメタデータの中に持つ作業メタデータを断る
- 最後のスナップショットだけを残す。前のスナップショット、それより前に終わった行、削除予定のファイルは入れない（[固めたメタデータ](/ja/spec/versions#固めたメタデータ)）
- 固めたメタデータの `data_path` を `<root><data_dir>` の絶対 URL にする
- 絶対パスで記録されたデータファイルや、`data_dir` の外のデータファイルがあれば断る

## 変更がないとき

書き手は、親と同じ中身のバージョンを作らないようにするべきです。Git が親と同じ tree のコミットを作らないのと同じです。次のどちらかなら、親と同じ中身です。

- 最後のスナップショットが親のもの（`ducklake.snapshot_id`）と同じ
- 同じ表とビューが同じ宣言で並び、`dependencies` が同じで、どの表も列の名前と型が同じで、行が同じ（重複を数え、順番は問わない）

比べるのはテーブル・ビューとその宣言、`dependencies` だけです。その外にある言葉（DuckLake の `comment` など）の変更だけではバージョンはできません。言葉をテーブルの行として持つ場合は、その行が変わればバージョンができます（[宣言](/ja/spec/versions#宣言)）。同じ入力から作り直した表は新しいデータファイルに書かれるので、ファイルやメタデータのバイトを比べても判定できません。書き手はまずファイルを比べ、ファイルが違う表だけ行を読みます。行を読めないときはバージョンを作ります。頼まれたときは、`git commit --allow-empty` と同じく、変更がなくても作ってかまいません。

## 元に戻す

前のバージョンが持っていたものに戻す書き手は、`git revert` が新しいコミットを作るのと同じく、新しいバージョンを作ります。ブランチを後ろに動かしません。ブランチは既定では前にしか進まず（[ref](/ja/spec/refs)）、読む人が間のバージョンをすでに使っていることがあるためです。

新しいバージョンの親は、作業メタデータをクローンしたバージョンです。ほかのコミットと同じく、その後にブランチが動いていれば push は断られます。テーブルとビューは前のバージョンのスナップショットの時点と同じ列・同じ行・同じ宣言を持ち、`dependencies` も前のバージョンのものにします。作業メタデータは新しいスナップショットでその状態にします。前のバージョンに無いテーブルは消し、その後に変わったテーブルは前のスナップショットの時点の行から書き直します。前のバージョンのテーブルは、マージで相手側を読むのと同じく、そのバージョンのメタデータから読みます。

## ブランチ

ブランチは、あるバージョンに `refs/heads/<名前>` を作ると作れます（[ref](/ja/spec/refs)）。ブランチでの作業も、`main` と同じくクローン・commit・push で行います。ブランチのバージョンは、マージするまで `main` の履歴に入りません。

## マージ

マージは、別のブランチでの変更を、書いているブランチに取り込みます。書き手は次の 3 つのバージョンから結果を作ります。

- 自分側: 書いているブランチで、作業メタデータをクローンしたバージョン
- 相手側: 別のブランチのバージョン
- 基点: 自分側と相手側に共通の祖先のうち、ほかの共通の祖先がどれもその子孫にならないもの。`parents` はすべての要素をたどる。該当するものが 2 つ以上あるとき、書き手はマージを断る

基点が相手側なら、取り込むものはありません。基点が自分側なら、新しいバージョンを作らずにブランチを相手側へ動かします。それ以外では、書き手はマージのバージョンを作ります。その `parents` は自分側、相手側の順で、ほかの commit と同じく、ブランチがその後に動いていれば push は断られます。基点のメタデータとそのスナップショットが残っている必要があり、保持期間を過ぎた基点からはマージを断ります。

### テーブル

2 つのバージョンで `schema.table` が同じテーブルを、同じテーブルとみなします。テーブルごとに 3 つのバージョンを比べます。列とその型、[宣言](/ja/spec/versions#宣言)、行（重複を数え、順番は問わない）が同じなら、2 つのバージョンは同じテーブルを持っています。

| 自分側と相手側（基点との比較） | マージのバージョンが持つもの |
| --- | --- |
| どちらも変えていない、または両方が同じように変えた | そのテーブル |
| 片方だけが変えた、追加した、または削除した | その側のテーブル。削除したならテーブルは無い |
| 片方が削除し、もう片方が変えた | 衝突 |
| 両方が違うように変えた、または違うものを追加した | 下の主キーでのセルのマージか主キーの無いテーブルの行のマージ、または衝突 |

ビューは SQL と宣言で比べます。両方がビューを違うように変えたときは、SQL と宣言をそれぞれ 1 つの値としてマージします。片方だけが変えたものはその側の変更を取り、両方が違う値に変えたものは衝突です。

`dependencies` も名前ごとに同じようにマージします。片方だけが追加・変更・削除した項目はその側の変更を取り、両方が違うように変えた項目は衝突です。

コメント（DuckLake の `comment`）は比べませんが、マージのバージョンに残します。テーブル・ビュー・列のコメントはそれぞれ 1 つの値としてマージします。片側だけが変えたコメントは、テーブルをどちらの側から取ったかによらず、その側の変更を取ります。両側が違う値に変えたときは ours を残し、書き手は警告を出します。

### 主キーでのセルのマージ

両方がテーブルを違うように変えたとき、書き手はセルごとにマージします。セルは 1 つの行が 1 つの列に持つ値で、行は主キーの値で識別します。テーブルは自分側・相手側・基点で同じ `primary_key` を持つか、基点にそのテーブルが無い必要があります。`primary_key` がこれらの間で違うテーブルや、一部だけが `primary_key` を持つテーブルは衝突です。

- `primary_key` 以外の宣言は、ビューと同じく 1 つの値としてマージする
- 基点にある列は `tables.json` の `id` で対応を取るので、列名の変更はその列の変更として扱う。これはテーブルが基点とその側で同じ DuckLake のテーブル ID を持つときだけで、同じ名前で作り直したテーブルは列名で対応を取る。基点のあとに追加した列は名前で対応を取る。片方だけが追加・列名の変更・削除・型の変更をした列は、その側の変更を取る。両方が違うように変えた列や、片方が削除しもう片方がセルを変えた列は衝突
- 片方が型を変えた列で、もう片方が変えたセルは新しい型にキャストする。キャストできない値のセルは衝突
- 片方だけが追加・削除した行は、その側の変更を取る。片方が削除し、もう片方がセルを変えた行は衝突。両方が追加した行は、値が同じなら残し、違えば衝突
- 両方が残した行では、片方だけが変えたセルはその側の値を取り、両方が違う値に変えたセルは衝突。`NULL` どうしは同じ値とする
- 片方だけが追加した列では、もう片方だけが追加した行はその列の既定値か `NULL` を持つ。列が `NOT NULL` で既定値が無いときは、そのテーブルは衝突

3 つのバージョンのどれかで、キーに `NULL` を持つ行か、同じキーが 2 回以上現れるテーブルは衝突です。マージのために作ったキー（行番号など）は主キーではありません。どの行が同じ行かを表さないためです。

### 主キーの無いテーブルの行のマージ

自分側・相手側・基点のどれでも `primary_key` の無いテーブルを両方が違うように変えたとき、書き手は行を多重集合としてマージします。行はすべての列の値の組で、書き手は各行が基点・自分側・相手側にいくつあるかを数えます。

- 宣言は、ビューと同じく 1 つの値としてマージする。列とその型は自分側と相手側で同じでなければならず、違えば衝突
- 行ごとに、片方の数だけが基点と違うときは、その側の数を取る。両方が基点と違い、数が同じなら、その数を取る。両方が違い、数も違うなら、その行は衝突
- 値の変更は、行の削除と追加として扱う。両方が同じ行を違うように変えたときは、どちらも古い行を消して自分の行を足すので、マージのバージョンは新しい行を両方持つ

書き手は、主キーの無いテーブルをこの方法でマージするとき、警告してかまいません。

### 衝突

衝突が 1 つでもあれば、マージはバージョンを作りません。書き手は衝突をテーブルごとに、セルなら主キーの値と列とともに並べ、データセットは何も変えません。マージする人は、衝突しないようにどちらかのブランチを変えてから、もう一度マージします。

### マージのバージョン

作業メタデータは自分側からクローンし、新しいスナップショットで結果を持ちます。データファイルは新しく書いてもよく、相手側から丸ごと取り込むテーブルなら相手側と同じファイルを参照してもかまいません。`diff` は、マージのバージョンを最初の親である自分側と比べます。

## 書き込みの順番

1. データファイル・アセット
2. `versions/<ID>/metadata.db`（と `metadata/`）
3. `versions/<ID>/tables.json`・`versions/<ID>/profiles/`
4. `versions/<ID>/version.json`
5. ref（条件付き）

途中で止まった書き手は、読み手に見えるものを何も変えていません。残ったファイルはどの ref からも参照されず、その中のデータファイルは猶予期間のあとに消されます。

バージョンのファイルは一度だけ書きます。既に同じ中身のファイルがあれば先へ進み、違う中身なら止まります。

## push が断られるとき

古い作業メタデータからの push は、次の 2 つの確認で断られます。

1. 新しいバージョンが、いまブランチが指すバージョンの子孫でない。ほかの人が先に push した
2. メタデータが参照するデータファイルがデータセットに無い。ホストは行が持つアセットも確認してよい。有効なバージョンから猶予期間より長く参照されなかったファイルは、書き手が見つけたあとでも消されていることがある

ホストは、`tables.json` が `version.json` と合わない push や、メタデータが参照するデータファイルと削除ファイルを `tables.json` が列挙していない push も断ります（[HTTP での push](/ja/spec/http#リクエスト)）。

書き手は、クローンしたときと別の `data_dir` を `fdl.json` が示しているときも、commit と push を断ります（[data_dir を変える](/ja/spec/layout#data_dir-を変える)）。

ホストは、自分の規則で push を断ってもかまいません。`primary_key` の無いテーブルがある、ホストが求めるライセンスや説明が無い、などです。規則は形式では決めず、ホストが断った理由を返します。書き手はホストが求めたところを直し、commit し直して push します。

どの場合も、書き手はクローンし直し、作業をやり直して、もう一度 push します。1 つめの確認で断られた場合は、代わりにブランチを自分の作業にマージしてもかまいません。データセットを片付ける必要はありません。断られたバージョンはどの ref からも参照されていません。
