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.

Parameters:: name – A column name. It is not checked here — a name that is not a column of the table raises when the expression is evaluated, not when it is built, so an expression can be assembled before a table is opened.

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).

Parameters:: values – Any iterable of values to match, in the column’s decoded form. It is consumed immediately, so a generator is fine.

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, *, masked: bool = True) → 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 it is read whole and then subset. A list column is always fetched with ListColumn.read_rows, which reads the span the matching rows cover and so is never wider than the whole column. The result is identical either way.

Parameters:

columns – Names to read, in the order given. None (the default) reads every column of the table.
masked – As for h5col.Table.read(): each scalar column comes back as a numpy.ma.MaskedArray marking its missing rows unless False is passed. List columns accept it and ignore it.

Raises:

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

to_arrow(columns: Any = None) → Any[source]#

Convert the selected rows to a pyarrow.Table.

As h5col.Table.to_arrow(), restricted to the matching rows.

Added in version 0.2.0.

Parameters:: columns – Names to convert, in the order given. None (the default) converts every column of the table.

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).