Databricks

@mfbaig35r/databricksv2026.05.30.11· 1d agoMODELS

01README

Databricks Jobs, DLT pipelines, SQL warehouses, workspace notebooks/files, secrets, Unity Catalog, permissions, DBSQL queries, and Git Repos as Swamp models. Compose Databricks pipelines with non-Databricks resources in Swamp workflows.

02Release Notes

v0.11 (2026.05.30.11) - bug fix

Fix: create_or_update tombstone bug. Previously after delete, readResource returned tombstoned data not null, so create_or_update took the PATCH/PUT/reset path against a workspace resource that no longer existed and 404'd. Affected: job, dlt_pipeline, sql_warehouse, secret_scope, uc_catalog, uc_schema, uc_volume.

Fix is workspace-first reconciliation: each create_or_update now checks the workspace via GET (or list for secret_scope) before deciding which path to take. New helper existsOnWorkspace in _lib/databricks.ts. Smoke-validated on Free: uc_schema and job delete-then-create_or_update both correctly take create path now.

Side benefit: also handles out-of-band workspace deletes (someone deletes the job via UI, then create_or_update via Swamp correctly recreates instead of failing).

No breaking changes from v0.10.

03Models15

@mfbaig35r/databricks/jobv2026.05.30.11job.ts

fn create(name: string, tasks: array, job_clusters?: array, schedule?: object, tags?: record, timeout_seconds?: number, max_concurrent_runs?: number, queue?: object)

Create a Databricks job via POST /api/2.2/jobs/create.

Argument	Type	Required
name	string	yes
tasks	array	yes
job_clusters?	array	no
schedule?	object	no
tags?	record	no
timeout_seconds?	number	no
max_concurrent_runs?	number	no
queue?	object	no

fn read(job_ref: string)

Fetch current settings from the workspace via GET /api/2.2/jobs/get.

Argument	Type	Required	Description
job_ref	string	yes

fn update(job_ref: string)

Full replace via POST /api/2.2/jobs/reset.

Argument	Type	Required	Description
job_ref	string	yes

fn delete(job_ref: string)

Delete the job via POST /api/2.2/jobs/delete.

Argument	Type	Required	Description
job_ref	string	yes

fn run(job_ref: string, job_parameters?: record, notebook_params?: record, idempotency_token?: string)

Trigger a one-off run via POST /api/2.2/jobs/run-now.

Argument	Type	Required
job_ref	string	yes
job_parameters?	record	no
notebook_params?	record	no
idempotency_token?	string	no

fn wait_run(run_id: number, poll_seconds: number, timeout_seconds: number)

Poll GET /api/2.2/jobs/runs/get until life_cycle_state is terminal

Argument	Type	Required
run_id	number	yes
poll_seconds	number	yes
timeout_seconds	number	yes

fn cancel_run(run_id: number)

POST /api/2.2/jobs/runs/cancel for a given run_id.

Argument	Type	Required	Description
run_id	number	yes

fn create_or_update(name: string, tasks: array, job_clusters?: array, schedule?: object, tags?: record, timeout_seconds?: number, max_concurrent_runs?: number, queue?: object)

Reconcile via Swamp data + workspace check: if a 'job' resource

Argument	Type	Required
name	string	yes
tasks	array	yes
job_clusters?	array	no
schedule?	object	no
tags?	record	no
timeout_seconds?	number	no
max_concurrent_runs?	number	no
queue?	object	no

Resources

job(infinite)— A Databricks Jobs API 2.2 job, keyed by user-supplied name

last_run(workflow)— Most recent run triggered through this model

@mfbaig35r/databricks/notebookv2026.05.30.11notebook.ts

fn upload(path: string, content: string, language: enum, overwrite: boolean)

Import a notebook source to the workspace via

Argument	Type	Required	Description
path	string	yes
content	string	yes	Raw notebook source text (NOT base64)
language	enum	yes
overwrite	boolean	yes

fn read(path: string, format: enum)

Export a notebook from the workspace via

Argument	Type	Required	Description
path	string	yes
format	enum	yes

fn delete(path: string, recursive: boolean)

Delete a notebook from the workspace via

Argument	Type	Required	Description
path	string	yes
recursive	boolean	yes

Resources

notebook(infinite)— A workspace notebook, keyed by absolute path.

@mfbaig35r/databricks/dlt_pipelinev2026.05.30.11dlt_pipeline.ts

fn create(name: string, storage?: string, configuration?: record, catalog?: string, target?: string, libraries: array, clusters?: array, continuous?: boolean, development?: boolean, photon?: boolean, edition?: enum, channel?: enum, serverless?: boolean)

Create a DLT pipeline via POST /api/2.0/pipelines.

