コンテンツにスキップ
FDL
Esc
↑↓移動↵開く⌘Jプレビュー
このページの内容

書く

クローン、コミット、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 は、マージのバージョンを最初の親である自分側と比べます。

書き込みの順番

  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)。

書き手は、クローンしたときと別の data_dir を fdl.json が示しているときも、commit と push を断ります(data_dir を変える)。

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

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

このページは役に立ちましたか?