Capability availability

English | 简体中文

The public catalog states what Doris MCP Server 1.0 can represent. Runtime availability states what the current request identity can safely call on the current Apache Doris route. These are deliberately different concepts.

Evidence model

Availability combines:

  1. Catalog contract — the child exists in the reviewed 8/55 catalog.
  2. Normalized version — the relevant active Doris component satisfies the declared major.minor.patch range.
  3. Live feature probe — required SQL metadata, system table, function, or allowlisted HTTP endpoint is observable.
  4. Provider readiness — optional ADBC, Ossie, MetricFlow, or lineage provider is configured and healthy.
  5. Deployment mode — required classic/cloud/compute behavior is compatible.
  6. Route coherence — active component versions and request route can be evaluated safely; unknown or mixed evidence may fail closed.
  7. Authorization — the identity can discover and execute the exact child.
  8. Doris visibility — Doris allows the request-specific account to observe the required metadata/data.

No single predicate, including the version number, overrides the others.

Version parsing

The detector issues the Doris version probe and accepts real-world comments such as:

Doris version doris-3.0.3-rc03-43f06a5e26 (Cloud Mode)

Capability and certification keys use only:

3.0.3

RC/GA labels, commit hashes, and deployment hints remain diagnostic metadata. They do not create a separate support bucket. Component version vectors are evaluated conservatively; dead components remain visible in inventory but do not gate active capability ranges.

Snapshot lifecycle

A DorisCapabilitySnapshot is private to one resolved route and contains:

  • route fingerprint;
  • capability generation;
  • provider generation;
  • sanitized cluster fingerprint;
  • component version vector;
  • deployment mode and mixed-version flag;
  • bounded probe results and stable reason codes;
  • probed domains;
  • creation, expiry, and stale-until timestamps.

The detector caches snapshots for a bounded TTL and uses singleflight so concurrent discovery does not issue duplicate probe storms. Domain-specific evidence extends the coherent base generation. If the route changes during extension, the operation is rejected rather than combining routes.

A stale snapshot is eligible only inside the configured bounded stale window and only for the detector's documented failure conditions. Stale state changes the generation fingerprint and remains visible; it is not presented as fresh.

Manifest rendering

For every authorized child, the manifest returns an Availability object with fields such as:

{
  "status": "available",
  "callable": true,
  "reason_code": "CAPABILITY_AVAILABLE",
  "evidence_sources": [
    "catalog_contract",
    "version_range",
    "runtime_probe"
  ]
}

Typical status classes are available, unavailable/unsupported, degraded, misconfigured, unknown, and pending. The exact wire enum and reason codes are defined by the runtime models. callable is the execution gate.

The description may receive a short dynamic prefix to help a model read the state, but descriptions are not authoritative. Hosts and applications must use the structured object.

Discoverable but not callable

An authorized child stays in the manifest when its runtime predicates fail. This design lets the Host explain:

  • the connected Doris patch is too old;
  • a required system table or function is absent;
  • a provider is disabled or unhealthy;
  • a companion lineage store is incomplete;
  • MetricFlow is disabled, its sidecar is unhealthy, or Doris SQL compilation is unavailable;
  • ADBC was not explicitly requested even though its provider is configured;
  • a route has mixed/unknown component versions;
  • the Doris identity cannot observe required metadata;
  • configuration is missing or invalid.

Removing such children would make the contract appear unstable and would hide actionable operator information. Unauthorized children, by contrast, are filtered out and cannot be distinguished from nonexistent names.

Manifest version

manifest_version changes when any relevant public contract, authorization, capability generation, provider generation, or route evidence changes. A Host may send the discovered version with a child call. A mismatch returns CHILD_MANIFEST_STALE and requires rediscovery.

This prevents a time-of-check/time-of-use gap in which a model calls a child under an obsolete provider or capability description.

Hierarchical and flat modes

Hierarchical mode resolves availability during domain discovery. Flat mode also obtains each formal child from the current authorized manifest before returning it in tools/list. Both modes therefore share:

  • the same 55 children;
  • the same exact scopes;
  • the same dynamic availability;
  • the same schemas and dispatcher;
  • the same execution gate.

Flat mode is a Host compatibility fallback, not a capability bypass.

Certification versus runtime support

Release certification records evidence gathered against named Doris patch targets. Runtime support is decided for the connected route.

The project baseline is Doris 2.0.0+. The 1.0 target set is 2.0.15, 2.1.11, 3.0.3, 3.1.4, 4.0.5, 4.0.6, 4.0.7, 4.1.0, 4.1.1, 4.1.2, and 4.1.3. At the release boundary, 4.0.5 is the first fully certified target. A target marked target_uncertified is not treated as automatically broken; its runtime manifests remain authoritative and honest about observed support.

The baseline does not mean every child works on 2.0. Features introduced later remain discoverable with callable=false, a stable reason code, and the required version/provider/probe evidence. The reviewed release-note mapping is documented in the Doris version capability matrix.

Example: lineage selection

For trace_column_lineage:

  • before Doris 4.0.6, readable audit evidence can make bounded audit inference the primary path;
  • on Doris 4.0.6+, native mode additionally requires the configured companion provider, a readable store, required columns, and healthy evidence;
  • if native mode is expected but unavailable and audit is readable, the child can remain callable in explicit degraded fallback mode;
  • if neither source is usable, it remains discoverable but not callable.

This is the intended pattern for every version- and provider-dependent child: state the active evidence path, do not infer success from version alone, and never silently substitute one evidence class for another.

Example: ADBC selection

  • Doris 2.0 routes keep both ADBC children discoverable but not callable;
  • Doris 2.1.0 introduces Arrow Flight SQL, while 2.1.0-2.1.4 are reported as degraded because later 2.1 patches fixed empty-result and metadata behavior;
  • provider installation, configured Flight endpoints, and live probes remain mandatory on every eligible version;
  • a tool call must also carry explicit_adbc=true, which represents an end user request that explicitly selected ADBC or Arrow Flight SQL;
  • an ordinary SQL request always uses doris_query.execute_query.

Operator checklist

When a child is not callable:

  1. Call doris_cluster.get_runtime_capabilities if authorized.
  2. Read the child reason_code and evidence sources.
  3. Confirm the request identity and exact scope.
  4. Confirm the selected Doris route and account privileges.
  5. Confirm optional provider configuration and health.
  6. Compare the normalized three-part version with the required feature range.
  7. Rediscover after changing configuration, route, provider, or permissions.

See Troubleshooting for failure-specific procedures.