Explain V3 in aggregation pipelines

    • Type: Improvement
    • Resolution: Unresolved
    • Priority: Blocker - P1
    • None
    • Affects Version/s: None
    • Component/s: None
    • None
    • Query Optimization
    • None
    • None
    • None
    • None
    • None
    • None
    • None

      SERVER-130403 introduces writeExplainOpsV3(legacyVerbosity) which receives an already-translated legacy verbosity and just calls writeExplainOps(legacyVerbosity). So every DocumentSource::serialize() sees a legacy value via SerializationOptions.verbosity, while expCtx->getExplain() still holds the real V3 value — hence the relaxed cross-check in document_source_cursor.cpp. V3 knowledge lives only above the per-stage serialize.

      The core problem: the verbosity is threaded into every DocumentSource::serialize() through SerializationOptions (query_shape/serialization_options.h), and stages branch on ordinal comparisons of it (verbosity >= kExecStats), plus some read expCtx->getExplain() directly. V3 values sort between kExecAllPlans and kInternal, so they would misfire.

      Proposed design for the ticket — two pieces:

      1. Stop relying on enum ordinality for V3; use semantic predicates. Introduce intent-revealing helpers (e.g. verbosityIncludesExecStats(v), verbosityIncludesAllPlansStats(v), verbosityIncludesPlannerChoice(v)) and replace the ordinal >= comparisons in the pipeline / DocumentSource serialize layer with them. This makes the code express what content is wanted rather than where the enum sorts.

      2. Thread the real V3 verbosity down, then fix the concequences:

      • writeExplainOpsV3() takes the requested V3 verbosity (not a translated legacy one) — the TODO on plan_executor_pipeline.h:215 already anticipates this.
      • Carry it through Pipeline::writeExplainOps → SerializationOptions, and make expCtx->getExplain() consistent with it.
      • Restore the uassert 50660 cross-check in document_source_cursor.cpp once serialize-verbosity and expCtx-verbosity agree again.
      • Redesign the plannerStats execution flip on the agg path: explainPipeline currently executes the pipeline for kPlannerStats (needed only by the interim legacy delegation). Real V3 plannerStats must not execute — need to confirm the embedded $cursor plan's trial stats are available without pipeline execution.
      • Decide the extension-boundary V3 story (explain_utils.h) — keep mapping to legacy, or define a V3 representation.

            Assignee:
            Unassigned
            Reporter:
            Timour Katchaounov
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

              Created:
              Updated: