httk.store.db.results

Lazy, named result rows for SqlSearcher.

Exceptions

MultipleResultsError	Report that a result-set one() operation found multiple results.
NoResultError	Report that a result-set one() operation found no matching result.
ExpiredCursorRowError	A cursor proxy was used after the cursor advanced.

Classes

ResultRow	Represent one named result row by position, name, or attribute.
ResultColumn	A declared scalar projection, with exact and float presentations.
SqlResultSet	A frozen, lazy result plan.

Module Contents

exception httk.store.db.results.MultipleResultsError

Bases: LookupError

Report that a result-set one() operation found multiple results.

exception httk.store.db.results.NoResultError

Bases: LookupError

Report that a result-set one() operation found no matching result.

class httk.store.db.results.ResultRow(values, names, resolver=None, guard=None)

Represent one named result row by position, name, or attribute.

Parameters:

• values (tuple[Any, Ellipsis]) – The row values in declaration order.

• names (tuple[str, Ellipsis]) – The corresponding output names.

• resolver (Any) – An optional lazy value resolver.

• guard (Any) – An optional callback that rejects access to expired values.

property names: tuple[str, Ellipsis]

Return the declared output names.

property values: tuple[Any, Ellipsis]

Return the row values in declaration order.

exception httk.store.db.results.ExpiredCursorRowError

Bases: RuntimeError

A cursor proxy was used after the cursor advanced.

class httk.store.db.results.ResultColumn(result, index)

A declared scalar projection, with exact and float presentations.

Parameters:

• result (SqlResultSet) – The result set containing the projection.

• index (int) – The projection’s position in the result set.

name

floats()

Yield the query-domain values for this projection.

Yield:

A projection value in the query-domain representation.

to_fracvector()

Convert this rational projection to a fraction vector.

Returns:

The projection values as a fraction vector.

Raises:

TypeError – If the projection is not a supported rational column.

Return type:

httk.core.FracVector

class httk.store.db.results.SqlResultSet(searcher, outputs=None)

A frozen, lazy result plan.

Parameters:

• searcher (httk.store.db.searcher.SqlSearcher) – The search whose query state is frozen.

• outputs (dict[str, Any] | None) – Optional output names mapped to query variables or columns.

property names: tuple[str, Ellipsis]

Return the names of the declared projections in order.

Returns:

The declared projection names.

Return type:

tuple[str, Ellipsis]

first()

Return the first result, or None when no result exists.

Returns:

The first result row, if present.

Return type:

httk.store.query.ResultRow | None

one()

Return the only result.

Returns:

The sole result row.

Raises:

• NoResultError – If no result exists.

• MultipleResultsError – If more than one result exists.

Return type:

httk.store.query.ResultRow

scalars(name=None)

Yield one projection from each result row.

Parameters:

name (str | None) – The projection name, required when several projections are declared.

Returns:

An iterator over the selected projection values.

Raises:

• ValueError – If name is omitted while several projections are declared.

• KeyError – If name is not a declared projection.

Return type:

collections.abc.Iterator[Any]

column(name)

Return a scalar projection by name.

Parameters:

name (str) – The declared scalar projection name.

Returns:

The selected result column.

Raises:

• KeyError – If name is not declared.

• TypeError – If name names an object projection.

Return type:

ResultColumn

page(*, size, order_by, cursor=None, include_total=False)

Fetch one bounded, live keyset page of this frozen SQL result plan.

Paging is intentionally separate from cursor(): this method returns independent rows whose page-local hydration state remains alive through their result-row resolvers, while cursor() returns reusable proxies that expire on advance. It performs one LIMIT size + 1 match query and never materializes this result set’s ordinary match cache. A total is deliberately opt-in because it requires the normal exact count query.

Parameters:

• size (int) – The maximum number of rows in the page.

• order_by (collections.abc.Iterable[httk.store.query.PageOrder]) – The declared scalar projections used for keyset ordering.

• cursor (httk.store.query.ContinuationToken | None) – The continuation token identifying the page position.

• include_total (bool) – Whether to include the exact filtered total.

Returns:

The requested result page.

Raises:

UnsupportedQueryError – If the query or ordering is not pageable.

Return type:

httk.store.query.ResultPage

cursor()

Yield cursor rows whose object proxies expire when iteration advances.

Returns:

An iterator over live cursor result rows.

Return type:

collections.abc.Iterator[httk.store.query.ResultRow]