Argument	Type	Required	Description
name	string	yes
storage?	string	no	DBFS/UC volume path for pipeline storage. Optional on Free/serverless.
configuration?	record	no	Spark conf passed into the pipeline runtime
catalog?	string	no	Unity Catalog target catalog (use with target schema)
target?	string	no	Default schema/database for pipeline outputs
libraries	array	yes	Notebooks or files that define the pipeline
clusters?	array	no
continuous?	boolean	no	true = streaming, false = triggered (default false)
development?	boolean	no	true = dev mode (no auto-restart on failure)
photon?	boolean	no
edition?	enum	no	DLT pricing edition; ignored on Free/serverless
channel?	enum	no
serverless?	boolean	no	Use serverless compute (required on Databricks Free)

fn read(pipeline_ref: string)

Fetch live pipeline state via GET /api/2.0/pipelines/{pipeline_id}.

Argument	Type	Required	Description
pipeline_ref	string	yes

fn update(pipeline_ref: string)

Full replace pipeline settings via PUT /api/2.0/pipelines/{pipeline_id}.

Argument	Type	Required	Description
pipeline_ref	string	yes

fn delete(pipeline_ref: string)

Delete the pipeline via DELETE /api/2.0/pipelines/{pipeline_id}.

Argument	Type	Required	Description
pipeline_ref	string	yes

fn start_update(pipeline_ref: string, full_refresh: boolean, full_refresh_selection?: array, refresh_selection?: array, cause?: string)

Trigger a pipeline update via POST /api/2.0/pipelines/{pipeline_id}/updates.

Argument	Type	Required	Description
pipeline_ref	string	yes
full_refresh	boolean	yes
full_refresh_selection?	array	no	Subset of tables to fully refresh
refresh_selection?	array	no	Subset of tables to incrementally refresh
cause?	string	no

fn wait_update(pipeline_ref: string, update_id: string, poll_seconds: number, timeout_seconds: number)

Poll GET /api/2.0/pipelines/{pipeline_id}/updates/{update_id} until

Argument	Type	Required
pipeline_ref	string	yes
update_id	string	yes
poll_seconds	number	yes
timeout_seconds	number	yes

fn stop(pipeline_ref: string)

Stop the pipeline via POST /api/2.0/pipelines/{pipeline_id}/stop.

Argument	Type	Required	Description
pipeline_ref	string	yes

fn create_or_update(name: string, storage?: string, configuration?: record, catalog?: string, target?: string, libraries: array, clusters?: array, continuous?: boolean, development?: boolean, photon?: boolean, edition?: enum, channel?: enum, serverless?: boolean)

Reconcile via Swamp data + workspace check: if a 'pipeline'

Argument	Type	Required	Description
name	string	yes
storage?	string	no	DBFS/UC volume path for pipeline storage. Optional on Free/serverless.
configuration?	record	no	Spark conf passed into the pipeline runtime
catalog?	string	no	Unity Catalog target catalog (use with target schema)
target?	string	no	Default schema/database for pipeline outputs
libraries	array	yes	Notebooks or files that define the pipeline
clusters?	array	no
continuous?	boolean	no	true = streaming, false = triggered (default false)
development?	boolean	no	true = dev mode (no auto-restart on failure)
photon?	boolean	no
edition?	enum	no	DLT pricing edition; ignored on Free/serverless
channel?	enum	no
serverless?	boolean	no	Use serverless compute (required on Databricks Free)

Resources

pipeline(infinite)— A DLT pipeline, keyed by user-supplied name

last_update(workflow)— Most recent update triggered through this model

@mfbaig35r/databricks/sql_warehousev2026.05.30.11sql_warehouse.ts

fn create(name: string, min_num_clusters: number, max_num_clusters: number, auto_stop_mins: number, enable_photon?: boolean, enable_serverless_compute: boolean, warehouse_type: enum, spot_instance_policy?: enum, channel?: object, tags?: object)

Create a SQL warehouse via POST /api/2.0/sql/warehouses.

Argument	Type	Required	Description
name	string	yes
min_num_clusters	number	yes
max_num_clusters	number	yes
auto_stop_mins	number	yes	Minutes idle before auto-stop. 0 disables auto-stop.
enable_photon?	boolean	no
enable_serverless_compute	boolean	yes	Required on Databricks Free (serverless-only).
warehouse_type	enum	yes
spot_instance_policy?	enum	no
channel?	object	no
tags?	object	no

fn read(warehouse_ref: string)

Fetch live warehouse state via GET /api/2.0/sql/warehouses/{id}.

Argument	Type	Required	Description
warehouse_ref	string	yes

fn list()

List all warehouses on the workspace via GET /api/2.0/sql/warehouses.

fn adopt(name: string, warehouse_id: string)

