Execution results and summaries

bondi.execution.ExecutionResult dataclass

Record one successful operation or a captured workload failure.

Parameters:

Name	Type	Description	Default
elapsed_ms	float	Client-observed monotonic elapsed time, not server execution time.	required
row_count	int | None	Fully consumed output-row count for a successful run or Couchbase profile; otherwise None.	None
documents	list[Any] | None	Collected output rows when requested; otherwise None. Rows may be documents, scalars or arrays, depending on the backend.	None
raw	dict[str, Any] | None	Backend-native diagnostic response or execution metadata when available. Parsing is explicit; this result does not contain a QuerySummary.	None
warnings	tuple[str, ...]	Nonfatal operation warnings; empty when none were reported.	()
error	Exception | None	Original exception for a failed workload entry; otherwise None.	None

Partial documents and counts are discarded on failure. Exception objects are retained for inspection; this class does not provide persistence.

Source code in src/bondi/execution.py

@dataclass
class ExecutionResult:
    """Record one successful operation or a captured workload failure.

    Args:
        elapsed_ms: Client-observed monotonic elapsed time, not server execution time.
        row_count: Fully consumed output-row count for a successful run or Couchbase
            profile; otherwise None.
        documents: Collected output rows when requested; otherwise None. Rows may be
            documents, scalars or arrays, depending on the backend.
        raw: Backend-native diagnostic response or execution metadata when available.
            Parsing is explicit; this result does not contain a QuerySummary.
        warnings: Nonfatal operation warnings; empty when none were reported.
        error: Original exception for a failed workload entry; otherwise None.

    Partial documents and counts are discarded on failure. Exception objects are
    retained for inspection; this class does not provide persistence.
    """

    elapsed_ms: float
    row_count: int | None = None
    documents: list[Any] | None = None
    raw: dict[str, Any] | None = None
    warnings: tuple[str, ...] = ()
    error: Exception | None = None

    @property
    def status(self) -> Literal["success", "timeout", "error"]:
        """Derive status from built-in, PyMongo and optional Couchbase timeout exceptions."""
        if self.error is None:
            return "success"
        if isinstance(self.error, TimeoutError) or (
            isinstance(self.error, PyMongoError) and self.error.timeout
        ):
            return "timeout"
        try:
            from couchbase.exceptions import (
                AmbiguousTimeoutException,
                TimeoutException,
                UnAmbiguousTimeoutException,
            )
        except ImportError:
            pass  # Couchbase execution is optional.
        else:
            if isinstance(
                self.error,
                (TimeoutException, AmbiguousTimeoutException, UnAmbiguousTimeoutException),
            ):
                return "timeout"
        return "error"

status property

Derive status from built-in, PyMongo and optional Couchbase timeout exceptions.

bondi.summary.QuerySummary dataclass

Describe observed query metrics and plan information, independently of execution.

Backend parsers define which fields can be populated for a particular response. Executors do not construct or attach summaries automatically. A shared field name does not imply identical measurement procedures across databases.

Attributes:

Name	Type	Description
execution_time_ms	float | None	Server-reported execution duration in milliseconds. Backend semantics apply; not client elapsed time or a sum of operator estimates.
rows_returned	int | None	Final query output count, including scalar or array rows. Not the number of plan documents returned by an explain operation.
documents_examined	int | None	Whole-operation document examinations, not distinct documents. Unavailable when the backend only reports a different counter.
keys_examined	int | None	Whole-operation index entries examined, not distinct values or simply the number of items emitted by an index operator.
plan_stages	tuple[str, ...] | None	Native structured plan stage names in root-first traversal order, preserving repetitions. A flattened description, not a complete plan tree.
index_names	tuple[str, ...] | None	Unique index names in first-encounter order; unavailable when the parser cannot determine complete index usage for its supported scope.

None means unavailable or unsupported, never zero. An empty index_names tuple means no named index use was found in a supported plan; it does not prove a collection scan. Keep the raw response separately for backend-specific analysis. This frozen value object provides no merging or automatic validation.

Examples:

>>> QuerySummary(rows_returned=0).rows_returned
0
>>> QuerySummary().keys_examined is None
True

Source code in src/bondi/summary.py

@dataclass(frozen=True)
class QuerySummary:
    """Describe observed query metrics and plan information, independently of execution.

    Backend parsers define which fields can be populated for a particular response.
    Executors do not construct or attach summaries automatically. A shared field name
    does not imply identical measurement procedures across databases.

    Attributes:
        execution_time_ms: Server-reported execution duration in milliseconds. Backend
            semantics apply; not client elapsed time or a sum of operator estimates.
        rows_returned: Final query output count, including scalar or array rows.
            Not the number of plan documents returned by an explain operation.
        documents_examined: Whole-operation document examinations, not distinct
            documents. Unavailable when the backend only reports a different counter.
        keys_examined: Whole-operation index entries examined, not distinct values
            or simply the number of items emitted by an index operator.
        plan_stages: Native structured plan stage names in root-first traversal order,
            preserving repetitions. A flattened description, not a complete plan tree.
        index_names: Unique index names in first-encounter order; unavailable when
            the parser cannot determine complete index usage for its supported scope.

    None means unavailable or unsupported, never zero. An empty index_names tuple
    means no named index use was found in a supported plan; it does not prove a
    collection scan. Keep the raw response separately for backend-specific analysis.
    This frozen value object provides no merging or automatic validation.

    Examples:
        >>> QuerySummary(rows_returned=0).rows_returned
        0
        >>> QuerySummary().keys_examined is None
        True
    """

    execution_time_ms: float | None = None
    rows_returned: int | None = None
    documents_examined: int | None = None
    keys_examined: int | None = None
    plan_stages: tuple[str, ...] | None = None
    index_names: tuple[str, ...] | None = None