The query layer#

Predicates, selections, and query plans. The queries section explains the model; the syntax reference defines every accepted form.

h5col.field(name: str) → Field[source]#: Reference a column by name for building query Expression objects.

class h5col.query.Field(name: str)[source]#

A column reference; comparisons return Expression leaves.

isin(values: Any) → Expression[source]#: A predicate matching rows whose value is in values (pyarrow in).

is_null() → Expression[source]#: A predicate matching rows that are missing (pyarrow is_null).

is_valid() → Expression[source]#: A predicate matching rows that are present (pyarrow is_valid).

class h5col.Expression(node: Any)[source]#

A boolean combination of predicates, built by field() + & | ~.

Mirrors pyarrow: (field("a") > 1) & (field("b") == 2) | ~field("c").is_valid().

class h5col.Selection(table: Table, expr: Expression | None)[source]#

A lazy, composable row selection over a table.

Built by Table.select(); evaluates on first use and caches the result (a query, not a snapshot — re-evaluate a fresh Selection after a mutation).

property row_positions: ndarray#

Sorted, unique int64 positions of the matching rows.

A Selection is lazy: the query is validated and evaluated on first access (here, and via count / read() / explain()).

Raises:

KeyError – If the predicate references a column the table does not have.
SchemaError – If the predicate is malformed — a list-column predicate, an unknown operator, a non-collection in value, an order comparison against an unknown categorical label, or a predicate that expands to too many DNF terms.

property count: int#: The number of matching rows (materializes no column data).

read(columns: Any = None) → dict[str, Any][source]#

Materialize the selected rows as {name: values}.

Each value is a NumPy array for a scalar column and a Python list (of per-row lists, None for a null row) for a list column. Evaluates the query on first use (see row_positions).

A scalar column whose matching rows sit in at most GATHER_CHUNK_FRACTION of its chunks is fetched with Column.read_rows, reading those chunks and no others; otherwise, and for list columns, the column is read whole and then subset. The result is identical either way.

Raises:

KeyError – If a requested column name is not a column of the table.
SchemaError – If the predicate is malformed (see row_positions).

explain() → QueryPlan[source]#: The QueryPlan describing how this selection was evaluated.

class h5col.QueryPlan(nrows: int, terms: list[TermPlan] = <factory>, matched: int = -1)[source]#: Machine-readable explanation of how a Selection was evaluated.

class h5col.query.TermPlan(leaves: list[LeafPlan] = <factory>)[source]#: How one AND-term of the DNF was evaluated (its per-leaf plans).

class h5col.query.LeafPlan(column: str, op: str, negated: bool, method: str, note: str = '')[source]#: How one predicate leaf was evaluated (a row in QueryPlan).