中核概念

オブジェクト

概念	一言で
Workbook	作業コンテナ(≠ファイル)。テーブル・シート・版・ポリシーを束ねる
Source	アップロードされた原本(immutable)。auto(全自動)/staged(analyze → parse-spec 修正 → materialize の明示制御)
Table	型付き・行 ID 付き・版管理されたデータセット。エージェントの主対象。base(編集可)と derived(transform の出力)がある
Transform	SQL(Jinja2)/ Python のテンプレート。{{ arg }} を args で入力テーブルに束縛し、出力 artifact を作る。lineage の単位
Sheet	データを持たない表示用 composition。blocks がテーブルを参照(n:m)し、render で xlsx に合成
Chart	エージェントが作るチャート。config と recipe(生成に使ったツールとパラメータ)を持つ
Version	versions.commit(label) = snapshot への不変ラベル。revert は snapshot 機構(DAG 再実行)で派生テーブルを復元 — base テーブルの行編集は edits ログ側の履歴で管理
Job	非同期操作のハンドル(async=true アップロード等)。jobs.wait() か webhook job.completed
Workspace	境界オブジェクト(メンバー・課金・ガバナンス)。開発者は Account API key で複数の workspace を管理できる

行編集と楽観ロック

すべての書き込みは expected_version(テーブルの etag)必須です。ズレていたら 409 — SDK は ConflictError を投げます。自動リトライはしません(並行編集を黙って上書きしないため): 再読込(rows() が edit_version を返す)→ 再適用 → リトライ、がコントラクトです。

page = client.tables.rows(wb, "売上明細")
client.tables.upsert_rows(
    wb, "売上明細",
    rows=[{"__d2b_row_id": 3, "金額": 999}],   # row_id 指定 = 更新、なし = 追加
    expected_version=page["edit_version"],
)

冪等性

SDK は全変異呼び出しに Idempotency-Key を自動付与します(同一キー + 同一ボディは初回応答を再生)。ネットワーク再試行で二重適用は起きません。HTTP を直接叩く場合はヘッダを自分で付けてください。

昇格モデル(raw は黙って消えない)

auto 取り込みは、シートを忠実に取り込んだ元の表から、D2B が構造化した表を作ります。構造化した表がファイル名を引き継ぎ、元の表は state=archived に降格します(レジストリ・lineage は残る)。tables.lineage() で元の表まで遡れ、元のシートは必要なら tables.unarchive() で再実体化できます。structuring=defer では元の表が先に着地し、構造化が終わった時点で同じ昇格が起きます。そのとき元の表の上に派生物を作っていた場合、昇格は自動的に見送られます(下流を壊さない)。

鮮度(staleness)

行編集など対話的な書き込みは、下流の派生テーブルを即時再計算せず stale マークします。GET .../tables/{name} の freshness: {stale, stale_since} で分かり、POST /workbooks/{id}/recompute(MCP recompute_stale)で依存順にまとめて再計算します。transform の実行は eager に伝播します(出力は常に新鮮)。

ガバナンス

列タグ × ロールのポリシー(mask / deny)はデータ層で強制されます。マスク列は型付き NULL で返り、masked_columns で通知。GET .../tables/{name}/access で事前に dry-run できます。export・profile・MCP・生ファイル preview まで同じポリシーが効き、迂回路はありません(governed workbook では生バイトの preview / revise は拒否されます)。

行の JSON Schema(constrained decoding 用)

静的な OpenAPI はテーブルの中身までは型付けできません(行の形はデータ依存)。そのため各テーブルの「1 行分の JSON Schema」を実行時に取得できます:

GET /api/v1/workbooks/{wb}/tables/{name}/schema?format=json-schema

MCP では get_schema(..., include_json_schema=true)。返る schema は列ポリシー適用後の列集合から生成され(deny 列は現れない)、additionalProperties: false・全セル nullable・__d2b_row_id は「省略 = insert / 指定 = update」。エージェントハーネスはこれを使って upsert_rows のペイロードを生成時に拘束(constrained decoding)できます。

履歴

• snapshot: 不変の commit。POST /snapshots / POST /snapshots/{id}/restore
• version: snapshot への名前(POST /versions、POST /versions/{label}/revert)
• op log: すべての変異を順序付きで記録(GET /ops)。行 op は POST /ops/{id}/undo で逆適用(履歴は append-only)
• branch / merge: POST /export に record_branch=true でエクスポート時の行を凍結し、編集されたファイルを POST /tables/{name}/merge で行 ID キーのセル単位 3-way merge。両側で変わったセルは conflict キューへ