---
title: はじめかた
description: リポジトリを作り、DuckDB で最初のバージョンを書いて、読み返します。
---

このページでは、フォルダにリポジトリを作り、表を 1 つ書き込み、読み手と同じ方法で結果を読みます。同じコマンドは S3 や R2 でも動きます。フォルダの代わりに `s3://bucket/prefix/` を渡してください。

## インストール

```bash
pip install 'fdl-cli[s3]'
```

`fdl` コマンドと `fdl` Python パッケージが入ります。Python 3.10 以上が必要です。フォルダしか使わない場合は `[s3]` を外してください。

## リポジトリを作る

```bash
fdl init ./towns/
```

`init` が書くのは次の 2 つのファイルだけです。

```
towns/
  fdl.json      {"fdl": "0.1", "id": "5f0c…", "data_dir": "data/"}
  HEAD          ref: refs/heads/main
```

`HEAD` は既定のブランチ `main` を指します。ブランチそのものはまだありません。指す先のバージョンがないためです。

`fdl init` は、サーバーで `git init --bare` を打つのと同じく、読み手が読む場所にリポジトリを作ります。手元で書く場所は、次に作る作業メタデータです。

## 作業メタデータをクローンする

リポジトリには直接書き込みません。自分のディスクにある SQLite ファイルの DuckLake メタデータ（作業メタデータ）に書き、書き終えたらそれをバージョンにします。

```bash
mkdir work && cd work
fdl clone ../towns/ lake.sqlite
```

最初のバージョンができる前は、`clone` は空のメタデータを作ります。その後は、`main` が指すバージョンのメタデータを写します。作業メタデータを ATTACH する文を表示します。

```sql
ATTACH 'ducklake:lake.sqlite' AS lake (
  DATA_PATH '/abs/path/towns/data/', OVERRIDE_DATA_PATH true,
  META_TYPE 'sqlite', DATA_INLINING_ROW_LIMIT 0,
  META_JOURNAL_MODE 'WAL', BUSY_TIMEOUT 5000
);
```

作業メタデータの隣の `lake.sqlite.fdl.json` に、リポジトリ、ブランチ、クローン元のバージョンが記録されます。

## 書く

DuckDB のクライアントなら何でも使えます。Parquet ファイルはリポジトリの `data/` フォルダに直接書かれます。

```sql
CREATE TABLE lake.main.towns AS
SELECT * FROM '../towns.csv';
```

`DATA_INLINING_ROW_LIMIT 0` を付けると、DuckLake はすべての行を Parquet に書きます。既定のままだと小さな表をメタデータの中に持ちますが、バージョンは行を、読み手が取得できるデータファイルとして持つ必要があります。

## 宣言する

行を識別する列を FDL に伝えます。マージは主キーで行を照合し、読み手は主キーで行を引けます。

```bash
fdl declare primary-key lake.sqlite main.towns code
```

宣言はコミットまで作業メタデータと一緒に保存され、コミットがテーブルと照らし合わせて確認します（[宣言](/ja/spec/versions#宣言)）。宣言は省略できます。宣言の無いバージョンはテーブルだけを持ちます。

## コミットして push する

```bash
fdl commit lake.sqlite -m "First towns" --author alice
fdl push lake.sqlite
```

`commit` は作業メタデータを固めて手元でバージョンにします。`push` はテーブルごとに、データを読まずに表示できる小さな要約（profile）を測り、バージョンと一緒にアップロードして `main` をそこへ動かし、`refs/heads/main -> 019a3c4e-… (version 1)` と表示します。リポジトリは次のようになります。

```
towns/
  fdl.json
  HEAD
  refs/heads/main                       019a3c4e-…
  versions/019a3c4e-…/
    metadata.db
    tables.json
    profiles/main/towns.json
    version.json
  tables/main/towns/ducklake-….parquet
```

```bash
fdl log ../towns/
```

```
   1  019a3c4e-…  2026-11-01T09:00:00Z  alice
      First towns
```

## 読む

```bash
fdl url ../towns/
```

`main` が指すバージョンのメタデータを表示します。読み取り専用で ATTACH し、データファイルの場所を DuckDB に渡してください。

```sql
ATTACH 'ducklake:../towns/versions/019a3c4e-…/metadata.db' AS towns (
  DATA_PATH '../towns/data/', OVERRIDE_DATA_PATH true, READ_ONLY
);
SELECT count(*) FROM towns.main.towns;
```

バージョンのメタデータは変わらないので、読み手はいつまでもキャッシュしてかまいません。変わるのは `HEAD` と `refs/` の下のファイルだけです。

## 2 つめのバージョンを作る

```bash
fdl clone ../towns/ lake.sqlite
```

```sql
INSERT INTO lake.main.towns SELECT * FROM '../towns-2026.csv';
```

```bash
fdl commit lake.sqlite -m "Add 2026" --author alice
fdl push lake.sqlite
```

新しいバージョンは、最初のバージョンを親として記録します。最初の Parquet ファイルは両方のメタデータが参照し、新しいファイルは 2 つめのメタデータだけが参照します。

途中でほかの人が push していたら、この push は断られます。新しいバージョンが、いまの `main` の上に積まれていないためです。クローンし直して、変更をやり直してください。理由は[バージョンと ref](/ja/concepts/versions-and-refs) で説明しています。
