Skip to content

Inspect ChunkManager State

Use inspection commands before recovery or cleanup. They do not change product state.

PRODUCT_URI="file:///data/products/MY_PRODUCT.zarr"
PRODUCT_NAME="MY_PRODUCT"

List Records

List the records Firecube tracks for a product:

firecube chunks list --product-name "$PRODUCT_NAME"

Expected output resembles:

Product      Key                       Type   Size (MB)  Date
-----------------------------------------------------------------------
product.zarr span_<run>_batch_0001...  span   0.0        2026-06-03 ...
product.zarr span_<run>_batch_0000...  span   0.0        2026-06-03 ...
product.zarr <run>_schema_verification schema_verification 0.0 2026-06-03 ...

Summary: 3 chunks, 0.0 MB total

Include span coverage:

firecube chunks list --product-name "$PRODUCT_NAME" --include-span

Expected output adds a Span column:

Product      Key                       Type   Size (MB)  Date          Span
----------------------------------------------------------------------------
product.zarr span_<run>_batch_0001...  span   0.0        2026-06-03    50
product.zarr span_<run>_batch_0000...  span   0.0        2026-06-03    50

Use JSON for scripts:

firecube chunks list \
  --product-name "$PRODUCT_NAME" \
  --type span \
  --format json

Expected output includes the product, key, type, manifest URI, and metadata:

[
  {
    "product": "product.zarr",
    "key": "span_<run>_batch_0001_data",
    "type": "span",
    "size_mb": 0.0,
    "manifest": "file:///data/products/product.zarr/.firecube",
    "meta": {
      "plugin": "direct_zarr_capable_test_plugin",
      "run_id": "<run>",
      "group": "data",
      "batch_id": "batch_0001"
    }
  }
]

Filter By Coverage

Use --time-range when span records include time_min and time_max metadata:

firecube chunks list \
  --product-name "$PRODUCT_NAME" \
  --type span \
  --time-range 2024-03-15T00:00:00:2024-03-15T23:59:59

--time-range uses overlap semantics. A span is included when its time window intersects the query window.

List Runs

firecube chunks runs list --product-name "$PRODUCT_NAME"

Expected output resembles:

Run ID                               Status    State   Parts Events
------------------------------------------------------------------------
direct_zarr_capable_test_plugin-...  complete  active  2     5

Filter by status:

firecube chunks runs list \
  --product-name "$PRODUCT_NAME" \
  --status complete \
  --format json

Expected output resembles:

[
  {
    "product": "product.zarr",
    "run_id": "<run>",
    "status": "complete",
    "events": 5,
    "parts": 2,
    "stale": false,
    "error": null
  }
]

List Claims

firecube chunks claims list --product-name "$PRODUCT_NAME"

If no writer currently owns a write domain, expected output is:

No claims found.

When a claim exists, output resembles:

Product       State   Owner                 Domain
---------------------------------------------------------------------------
product.zarr  active  run-123:F024          product.zarr:zarr_region:F024

Check Snapshot Status

firecube chunks snapshots status --product-name "$PRODUCT_NAME"

If no snapshot exists:

No snapshot found for product.zarr

After a rebuild, expected output resembles:

Product:    product.zarr
Age:        3m
Cutoff:     2026-06-03T15:54:27.100797+00:00
Generation: 1780502101660654725
Records:    <count>

Use JSON for automation:

firecube chunks snapshots status \
  --product-name "$PRODUCT_NAME" \
  --format json

Next Steps