dr.David
Rhodus
The bookREFERENCE COLLECTION Contents
Appendix L200 / 232

Experiment Warehouse Schema Catalog

Operating Quantum Computers · 3 min read

This appendix sketches warehouse tables and event schemas for quantum experiment operations.

L.1 Top-level entity map

DIAGRAM
Diagram loads as you read
L.1 Top-level entity map · Figure 1
View diagram source
erDiagram
    PROJECT ||--o{ EXPERIMENT : owns
    EXPERIMENT ||--o{ RUN : contains
    RUN ||--o{ ARTIFACT : produces
    RUN ||--o{ EVENT : emits
    RUN ||--o{ METRIC : reports
    RUN ||--o{ COST_RECORD : incurs
    RUN }o--|| TARGET_SNAPSHOT : uses
    RUN }o--|| SOURCE_VERSION : built_from

L.2 experiment table

Field Type Notes
experiment_id string immutable identifier
project_id string parent project
owner string accountable owner
objective string testable objective
assurance_level string L0, L1, L2, L3
status string draft, active, archived
created_at timestamp creation time

L.3 run table

Field Type Notes
run_id string immutable identifier
experiment_id string parent experiment
workload_type string sampling, estimation, AHS, annealing, hybrid
run_class string exploratory, benchmark, decision
target_snapshot_id string immutable target profile
source_version_id string source hash and repository
submitted_at timestamp submission time
completed_at timestamp completion time
status string completed, failed, canceled

L.4 target_snapshot table

DIAGRAM
Diagram loads as you read
L.4 targetsnapshot table · Figure 2
View diagram source
flowchart LR
    Backend[Backend] --> Snapshot[Target snapshot]
    Calibration[Calibration] --> Snapshot
    Capabilities[Capabilities] --> Snapshot
    Policy[Policy] --> Snapshot
Field Type Notes
target_snapshot_id string hash or immutable ID
provider string vendor or internal platform
backend string target name
captured_at timestamp snapshot time
capability_profile json gates, timing, dynamic control, shots
calibration_hash string calibration data hash
status string healthy, degraded, retired

L.5 artifact table

Field Type Notes
artifact_id string immutable identifier
run_id string parent run
artifact_type string source, circuit, counts, trace, plot, review
uri string storage URI
content_hash string hash for integrity
schema_version string artifact schema
retention_class string exploratory, decision, regulated

L.6 Event schema

Illustrative listing · json
{
  "event_id": "evt_01",
  "run_id": "run_20260419_001",
  "timestamp": "2026-04-19T17:00:00Z",
  "event_type": "runtime.submitted",
  "attributes": {
    "quantum.workload.type": "estimation",
    "quantum.target.id": "ibm_fez",
    "quantum.circuit.hash": "sha256:...",
    "quantum.shots.requested": 10000
  }
}

L.7 Metric schema

Field Type Notes
metric_id string immutable identifier
run_id string parent run
name string metric name
value float/string metric value
unit string shots, seconds, USD, probability
method string how computed
created_at timestamp metric timestamp

Recommended metrics:

DIAGRAM
Diagram loads as you read
L.7 Metric schema · Figure 3
View diagram source
flowchart TB
    Metrics[Metrics] --> Quality[quality]
    Metrics --> Cost[cost]
    Metrics --> Capacity[capacity]
    Metrics --> Repro[reproducibility]
    Quality --> Fidelity[fidelity / objective]
    Cost --> Spend[spend]
    Capacity --> Queue[queue wait]
    Repro --> Hash[artifact completeness]

L.8 Cost record

Field Type Notes
cost_record_id string immutable identifier
run_id string parent run
provider string cost source
cost_type string shots, reservation, simulator, storage, labor
amount decimal amount
currency string currency
allocation_key string team, project, customer

L.9 Claim schema

DIAGRAM
Diagram loads as you read
L.9 Claim schema · Figure 4
View diagram source
erDiagram
    CLAIM ||--o{ CLAIM_SUPPORT : uses
    CLAIM_SUPPORT }o--|| RUN : references
    CLAIM ||--o{ CLAIM_REVIEW : receives

    CLAIM {
        string claim_id
        string text
        string assurance_level
        string status
        string owner
    }
Field Type Notes
claim_id string immutable identifier
text string approved claim text
assurance_level string L0-L3
status string draft, approved, superseded, retracted
owner string accountable owner
approved_at timestamp approval time

L.10 Warehouse quality flow

DIAGRAM
Diagram loads as you read
L.10 Warehouse quality flow · Figure 5
View diagram source
flowchart LR
    Raw[Raw ingestion] --> Schema[Schema check]
    Schema --> Hash[Hash check]
    Hash --> Lineage[Lineage check]
    Lineage --> Policy[Policy check]
    Policy --> Publish[Publish]
    Policy --> Quarantine[Quarantine]

Quarantine incomplete runs rather than silently publishing them.

L.11 Common lineage query

Illustrative listing · sql
select
  c.claim_id,
  c.text,
  r.run_id,
  ts.backend,
  ts.calibration_hash,
  a.uri
from claim c
join claim_support cs on c.claim_id = cs.claim_id
join run r on cs.run_id = r.run_id
join target_snapshot ts on r.target_snapshot_id = ts.target_snapshot_id
join artifact a on r.run_id = a.run_id
where c.status = 'approved'
  and ts.status = 'degraded';

L.12 Schema evolution

DIAGRAM
Diagram loads as you read
L.12 Schema evolution · Figure 6
View diagram source
stateDiagram-v2
    [*] --> DraftSchema
    DraftSchema --> ActiveSchema: approved
    ActiveSchema --> DeprecatedSchema: new version active
    DeprecatedSchema --> ArchivedSchema: retention expired

Schema evolution rules:

  • never mutate old evidence in place
  • version every schema
  • keep readers for old decision-grade evidence
  • record migrations as artifacts
  • test lineage queries after every schema change

Additional technical sources: [R267].