sandboxes

Creates, updates, deletes, gets or lists a sandboxes resource.

Overview

Name	sandboxes
Type	Resource
Id	databricks_workspace.sandbox.sandboxes

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
name	string	The sandbox resource name, in the form ``sandboxes/{sandbox_id}``. Derived from ``sandbox_id``; any value supplied in a create or update request body is ignored.
display_name	string	Human-readable display label for the sandbox. At most 256 characters.
create_time	string (date-time)	Output only. The creation time of the sandbox.
▶metadata	object	Metadata associated with the sandbox.
▶spec	object	The desired configuration of the sandbox, supplied by the caller at creation time.
▶status	object	The observed runtime state of the sandbox, populated by the server.
update_time	string (date-time)	Output only. The last update time of the sandbox metadata and spec.

list

Name	Datatype	Description
name	string	The sandbox resource name, in the form ``sandboxes/{sandbox_id}``. Derived from ``sandbox_id``; any value supplied in a create or update request body is ignored.
display_name	string	Human-readable display label for the sandbox. At most 256 characters.
create_time	string (date-time)	Output only. The creation time of the sandbox.
▶metadata	object	Metadata associated with the sandbox.
▶spec	object	The desired configuration of the sandbox, supplied by the caller at creation time.
▶status	object	The observed runtime state of the sandbox, populated by the server.
update_time	string (date-time)	Output only. The last update time of the sandbox metadata and spec.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	sandbox_id, deployment_name, workspace_domain		Retrieves a Sandbox by name.
list	select	deployment_name, workspace_domain	page_size, page_token	Lists all Sandboxes.
create	insert	sandbox_id, deployment_name, workspace_domain		Creates a new Sandbox.
update	update	sandbox_id, update_mask, deployment_name, workspace_domain		Updates mutable fields on an existing Sandbox. Allowlisted update_mask paths today: display_name,
delete	delete	sandbox_id, deployment_name, workspace_domain		Deletes a Sandbox.
start	exec	sandbox_id, deployment_name, workspace_domain		Starts a previously stopped Sandbox under the same sandbox name. Returns NOT_FOUND if there is no
stop	exec	sandbox_id, deployment_name, workspace_domain		Stops a running Sandbox, preserving it so it can later be restarted with a Start request.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
deployment_name	string	The Databricks workspace deployment name: the host prefix of the workspace URL (dbc-abcd0123-a1bc on AWS, adb-1234567890123456.7 on Azure, 1234567890123456.7 on GCP). Set DATABRICKS_DEPLOYMENT_NAME to default it for the session. (default: dbc-abcd0123-a1bc, x-stackQL-envVar: DATABRICKS_DEPLOYMENT_NAME)
sandbox_id	string	The sandbox_id segment of the name resource name (sandboxes/{sandbox_id}). Resource name of the sandbox to stop, in the form sandboxes/{sandbox_id}.
update_mask	object	Field paths to update. Must be a non-empty subset of: - display_name - spec.compute.inactivity_timeout Any other path returns INVALID_PARAMETER_VALUE.
workspace_domain	string	The Databricks workspace domain suffix for the cloud. Selected by DATABRICKS_CLOUD (aws, azure or gcp; default aws). (default: cloud.databricks.com, x-stackQL-envVarSelector: {"envVar":"DATABRICKS_CLOUD","default":"aws","values":{"aws":"cloud.databricks.com","azure":"azuredatabricks.net","gcp":"gcp.databricks.com"}})
page_size	integer
page_token	string

SELECT examples

get

Retrieves a Sandbox by name.

SELECT
name,
display_name,
create_time,
metadata,
spec,
status,
update_time
FROM databricks_workspace.sandbox.sandboxes
WHERE sandbox_id = '{{ sandbox_id }}' -- required
AND deployment_name = '{{ deployment_name }}' -- required
AND workspace_domain = '{{ workspace_domain }}' -- required
;

list

Lists all Sandboxes.

SELECT
name,
display_name,
create_time,
metadata,
spec,
status,
update_time
FROM databricks_workspace.sandbox.sandboxes
WHERE deployment_name = '{{ deployment_name }}' -- required
AND workspace_domain = '{{ workspace_domain }}' -- required
AND page_size = '{{ page_size }}'
AND page_token = '{{ page_token }}'
;

