New InfoReporter for CTable. Example on how to use a .b2z file.

Author: FrancescAlted

examples/ctable/indexing.py

@@ -5,7 +5,7 @@
 # SPDX-License-Identifier: BSD-3-Clause
 #######################################################################
 
-# CTable indexing: create, query, rebuild, and drop indexes on columns.
+# CTable indexing with mixed dtypes, persistent sidecars, and a packed .b2z bundle.
 
 import shutil
 import tempfile
@@ -19,79 +19,77 @@
 class Measurement:
     sensor_id: int = blosc2.field(blosc2.int32())
     temperature: float = blosc2.field(blosc2.float64())
-    region: int = blosc2.field(blosc2.int32())
+    region: str = blosc2.field(blosc2.string(max_length=12), default="")
+    active: bool = blosc2.field(blosc2.bool(), default=True)
+    status: str = blosc2.field(blosc2.string(max_length=12), default="")
 
 
-# -------------------------------------------------------------------------
-# In-memory table
-# -------------------------------------------------------------------------
+def load_rows(table: blosc2.CTable, nrows: int = 240) -> None:
+    regions = ["north", "south", "east", "west"]
+    for i in range(nrows):
+        region = regions[i % len(regions)]
+        active = (i % 7) not in (0, 6)
+        status = "alert" if i % 23 == 0 else ("warm" if i % 11 == 0 else "ok")
+        table.append([i, 12.5 + (i % 40) * 0.35, region, active, status])
 
-t = blosc2.CTable(Measurement)
-for i in range(200):
-    t.append([i, 15.0 + (i % 30) * 0.5, i % 4])
 
-# Create a bucket index on 'sensor_id' (default kind).
-idx = t.create_index("sensor_id")
-print("Index created:", idx)
-print("Stale?", idx.stale)
+bundle_path = Path("indexed_measurements.b2z").resolve()
+workspace = Path(tempfile.mkdtemp())
+table_path = workspace / "indexed_measurements.b2d"
 
-# The where() call automatically uses the index when possible.
-result = t.where(t["sensor_id"] > 180)
-print("Rows with sensor_id > 180 (via index):", len(result))
-print("sensor_ids:", sorted(int(v) for v in result["sensor_id"].to_numpy()))
+pt = None
+packed = None
 
-# List all indexes on the table.
-print("\nAll indexes:", t.indexes)
-
-# After mutating the table the index is marked stale and where() falls
-# back to a full scan automatically — results are still correct.
-t.append([999, 42.0, 2])
-idx = t.index("sensor_id")
-print("\nAfter append, stale?", idx.stale)
-
-result_stale = t.where(t["sensor_id"] == 999)
-print("Row with sensor_id=999 (scan fallback):", len(result_stale))
-
-# Rebuild the index to make it current again.
-idx = t.rebuild_index("sensor_id")
-print("\nAfter rebuild, stale?", idx.stale)
-
-result_rebuilt = t.where(t["sensor_id"] == 999)
-print("Row with sensor_id=999 (via rebuilt index):", len(result_rebuilt))
-
-# Drop the index.
-t.drop_index("sensor_id")
-print("\nIndexes after drop:", t.indexes)
+try:
+    pt = blosc2.CTable(Measurement, urlpath=str(table_path), mode="w")
+    load_rows(pt)
+
+    # Create a couple of indexes on columns with different dtypes.
+    idx_sensor = pt.create_index("sensor_id", kind=blosc2.IndexKind.FULL)
+    idx_active = pt.create_index("active")
+    print("Indexes created:", pt.indexes)
+    print("sensor_id stale?", idx_sensor.stale)
+    print("active stale?", idx_active.stale)
+
+    # Queries can combine indexed and non-indexed predicates.
+    recent_active = pt.where((pt["sensor_id"] >= 180) & pt["active"] & (pt["region"] == "north"))
+    print("\nLive rows with sensor_id >= 180, active=True, region='north':", len(recent_active))
+    print("sensor_ids:", recent_active["sensor_id"].to_numpy().tolist())
+    print("statuses:", recent_active["status"].to_numpy().tolist())
+
+    # Close the table, pack the TreeStore into a single .b2z file, and reopen it.
+    del pt
+    pt = None
 
-# -------------------------------------------------------------------------
-# Persistent table
-# -------------------------------------------------------------------------
+    if bundle_path.exists():
+        bundle_path.unlink()
 
-tmpdir = Path(tempfile.mkdtemp())
-path = str(tmpdir / "measurements.b2d")
+    store = blosc2.TreeStore(str(table_path), mode="r")
+    try:
+        packed_path = store.to_b2z(filename=str(bundle_path), overwrite=True)
+    finally:
+        store.close()
 
-try:
-    pt = blosc2.CTable(Measurement, urlpath=path, mode="w")
-    for i in range(200):
-        pt.append([i, 15.0 + (i % 30) * 0.5, i % 4])
+    print(f"\nPacked bundle created at: {packed_path}")
 
-    pidx = pt.create_index("sensor_id")
-    print("\nPersistent index created:", pidx)
+    packed = blosc2.open(str(bundle_path), mode="r")
+    print("Reopened object type:", type(packed).__name__)
+    print("Indexes after reopen from .b2z:", packed.indexes)
 
-    # Sidecar files are stored under <table.b2d>/_indexes/sensor_id/
-    index_dir = Path(path) / "_indexes" / "sensor_id"
-    sidecars = list(index_dir.glob("**/*.b2nd"))
-    print(f"Sidecar files: {len(sidecars)}")
+    # Query directly against the .b2z bundle; no unpack step is needed.
+    warm_active = packed.where(packed["active"] & (packed["status"] == "warm") & (packed["sensor_id"] > 100))
+    print("\nRows from .b2z with active=True, status='warm', sensor_id > 100:", len(warm_active))
+    print("sensor_ids:", warm_active["sensor_id"].to_numpy().tolist())
+    print("regions:", warm_active["region"].to_numpy().tolist())
 
-    result_p = pt.where(pt["sensor_id"] > 190)
-    print("Rows sensor_id > 190:", len(result_p))
-
-    # Close and reopen — the index catalog is persisted.
-    del pt
-    pt2 = blosc2.open(path)
-    print("\nAfter reopen, indexes:", pt2.indexes)
-    result_p2 = pt2.where(pt2["sensor_id"] > 190)
-    print("Rows sensor_id > 190 (after reopen):", len(result_p2))
+    print("\nThe packed file is kept on disk.")
+    print(f"Inspect it later with: f = blosc2.open({bundle_path.name!r}, mode='r')")
+    print("Then call: f.info()")
+    print("For a quick check of the available info entry point, print: f.info")
 
 finally:
-    shutil.rmtree(tmpdir, ignore_errors=True)
+    if packed is not None:
+        del packed
+    if pt is not None:
+        del pt
+    shutil.rmtree(workspace, ignore_errors=True)