workspace_base_environments

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

Overview

Name	workspace_base_environments
Type	Resource
Id	databricks_workspace.environments.workspace_base_environments

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
name	string	The resource name of the workspace base environment. Format: workspace-base-environments/{workspace-base-environment}
creator_user_id	string	User ID of the creator.
last_updated_user_id	string	User ID of the last user who updated the environment.
display_name	string	Human-readable display name for the workspace base environment.
base_environment_type	string	The type of base environment (CPU or GPU). (CPU, GPU)
create_time	string (date-time)	Timestamp when the environment was created.
filepath	string	The WSFS or UC Volumes path to the environment YAML file.
is_default	boolean	Whether this is the default environment for the workspace.
message	string	Status message providing additional details about the environment status.
▶spec	object	The environment specification containing version and dependencies.
status	string	The status of the materialized workspace base environment. (CREATED, EXPIRED, FAILED, INVALID, PENDING, REFRESHING)
update_time	string (date-time)	Timestamp when the environment was last updated.

list

Name	Datatype	Description
name	string	The resource name of the workspace base environment. Format: workspace-base-environments/{workspace-base-environment}
creator_user_id	string	User ID of the creator.
last_updated_user_id	string	User ID of the last user who updated the environment.
display_name	string	Human-readable display name for the workspace base environment.
base_environment_type	string	The type of base environment (CPU or GPU). (CPU, GPU)
create_time	string (date-time)	Timestamp when the environment was created.
filepath	string	The WSFS or UC Volumes path to the environment YAML file.
is_default	boolean	Whether this is the default environment for the workspace.
message	string	Status message providing additional details about the environment status.
▶spec	object	The environment specification containing version and dependencies.
status	string	The status of the materialized workspace base environment. (CREATED, EXPIRED, FAILED, INVALID, PENDING, REFRESHING)
update_time	string (date-time)	Timestamp when the environment was last updated.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	workspace_base_environment, deployment_name, workspace_domain		Retrieves a WorkspaceBaseEnvironment by its name.
list	select	deployment_name, workspace_domain	page_size, page_token	Lists all WorkspaceBaseEnvironments in the workspace.
create	insert	deployment_name, workspace_domain, display_name	request_id, workspace_base_environment_id	Creates a new WorkspaceBaseEnvironment. This is a long-running operation. The operation will
update	update	workspace_base_environment, deployment_name, workspace_domain		Updates an existing WorkspaceBaseEnvironment. This is a long-running operation. The operation will
delete	delete	workspace_base_environment, deployment_name, workspace_domain		Deletes a WorkspaceBaseEnvironment. Deleting a base environment may impact linked notebooks and jobs.
refresh	exec	workspace_base_environment, deployment_name, workspace_domain		Refreshes the materialized environment for a WorkspaceBaseEnvironment. This is a long-running

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)
workspace_base_environment	string	The workspace_base_environment segment of the name resource name (workspace-base-environments/{workspace_base_environment}). Required. The resource name of the workspace base environment to delete. Format: workspace-base-environments/{workspace_base_environment}
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	The maximum number of environments to return per page. Default is 1000.
page_token	string	Page token for pagination. Received from a previous ListWorkspaceBaseEnvironments call.
request_id	string	A unique identifier for this request. A random UUID is recommended. This request is only idempotent if a request_id is provided.
workspace_base_environment_id	string	The ID to use for the workspace base environment, which will become the final component of the resource name. This value should be 4-63 characters, and valid characters are /[a-z][0-9]-/.

SELECT examples

get

Retrieves a WorkspaceBaseEnvironment by its name.

SELECT
name,
creator_user_id,
last_updated_user_id,
display_name,
base_environment_type,
create_time,
filepath,
is_default,
message,
spec,
status,
update_time
FROM databricks_workspace.environments.workspace_base_environments
WHERE workspace_base_environment = '{{ workspace_base_environment }}' -- required
AND deployment_name = '{{ deployment_name }}' -- required
AND workspace_domain = '{{ workspace_domain }}' -- required
;

list

Lists all WorkspaceBaseEnvironments in the workspace.

SELECT
name,
creator_user_id,
last_updated_user_id,
display_name,
base_environment_type,
create_time,
filepath,
is_default,
message,
spec,
status,
update_time
FROM databricks_workspace.environments.workspace_base_environments
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 WorkspaceBaseEnvironment. This is a long-running operation. The operation will