Argument	Type	Required	Description
name	string	yes
warehouse_id	string	yes

fn update(warehouse_ref: string)

Full replace warehouse settings via POST /api/2.0/sql/warehouses/{id}/edit.

Argument	Type	Required	Description
warehouse_ref	string	yes

fn delete(warehouse_ref: string)

Delete the warehouse via DELETE /api/2.0/sql/warehouses/{id}.

Argument	Type	Required	Description
warehouse_ref	string	yes

fn start(warehouse_ref: string)

Start the warehouse via POST /api/2.0/sql/warehouses/{id}/start.

Argument	Type	Required	Description
warehouse_ref	string	yes

fn stop(warehouse_ref: string)

Stop the warehouse via POST /api/2.0/sql/warehouses/{id}/stop.

Argument	Type	Required	Description
warehouse_ref	string	yes

fn run_query(warehouse_ref: string, statement: string, catalog?: string, schema?: string, wait_timeout_seconds: number, on_wait_timeout: enum, row_limit?: number)

Submit a SQL statement via POST /api/2.0/sql/statements.

Argument	Type	Required	Description
warehouse_ref	string	yes
statement	string	yes
catalog?	string	no
schema?	string	no
wait_timeout_seconds	number	yes	0 = async (returns statement_id, poll with wait_statement). 5-50 = sync wait.
on_wait_timeout	enum	yes
row_limit?	number	no

fn wait_statement(statement_id: string, poll_seconds: number, timeout_seconds: number)

Poll GET /api/2.0/sql/statements/{statement_id} until state is

Argument	Type	Required
statement_id	string	yes
poll_seconds	number	yes
timeout_seconds	number	yes

fn cancel_statement(statement_id: string)

Cancel a running statement via POST /api/2.0/sql/statements/{id}/cancel.

Argument	Type	Required	Description
statement_id	string	yes

fn create_or_update(name: string, min_num_clusters: number, max_num_clusters: number, auto_stop_mins: number, enable_photon?: boolean, enable_serverless_compute: boolean, warehouse_type: enum, spot_instance_policy?: enum, channel?: object, tags?: object)

Reconcile via Swamp data + workspace check: if a 'warehouse'

Argument	Type	Required	Description
name	string	yes
min_num_clusters	number	yes
max_num_clusters	number	yes
auto_stop_mins	number	yes	Minutes idle before auto-stop. 0 disables auto-stop.
enable_photon?	boolean	no
enable_serverless_compute	boolean	yes	Required on Databricks Free (serverless-only).
warehouse_type	enum	yes
spot_instance_policy?	enum	no
channel?	object	no
tags?	object	no

Resources

warehouse(infinite)— A SQL warehouse, keyed by user-supplied name. State refreshed on read.

last_statement(workflow)— Most recent statement submitted through this model.

@mfbaig35r/databricks/workspace_filev2026.05.30.11workspace_file.ts

fn upload(path: string, content: string, overwrite: boolean)

Import a file to the workspace via

Argument	Type	Required	Description
path	string	yes
content	string	yes	Raw file content (NOT base64). UTF-8 text only in v0.6.
overwrite	boolean	yes

fn read(path: string)

Export a workspace file via GET /api/2.0/workspace/export?format=AUTO.

Argument	Type	Required	Description
path	string	yes

fn delete(path: string)

Delete the workspace file via POST /api/2.0/workspace/delete.

Argument	Type	Required	Description
path	string	yes

Resources

file(infinite)— A workspace file (or, in some workspaces, a notebook), keyed by

@mfbaig35r/databricks/secret_scopev2026.05.30.11secret_scope.ts

fn create(scope: string, initial_manage_principal?: string, scope_backend_type?: enum)

Create a secret scope via POST /api/2.0/secrets/scopes/create.

Argument	Type	Required	Description
scope	string	yes
initial_manage_principal?	string	no	Principal granted MANAGE on the scope (e.g. 'users').
scope_backend_type?	enum	no	DATABRICKS = workspace-managed (default). AZURE_KEYVAULT only on Azure.

fn list()

List all secret scopes on the workspace via

fn create_or_update(scope: string, initial_manage_principal?: string, scope_backend_type?: enum)

Reconcile against the workspace: list scopes; if args.scope is

Argument	Type	Required	Description
scope	string	yes
initial_manage_principal?	string	no	Principal granted MANAGE on the scope (e.g. 'users').
scope_backend_type?	enum	no	DATABRICKS = workspace-managed (default). AZURE_KEYVAULT only on Azure.

fn delete(scope_ref: string)

Delete a secret scope via POST /api/2.0/secrets/scopes/delete.

Argument	Type	Required	Description
scope_ref	string	yes

Resources

scope(infinite)— A workspace secret scope, keyed by scope name.

