핵심 개념

오브젝트

개념	한 줄 설명
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, "sales")
client.tables.upsert_rows(
    wb, "sales",
    rows=[{"__d2b_row_id": 3, "amount": 999}],   # row_id present = update, absent = insert
    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로 export 시점의 행을 동결하고, 편집된 파일을 POST /tables/{name}/merge로 행 ID를 키로 하는 셀 단위 3-way merge. 양쪽에서 바뀐 셀은 conflict 큐로