Couchbase summary parsing

bondi.couchbase.summarize(raw)

Summarize native EXPLAIN rows or toolkit run/profile metadata automatically.

Parameters:

Name	Type	Description	Default
raw	dict[str, Any] | None	ExecutionResult.raw, or the same data restored from JSON. None means no diagnostics and returns an empty summary; check result.status first because failed workload entries also have raw=None.	required

Returns:

Type	Description
QuerySummary	A frozen QuerySummary. A top-level plan selects EXPLAIN interpretation and
QuerySummary	contributes no execution metrics, even when request metrics are attached.
QuerySummary	Otherwise toolkit execution metadata supplies server time and row count,
QuerySummary	plus plan information when a supported executionTimings tree is present.
QuerySummary	Missing or unsupported measurements remain None. Examination totals are
QuerySummary	unavailable; operator output counts are not treated as examined totals.

Raises:

Type	Description
ValueError	Unrecognized input, reported failure, invalid consumed metrics or malformed supported plan structures.

Runs offline without the SDK, mutation, database calls or merging. Accepts toolkit SDK metadata, not REST envelopes/duration strings. Plan traversal is root-first with repeated operators and deduplicated index names. Unknown plan layouts leave plan fields unavailable while retaining valid execution metrics.

Source code in src/bondi/couchbase/explain.py

def summarize(raw: dict[str, Any] | None) -> QuerySummary:
    """Summarize native EXPLAIN rows or toolkit run/profile metadata automatically.

    Args:
        raw: ExecutionResult.raw, or the same data restored from JSON. None means
            no diagnostics and returns an empty summary; check result.status first
            because failed workload entries also have raw=None.

    Returns:
        A frozen QuerySummary. A top-level plan selects EXPLAIN interpretation and
        contributes no execution metrics, even when request metrics are attached.
        Otherwise toolkit execution metadata supplies server time and row count,
        plus plan information when a supported executionTimings tree is present.
        Missing or unsupported measurements remain None. Examination totals are
        unavailable; operator output counts are not treated as examined totals.

    Raises:
        ValueError: Unrecognized input, reported failure, invalid consumed metrics
            or malformed supported plan structures.

    Runs offline without the SDK, mutation, database calls or merging. Accepts
    toolkit SDK metadata, not REST envelopes/duration strings. Plan traversal is
    root-first with repeated operators and deduplicated index names. Unknown plan
    layouts leave plan fields unavailable while retaining valid execution metrics.
    """
    if raw is None:
        return QuerySummary()
    document = _document(raw, "raw")
    if "plan" in document:
        return _summarize_explain(document)
    return _summarize_execution(document)

Supported inputs and limits

• summarize() accepts the single result row returned as explain().raw, containing a plan object. It does not accept a list of rows or an HTTP envelope.
• summarize() accepts the toolkit's JSON-compatible SDK metadata from run().raw / profile().raw, including restored JSON. It does not parse raw REST duration strings such as executionTime: "1ms".
• Fixtures cover Community and Enterprise 7.6.2 using SDK 4.6.3: filtered and covering index scans, primary scans, grouping, empty results, scalars, sorting and limits.
• Supported operators are Sequence, Parallel, Authorize, IndexScan3, PrimaryScan3, Fetch, Filter, InitialProject, InitialGroup, IntermediateGroup, FinalGroup, Stream, DummyScan, Order, Limit, Offset.
• Unknown operators, missing tree structure and unknown structural ~ fields leave both plan fields None, while valid execution metrics remain available. Joins, unions, nested subqueries and distributed interpretation are deferred. The parser does not inspect SQL++ expressions or embedded user data for hidden index access.
• No operator tree (Community, ordinary execution or phases-only profiling) means no plan summary. No index use is inferred from phase names or counts.

Wrong input types, failed request statuses, reported errors, invalid consumed metrics, malformed supported children and cyclic trees raise ValueError. Validation covers consumed fields, not the complete server schema. A parser failure does not modify the successful execution result. Extend fixture coverage before relying on a new operator layout.

Couchbase defines #itemsIn and #itemsOut as operator input/output counts. See the Query Service response reference and profiling documentation. The notebook notebooks/couchbase_demo.ipynb shows automatic format detection alongside raw metadata.

No diagnostics and failures

summarize(None) returns an empty QuerySummary. Check result.status before summarizing workload results: failures also have raw=None, so an empty summary alone does not imply success. Unrecognized or malformed dictionaries raise ValueError; they are not silently treated as absent diagnostics.

A top-level plan selects EXPLAIN interpretation, even when request metrics are attached. Otherwise the parser reads toolkit execution metadata. It does not merge both shapes or infer execution statistics from EXPLAIN request timing.