@mfbaig35r/databricks/secretv2026.05.30.11secret.ts

fn put(scope: string, key: string, string_value: string)

Put a secret via POST /api/2.0/secrets/put. Writes scope+key

Argument	Type	Required	Description
scope	string	yes
key	string	yes
string_value	string	yes	The secret value. Pass via CEL vault.get to avoid surfacing the literal:

fn delete(scope: string, key: string)

Delete a secret via POST /api/2.0/secrets/delete.

Argument	Type	Required	Description
scope	string	yes
key	string	yes

fn list(scope: string)

List all keys in a scope via GET /api/2.0/secrets/list?scope=...

Argument	Type	Required	Description
scope	string	yes

Resources

secret_meta(infinite)— Metadata for a workspace secret (scope + key only).

@mfbaig35r/databricks/uc_catalogv2026.05.30.11uc_catalog.ts

fn create(name: string, comment?: string, properties?: record, storage_root?: string)

Create a catalog via POST /api/2.1/unity-catalog/catalogs.

Argument	Type	Required	Description
name	string	yes
comment?	string	no
properties?	record	no
storage_root?	string	no	Managed-storage URI for the catalog (s3://, abfss://, gs://).

fn read(catalog_ref: string)

GET /api/2.1/unity-catalog/catalogs/{name}.

Argument	Type	Required	Description
catalog_ref	string	yes

fn update(catalog_ref: string, new_name?: string, comment?: string, owner?: string, properties?: record)

PATCH /api/2.1/unity-catalog/catalogs/{name}.

Argument	Type	Required
catalog_ref	string	yes
new_name?	string	no
comment?	string	no
owner?	string	no
properties?	record	no

fn delete(catalog_ref: string, force: boolean)

DELETE /api/2.1/unity-catalog/catalogs/{name}.

Argument	Type	Required	Description
catalog_ref	string	yes
force	boolean	yes

fn list()

List all catalogs via GET /api/2.1/unity-catalog/catalogs.

fn create_or_update(name: string, comment?: string, properties?: record, storage_root?: string)

Reconcile against the workspace: GET the catalog first; if it

Argument	Type	Required	Description
name	string	yes
comment?	string	no
properties?	record	no
storage_root?	string	no	Managed-storage URI for the catalog (s3://, abfss://, gs://).

Resources

catalog(infinite)— A Unity Catalog catalog, keyed by name.

@mfbaig35r/databricks/uc_schemav2026.05.30.11uc_schema.ts

fn create(name: string, catalog_name: string, comment?: string, properties?: record, storage_root?: string)

Create a schema via POST /api/2.1/unity-catalog/schemas.

Argument	Type	Required	Description
name	string	yes	Schema name (NOT full_name)
catalog_name	string	yes	Parent catalog (e.g. 'workspace' on Free)
comment?	string	no
properties?	record	no
storage_root?	string	no	External storage root (managed-storage UC volumes path)

fn read(schema_ref: string)

GET /api/2.1/unity-catalog/schemas/{full_name}.

Argument	Type	Required	Description
schema_ref	string	yes

fn update(schema_ref: string, new_name?: string, comment?: string, owner?: string, properties?: record)

Update schema via PATCH /api/2.1/unity-catalog/schemas/{full_name}.

Argument	Type	Required
schema_ref	string	yes
new_name?	string	no
comment?	string	no
owner?	string	no
properties?	record	no

fn delete(schema_ref: string, force: boolean)

DELETE /api/2.1/unity-catalog/schemas/{full_name}.

Argument	Type	Required	Description
schema_ref	string	yes
force	boolean	yes

fn list(catalog_name: string)

List schemas in a catalog via GET /api/2.1/unity-catalog/schemas?catalog_name=...

Argument	Type	Required	Description
catalog_name	string	yes

fn create_or_update(name: string, catalog_name: string, comment?: string, properties?: record, storage_root?: string)

Reconcile against the workspace: GET the schema first; if it

Argument	Type	Required	Description
name	string	yes	Schema name (NOT full_name)
catalog_name	string	yes	Parent catalog (e.g. 'workspace' on Free)
comment?	string	no
properties?	record	no
storage_root?	string	no	External storage root (managed-storage UC volumes path)

Resources

schema(infinite)— A Unity Catalog schema, keyed by user-supplied name.

@mfbaig35r/databricks/uc_tablev2026.05.30.11uc_table.ts

fn read(full_name: string)

Fetch table metadata via GET /api/2.1/unity-catalog/tables/{full_name}.

Argument	Type	Required	Description
full_name	string	yes

fn delete(full_name: string)

DELETE /api/2.1/unity-catalog/tables/{full_name}.

Argument	Type	Required	Description
full_name	string	yes

fn list(catalog_name: string, schema_name: string, max_results?: number)

List tables in a schema via GET /api/2.1/unity-catalog/tables.

Argument	Type	Required
catalog_name	string	yes
schema_name	string	yes
max_results?	number	no

Resources

table(infinite)— An observed UC table snapshot. observed_time_ms records when

@mfbaig35r/databricks/uc_volumev2026.05.30.11uc_volume.ts

fn create(name: string, catalog_name: string, schema_name: string, comment?: string, storage_location?: string)

Create a volume via POST /api/2.1/unity-catalog/volumes.

Argument	Type	Required	Description
name	string	yes
catalog_name	string	yes
schema_name	string	yes
comment?	string	no
storage_location?	string	no	Required for EXTERNAL volumes (cloud URI).

fn read(volume_ref: string)

GET /api/2.1/unity-catalog/volumes/{full_name}.

Argument	Type	Required	Description
volume_ref	string	yes

fn update(volume_ref: string, new_name?: string, comment?: string, owner?: string)

PATCH /api/2.1/unity-catalog/volumes/{full_name}.

Argument	Type	Required
volume_ref	string	yes
new_name?	string	no
comment?	string	no
owner?	string	no

fn delete(volume_ref: string)

DELETE /api/2.1/unity-catalog/volumes/{full_name}.

Argument	Type	Required	Description
volume_ref	string	yes

fn list(catalog_name: string, schema_name: string, max_results?: number)

List volumes via GET /api/2.1/unity-catalog/volumes.

Argument	Type	Required
catalog_name	string	yes
schema_name	string	yes
max_results?	number	no

fn create_or_update(name: string, catalog_name: string, schema_name: string, comment?: string, storage_location?: string)

Reconcile against the workspace: GET the volume first; if it

Argument	Type	Required	Description
name	string	yes
catalog_name	string	yes
schema_name	string	yes
comment?	string	no
storage_location?	string	no	Required for EXTERNAL volumes (cloud URI).

Resources

volume(infinite)— A Unity Catalog volume, keyed by user-supplied name.

@mfbaig35r/databricks/workspace_permissionsv2026.05.30.11workspace_permissions.ts

fn get(object_id: string)

GET /api/2.0/permissions/{object_type}/{object_id}. Returns the

Argument	Type	Required	Description
object_id	string	yes

fn set(object_id: string, access_control_list: array)

PUT /api/2.0/permissions/{object_type}/{object_id}. Full replace

Argument	Type	Required	Description
object_id	string	yes
access_control_list	array	yes

fn update(object_id: string, access_control_list: array)

PATCH /api/2.0/permissions/{object_type}/{object_id}. Additive

Argument	Type	Required	Description
object_id	string	yes
access_control_list	array	yes

fn list_levels(object_id: string)

GET /api/2.0/permissions/{object_type}/{object_id}/permissionLevels.

Argument	Type	Required	Description
object_id	string	yes	Sample object id; needed because levels are returned per-object

Resources

permissions(infinite)— Last access_control_list applied to a (object_type, object_id)

@mfbaig35r/databricks/uc_permissionsv2026.05.30.11uc_permissions.ts

fn get(full_name: string)

GET /api/2.1/unity-catalog/permissions/{securable_type}/{full_name}.

Argument	Type	Required	Description
full_name	string	yes	Securable identifier: '<catalog>' for catalog, '<catalog>.<schema>' for schema, '<catalog>.<schema>.<table>' for table/volume/function

fn get_effective(full_name: string)

GET /api/2.1/unity-catalog/effective-permissions/{securable_type}/{full_name}.

Argument	Type	Required	Description
full_name	string	yes	Securable identifier: '<catalog>' for catalog, '<catalog>.<schema>' for schema, '<catalog>.<schema>.<table>' for table/volume/function

fn update(full_name: string, changes: array)

PATCH /api/2.1/unity-catalog/permissions/{securable_type}/{full_name}.

Argument	Type	Required	Description
full_name	string	yes
changes	array	yes

Resources

uc_permissions(infinite)— Last set of changes applied to a UC securable. update writes this;

@mfbaig35r/databricks/queryv2026.05.30.11query.ts

fn create(name: string, query: string, warehouse_id: string, description?: string, parent?: string, run_as_role?: enum, tags?: array)

Create a saved query via POST /api/2.0/sql/queries.

Argument	Type	Required	Description
name	string	yes
query	string	yes	SQL text
warehouse_id	string	yes	SQL warehouse the query runs against (NOT the data_source_id)
description?	string	no
parent?	string	no	Folder path in the workspace, e.g. 'folders/<id>'
run_as_role?	enum	no
tags?	array	no

fn read(query_ref: string)

GET /api/2.0/sql/queries/{query_id}.

Argument	Type	Required	Description
query_ref	string	yes

fn update(query_ref: string, name?: string, query?: string, warehouse_id?: string, description?: string, run_as_role?: enum, tags?: array)

Update a saved query via POST /api/2.0/sql/queries/{query_id}.

Argument	Type	Required
query_ref	string	yes
name?	string	no
query?	string	no
warehouse_id?	string	no
description?	string	no
run_as_role?	enum	no
tags?	array	no

fn delete(query_ref: string)

DELETE /api/2.0/sql/queries/{query_id}.

Argument	Type	Required	Description
query_ref	string	yes

fn list(page_size?: number)

GET /api/2.0/sql/queries (list all queries).

Argument	Type	Required	Description
page_size?	number	no

Resources

query(infinite)— A saved DBSQL query, keyed by user-supplied name.

@mfbaig35r/databricks/repov2026.05.30.11repo.ts

fn create(name: string, url: string, path?: string, branch?: string)

Create a Git Repo via POST /api/2.0/repos. Clones the repository

Argument	Type	Required	Description
name	string	yes	Swamp-side handle. Workspace path becomes /Repos/<user>/<name> unless `path` is set.
url	string	yes	Git repository URL
path?	string	no	Absolute workspace path. Defaults to /Repos/<current-user>/<name>.
branch?	string	no	Initial branch to check out. Defaults to remote default.

fn read(repo_ref: string)

GET /api/2.0/repos/{repo_id}.

Argument	Type	Required	Description
repo_ref	string	yes

fn update(repo_ref: string, branch?: string, tag?: string)

PATCH /api/2.0/repos/{repo_id}. Switch branch/tag (triggers a pull)

Argument	Type	Required	Description
repo_ref	string	yes
branch?	string	no	New branch to check out. Triggers a pull. Mutually exclusive with `tag`.
tag?	string	no	Tag to check out. Mutually exclusive with `branch`.

fn pull(repo_ref: string)

PATCH /api/2.0/repos/{repo_id} with the current branch. Pulls the

Argument	Type	Required	Description
repo_ref	string	yes

fn delete(repo_ref: string)

DELETE /api/2.0/repos/{repo_id}.

Argument	Type	Required	Description
repo_ref	string	yes

fn list(path_prefix?: string, next_page_token?: string)

GET /api/2.0/repos (list all repos).

Argument	Type	Required	Description
path_prefix?	string	no	Filter by workspace path prefix (e.g. /Repos/me)
next_page_token?	string	no

Resources

repo(infinite)— A Databricks Git Repo, keyed by user-supplied name.

04Previous Versions10

2026.05.30.10May 30, 2026

v0.10 (2026.05.30.10) - Phase 3 (query + repo)

Two new models close the last two critical gaps from the v0.7 review:

@mfbaig35r/databricks/query (create, read, update, delete, list) Manages DBSQL saved queries via /api/2.0/sql/queries. The query_id that this model returns pairs with the job model's sql_task.query.query_id field.
@mfbaig35r/databricks/repo (create, read, update, pull, delete, list) Manages Databricks Git Repos via /api/2.0/repos. Real Databricks jobs reference notebooks via repo paths rather than uploading to /Shared/. pull re-sends the stored branch in the PATCH body (Databricks rejects empty-body PATCH).

Smoke validated end-to-end on Databricks Free serverless:

query: list (empty), create with SELECT 1 on Starter warehouse, read, list (1 visible), delete
repo: create against github.com/mfbaig35r/swamp-databricks (public, no Git PAT setup required), read, pull (after fix), delete

No breaking changes from v0.9.

Total models: 15. End-to-end smoke validated since v0.1: job, notebook, dlt_pipeline, sql_warehouse, workspace_file, secret_scope, secret, uc_schema, uc_table, uc_volume, uc_catalog (list+schema-validated create), workspace_permissions, uc_permissions, query, repo. uc_table has no create (use sql_warehouse.run_query).

Added 2 models. updated labels

2026.05.30.9May 30, 2026

v0.9 (2026.05.30.9) - Phase 2 (permissions)

Phase 1 (uc_catalog + idempotency):

New model: @mfbaig35r/databricks/uc_catalog (create, read, update, delete, list, create_or_update). Completes the UC top-down tree.
New create_or_update method on: job, dlt_pipeline, sql_warehouse, secret_scope, uc_catalog, uc_schema, uc_volume. Reconcile semantics via Swamp data layer.

Phase 2 (permissions):

New model: @mfbaig35r/databricks/workspace_permissions (get, set, update, list_levels). Workspace-level ACLs for jobs, pipelines, warehouses, notebooks, repos, queries, dashboards, alerts, experiments, registered-models, serving-endpoints, clusters, cluster-policies, instance-pools.
New model: @mfbaig35r/databricks/uc_permissions (get, get_effective, update). UC grants on catalogs, schemas, tables, volumes, functions, external_locations, storage_credentials, models. Changes-style PATCH (add/remove per principal).

Smoke validated end-to-end on Free serverless:

uc_schema.create_or_update fresh create + same-call patch
workspace_permissions.list_levels (5 levels for sql/warehouses), get on Starter Warehouse, update to grant CAN_VIEW on a job to users group
uc_permissions.get on workspace catalog, update to grant USE_SCHEMA on a smoke schema to account users, verify

Tombstone caveat (Phase 1): create_or_update checks Swamp data layer not workspace. After delete, the resource is tombstoned and create_or_update will mistakenly take the update path. Use create() explicitly for delete-then-recreate flows. v0.9 candidate fix: workspace-first lookup.

uc_catalog.create requires storage_root on Free (no default metastore storage); ships as schema-validated only.

No breaking changes from v0.7.

Added 2 models. updated labels

2026.05.30.8May 30, 2026

v0.8 (2026.05.30.8) - Phase 1: uc_catalog + idempotency

New model: @mfbaig35r/databricks/uc_catalog (create, read, update, delete, list, create_or_update). Completes the UC top-down tree: catalog -> schema -> table/volume.
New create_or_update method on: job, dlt_pipeline, sql_warehouse, secret_scope, uc_catalog, uc_schema, uc_volume. Reconcile semantics: if a resource with args.name exists in Swamp's data layer, take the update path (PATCH/PUT/reset); otherwise create. Closes the "create errors on second run" gap that blocked real automation.

Tombstone caveat: create_or_update checks Swamp's data layer, not the workspace. If you call delete and then create_or_update with the same name, the second call will hit the patch path against a workspace resource that no longer exists and fail. For now, delete + recreate flows should use create explicitly. v0.9 may add a workspace-first lookup variant.

notebook.upload and workspace_file.upload already have idempotency via overwrite: true. secret.put is already idempotent (Databricks replaces on put). uc_table has no create endpoint so no create_or_update.

Smoke validated on Free serverless: catalog list (3 catalogs visible), schema create_or_update fresh-call (create path) + same-call-again (patch path), delete cleanup. uc_catalog.create requires storage_root on Free (no default metastore storage available); ships as schema-validated.

No breaking changes from v0.7.

Added 1, modified 6 models

2026.05.30.7May 30, 2026

v0.7 (2026.05.30.7)

Five new models, ten total.

Secrets (workspace-level, distinct from Swamp vault):

@mfbaig35r/databricks/secret_scope: create, list, delete.
@mfbaig35r/databricks/secret: put, delete, list (keys only, never values). Secret values pass through to Databricks and are NEVER persisted in Swamp's data layer. Pass values via CEL ${{ vault.get(...) }}.

Unity Catalog:

@mfbaig35r/databricks/uc_schema: create, read, update, delete, list.
@mfbaig35r/databricks/uc_table: read, delete, list. Tables are NOT created via this API; use sql_warehouse.run_query or a job notebook task to CREATE TABLE, then this model captures the snapshot.
@mfbaig35r/databricks/uc_volume: create, read, update, delete, list.

No breaking changes from v0.6.

Added 5 models. updated labels

2026.05.30.6May 30, 2026

v0.6 (2026.05.30.6)

New model: @mfbaig35r/databricks/workspace_file. Owns upload, read (export), and delete for workspace files (FILE object type). Distinct from @mfbaig35r/databricks/notebook (which owns NOTEBOOK objects). Use this when a downstream task references a plain file at a workspace path: sql_task.file, spark_python_task.python_file, dbt project files, etc.
sql_task end-to-end validated. Closes the v0.5 gap: workspace_file upload -> job with sql_task.file -> run -> wait_run COMPLETED + SUCCESS on Databricks Free serverless.
upload uses POST /api/2.0/workspace/import with format=AUTO and no language, then calls /api/2.0/workspace/get-status to verify and record the resulting object_type on the resource. Modern workspaces produce FILE; older workspaces may produce NOTEBOOK depending on content, and the resource reflects what was created.

No breaking changes from v0.5.

Added 1 models

2026.05.30.5May 30, 2026

v0.5 (2026.05.30.5)

Expanded job task-type schema from 3 types to 10. Added: spark_python_task, spark_jar_task, python_wheel_task, dbt_task, run_job_task, condition_task, for_each_task (Zod recursive via z.lazy). sql_task now also covers dashboard and alert variants alongside query and file. Workflows that use any of these no longer reject at the schema layer.
End-to-end smoke validation in this release covers notebook_task only (matches what the Databricks Free smoke environment can reasonably exercise). Other task types are schema-validated; the Databricks API accepts the schemas at job-create time. If you hit an edge case on a real workload, open an issue at github.com/mfbaig35r/swamp-databricks.

Not yet covered: spark_submit_task, clean_rooms_notebook_task. Add in a later release if there is real demand.

No breaking changes from v0.4.

2026.05.30.4May 30, 2026

v0.4 (2026.05.30.4)

New model: @mfbaig35r/databricks/sql_warehouse. Lifecycle (create, read, update, delete, start, stop) plus SQL Statement Execution (run_query, wait_statement, cancel_statement). run_query waits synchronously up to 50 seconds; longer-running statements get a last_statement resource so wait_statement can take over.
sql_warehouse.adopt method: register an existing workspace warehouse as a Swamp resource without creating a new one. Required pattern on Databricks Free where warehouse quotas are small and the workspace ships with a Starter Warehouse already.
This closes the DLT cleanup gap from v0.3: run_query can execute the DROP TABLE for tables materialized by a deleted pipeline.

No breaking changes from v0.3.

Added 1 models. updated labels

2026.05.30.3May 30, 2026

v0.3 (2026.05.30.3)

DLT pipeline model validated end-to-end on Databricks Free serverless. The "preview" caveat from v0.2 is removed.
Schema fix: PipelineSettings now requires catalog when serverless: true via a Zod .refine(). Surfaces the Databricks API constraint at validation time instead of as a 400 INVALID_PARAMETER_VALUE on create.
README clarifies that DELETE /api/2.0/pipelines/{id} does NOT drop the Delta tables a pipeline materialized. After deleting a pipeline, tables in the target schema persist; remove them with a DROP TABLE in a SQL warehouse or notebook. A future @mfbaig35r/databricks/sql_warehouse model will make this a Swamp-native operation.

No breaking changes from v0.2.

2026.05.30.2yankedMay 30, 2026

v0.2 (2026.05.30.2)

New model: @mfbaig35r/databricks/notebook. Owns upload, read (export), and delete for workspace notebooks. The upload_notebook / delete_notebook methods and 'notebook' resource have moved off the job model into this dedicated model. Workflows that called those methods on the job model in v0.1 must update their model: references to the new model.
New model: @mfbaig35r/databricks/dlt_pipeline. Lifecycle for Delta Live Tables pipelines: create, read, update (full replace via PUT), delete, start_update (POST /pipelines/{id}/updates), wait_update (poll until COMPLETED / FAILED / CANCELED), stop. Libraries support notebook or file references. On Databricks Free serverless, set serverless: true on create. Note: DLT pipeline behavior on Databricks Free has not been validated end-to-end yet; treat as preview until smoke-tested.
Refactor: workspace auth + bearer fetch + global args schema extracted into extensions/models/_lib/databricks.ts. All three models share one auth surface.
Breaking from v0.1: upload_notebook / delete_notebook removed from @mfbaig35r/databricks/job. Workflows that used those must switch to @mfbaig35r/databricks/notebook upload / delete.

Added 2, modified 1 models. updated labels

2026.05.30.1May 30, 2026

Initial release. Adds the @mfbaig35r/databricks/job model with create, read, update (full reset), delete, run, wait_run, and cancel_run methods. Auth via PAT (resolved through CEL: vault.get) or OAuth M2M client_credentials. Azure MSI is stubbed.

v1 task types validated by Zod: notebook_task, sql_task, pipeline_task. Other Databricks task types (spark_python_task, python_wheel_task, dbt_task, run_job_task, for_each_task, condition_task, spark_jar_task) will reject at the schema layer until added in subsequent releases.

Preview surface (will move): upload_notebook and delete_notebook methods, and the 'notebook' resource, are convenience APIs for smoke-testing the run/wait_run loop end-to-end. They will split into a dedicated @mfbaig35r/databricks/notebook model in v0.2. Workflows that call them by name will need to update the model reference at that point.

Validated end-to-end on Databricks Free (AWS serverless): upload_notebook -> create -> run -> wait_run (TERMINATED+SUCCESS) -> delete -> delete_notebook, zero orphan workspace state.

05Stats

100 / 100

Downloads

Archive size

63.6 KB

Has README or module doc2/2earned
README has a code example1/1earned
README is substantive1/1earned
Most symbols documented1/1earned
No slow types1/1earned
Dependencies pass trust audit2/2earned
Has description1/1earned
Platform support declared (or universal)2/2earned
License declared1/1earned
Verified public repository2/2earned

Repository

https://github.com/mfbaig35r/swamp-databricks

06Platforms

linux · x86_64 linux · aarch64 macOS · x86_64 macOS · aarch64

07Labels

#databricks #data #pipelines #dlt #sql #unity-catalog #secrets #permissions #git-repos