THE INCQL BOOK

5. Check adapter coverage

Ask a separate question: what capabilities is the selected adapter known to cover for this plan?

Part II

Explain and execute it

Chapter 3 of 3

Goal

Evaluate the adapter requirements inferred from the review plan and interpret every coverage state conservatively.

Execution success is not capability evidence

Chapter 4 showed that one concrete plan attempt ran. check_plan_coverage(...) answers an independent question: for requirements visible in the inspected plan, what does IncQL know about the selected adapter's capability or guarantee? In this checkpoint, DataFusion reports null_semantics as covered and lineage_preservation as uncovered even though the three-row collection succeeded.

With this example, you are reading record.requirement.capability.value() and record.state.value() only to display the two enum values; calling .value() does not change or enforce either classification. check_plan_coverage(plan) is the convenient inspect-and-check form. Use check_inspection_coverage(inspection) when you already retain a PlanInspection, or check_coverage(requirements) when the caller supplies explicit requirements that plan inspection cannot infer.

01
Concrete attemptExecute the review plan once
```
observed = session.collect_observed(plan.clone()) # (1)!
```
1. Preserve the plan for a second question. This clone is the input to one concrete collection attempt. The original plan remains available because the next stage asks about adapter coverage, which is evidence about known capability rather than proof inferred from execution success.
Owner
Session and selected backend

Artifact
ObservedDataFrame[Order]

Knowable now
This attempt ran on datafusion and materialised three rows
02
Explicit coverage checkClassify requirements inferred from the plan
```
coverage = session.check_plan_coverage(plan) # (1)!
for record in coverage:
    capability = record.requirement.capability.value()
    state = record.state.value()
    println(f"- {capability}: {state}") # (2)!
```
1. Inspect, then classify the inferred requirements. check_plan_coverage(plan) is the convenient form when you still have the LazyFrame. If you already retain a PlanInspection, use check_inspection_coverage(inspection); use check_coverage(requirements) when the caller supplies explicit requirements.
2. Read names, not an enforcement result. capability.value() names the requirement family and state.value() names the adapter's conservative classification. These accessors only render enum values; uncovered and unknown do not become acceptable merely because this example's collection succeeded.
Owner
Session coverage evaluation

Artifact
list[AdapterCoverageRecord]

Knowable now
The selected adapter's classification for each plan-inferred requirement
03
Conservative resultRead every state literally

Execution
3 rows materialised

Null semantics
covered

Lineage preservation
uncovered

Observed result Coverage records

Coverage states are deliberately conservative:

Covered means the adapter is known to cover that requirement family.
PartiallyCovered means support depends on the specific expression or plan shape.
Uncovered means the adapter is known not to provide the guarantee.
Unknown means IncQL has no classification; it is not a soft success.

The current DataFusion adapter provides the classifications printed by the checkpoint. They are not a hidden policy decision and do not replace the execution observation.

Open the complete Chapter 5 checkpoint

"""Chapter 5: compare the inspected plan with adapter coverage evidence."""

from domain import Order
from pub::incql import LazyFrame, Session, SessionError, inspect_lineage, inspect_plan, report_session_error


def check_orders(mut session: Session) -> Result[None, SessionError]:
    """Collect the plan, then inspect DataFusion coverage for its requirements."""
    orders: LazyFrame[Order] = session.read_csv("tutorial_orders", "orders.csv")?
    plan = orders.limit(3)
    inspection = inspect_plan(plan.clone())
    lineage = inspect_lineage(plan.clone())
    observed = session.collect_observed(plan.clone())

    println(f"plan id: {inspection.plan_id}")
    println(f"lineage edges: {len(lineage.edges)}")
    println(f"backend: {observed.observation.backend_name}")
    match observed.data:
        Some(frame) =>
            println(f"columns: {frame.resolved_columns():?}")
            println(f"rows: {frame.row_count()}")
            println(frame.preview_text())
        None =>
            match observed.error:
                Some(error) => return Err(error)
                None => println("collect_observed returned no data and no typed error")

    coverage = session.check_plan_coverage(plan)
    println(f"coverage records: {len(coverage)}")
    for record in coverage:
        println(f"- {record.requirement.capability.value()}: {record.state.value()}")
    return Ok(None)


def main() -> None:
    mut session = Session.default()
    match check_orders(session):
        Ok(_) => println("Chapter 5: adapter coverage remained explicit")
        Err(error) => report_session_error("tutorial.chapter_05", error)

Run it from the included tutorial project:

incan run src/chapter_05.incn

A successful run reports the concrete DataFusion result separately from two coverage records: null_semantics: covered and lineage_preservation: uncovered.

Read the complete capability vocabulary and current DataFusion matrix in Execution context.

Try it

Add a match over the coverage states and print a separate message for Unknown. Make that message say “not classified,” not “supported,” then restore the checkpoint.

Chapter complete

You can explain why a successful query may still have an uncovered or unknown requirement, and why only caller-owned policy can decide whether that evidence is acceptable.