INSERT examples

create

Creates a new Sandbox.

INSERT INTO databricks_workspace.sandbox.sandboxes (
create_time,
display_name,
metadata,
name,
spec,
status,
update_time,
sandbox_id,
deployment_name,
workspace_domain
)
SELECT 
'{{ create_time }}',
'{{ display_name }}',
'{{ metadata }}',
'{{ name }}',
'{{ spec }}',
'{{ status }}',
'{{ update_time }}',
'{{ sandbox_id }}',
'{{ deployment_name }}',
'{{ workspace_domain }}'
RETURNING
name,
display_name,
create_time,
metadata,
spec,
status,
update_time
;

Manifest

# Description fields are for documentation purposes
- name: sandboxes
props:
  - name: sandbox_id
    value: "{{ sandbox_id }}"
    description: Required parameter for the sandboxes resource.
  - name: deployment_name
    value: "{{ deployment_name }}"
    description: Required parameter for the sandboxes resource.
  - name: workspace_domain
    value: "{{ workspace_domain }}"
    description: Required parameter for the sandboxes resource.
  - name: create_time
    value: "{{ create_time }}"
    description: |
      Output only. The creation time of the sandbox.
  - name: display_name
    value: "{{ display_name }}"
    description: |
      Human-readable display label for the sandbox. At most 256 characters.
  - name: metadata
    description: |
      Metadata associated with the sandbox.
    value:
      custom_tags: "{{ custom_tags }}"
  - name: name
    value: "{{ name }}"
    description: |
      The sandbox resource name, in the form ``sandboxes/{sandbox_id}``. Derived from ``sandbox_id``; any value supplied in a create or update request body is ignored.
  - name: spec
    description: |
      The desired configuration of the sandbox, supplied by the caller at creation time.
    value:
      compute:
        inactivity_timeout: "{{ inactivity_timeout }}"
      environment:
        image_uri: "{{ image_uri }}"
  - name: status
    description: |
      The observed runtime state of the sandbox, populated by the server.
    value:
      state: "{{ state }}"
  - name: update_time
    value: "{{ update_time }}"
    description: |
      Output only. The last update time of the sandbox metadata and spec.

UPDATE examples

update

Updates mutable fields on an existing Sandbox. Allowlisted update_mask paths today: display_name,

UPDATE databricks_workspace.sandbox.sandboxes
SET 
create_time = '{{ create_time }}',
display_name = '{{ display_name }}',
metadata = '{{ metadata }}',
name = '{{ name }}',
spec = '{{ spec }}',
status = '{{ status }}',
update_time = '{{ update_time }}'
WHERE 
sandbox_id = '{{ sandbox_id }}' --required
AND update_mask = '{{ update_mask }}' --required
AND deployment_name = '{{ deployment_name }}' --required
AND workspace_domain = '{{ workspace_domain }}' --required
RETURNING
name,
display_name,
create_time,
metadata,
spec,
status,
update_time;

DELETE examples

delete

Deletes a Sandbox.

DELETE FROM databricks_workspace.sandbox.sandboxes
WHERE sandbox_id = '{{ sandbox_id }}' --required
AND deployment_name = '{{ deployment_name }}' --required
AND workspace_domain = '{{ workspace_domain }}' --required
;

Lifecycle Methods

start

Starts a previously stopped Sandbox under the same sandbox name. Returns NOT_FOUND if there is no

EXEC databricks_workspace.sandbox.sandboxes.start 
@sandbox_id='{{ sandbox_id }}' --required, 
@deployment_name='{{ deployment_name }}' --required, 
@workspace_domain='{{ workspace_domain }}' --required
;

stop

Stops a running Sandbox, preserving it so it can later be restarted with a Start request.

EXEC databricks_workspace.sandbox.sandboxes.stop 
@sandbox_id='{{ sandbox_id }}' --required, 
@deployment_name='{{ deployment_name }}' --required, 
@workspace_domain='{{ workspace_domain }}' --required
;