blosc2 4.2.0__tar.gz → 4.3.0__tar.gz

blosc2-4.3.0/ANNOUNCE.rst

@@ -0,0 +1,135 @@
+Announcing Python-Blosc2 4.3.0
+===============================
+
+We are happy to announce Python-Blosc2 4.3.0.  This release deepens the
+``CTable`` container with three major additions: **N-dimensional columns**,
+**group-by aggregation**, and **dictionary/categorical column types**.
+
+N-dimensional columns let each cell in a CTable hold a full compressed
+multidimensional array — ideal for embedding vectors, image patches,
+time-series windows or any per-row tensor payload.  ndarray columns support
+CSV/DataFrame round-trips, nullable semantics, and are automatically detected
+when importing from pandas.
+
+N-dimensional columns inherit the full power of Blosc2 ``NDArray`` objects.
+They are not opaque blobs, but first-class arrays that support slicing,
+indexing, and full Blosc2 operations, including multi-threaded and
+SIMD-accelerated expression evaluation. This gives ``CTable`` a strong bridge
+between tabular and array workflows in a single container.
+
+See example at: https://github.com/Blosc/python-blosc2/blob/main/examples/ctable/ndim-cols.py
+
+Group-by brings SQL-style ``GROUP BY`` directly to CTables::
+
+    by_city = t.group_by("city", sort=True)
+    by_city.agg({"sales": ["sum", "mean"], "qty": "sum"})
+
+Multi-key groupings, filtered aggregates (``where=`` pushdown), and persistent
+output (``urlpath=``) are all supported.  Behind the scenes, Cython-accelerated
+kernels deliver dramatic speedups — ~25× for float keys, ~8× for integer keys —
+backed by dense-indexing and general-purpose hash-table paths.
+
+Also, ``DictionarySpec`` introduces dictionary-encoded (categorical) columns
+that store compact integer codes mapped to a shared string dictionary, giving
+both compact storage and accelerated equality/membership queries.  Dictionary
+columns work transparently in ``where`` clauses and nested dotted-name
+expressions.
+
+Other highlights in 4.3.0 include:
+
+- **Nested columns and field-name escaping**: Columns from Arrow/Parquet struct
+  hierarchies are flattened into physical leaf columns under hierarchical
+  ``_cols`` storage paths, with logical dotted-name access preserved.
+  Round-trip fidelity is maintained for nested schemas, and literal ``.`` / ``/``
+  in field names are automatically escaped.
+
+- **Parquet import improvements**: Arrow serializer is now the default;
+  nested columns are always separated; new ``--progress``/``--max-rows``/
+  ``--timestamp-unit``/``--float-trunc-prec`` options for
+  ``parquet-to-blosc2`` CLI; and a ``list_serializer`` parameter for fine-tuning
+  list-type column storage.
+
+- **Inline CTable support in TreeStore**: CTables can now be stored as items
+  inside a ``TreeStore``, enabling hierarchical containers that mix arrays
+  and tables.
+
+- **Performance wins**: ``CTable.open()`` is faster thanks to lazy ``nrows``
+  and deferred column metainfo loading.  Scalar and small-slice access paths
+  have been overhauled.  ``import blosc2`` is leaner via late-import
+  optimizations for heavy optional dependencies.
+
+- **New tutorials and examples**: Group-by, nested fields, dictionary columns,
+  TreeStore–CTable integration, and dedicated benchmarks for group-by,
+  nested-filter, and Parquet round-trips.
+
+- **Fixes**: Null/NaN sentinel normalization, empty aggregate results,
+  generated-column safety, miniexpr bundling, and more.
+
+- **Updated C-Blosc2** to version 3.0.3 (latest).
+
+You can think of Python-Blosc2 4.x as an extension of NumPy/numexpr that:
+
+- Can deal with NDArray compressed objects using first-class codecs & filters.
+- Performs many kinds of math expressions, including reductions, indexing...
+- Supports multi-threading and SIMD acceleration (via numexpr/miniexpr).
+- Can operate with data from other libraries (like PyTables, h5py, Zarr, Dask, etc).
+- Supports NumPy ufunc mechanism: mix and match NumPy and Blosc2 computations.
+- Integrates with Numba and Cython via UDFs (User Defined Functions).
+- Adheres to modern array API standard conventions (https://data-apis.org/array-api/).
+- Can perform linear algebra operations (like ``blosc2.tensordot()``).
+- Can store and query compressed columnar tables via ``blosc2.CTable``.
+
+Install it with::
+
+    pip install blosc2 --upgrade   # if you prefer wheels
+    conda install -c conda-forge python-blosc2 mkl  # if you prefer conda and MKL
+
+For more info, you can have a look at the release notes in:
+
+https://github.com/Blosc/python-blosc2/releases
+
+Small CTable group-by example::
+
+    import blosc2
+    from dataclasses import dataclass
+
+    @dataclass
+    class Order:
+        city: str = blosc2.field(blosc2.string(max_length=16))
+        product: str = blosc2.field(blosc2.string(max_length=16))
+        qty: int = blosc2.field(blosc2.int32())
+        price: float = blosc2.field(blosc2.float64(nullable=True), default=0.0)
+
+    # Create a table with 200 random orders
+    t = blosc2.CTable(Order, new_data=orders)
+
+    # Group by city: total and average price per city in one call
+    print(t.group_by("city", sort=True).agg({"price": ["sum", "mean"], "qty": "sum"}))
+
+    # Multi-key: city + product breakdown
+    print(t.group_by(["city", "product"], sort=True).agg({"qty": "sum", "price": "mean"}))
+
+    # Filtered: only Widget orders, grouped by city
+    print(t.where(t.product == "Widget").group_by("city", sort=True).agg({"qty": "sum"}))
+
+Sources repository
+------------------
+
+The sources and documentation are managed through GitHub services at:
+
+https://github.com/Blosc/python-blosc2
+
+Python-Blosc2 is distributed using the BSD license, see
+https://github.com/Blosc/python-blosc2/blob/main/LICENSE.txt
+for details.
+
+Mastodon feed
+-------------
+
+Follow https://fosstodon.org/@Blosc2 to get informed about the latest
+developments.
+
+Enjoy!
+
+- Blosc Development Team
+  Compress Better, Compute Bigger

{blosc2-4.2.0 → blosc2-4.3.0}/CMakeLists.txt

@@ -15,7 +15,7 @@ endif()
 project(python-blosc2)
 
 set(BLOSC2_MIN_VERSION 3.0.0)
-set(BLOSC2_BUNDLED_VERSION v3.0.2)
+set(BLOSC2_BUNDLED_VERSION v3.0.3)
 
 if(WIN32 AND NOT CMAKE_C_COMPILER_ID STREQUAL "Clang")
     message(FATAL_ERROR "Windows builds require clang-cl. Set CC/CXX to clang-cl or configure CMake with -T ClangCL.")
@@ -51,6 +51,13 @@ add_custom_command(
   DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/src/blosc2/indexing_ext.pyx"
   VERBATIM)
 
+add_custom_command(
+  OUTPUT groupby_ext.c
+  COMMAND Python::Interpreter -m cython
+          "${CMAKE_CURRENT_SOURCE_DIR}/src/blosc2/groupby_ext.pyx" --output-file groupby_ext.c
+  DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/src/blosc2/groupby_ext.pyx"
+  VERBATIM)
+
 # ...and add it to the target
 Python_add_library(blosc2_ext MODULE blosc2_ext.c WITH_SOABI)
 target_sources(blosc2_ext PRIVATE src/blosc2/matmul_kernels.c)
@@ -59,10 +66,12 @@ if(UNIX)
   target_link_libraries(blosc2_ext PRIVATE ${CMAKE_DL_LIBS})
 endif()
 Python_add_library(indexing_ext MODULE indexing_ext.c WITH_SOABI)
+Python_add_library(groupby_ext MODULE groupby_ext.c WITH_SOABI)
 
 # We need to link against NumPy
 target_link_libraries(blosc2_ext PRIVATE Python::NumPy)
 target_link_libraries(indexing_ext PRIVATE Python::NumPy)
+target_link_libraries(groupby_ext PRIVATE Python::NumPy)
 
 # Fetch and build miniexpr library
 include(FetchContent)
@@ -72,6 +81,12 @@ set(MINIEXPR_BUILD_SHARED OFF CACHE BOOL "Build miniexpr shared library" FORCE)
 set(MINIEXPR_BUILD_TESTS OFF CACHE BOOL "Build miniexpr tests" FORCE)
 set(MINIEXPR_BUILD_EXAMPLES OFF CACHE BOOL "Build miniexpr examples" FORCE)
 set(MINIEXPR_BUILD_BENCH OFF CACHE BOOL "Build miniexpr benchmarks" FORCE)
+# Keep miniexpr's bundled libtcc and related files inside the blosc2 package.
+# Without this, miniexpr's install rules use the default CMAKE_INSTALL_LIBDIR
+# ("lib"), which scikit-build places at site-packages/lib.
+set(CMAKE_INSTALL_INCLUDEDIR ${SKBUILD_PLATLIB_DIR}/blosc2/include)
+set(CMAKE_INSTALL_LIBDIR ${SKBUILD_PLATLIB_DIR}/blosc2/lib)
+set(CMAKE_INSTALL_DATADIR ${SKBUILD_PLATLIB_DIR}/blosc2/share)
 
 if(EMSCRIPTEN)
   set(MINIEXPR_ENABLE_TCC_JIT ON CACHE BOOL "Enable TCC JIT in Emscripten builds" FORCE)
@@ -93,6 +108,7 @@ endif()
 
 target_compile_features(blosc2_ext PRIVATE c_std_11)
 target_compile_features(indexing_ext PRIVATE c_std_11)
+target_compile_features(groupby_ext PRIVATE c_std_11)
 if(WIN32 AND CMAKE_C_COMPILER_ID STREQUAL "Clang")
     execute_process(
         COMMAND "${CMAKE_C_COMPILER}" -print-resource-dir
@@ -131,8 +147,6 @@ else()
     set(BUILD_BENCHMARKS OFF CACHE BOOL "Build C-Blosc2 benchmarks")
     set(BUILD_FUZZERS OFF CACHE BOOL "Build C-Blosc2 fuzzers")
     set(CMAKE_POSITION_INDEPENDENT_CODE ON)
-    set(CMAKE_INSTALL_INCLUDEDIR ${SKBUILD_PLATLIB_DIR}/blosc2/include) # directory for include files
-    set(CMAKE_INSTALL_LIBDIR ${SKBUILD_PLATLIB_DIR}/blosc2/lib) # directory for libblosc2 and pkgconfig
     set(Blosc2_INSTALL_CMAKEDIR ${CMAKE_INSTALL_LIBDIR}/cmake/blosc2) # directory for cmake files
     set(CMAKE_INSTALL_BINDIR ${SKBUILD_PLATLIB_DIR}/blosc2/lib) # directory for libblosc2.dll on windows
     # we will put the binaries of the C-Blosc2 library into the wheels according to PEP
@@ -169,7 +183,7 @@ endif()
 
 # Python extension -> site-packages/blosc2
 install(
-  TARGETS blosc2_ext indexing_ext
+  TARGETS blosc2_ext indexing_ext groupby_ext
   LIBRARY DESTINATION ${SKBUILD_PLATLIB_DIR}/blosc2
 )
 
@@ -177,33 +191,3 @@ install(
   FILES "${miniexpr_SOURCE_DIR}/src/me_jit_glue.js"
   DESTINATION ${SKBUILD_PLATLIB_DIR}/blosc2
 )
-
-# Install bundled libtcc next to the Python package (separate LGPL artifact).
-if(MINIEXPR_ENABLE_TCC_JIT)
-  if(APPLE)
-    install(
-      FILES "${miniexpr_BINARY_DIR}/libtcc.dylib"
-      DESTINATION ${SKBUILD_PLATLIB_DIR}/blosc2/lib
-      OPTIONAL
-    )
-  elseif(WIN32)
-    install(
-      FILES
-        "${miniexpr_BINARY_DIR}/tcc.dll"
-        "${miniexpr_BINARY_DIR}/Debug/tcc.dll"
-        "${miniexpr_BINARY_DIR}/Release/tcc.dll"
-        "${miniexpr_BINARY_DIR}/RelWithDebInfo/tcc.dll"
-        "${miniexpr_BINARY_DIR}/MinSizeRel/tcc.dll"
-      DESTINATION ${SKBUILD_PLATLIB_DIR}/blosc2/lib
-      OPTIONAL
-    )
-  else()
-    install(
-      FILES
-        "${miniexpr_BINARY_DIR}/libtcc.so"
-        "${miniexpr_BINARY_DIR}/libtcc.so.1"
-      DESTINATION ${SKBUILD_PLATLIB_DIR}/blosc2/lib
-      OPTIONAL
-    )
-  endif()
-endif()

{blosc2-4.2.0 → blosc2-4.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: blosc2
-Version: 4.2.0
+Version: 4.3.0
 Summary: A fast & compressed ndarray library with a flexible compute engine.
 Author-Email: Blosc Development Team <blosc@blosc.org>
 Maintainer-Email: Blosc Development Team <blosc@blosc.org>

{blosc2-4.2.0 → blosc2-4.3.0}/RELEASE_NOTES.md

@@ -1,5 +1,158 @@
 # Release notes
 
+## Changes from 4.2.0 to 4.3.0
+
+### CTable: N-dimensional (ndarray) columns
+
+- **Multidimensional columns**: CTable columns can now hold NDArray-backed cells, allowing
+  each row of a column to contain a full n-dimensional compressed array.  This enables
+  use cases such as embedding vectors, image patches, time-series windows, or any other
+  multidimensional per-row payload.
+- **CSV and DataFrame import/export**: Multidimensional column data can be imported and
+  exported via CSV and pandas DataFrames, with automatic detection of array-valued cells.
+- **Nullable ndarray columns**: Multidimensional columns fully support the nullable
+  semantics (`null_count`, sentinel handling, `null_policy`) already available for scalar
+  columns.
+- **`from_pandas()` improvements**: `CTable.from_pandas()` now creates the correct
+  specialized backing storage for `DictionarySpec`, `ListSpec`, `VLStringSpec`,
+  `VLBytesSpec`, and other variable-length scalar specifications.
+- **Improved schema coverage**: New CTable timestamp schema type and extended
+  `Column.info` output with `shape`, `chunks`, and `blocks` descriptors.
+- **Arg reductions**: Added `argmin()` and `argmax()` for scalar and ndarray
+  CTable columns, plus row-transformer support for generated columns such as
+  per-row peak-hour or dominant-embedding-dimension features.
+
+### CTable: Group-by and filtered aggregation
+
+- **`CTable.group_by()`**: The primary group-by interface.  Call
+  ``t.group_by("city", sort=True).agg({"qty": "mean"})`` to produce a new
+  :class:`CTable` with aggregated results.  Single-key and multi-key groupings are
+  supported, along with convenience methods such as ``.size()``, ``.count()``,
+  ``.sum()``, ``.mean()``, ``.min()`` and ``.max()``:
+
+  .. code-block:: python
+
+      by_city = t.group_by("city", sort=True)
+      by_city.size()  # COUNT(*)
+      by_city.sum("sales")  # SUM(sales) per city
+      by_city.agg({"sales": ["sum", "mean"]})  # SUM(sales), AVG(sales) per city
+
+- **Performance accelerators**: Dedicated Cython fast paths deliver significant speedups:
+  ~25× for float32/64 group-by keys, ~8× for integer and dictionary-code keys, and a
+  general-purpose hash table for arbitrary float keys.
+- **Filtered aggregate pushdown**: The `where=` parameter is now accepted in aggregation
+  methods, pushing the filter into the compute engine so that only matching rows are
+  read and reduced.
+- **Persistent grouped output**: Group-by results can be saved directly to persistent
+  storage via the `urlpath=` parameter.
+- **`blosc2.group_reduce()`**: New public function that performs group-by reduction over
+  NDArray instances and CTable columns, with Cython-accelerated backends for common
+  key/reduction combinations.
+
+### CTable: Dictionary / categorical columns
+
+- **`DictionarySpec` column type**: Introduced a new dictionary-encoded (categorical)
+  column type that stores string or integer codes mapped to a shared dictionary, providing
+  compact storage and accelerated equality and membership queries.
+- **Dictionary types in `where` clauses**: Dictionary columns can be queried with the same
+  `where=` expression syntax as other column types, including nested dotted-name access.
+- **Improved display**: `CTable` printing now adapts to the terminal width, and dictionary
+  values are shown in their decoded form.  `Column.info` has been extended with type
+  details, shape, chunks, and blocks.
+
+### CTable: Nested columns and field-name escaping
+
+- **Dotted nested column access**: Columns whose names contain literal `.`
+  (e.g., `"root.nested"`) are now fully addressable via the dotted accessor syntax in
+  `where` expressions, `__getitem__`, and the public API.
+- **Hierarchical `_cols` storage paths**: The internal column storage layout now preserves
+  a hierarchical structure that mirrors the logical nesting, improving introspection
+  and interop.
+- **Nested-field pipeline**: A new flattened-storage pipeline with logical mapping
+  preserves nested schema structure (field names, types, and hierarchy) through
+  Arrow and Parquet import/export.  For unnamed top-level `list<struct<...>>` Parquet
+  files, the logical schema round-trips faithfully, though the original physical row
+  grouping is intentionally not preserved.
+- **Field-name escaping**: Special characters (`.` and `/`) in column names are
+  automatically escaped during schema construction and metadata round-trips.
+
+### Parquet import/export improvements
+
+- **Arrow serializer by default**: `CTable.from_parquet()` now defaults to the Arrow
+  serializer, providing better schema fidelity and nested-type support.
+- **Progress reporting**: A `--progress` flag and an ETA estimator have been added to
+  the `parquet-to-blosc2` CLI for long-running imports.
+- **`--max-rows` parameter**: `CTable.from_parquet()` and the CLI now accept `max_rows`
+  to limit the number of imported rows.
+- **`--timestamp-unit`**: New CLI option to control timestamp unit conversion on import.
+- **`--float-trunc-prec`**: New CLI option to truncate floating-point precision on import.
+- **Separated nested columns enabled by default**: The `separate_nested_cols` flag is now
+  `True` by default for both the Python API and the CLI, ensuring nested Arrow structs
+  are always expanded into flat columns.
+- **`list_serializer` parameter**: New option to control how list-type columns are
+  serialized, with sensible defaults for different list layouts.
+- **Validation optimizations**: Arrow datetime values are validated only during import,
+  reducing runtime overhead on subsequent operations.
+
+### TreeStore: Inline CTable support
+
+- **CTables inside TreeStore**: `CTable` objects can now be stored inline as items
+  inside a `TreeStore`, enabling hierarchical storage that mixes arrays and tables in a
+  single persistent container.
+- **Cache hardening**: TreeStore cache assignments now use defensive copies and cache
+  effective object roots to avoid aliasing and stale-cache errors.
+- **Examples and tutorials**: New tutorials and docstring examples demonstrate how to
+  store, retrieve, and query CTables within a TreeStore.
+
+### Performance and usability enhancements
+
+- **Faster open and import**: `blosc2.open()` and store constructors now assume valid
+  file extensions and defer column metainfo loading, making `CTable.open()` and
+  package import noticeably faster.
+- **`CTable.nrows` is now lazy**: The row count is computed on demand rather than eagerly,
+  speeding up open and schema-inspection workflows.
+- **Accelerated scalar and small-slice access**: The batch/list path for reading scalar
+  values or small column slices has been overhauled, eliminating internal placeholder
+  materialization and yielding lower latency.
+- **Late-import optimizations**: Heavy optional dependencies are imported lazily at the
+  blosc2 package level, reducing the baseline `import blosc2` overhead.
+- **`iter_arrow_batches()` optimization**: Avoids full Python object materialization of
+  batches during iteration, reducing memory pressure.
+- **`NDArray`-to-list conversion**: Small optimization when converting NDArray objects
+  to Python lists.
+- **`_last_pos` invalidation skipped**: Mid-table deletes no longer eagerly invalidate
+  cached positional state, improving delete latency.
+
+### Documentation, examples and benchmarks
+
+- **API reference expanded**: `blosc2.group_reduce()` has been added to the Sphinx
+  reference, along with updated CTable, Column, and TreeStore pages.
+- **New tutorials and examples**: Added sections on CTable–TreeStore integration,
+  nested fields, dictionary columns, aggregates, grouping and querying with `where=`.
+- **New benchmarks**: Graph benchmarks for CTable insert time, column count, memory usage,
+  and `where=` queries, plus dedicated group-by, nested-filter, and Parquet round-trip
+  benchmarks.
+
+### Fixes and compatibility
+
+- **Null and NaN handling**: NumPy scalar null sentinels are now normalized to plain Python
+  scalars, and floating-point NaN sentinels are treated consistently with Python
+  `float('nan')`.
+- **Empty aggregate results**: Filtered aggregations that produce no rows now handle the
+  empty result gracefully.
+- **Generated column safety**: Accessing a stalled (unfillable) generated column now raises
+  a clear exception instead of producing undefined results.
+- **Miniexpr bundling**: Miniexpr’s bundled `libtcc` and related runtime files are now
+  kept inside the `blosc2` package, avoiding conflicts with other TCC installations.
+- **Test improvements**: Torch-dependent tests are marked as `heavy`, PyArrow-optional
+  tests are skipped when the library is absent, and parametrization matrices have been
+  trimmed to reduce CI time.
+- **Missing Cython validation**: Added validation guards for several Cython extension
+  functions that previously lacked explicit error checking.
+- **C-Blosc2 update**: Bundled C-Blosc2 has been updated to the latest version (3.0.3).
+- **``blosc2.open()`` default mode changed from 'a' to 'r'**: Removed the FutureWarning that
+  was added to prepare for this transition.
+
 ## Changes from 4.1.2 to 4.2.0
 
 ### CTable: columnar compressed tables

{blosc2-4.2.0 → blosc2-4.3.0}/RELEASING.rst

@@ -42,7 +42,7 @@ Preliminaries
 
 * Check that the metainfo for the package is correct::
 
-    pipx run build --sdist
+    uv build --sdist --no-build-isolation
     twine check --strict dist/*
 
 
@@ -101,7 +101,6 @@ Checking packaging
 
     pip install --group test
     pip install blosc2 -U
-    python -c "import blosc2; blosc2.print_versions()"
     pytest
 
 * Do an actual release in GitHub by visiting:

{blosc2-4.2.0 → blosc2-4.3.0}/doc/conf.py

@@ -186,6 +186,21 @@ Reduction operations can be used with any of :ref:`NDArray <NDArray>`, :ref:`C2A
 """
     )
     genbody(f, sorted(reducers))
+    f.write(
+        """
+Grouped reductions
+~~~~~~~~~~~~~~~~~~
+
+The :func:`blosc2.group_reduce` function is a lower-level, array-oriented primitive that groups one-dimensional keys and applies eager reductions to the associated values.
+
+.. autosummary::
+
+    group_reduce
+
+
+.. autofunction:: blosc2.group_reduce
+"""
+    )
 
 hidden = "_ignore_multiple_size"
 

{blosc2-4.2.0 → blosc2-4.3.0}/doc/getting_started/tutorials/13.containers.ipynb

@@ -5,22 +5,7 @@
    "id": "cell-01",
    "metadata": {},
    "source": [
-    "# Working with Containers\n",
-    "\n",
-    "This notebook is a guided tour of the main data containers in `python-blosc2`.\n",
-    "\n",
-    "The goal is to build a practical mental model first: what each container is, how the containers relate, and when each one is the right tool.\n",
-    "\n",
-    "We will cover these containers in this order:\n",
-    "\n",
-    "1. `SChunk`\n",
-    "2. `NDArray`\n",
-    "3. `ObjectArray`\n",
-    "4. `BatchArray`\n",
-    "5. `EmbedStore`\n",
-    "6. `DictStore`\n",
-    "7. `TreeStore`\n",
-    "8. `C2Array`"
+    "# Working with Containers\n\nThis notebook is a guided tour of the main data containers in `python-blosc2`.\n\nThe goal is to build a practical mental model first: what each container is, how the containers relate, and when each one is the right tool.\n\nWe will cover these containers in this order:\n\n1. `SChunk`\n2. `NDArray`\n3. `ObjectArray`\n4. `BatchArray`\n5. `EmbedStore`\n6. `DictStore`\n7. `TreeStore` (including inline `CTable` support)\n8. `C2Array`"
    ]
   },
   {
@@ -444,6 +429,73 @@
     "    show(\"/exp/run2/data\", tstore[\"/exp/run2/data\"][:])"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "cell-17b",
+   "metadata": {},
+   "source": [
+    "### Storing CTables inside a TreeStore\n",
+    "\n",
+    "A `TreeStore` can hold **both NDArrays and CTables** in the same bundle.  A `CTable` is stored inline as a named subtree — all its columns, metadata, and index sidecars live as ordinary Blosc2 leaves inside the outer store.  From the outside it appears as a single key, exactly like any other leaf:\n",
+    "\n",
+    "* `ts[\"/table\"] = ctable` — stores the CTable inline (same syntax as NDArray).\n",
+    "* `ts[\"/table\"]` — returns a `CTable` object transparently.\n",
+    "* `\"/table/_meta\" not in ts` — internal keys are hidden from normal traversal.\n",
+    "* `del ts[\"/table\"]` — removes the whole object and all its leaves at once.\n",
+    "\n",
+    "The inline layout means there are **no nested ZIP files**: all leaves are flat members of the outer `.b2z` archive and can be opened by offset without extraction."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cell-17c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from dataclasses import dataclass\n",
+    "\n",
+    "\n",
+    "@dataclass\n",
+    "class Reading:\n",
+    "    sensor_id: int = 0\n",
+    "    value: float = 0.0\n",
+    "\n",
+    "\n",
+    "bundle_path = reset(\"bundle.b2z\")\n",
+    "\n",
+    "# --- Write: mix NDArrays and CTables in one bundle ----------------------\n",
+    "t = blosc2.CTable(Reading)\n",
+    "for i in range(6):\n",
+    "    t.append(Reading(sensor_id=i, value=round(i * 1.1, 2)))\n",
+    "\n",
+    "with blosc2.TreeStore(bundle_path, mode=\"w\") as ts:\n",
+    "    ts[\"/raw/signal\"] = np.arange(8, dtype=np.float32)\n",
+    "    ts[\"/tables/readings\"] = t  # CTable stored inline\n",
+    "    show(\"keys after write\", sorted(ts.keys()))\n",
+    "    show(\"/tables/readings/_meta in ts (hidden)\", \"/tables/readings/_meta\" in ts)\n",
+    "\n",
+    "# --- Read back from the .b2z archive ------------------------------------\n",
+    "with blosc2.open(bundle_path, mode=\"r\") as ts:\n",
+    "    readings = ts[\"/tables/readings\"]  # returns CTable transparently\n",
+    "    show(\"type\", type(readings).__name__)\n",
+    "    show(\"rows\", len(readings))\n",
+    "    show(\"sensor_id\", list(readings[\"sensor_id\"][:]))\n",
+    "    show(\"value\", list(readings[\"value\"][:]))\n",
+    "\n",
+    "# --- Append a row in-place (append mode) --------------------------------\n",
+    "with blosc2.TreeStore(bundle_path, mode=\"a\") as ts:\n",
+    "    r = ts[\"/tables/readings\"]\n",
+    "    r.append(Reading(sensor_id=99, value=-1.0))\n",
+    "    r.close()  # optional; outer store also closes it on __exit__\n",
+    "    show(\"rows after append\", len(ts[\"/tables/readings\"]))\n",
+    "\n",
+    "# --- Delete the CTable (all internal leaves removed) -------------------\n",
+    "with blosc2.TreeStore(bundle_path, mode=\"a\") as ts:\n",
+    "    del ts[\"/tables/readings\"]\n",
+    "    show(\"keys after delete\", sorted(ts.keys()))"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "cell-18",
@@ -494,25 +546,7 @@
    "id": "cell-20",
    "metadata": {},
    "source": [
-    "## Choosing The Right Container\n",
-    "\n",
-    "| Container | Backing idea | Best for |\n",
-    "| --- | --- | --- |\n",
-    "| `SChunk` | raw compressed chunks | direct chunk-level storage control |\n",
-    "| `NDArray` | `SChunk` plus array metadata | dense numeric arrays |\n",
-    "| `ObjectArray` | one variable-length entry per chunk | ragged or heterogeneous Python values |\n",
-    "| `BatchArray` | one batch per chunk | batch-oriented ingestion and access |\n",
-    "| `EmbedStore` | one bundled object store | packaging a few Blosc2 objects together |\n",
-    "| `DictStore` | keyed collection of leaves | portable multi-object datasets |\n",
-    "| `TreeStore` | hierarchical keyed collection | tree-structured datasets |\n",
-    "| `C2Array` | remote array handle | arrays hosted by a remote Caterva2 service |\n",
-    "\n",
-    "A simple rule of thumb is:\n",
-    "\n",
-    "- start with `NDArray` for dense numeric data\n",
-    "- drop down to `SChunk` if you need chunk-level control\n",
-    "- use `ObjectArray` or `BatchArray` for variable-length Python objects\n",
-    "- use `EmbedStore`, `DictStore`, or `TreeStore` when your dataset contains multiple objects"
+    "## Choosing The Right Container\n\n| Container | Backing idea | Best for |\n| --- | --- | --- |\n| `SChunk` | raw compressed chunks | direct chunk-level storage control |\n| `NDArray` | `SChunk` plus array metadata | dense numeric arrays |\n| `ObjectArray` | one variable-length entry per chunk | ragged or heterogeneous Python values |\n| `BatchArray` | one batch per chunk | batch-oriented ingestion and access |\n| `EmbedStore` | one bundled object store | packaging a few Blosc2 objects together |\n| `DictStore` | keyed collection of leaves | portable multi-object datasets |\n| `TreeStore` | hierarchical keyed collection | tree-structured datasets with NDArrays and/or CTables |\n| `C2Array` | remote array handle | arrays hosted by a remote Caterva2 service |\n\nA simple rule of thumb is:\n\n- start with `NDArray` for dense numeric data\n- drop down to `SChunk` if you need chunk-level control\n- use `ObjectArray` or `BatchArray` for variable-length Python objects\n- use `EmbedStore`, `DictStore`, or `TreeStore` when your dataset contains multiple objects"
    ]
   },
   {
@@ -520,17 +554,7 @@
    "id": "cell-21",
    "metadata": {},
    "source": [
-    "## Final Notes\n",
-    "\n",
-    "This notebook is intentionally organized from low-level storage to higher-level organization:\n",
-    "\n",
-    "- understand `SChunk` first\n",
-    "- use `NDArray` for most dense numeric workloads\n",
-    "- move to `ObjectArray` or `BatchArray` when entries stop being fixed-size arrays\n",
-    "- use `EmbedStore`, `DictStore`, or `TreeStore` when you need to package multiple objects together\n",
-    "- use `C2Array` when the data lives on a remote service\n",
-    "\n",
-    "For deeper details on a specific class, continue with the reference docs and the dedicated tutorials for `ObjectArray`, `BatchArray`, and indexing."
+    "## Final Notes\n\nThis notebook is intentionally organized from low-level storage to higher-level organization:\n\n- understand `SChunk` first\n- use `NDArray` for most dense numeric workloads\n- move to `ObjectArray` or `BatchArray` when entries stop being fixed-size arrays\n- use `EmbedStore`, `DictStore`, or `TreeStore` when you need to package multiple objects together\n- use `TreeStore` + `CTable` together when your bundle mixes dense arrays with structured tables\n- use `C2Array` when the data lives on a remote service\n\nFor deeper details on a specific class, continue with the reference docs and the dedicated tutorials for `ObjectArray`, `BatchArray`, and indexing."
    ]
   },
   {