Databricks recipes (`fh add`)

Use managed Databricks recipes to wire @fabric-harness/databricks into an existing project without copying examples by hand. Recipes write versioned files under .fabricharness/databricks/ (or a job for the analyst composite), update dependencies, and leave secrets in environment variables.

Greenfield projects can still start with:

fh init --template databricks

Recipes are for adding one product surface (or a small workload composite) afterward.

Generated Databricks recipes default to DATABRICKS_MODEL=system.ai.gpt-oss-20b and DATABRICKS_INFERENCE_MODE=auto. Set DATABRICKS_HOST to the workspace origin, for example https://<workspace-host>; do not include /ai-gateway/mlflow/v1 in the host value.

List and install

fh add
fh add --json

fh add databricks core
fh add databricks sql
fh add lakebase          # alias
fh add ai-search
fh add lakeflow
fh add jobs
fh add bundle          # checked-in Asset Bundle lifecycle
fh add system-tables-cost
fh add apps
fh add agent-services
fh add genie              # governed Genie + SELECT-only SQL copilot
fh add mcp--databricks    # governed managed MCP client
fh add data--databricks   # compatibility alias for genie
fh add kb--databricks     # compatibility alias for rag-chain
fh add lakehouse         # analyst composite (sql + tables)

fh add databricks lakebase --dry-run
fh update databricks sql

Catalog

“Lakehouse” is an alias for the analyst composite (governed SQL + UC tools), not a separate Databricks SDK product. kb--databricks maps to rag-chain. mcp--databricks now maps to the tested managed-MCP adapter; the generated factory is asynchronous because remote tool discovery happens at startup.

Typical flows

SQL analyst on Apps

fh init --template minimal
fh add databricks core
fh add databricks sql
fh add databricks analyst
# set DATABRICKS_* in .env
fh run databricks-analyst --question "What tables are in main?" --mock
fh build --target databricks-app

Genie analytics copilot

fh init --template minimal
fh add databricks genie
# set host, identity, Warehouse, Genie Space, catalog, and steward audience
fh test

The generated bundle adds databricks_genie_ask for governed natural-language questions and a separate sql_read tool. sql_read rejects mutations and multiple statements before calling Statement Execution. Arbitrary SQL is not generated; add databricksSqlTool() only with its required statement policy and separate approval routing. Genie lifecycle tools remain approval-bound. Missing Warehouse, Genie Space, identity, or steward configuration fails during bundle construction. The DATABRICKS_GENIE_SPACE_ID environment value is passed to the current conversation contract as agentId; generated code does not emit the retired legacy configuration alias.

RAG support agent

# Deterministic cookbook chain (retrieve → augment → generate):
fh add databricks rag-chain
fh run rag-answer --question "How do I reset my password?"

# Or agentic multi-tool search (SQL + search + …):
fh add ai-search
# Import createVectorSearchBundle() and pass modelProvider + tools into init()

See RAG on Databricks for citation validation, MLflow 3 export, and the quality workflow.

Managed MCP or AI Gateway MCP Service

fh add mcp--databricks
# set host, identity, a same-workspace MCP URL, and one safe tool name
fh test

The generated createDatabricksManagedMcp() returns a principal-bound bundle. Close bundle.managedMcp when the request or worker stops. Its default recipe exposes one named tool as read; expand allowTools and effects deliberately after reviewing the server contract. Missing host, credentials, URL, tool name, remote permission, or effect classification fails before the tool is usable. See the managed MCP integration guide.

Lakebase durable state

fh add lakebase
# In .fabricharness/config.ts:
#   import { createLakebasePersistence } from './databricks/lakebase.js';
#   persistence: createLakebasePersistence(),

Data engineering

fh add lakeflow
fh add jobs
# Use createLakeflowBundle() / createDatabricksJobsTools() in agent init

Checked-in Asset Bundle lifecycle

fh add databricks bundle
# set DATABRICKS_HOST, identity, DATABRICKS_BUNDLE_DIR, DATABRICKS_BUNDLE_TARGET
# Use createDatabricksAssetBundleTools() in agent init; deploy/run/destroy require approval

The generated createDatabricksAssetBundleTools() wires databricksAssetBundleLifecycle and its tools for the checked-in bundle in DATABRICKS_BUNDLE_DIR; the policy file adds databricks_bundle_deploy, databricks_bundle_run, and databricks_bundle_destroy to toolPolicy.requireApproval while validation stays read-only. Run submission is always --no-wait; poll status through the bounded jobs/lakeflow tools. The Databricks CLI must be on PATH. See Checked-in Asset Bundles for the fingerprint and managed-only-destroy semantics.

Conventions

• Package owns behavior — recipes only wire @fabric-harness/databricks into your workspace.
• Managed markers — files start with // fabric-harness-recipe: databricks/<name>@1 for safe fh update.
• No secrets in source — only env names are written to .env.example.
• Runnable verification — generated tests import from ../../.fabricharness/ and are compiled by the recipe contract suite.
• Merge config yourself — recipes do not silently rewrite config.ts; they print paths and env requirements.
• Deploy — Apps/Serving artifacts still come from fh build --target databricks-app|databricks-serving.

See also

• Databricks quickstart
• Integrations map
• Connector recipes reference
• Examples