A successful telemetry query is not always a complete answer

Keep three questions separate

1. Did the request succeed? Authentication, transport and query execution have their own failure states.
2. Did the answering service report missing evidence? Preserve that information alongside the rows instead of dropping it at the client boundary.
3. Is the evidence sufficient for this conclusion? Even a response with no reported partial causes does not prove that instrumentation, ingestion or the chosen window covers the incident.

An empty list of reported causes is not an independent audit of the underlying telemetry.

A small example

The illustration shows the same synthetic row in three HTTP 200 responses. One has no partial-causes header; one carries tier_scan_failed; one carries only commas and spaces. The last two should not support a complete-data conclusion just because their HTTP status and rows look normal.

tier_scan_failed is a cause token, not a diagnosis of why a tier failed. x-packdb-partial-causes is a PackDB response contract, not an OpenTelemetry or industry-wide standard. The diagram separates response metadata, returned data and SDK output; it is not a literal wire envelope or a production recovery test.

The public PackDB Rust SDK exposes a query response containing both data and partial_causes. In the HTTP quickstart, the application checks the causes before printing the returned rows.

The second argument is an extra_headers map for this request. Add http = "1.3" under your application's [dependencies]alongside the quickstart's dependencies. An empty http::HeaderMap adds no request-specific headers; authentication still comes from the configured client.

use http::HeaderMap;

let response = client
    .execute_query_rows_with_completeness(
        "SELECT 1 AS connected",
        HeaderMap::new(),
    )
    .await?;

if !response.partial_causes.is_empty() {
    eprintln!("Incomplete query response: {:?}", response.partial_causes);
    return Err("query returned partial data; do not treat it as complete".into());
}

println!("{:#?}", response.data);

This fragment, including the block-local import, belongs inside the quickstart's main function. The complete quickstart pins SDK v0.2.4 and includes setup, credentials and error handling. The explicit-header variant adds a direct http dependency rather than relying on a transitive import.

An unusable completeness marker must not become success

There is another easy mistake: a completeness carrier exists, but contains only whitespace or commas. Filtering those values into an empty list would erase the fact that the answering service supplied an unusable marker.

The SDK distinguishes absence from malformed presence. An empty marker produces empty_partial_causes; an unreadable value produces unparseable_partial_causes. Unknown nonempty cause tokens are preserved rather than treated as complete because the client does not recognize them.

These are documented and tested client behaviors, not a claim that every data-loss or instrumentation problem can be detected.

Carry the limitation into the investigation

An application may reject partial data, display it with an explicit warning, or save it as limited evidence for later review. The right policy depends on the decision being made. What should not happen is silently discarding the limitation between the query, chart, report and explanation.

This becomes especially important when an AI system summarizes the evidence. The explanation should inherit its limitations, not make unavailable evidence sound conclusive. A deterministic check before interpretation is a useful starting point; a more confident paragraph is not a substitute.

We are building PackDB around that distinction. The SDK is public today. Hosted investigation workflows remain under internal exercise; this example does not announce general onboarding or continuous-operation certification.

Try the public tools

Start with the SDK quickstart. It requires an existing PackDB endpoint. To try a supporting component entirely locally, follow the no-account open-source guide. Its LogQL and supported-subset TraceQL parsers need no PackDB account and do not execute queries.

When your tooling returns only part of the evidence, does that limitation survive all the way to the person making the decision?