INSERT INTO databricks_workspace.environments.workspace_base_environments (
display_name,
base_environment_type,
create_time,
creator_user_id,
filepath,
is_default,
last_updated_user_id,
message,
name,
spec,
status,
update_time,
deployment_name,
workspace_domain,
request_id,
workspace_base_environment_id
)
SELECT 
'{{ display_name }}' /* required */,
'{{ base_environment_type }}',
'{{ create_time }}',
'{{ creator_user_id }}',
'{{ filepath }}',
{{ is_default }},
'{{ last_updated_user_id }}',
'{{ message }}',
'{{ name }}',
'{{ spec }}',
'{{ status }}',
'{{ update_time }}',
'{{ deployment_name }}',
'{{ workspace_domain }}',
'{{ request_id }}',
'{{ workspace_base_environment_id }}'
;

Manifest

# Description fields are for documentation purposes
- name: workspace_base_environments
props:
  - name: deployment_name
    value: "{{ deployment_name }}"
    description: Required parameter for the workspace_base_environments resource.
  - name: workspace_domain
    value: "{{ workspace_domain }}"
    description: Required parameter for the workspace_base_environments resource.
  - name: display_name
    value: "{{ display_name }}"
    description: |
      Human-readable display name for the workspace base environment.
  - name: base_environment_type
    value: "{{ base_environment_type }}"
    description: |
      The type of base environment (CPU or GPU).
  - name: create_time
    value: "{{ create_time }}"
    description: |
      Timestamp when the environment was created.
  - name: creator_user_id
    value: "{{ creator_user_id }}"
    description: |
      User ID of the creator.
  - name: filepath
    value: "{{ filepath }}"
    description: |
      The WSFS or UC Volumes path to the environment YAML file.
  - name: is_default
    value: {{ is_default }}
    description: |
      Whether this is the default environment for the workspace.
  - name: last_updated_user_id
    value: "{{ last_updated_user_id }}"
    description: |
      User ID of the last user who updated the environment.
  - name: message
    value: "{{ message }}"
    description: |
      Status message providing additional details about the environment status.
  - name: name
    value: "{{ name }}"
    description: |
      The resource name of the workspace base environment. Format: workspace-base-environments/{workspace-base-environment}
  - name: spec
    description: |
      The environment specification containing version and dependencies.
    value:
      dependencies:
        - "{{ dependencies }}"
      environment_version: "{{ environment_version }}"
  - name: status
    value: "{{ status }}"
    description: |
      The status of the materialized workspace base environment.
  - name: update_time
    value: "{{ update_time }}"
    description: |
      Timestamp when the environment was last updated.
  - name: request_id
    value: "{{ request_id }}"
    description: A unique identifier for this request. A random UUID is recommended. This request is only idempotent if a request_id is provided.
    description: A unique identifier for this request. A random UUID is recommended. This request is only idempotent if a request_id is provided.
  - name: workspace_base_environment_id
    value: "{{ workspace_base_environment_id }}"
    description: The ID to use for the workspace base environment, which will become the final component of the resource name. This value should be 4-63 characters, and valid characters are /[a-z][0-9]-/.
    description: The ID to use for the workspace base environment, which will become the final component of the resource name. This value should be 4-63 characters, and valid characters are /[a-z][0-9]-/.

UPDATE examples

update

Updates an existing WorkspaceBaseEnvironment. This is a long-running operation. The operation will

UPDATE databricks_workspace.environments.workspace_base_environments
SET 
-- No updatable properties
WHERE 
workspace_base_environment = '{{ workspace_base_environment }}' --required
AND deployment_name = '{{ deployment_name }}' --required
AND workspace_domain = '{{ workspace_domain }}' --required;

DELETE examples

delete

Deletes a WorkspaceBaseEnvironment. Deleting a base environment may impact linked notebooks and jobs.

DELETE FROM databricks_workspace.environments.workspace_base_environments
WHERE workspace_base_environment = '{{ workspace_base_environment }}' --required
AND deployment_name = '{{ deployment_name }}' --required
AND workspace_domain = '{{ workspace_domain }}' --required
;

Lifecycle Methods

refresh

Refreshes the materialized environment for a WorkspaceBaseEnvironment. This is a long-running

EXEC databricks_workspace.environments.workspace_base_environments.refresh 
@workspace_base_environment='{{ workspace_base_environment }}' --required, 
@deployment_name='{{ deployment_name }}' --required, 
@workspace_domain='{{ workspace_domain }}' --required
;