httk.store.federated_store ========================== .. py:module:: httk.store.federated_store .. autoapi-nested-parse:: Frozen query planning and sequential execution for a federated store. Federated expressions are deliberately represented by a private, backend-neutral AST. Child searcher expressions are used only while validating that each participating source accepts an operation; every execution replays that AST into fresh child searchers. Exceptions ---------- .. autoapisummary:: httk.store.federated_store.FederatedStoreError httk.store.federated_store.FederatedSourceError Classes ------- .. autoapisummary:: httk.store.federated_store.FederatedResultColumn httk.store.federated_store.FederatedResultSet httk.store.federated_store.FederatedTarget httk.store.federated_store.FederatedStore httk.store.federated_store.FederatedVariable httk.store.federated_store.FederatedField httk.store.federated_store.FederatedExpression httk.store.federated_store.FederatedSearcher Module Contents --------------- .. py:exception:: FederatedStoreError Bases: :py:obj:`RuntimeError` Report that a federation-level store operation failed. .. py:exception:: FederatedSourceError(source, operation) Bases: :py:obj:`FederatedStoreError` Report that a named source rejected or failed a federated operation. :param source: The source name that failed. :param operation: The federation operation being performed. .. py:attribute:: source .. py:attribute:: operation .. py:class:: FederatedResultColumn(result, index) Expose one scalar projection lazily from a federated result set. :param result: The result set supplying rows. :param index: The zero-based projection index. .. py:attribute:: name .. py:class:: FederatedResultSet(store, plan) Represent a frozen, lazy, re-iterable federated result plan. Results execute source-major in federation source order, preserve duplicate rows, and remain read-only views over the borrowed stores. :param store: The federation whose sources execute the plan. :param plan: The validated frozen federation plan. .. py:property:: names :type: tuple[str, Ellipsis] Return the declared projection names. :return: The result projection names in declaration order. .. py:method:: first() Return the first result row, or ``None`` when no row matches. :return: The first matching row, or ``None``. .. py:method:: one() Return the only result row. :return: The sole matching result row. :raises httk.store.query.protocols.NoResultError: If no row matches. :raises httk.store.query.protocols.MultipleResultsError: If more than one row matches. .. py:method:: scalars(name = None) Iterate over one named projection. :param name: The projection name, required when more than one output exists. :return: An iterator over the selected projection values. :raises ValueError: If no name is supplied for multiple outputs. :raises KeyError: If ``name`` is not a declared output. .. py:method:: column(name) Return a lazy scalar column by projection name. :param name: The scalar projection name. :return: A lazy column view over the projection. :raises KeyError: If ``name`` is not a declared output. :raises TypeError: If ``name`` identifies an object output. .. py:method:: cursor() :abstractmethod: Reject cursor access because federation cursors are unsupported. :return: Never returns. :raises NotImplementedError: Always, because federated cursors are not implemented. .. py:class:: FederatedTarget Bind one logical target to exact concrete targets for named sources. :param name: The nonempty logical target name. :param targets: Concrete targets keyed by federation source name. :param _owner: The federation that owns this target binding. :raises TypeError: If ``targets`` is not a mapping or ``_owner`` is not a federation. :raises ValueError: If the name, source set, or source names are invalid. .. py:attribute:: name :type: str .. py:attribute:: targets :type: collections.abc.Mapping[str, object] .. py:class:: FederatedStore(sources) Fan out read-only queries over an ordered collection of borrowed stores. The union is source-major, lazy, and non-deduplicating. Queries require the strict common query surface accepted by every participating source, and counts are exact sums of the unpaged source counts. This live borrowed-store view is distinct from the persisted registry in :mod:`httk.store.backend.sql.stored_federation`. :param sources: Child stores keyed by stable federation source name. :raises TypeError: If ``sources`` is not a mapping. :raises ValueError: If fewer than two sources or an invalid source name is supplied. .. py:property:: source_names :type: tuple[str, Ellipsis] Return the immutable source names in constructor iteration order. :return: The source names in constructor order. .. py:method:: target(name, targets) Create an immutable target mapping for an intentional source subset. :param name: The logical target name. :param targets: Concrete targets keyed by federation source name. :return: The validated target binding. :raises TypeError: If ``targets`` is not a mapping. :raises ValueError: If a target name or source name is invalid. .. py:method:: searcher(*, as_of = None, only_latest = False) Create an unbound federated searcher without touching child stores. :param as_of: Optional historic cutoff forwarded to every child store. A child that cannot honor it raises and the federation surfaces that child failure; this is a user-facing store API. :param only_latest: Whether each child restricts root variables to the latest row of each lineage. A child that cannot honor it raises and the federation surfaces that child failure. :return: A new mutable query builder. .. py:class:: FederatedVariable(searcher, variables, targets) Represent the one root variable supported by a federated query. :param searcher: The owning federated searcher. :param variables: Child variables keyed by source name. :param targets: Concrete child targets keyed by source name. .. py:method:: always_true() Build an expression that matches every federated row. :return: A federated expression matching every row. .. py:method:: always_false() Build an expression that matches no federated row. :return: A federated expression matching no row. .. py:class:: FederatedField(variable, path) Represent a backend-neutral path from a federated root variable. :param variable: The federated root variable owning the path. :param path: The field path relative to that variable. .. py:method:: contains(text) Match literal values containing ``text``. :param text: The literal substring to find. :return: The resulting federated expression. .. py:method:: startswith(prefix) Match literal values beginning with ``prefix``. :param prefix: The literal prefix to find. :return: The resulting federated expression. .. py:method:: endswith(suffix) Match literal values ending with ``suffix``. :param suffix: The literal suffix to find. :return: The resulting federated expression. .. py:method:: has(value) Match a list field containing ``value``. :param value: The list member to match. :return: The resulting federated expression. .. py:method:: has_any(*values) Match a list field containing any of ``values``. :param \*values: The list members to match. :return: The resulting federated expression. .. py:method:: has_only(*values) Match a list field containing no values outside ``values``. :param \*values: The complete allowed list-member set. :return: The resulting federated expression. .. py:method:: is_in(*values) Match a scalar field whose value is one of ``values``. :param \*values: The accepted field values. :return: The resulting federated expression. .. py:class:: FederatedExpression(searcher, ast) Represent a federated expression backed by the neutral private AST. :param searcher: The owning federated searcher. :param ast: The validated private expression tree. .. py:class:: FederatedSearcher(store, *, as_of = None, only_latest = False) Build and validate one portable, single-root federated query. :param store: The federation whose child stores provide the query surface. :param as_of: Optional historic cutoff forwarded to child stores. :param only_latest: Whether each child restricts root variables to the latest row of each lineage. .. py:attribute:: offset :value: 0 .. py:attribute:: origin .. py:method:: variable(target) Bind one shared or explicit target against child searcher prototypes. :param target: A shared child target or a source-specific target binding. :return: The federated root variable. :raises httk.store.query.protocols.UnsupportedQueryError: If a second root or foreign target is supplied. :raises FederatedSourceError: If a source rejects target binding. .. py:method:: add(expression) Validate and retain a portable condition for the future frozen plan. :param expression: An expression produced by this searcher. :return: None. :raises httk.store.query.protocols.UnsupportedQueryError: If the expression belongs to another searcher. :raises FederatedSourceError: If a source rejects the expression. .. py:method:: output(value, name) Declare a record, scalar field, or origin output for a future plan. :param value: The root variable, field, or ``origin`` sentinel to project. :param name: The nonempty output name. :return: None. :raises ValueError: If ``name`` is empty or already declared. :raises httk.store.query.protocols.UnsupportedQueryError: If ``value`` is not owned by this searcher. :raises FederatedSourceError: If a source rejects the output. .. py:method:: add_sort(field, descending = False) Reject global sorting until a portable sort-semantics contract exists. :param field: The requested sort field. :param descending: Whether the requested order is descending. :raises httk.store.query.protocols.UnsupportedQueryError: Always, because global federation sorting has no portable contract. .. py:method:: count() Return the exact unpaged count of the current filtered union. :return: The exact sum of matching rows across participating sources. :raises httk.store.query.protocols.CountUnavailableError: If a source cannot provide an exact count. :raises FederatedSourceError: If a source fails while counting. .. py:method:: set_limit(limit) Set the global output limit; a negative value clears it. :param limit: The nonnegative limit, or a negative value to clear it. :return: None. :raises TypeError: If ``limit`` is not an integer. .. py:method:: add_offset(offset) Add a global source-union offset. :param offset: The nonnegative number of union rows to skip. :return: None. :raises TypeError: If ``offset`` is not an integer. :raises ValueError: If ``offset`` is negative. .. py:method:: results(**outputs) Freeze a projection plan into a lazy, re-iterable result set. :param \*\*outputs: Optional output names mapped to root variables or fields. :return: The lazy frozen result set. :raises ValueError: If no outputs are declared or an output name is invalid. :raises httk.store.query.protocols.UnsupportedQueryError: If an output does not belong to this searcher. :raises FederatedSourceError: If a source rejects an output. .. py:method:: slicer(target) A pandas-style ``[]`` indexing view over ``target`` records. Each terminal indexing operation runs against a fresh federated searcher minted with this searcher's ``as_of``/``only_latest`` scope, so slicer operations never share filter state. Slicer masks never sort, so the federation's rejection of sorting does not apply. :param target: The stored record class to index. :return: A slicer over ``target``.