PyTables Cheat Sheet

1Install & open_fileimport tables

pip install tables # the package name; import as `tables`★
Needs the HDF5 C library (bundled in the wheels). Also on conda as pytables. Python 3.11+.
import tables as tb f = tb.open_file("data.h5", mode="w")★
Modes: "r" read, "w" create/overwrite, "a" append/read-write, "r+". Always f.close() or use a with block.
with tb.open_file("data.h5", "a") as f: print(f) # prints the whole tree★
The context manager guarantees flush/close. Printing the file shows every node.
# forgot to close in "w"/"a"? data may not be flushed to diskgotcha
HDF5 buffers writes — call f.flush() or close the file. An unclosed file can also lock it.

2Groups & hierarchythe tree

g = f.create_group("/", "sensors", "Sensor data")★
Groups are like directories under the root "/". Third arg is a human title. createparents=True to make intermediate groups.
f.root.sensors # natural-name attribute access f.get_node("/sensors/temp") # path access★
Navigate by attribute (f.root.sensors.temp) or by path string. Both reach the same node.
for node in f.walk_nodes("/", "Table"): print(node)
Traverse the tree; filter by class ("Table", "Array", "Group", "Leaf").
f.remove_node("/sensors", recursive=True) · f.rename_node(...)
Manage the tree: remove, rename, move, or copy nodes.

3Tables & IsDescriptiontyped records

class Reading(tb.IsDescription): ts = tb.Time64Col() value = tb.Float64Col() name = tb.StringCol(16) valid = tb.BoolCol()★
Define a table schema as an IsDescription subclass — each attribute is a typed column. Cols: Int32Col, Float64Col, StringCol(n), BoolCol, Time64Col, EnumCol…
t = f.create_table("/sensors", "temp", Reading, "Temp readings")★
Create the table under a group. You can also pass a NumPy structured dtype or a sample record instead of an IsDescription.
pos = {"x": tb.Float64Col(shape=(3,))} # multidim column
Columns can be multidimensional (arrays per row) via shape=.
t.colnames · t.coltypes · t.nrows · t.description
Introspect a table's schema and size.

4Append & read rowsthe Row accessor

row = t.row for r in data: row["ts"] = r.ts; row["value"] = r.v row.append() t.flush()★
The idiomatic append: fill the Row buffer field-by-field, call row.append(), then t.flush() to write. Fast for streaming inserts.
t.append([(ts1, v1, b"a", True), (ts2, v2, b"b", False)])★
Bulk-append a list of tuples / a NumPy structured array — much faster than row-by-row for big batches.
arr = t.read() # whole table -> NumPy structured array t.read(start=0, stop=100, step=2)★
Read all or a slice into a NumPy recarray. t.col("value") reads one column.
for r in t: # iterate rows (out-of-core) print(r["value"])
Iterate rows without loading the whole table — the out-of-core workhorse.

5Querying (where)in-kernel search

for r in t.where("(value > 20) & (valid == True)"): print(r["ts"], r["value"])★
where() evaluates a boolean expression in-kernel (via numexpr) directly on disk — fast, low-memory row filtering. Yields matching rows.
rows = t.read_where("value > 20") # -> NumPy array of matches★
read_where returns all matching rows as an array in one call.
t.read_where("name == n", condvars={"n": b"sensor1"})
Bind Python variables into the expression with condvars= (or they're picked up from scope). Strings are bytes.
idx = t.get_where_list("value > 20") # matching row numbers
Get just the row coordinates — then t.read_coordinates(idx).

6Arraysdense data

f.create_array("/", "vec", np.arange(1000))★
Array: a fixed NumPy array stored whole (read/written in one shot). Good for small/medium dense data.
ca = f.create_carray("/", "img", tb.Float32Atom(), shape=(10000, 256, 256))★
CArray: chunked & compressible fixed-shape array — read/write slices without loading it all.
ea = f.create_earray("/", "stream", tb.Float32Atom(), shape=(0, 128)) ea.append(batch) # grow along axis 0★
EArray: extendable array — start with a 0-length axis and append() batches (streaming rows of features).
ca[100:200] · ea[-1] · arr.read()
Slice arrays like NumPy — only the requested chunks are read from disk. VLArray for ragged/variable-length rows.

7Compression & chunksFilters

flt = tb.Filters(complevel=5, complib="blosc2:zstd") f.create_table("/", "t", Reading, filters=flt)★
Filters controls compression. Blosc2 (default, multithreaded) is fastest; complib: blosc2, zlib, lzo, bzip2. complevel 0–9.
f = tb.open_file("data.h5", "w", filters=tb.Filters(complevel=5))
Set default filters for the whole file — every leaf inherits them unless overridden.
tb.Filters(complevel=5, shuffle=True, bitshuffle=True)
Shuffle/bitshuffle reorder bytes before compression — often big ratio gains on numeric data.
create_carray(..., chunkshape=(100, 256, 256))tip
Chunk shape drives I/O granularity — match it to your access pattern (PyTables auto-picks a reasonable default).

8Indexing & performancego faster

t.cols.value.create_index()★
Build an on-disk index on a column so where/read_where on it become sub-linear — huge for repeated range/equality queries. (Needs the tables[...] indexing deps / OPSI.)
t.cols.value.create_csindex() # completely-sorted index
A CSI gives the best query speed (at higher build cost) and enables efficient sorted reads.
t2 = t.copy("/", "t_sorted", sortby="value", checkCSI=True)
Write a physically sorted copy for fast ordered scans.
t.expectedrows = 10_000_000 # set before creating for better chunking
Hint the row count on creation (expectedrows=) so PyTables sizes chunks/buffers well.

PyTables cheat sheet