作業カタログ

書き込みをする場所です。SQLite の DuckLake カタログで、バージョンからチェックアウトし、次のバージョンに固めます。

作業カタログは、書き手のディスクかコンテナにある、SQLite ファイルの DuckLake カタログです。書き込むのはここだけです。Git の作業ツリーにあたり、バージョンから作り、自由に変え、変更ができたら次のバージョンにします。

流れ

チェックアウトでは、DuckLake の管理用の表を、固めた DuckDB ファイルから SQLite へそのまま写します。固めるときはその逆です。どちらも Parquet ファイルは書き換えないので、大きなデータセットでもすぐ終わります。カタログは小さく、データはその場に残ります。

SQLite を使う理由

作業カタログは、DuckDB から書けて、作業をまたいで残せる必要があります。SQLite はデータベースサーバーなしでその両方ができ、手元のパソコンでもコンテナでも同じように動き、DuckDB の形式との間で欠けなく写せます。

作業カタログは 1 種類です。利用者の代わりに書くホスト（定期の取り込みや Web のフォームなど）も、人がパソコンでするのと同じ手順でチェックアウトし、書き、コミットします。2 つが同時にコミットしたときは、ref の条件付き書き込みで決まります。一方が通り、もう一方はチェックアウトし直します。

ATTACH の仕方

fdl checkout が、作業カタログを ATTACH する文を表示します。

ATTACH 'ducklake:work/lake.sqlite' AS lake (
  DATA_PATH 's3://my-bucket/towns/data/', OVERRIDE_DATA_PATH true,
  META_TYPE 'sqlite', DATA_INLINING_ROW_LIMIT 0,
  META_JOURNAL_MODE 'WAL', BUSY_TIMEOUT 5000
);

• DATA_PATH はリポジトリのデータフォルダです。新しい Parquet ファイルは、読み手が探す場所に書かれます。HTTP 越しのリポジトリでは、かわりに作業カタログの隣のフォルダになり、新しいファイルは fdl commit が上げます（HTTP での push）
• DATA_INLINING_ROW_LIMIT 0 で、行をカタログの中に入れないようにします。バージョンはカタログの中に行を持てないので、行を持つ作業カタログは fdl commit が断ります
• META_TYPE 'sqlite' は省略できません。省くと DuckDB がファイルから種類を推測し、SQLite が受け付けないオプションを渡してしまいます

コミット前に書かれたデータファイル

DuckLake は書くそばから Parquet を書くので、データファイルは、それを参照するバージョンより先にリポジトリに届きます。読み手には見えません。読み手はバージョンのカタログしか開かず、まだどのバージョンもそのファイルを参照していないからです。

どこからも参照されないまま猶予期間（既定で 7 日）を過ぎたファイルは、保守で消されることがあります。その前にコミットしてください。参照しているファイルが無いと言われてコミットが断られたら、作業カタログで表を作り直してコミットし直してください。

作業カタログのスナップショット

作業カタログで ducklake_expire_snapshots や ducklake_cleanup_old_files を流さないでください。これらは作業カタログしか見ないので、ほかのバージョンが参照しているファイルまで消してしまいます。古いバージョンとファイルの片付けは、リポジトリ全体を見て行います（保持期間を参照）。