Native access and platform coverage

Use generated Databricks clients, native-complete adapters, or the credential-safe workspace API without losing Harness governance.

Fabric Harness is a native-superset integration. Developers do not need to wait for a Harness-specific wrapper before using a Databricks feature.

Three API levels

Level	Use it for	Surface
Native generated clients	Full request and response types for supported modular SDK services	`databricksSdk()` or `databricks(...).sdk`
Native-complete Fabric adapters	Databricks behavior plus cancellation, identity, policy, lineage, citations, or durable runtime integration	`databricksAiSearch()`, `databricksRagChain()`, governed tools
Workspace REST escape hatch	A new or uncommon Databricks API not yet present in the generated TypeScript SDK	`databricksWorkspaceApi()`

The third level is application-facing but is never projected into model context automatically. A mutating endpoint becomes a model tool only after the application adds input validation, capability policy, approval behavior, and ownership semantics.

Generated SDK clients

import { databricksSdk, databricksPrincipalFromEnv } from '@fabric-harness/databricks';

const sdk = databricksSdk({
  host: process.env.DATABRICKS_HOST!,
  principal: databricksPrincipalFromEnv(process.env),
});

const jobs = await sdk.jobs.list({});
const indexes = await sdk.vectorSearch.listVectorIndexes({
  endpointName: 'one-env-shared-endpoint-0',
});

These are the official modular @databricks/sdk-* clients. Fabric supplies one rotating identity and does not narrow their native method or result types.

Workspace API escape hatch

import {
  databricksPrincipalFromEnv,
  databricksWorkspaceApi,
} from '@fabric-harness/databricks';

const workspace = databricksWorkspaceApi({
  host: process.env.DATABRICKS_HOST!,
  principal: databricksPrincipalFromEnv(process.env),
});

const dashboards = await workspace.request<{
  dashboards?: Array<{ dashboard_id?: string; display_name?: string }>;
}>('GET', '/api/2.0/lakeview/dashboards', {
  query: { page_size: 25 },
});

The client:

accepts workspace-relative /api/* and /serving-endpoints/* paths only;
rejects origin escapes, normalized relative segments, and encoded path separators;
resolves the configured PAT, OAuth M2M, CLI, App, or OBO identity per attempt;
keeps authorization headers out of the public object and prevents callers from replacing them;
propagates cancellation and redacts credentials from errors;
retries transient reads, but never retries a mutation unless it is explicitly classified as idempotent and carries a stable idempotency key.

await workspace.request('POST', '/api/2.1/jobs/run-now', {
  body: { job_id: 123 },
  retry: 'idempotent',
  idempotencyKey: `submission:${submissionId}:job:123`,
});

Prefer a generated client when one exists. The escape hatch preserves native HTTP fidelity, but it does not supply domain schemas, cleanup ownership, policy, or a governed ToolDef. Use requestRaw() plus bodyEncoding: 'raw' for binary upload/download APIs.

Inspect coverage without guessing

DATABRICKS_CAPABILITIES reports independent dimensions rather than treating “supported” as one boolean:

import {
  DATABRICKS_PLATFORM_DOMAINS,
  getDatabricksCapability,
  listDatabricksCapabilities,
} from '@fabric-harness/databricks';

const search = getDatabricksCapability('ai-search');
console.log(search?.coverage);
// upstreamMaturity, apiFidelity, lifecycle, runtimeCertification,
// identities, contractClouds, certifiedClouds, knownGaps

const nativeComplete = listDatabricksCapabilities({
  apiFidelity: 'native-complete',
});

DATABRICKS_PLATFORM_DOMAINS deliberately includes product families with no current first-party surface. Delta Sharing, Clean Rooms, Marketplace, dashboard authoring, training, and other gaps therefore remain visible instead of disappearing from the compatibility story. Use databricksWorkspaceApi() for an unwrapped native API while a first-party adapter is being added.

Migration from the earlier AI Search API

The old queryType: 'text' | 'vector' option mixed two independent concepts. Use inputMode for the query representation and strategy for the Databricks retrieval algorithm:

// Earlier
aiSearch: { queryType: 'vector', embeddingEndpoint: 'bge-large-en' }

// Current
aiSearch: {
  inputMode: 'vector',
  strategy: 'ann',
  embeddingEndpoint: 'bge-large-en',
}

Text input defaults to strategy: 'hybrid'. Set ann, hybrid, or full-text explicitly when the retrieval contract is part of an evaluation or release gate.