書く
クローン、コミット、push。作業メタデータ、書き込みの順番、push が断られるとき。
作業メタデータ
書き手は作業メタデータに書きます。データセットの外にある、SQLite の DuckLake メタデータです。手元のパソコンでもホストのコンテナでも、作業メタデータは 1 種類です。
DATA_INLINING_ROW_LIMIT 0で ATTACH し、すべての行をデータファイルに書かなければならない- データパスはデータセットのデータフォルダ(
<root><data_dir>)。新しいデータファイルはデータセットに書かれる。HTTP 越しのデータセットだけは例外で、新しいデータファイルは書き手のマシンのフォルダに書き、push がそれを上げる(HTTP での push) ducklake_expire_snapshotsとducklake_cleanup_old_filesを流してはいけない
段階
| 段階 | すること |
|---|---|
| クローン | ブランチのバージョンのメタデータから作業メタデータを作り、そのバージョンを覚える。最初のバージョンの前は空のものを作る |
| コミット | 作業メタデータの最後のスナップショットを新しいバージョンに固める。親は覚えておいたバージョン。親の宣言に書き手のツールが加えた変更を合わせて、tables.json を書く |
| push | データファイルを確かめ、テーブルごとに profile を測り(任意)、メタデータ、tables.json・profile、version.json の順にアップロードし、条件付きで ref を動かす |
書き手は、Git が git push までコミットを手元に置くのと同じく、コミットしたバージョンを手元に置いてあとで push してかまいません。push までデータセットは変わりません。例外は作業メタデータがデータセットに書いたデータファイルで、どのバージョンもまだ参照していないので、push しないままなら猶予期間のあとに削除されます。
クローンでは、DuckLake の管理用の表を、固めたメタデータから SQLite へそのまま写します。固めるときはその逆で、最後のスナップショットとそれが読む行だけを残します。どちらもデータファイルは書き換えません。
固めるとき、書き手は次のことをしなければなりません。
- 行をメタデータの中に持つ作業メタデータを断る
- 最後のスナップショットだけを残す。前のスナップショット、それより前に終わった行、削除予定のファイルは入れない(固めたメタデータ)
- 固めたメタデータの
data_pathを<root><data_dir>の絶対 URL にする - 絶対パスで記録されたデータファイルや、
data_dirの外のデータファイルがあれば断る
変更がないとき
書き手は、親と同じ中身のバージョンを作らないようにするべきです。Git が親と同じ tree のコミットを作らないのと同じです。次のどちらかなら、親と同じ中身です。
- 最後のスナップショットが親のもの(
ducklake.snapshot_id)と同じ - 同じ表とビューが同じ宣言で並び、
dependenciesが同じで、どの表も列の名前と型が同じで、行が同じ(重複を数え、順番は問わない)
比べるのはテーブル・ビューとその宣言、dependencies だけです。その外にある言葉(DuckLake の comment など)の変更だけではバージョンはできません。言葉をテーブルの行として持つ場合は、その行が変わればバージョンができます(宣言)。同じ入力から作り直した表は新しいデータファイルに書かれるので、ファイルやメタデータのバイトを比べても判定できません。書き手はまずファイルを比べ、ファイルが違う表だけ行を読みます。行を読めないときはバージョンを作ります。頼まれたときは、git commit --allow-empty と同じく、変更がなくても作ってかまいません。
元に戻す
前のバージョンが持っていたものに戻す書き手は、git revert が新しいコミットを作るのと同じく、新しいバージョンを作ります。ブランチを後ろに動かしません。ブランチは既定では前にしか進まず(ref)、読む人が間のバージョンをすでに使っていることがあるためです。
新しいバージョンの親は、作業メタデータをクローンしたバージョンです。ほかのコミットと同じく、その後にブランチが動いていれば push は断られます。テーブルとビューは前のバージョンのスナップショットの時点と同じ列・同じ行・同じ宣言を持ち、dependencies も前のバージョンのものにします。作業メタデータは新しいスナップショットでその状態にします。前のバージョンに無いテーブルは消し、その後に変わったテーブルは前のスナップショットの時点の行から書き直します。前のバージョンのテーブルは、マージで相手側を読むのと同じく、そのバージョンのメタデータから読みます。
ブランチ
ブランチは、あるバージョンに refs/heads/<名前> を作ると作れます(ref)。ブランチでの作業も、main と同じくクローン・commit・push で行います。ブランチのバージョンは、マージするまで main の履歴に入りません。
マージ
マージは、別のブランチでの変更を、書いているブランチに取り込みます。書き手は次の 3 つのバージョンから結果を作ります。
- 自分側: 書いているブランチで、作業メタデータをクローンしたバージョン
- 相手側: 別のブランチのバージョン
- 基点: 自分側と相手側に共通の祖先のうち、ほかの共通の祖先がどれもその子孫にならないもの。
parentsはすべての要素をたどる。該当するものが 2 つ以上あるとき、書き手はマージを断る
基点が相手側なら、取り込むものはありません。基点が自分側なら、新しいバージョンを作らずにブランチを相手側へ動かします。それ以外では、書き手はマージのバージョンを作ります。その parents は自分側、相手側の順で、ほかの commit と同じく、ブランチがその後に動いていれば push は断られます。基点のメタデータとそのスナップショットが残っている必要があり、保持期間を過ぎた基点からはマージを断ります。
テーブル
2 つのバージョンで schema.table が同じテーブルを、同じテーブルとみなします。テーブルごとに 3 つのバージョンを比べます。列とその型、宣言、行(重複を数え、順番は問わない)が同じなら、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 は、マージのバージョンを最初の親である自分側と比べます。
書き込みの順番
- データファイル・アセット
versions/<ID>/metadata.db(とmetadata/)versions/<ID>/tables.json・versions/<ID>/profiles/versions/<ID>/version.json- ref(条件付き)
途中で止まった書き手は、読み手に見えるものを何も変えていません。残ったファイルはどの ref からも参照されず、その中のデータファイルは猶予期間のあとに消されます。
バージョンのファイルは一度だけ書きます。既に同じ中身のファイルがあれば先へ進み、違う中身なら止まります。
push が断られるとき
古い作業メタデータからの push は、次の 2 つの確認で断られます。
- 新しいバージョンが、いまブランチが指すバージョンの子孫でない。ほかの人が先に push した
- メタデータが参照するデータファイルがデータセットに無い。ホストは行が持つアセットも確認してよい。有効なバージョンから猶予期間より長く参照されなかったファイルは、書き手が見つけたあとでも消されていることがある
ホストは、tables.json が version.json と合わない push や、メタデータが参照するデータファイルと削除ファイルを tables.json が列挙していない push も断ります(HTTP での push)。
書き手は、クローンしたときと別の data_dir を fdl.json が示しているときも、commit と push を断ります(data_dir を変える)。
ホストは、自分の規則で push を断ってもかまいません。primary_key の無いテーブルがある、ホストが求めるライセンスや説明が無い、などです。規則は形式では決めず、ホストが断った理由を返します。書き手はホストが求めたところを直し、commit し直して push します。
どの場合も、書き手はクローンし直し、作業をやり直して、もう一度 push します。1 つめの確認で断られた場合は、代わりにブランチを自分の作業にマージしてもかまいません。データセットを片付ける必要はありません。断られたバージョンはどの ref からも参照されていません。