Workspace Base Environment

View as Markdown

A WorkspaceBaseEnvironment defines a workspace-level environment configuration consisting of an environment version and a list of dependencies.

WorkspaceBaseEnvironment object

A WorkspaceBaseEnvironment defines a workspace-level environment configuration consisting of an environment version and a list of dependencies.

namestring: The resource name of the workspace base environment. Format: workspace-base-environments/{workspace-base-environment}

display_namestring: Human-readable display name for the workspace base environment.

filepathstring: The WSFS or UC Volumes path to the environment YAML file.

creator_user_idstring: User ID of the creator.

create_timestring: Timestamp when the environment was created.

last_updated_user_idstring: User ID of the last user who updated the environment.

update_timestring: Timestamp when the environment was last updated.

statusstring: The status of the materialized workspace base environment.
Values: STATUS_UNSPECIFIED, PENDING, CREATED, FAILED, EXPIRED, INVALID, REFRESHING

messagestring: Status message providing additional details about the environment status.

is_defaultboolean: Whether this is the default environment for the workspace.

base_environment_typestring: The type of base environment (CPU or GPU).
Values: BASE_ENVIRONMENT_TYPE_UNSPECIFIED, CPU, GPU

specobjectBeta

The environment specification containing version and dependencies.

Show child attributesHide child attributes

dependenciesarray of stringBeta: List of pip dependencies, as supported by the version of pip in this environment. Each dependency is a valid pip requirements file line per https://pip.pypa.io/en/stable/reference/requirements-file-format/. Allowed dependencies include a requirement specifier, an archive URL, a local project path (such as WSFS or UC Volumes in <Databricks>), or a VCS project URL.

environment_versionstringBeta: Environment version used by the environment. Each version comes with a specific Python version and a set of Python packages. The version is a string, consisting of an integer.
Example: 5

View as Markdown

The WorkspaceBaseEnvironment object

{
  "name": "string",
  "display_name": "string",
  "filepath": "string",
  "creator_user_id": "string",
  "create_time": "string",
  "last_updated_user_id": "string",
  "update_time": "string",
  "status": "string",
  "message": "string",
  "is_default": true,
  "base_environment_type": "string",
  "spec": {
    "dependencies": [
      "string"
    ],
    "environment_version": "5"
  }
}

Get GA

GET /api/environments/v1/{name=workspace-base-environments/*}

Retrieves a WorkspaceBaseEnvironment by its name.

API scopes: environments

Parameters

namestringpath: Required. The resource name of the workspace base environment to retrieve. Format: workspace-base-environments/{workspace_base_environment}

Response

Returns the WorkspaceBaseEnvironment object.

View as Markdown

Response

{
  "name": "string",
  "display_name": "string",
  "filepath": "string",
  "creator_user_id": "string",
  "create_time": "string",
  "last_updated_user_id": "string",
  "update_time": "string",
  "status": "string",
  "message": "string",
  "is_default": true,
  "base_environment_type": "string",
  "spec": {
    "dependencies": [
      "string"
    ],
    "environment_version": "5"
  }
}

List GA

GET /api/environments/v1/workspace-base-environments

Lists all WorkspaceBaseEnvironments in the workspace.

<Databricks> provides the following base environments:

workspace-base-environments/databricks_ai_...: includes popular AI and deep learning packages for serverless GPU compute.
workspace-base-environments/databricks_ml_...: includes popular ML packages for serverless compute.

Databricks-provided base environments are versioned. For example, workspace-base-environments/databricks_ml_v5 corresponds to the ML environment built on environment version 5.

API scopes: environments

AWS

Lists all WorkspaceBaseEnvironments in the workspace.

<Databricks> provides the following base environments:

workspace-base-environments/databricks_ai_...: includes popular AI and deep learning packages for serverless GPU compute. See https://docs.databricks.com/aws/en/release-notes/serverless/environment-version/five-gpu#ai-environment.
workspace-base-environments/databricks_ml_...: includes popular ML packages for serverless compute. See https://docs.databricks.com/aws/en/release-notes/serverless/environment-version/five#ml-environment.

Databricks-provided base environments are versioned. For example, workspace-base-environments/databricks_ml_v5 corresponds to the ML environment built on environment version 5.

Azure

Lists all WorkspaceBaseEnvironments in the workspace.

<Databricks> provides the following base environments:

workspace-base-environments/databricks_ai_...: includes popular AI and deep learning packages for serverless GPU compute.

See https://learn.microsoft.com/azure/databricks/release-notes/serverless/environment-version/five-gpu#ai-environment.

workspace-base-environments/databricks_ml_...: includes popular ML packages for serverless compute.

See https://learn.microsoft.com/azure/databricks/release-notes/serverless/environment-version/five#ml-environment.

Databricks-provided base environments are versioned. For example, workspace-base-environments/databricks_ml_v5 corresponds to the ML environment built on environment version 5.

GCP

Lists all WorkspaceBaseEnvironments in the workspace.

<Databricks> provides the following base environments:

workspace-base-environments/databricks_ai_...: includes popular AI and deep learning packages for serverless GPU compute.

See https://docs.databricks.com/gcp/en/release-notes/serverless/environment-version/five-gpu#ai-environment.

workspace-base-environments/databricks_ml_...: includes popular ML packages for serverless compute.

See https://docs.databricks.com/gcp/en/release-notes/serverless/environment-version/five#ml-environment.

Databricks-provided base environments are versioned. For example, workspace-base-environments/databricks_ml_v5 corresponds to the ML environment built on environment version 5.

Parameters

page_sizeint32query: The maximum number of environments to return per page. Default is 1000.
Default: 1000

page_tokenstringquery: Page token for pagination. Received from a previous ListWorkspaceBaseEnvironments call.

Response

Returns a list of WorkspaceBaseEnvironment objects.

View as Markdown

Response

{
  "workspace_base_environments": [
    {
      "name": "string",
      "display_name": "string",
      "filepath": "string",
      "creator_user_id": "string",
      "create_time": "string",
      "last_updated_user_id": "string",
      "update_time": "string",
      "status": "string",
      "message": "string",
      "is_default": true,
      "base_environment_type": "string",
      "spec": {}
    }
  ],
  "next_page_token": "string"
}

Create GA

POST /api/environments/v1/workspace-base-environments

Creates a new WorkspaceBaseEnvironment. This is a long-running operation. The operation will asynchronously generate a materialized environment to optimize dependency resolution and is only marked as done when the materialized environment has been successfully generated or has failed.

API scopes: environments

Parameters

workspace_base_environment_idstringquery: 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]-/.
Constraints: [ 4 .. 63 ] characters

request_idstringquery: A unique identifier for this request. A random UUID is recommended. This request is only idempotent if a request_id is provided.
Constraints: = 36 characters

Request body

workspace_base_environmentobject

Required. The workspace base environment to create.

Show child attributesHide child attributes

namestring: The resource name of the workspace base environment. Format: workspace-base-environments/{workspace-base-environment}

display_namestring: Human-readable display name for the workspace base environment.

filepathstring: The WSFS or UC Volumes path to the environment YAML file.

creator_user_idstring: User ID of the creator.

create_timestring: Timestamp when the environment was created.

last_updated_user_idstring: User ID of the last user who updated the environment.

update_timestring: Timestamp when the environment was last updated.

statusstring: The status of the materialized workspace base environment.
Values: STATUS_UNSPECIFIED, PENDING, CREATED, FAILED, EXPIRED, INVALID, REFRESHING

messagestring: Status message providing additional details about the environment status.

is_defaultboolean: Whether this is the default environment for the workspace.

base_environment_typestring: The type of base environment (CPU or GPU).
Values: BASE_ENVIRONMENT_TYPE_UNSPECIFIED, CPU, GPU

specobjectBeta

The environment specification containing version and dependencies.

Show child attributesHide child attributes

dependenciesarray of stringBeta: List of pip dependencies, as supported by the version of pip in this environment. Each dependency is a valid pip requirements file line per https://pip.pypa.io/en/stable/reference/requirements-file-format/. Allowed dependencies include a requirement specifier, an archive URL, a local project path (such as WSFS or UC Volumes in <Databricks>), or a VCS project URL.

environment_versionstringBeta: Environment version used by the environment. Each version comes with a specific Python version and a set of Python packages. The version is a string, consisting of an integer.
Example: 5

Response

namestring: The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the name should be a resource name ending with operations/{unique_id}.

metadataobject: Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata.

doneboolean: If the value is false, it means the operation is still in progress. If true, the operation is completed, and either error or response is available.

errorobjectRequired

The error result of the operation in case of failure or cancellation.

Show child attributesHide child attributes

error_codestring: Values: UNKNOWN, INTERNAL_ERROR, TEMPORARILY_UNAVAILABLE, IO_ERROR, BAD_REQUEST, SERVICE_UNDER_MAINTENANCE, WORKSPACE_TEMPORARILY_UNAVAILABLE, DEADLINE_EXCEEDED, CANCELLED, RESOURCE_EXHAUSTED, ABORTED, NOT_FOUND, ALREADY_EXISTS, UNAUTHENTICATED, UNAVAILABLE, INVALID_PARAMETER_VALUE, ENDPOINT_NOT_FOUND, MALFORMED_REQUEST, INVALID_STATE, PERMISSION_DENIED, FEATURE_DISABLED, CUSTOMER_UNAUTHORIZED, REQUEST_LIMIT_EXCEEDED, RESOURCE_CONFLICT, UNPARSEABLE_HTTP_ERROR, NOT_IMPLEMENTED, DATA_LOSS, INVALID_STATE_TRANSITION, COULD_NOT_ACQUIRE_LOCK, RESOURCE_ALREADY_EXISTS, RESOURCE_DOES_NOT_EXIST, QUOTA_EXCEEDED, MAX_BLOCK_SIZE_EXCEEDED, MAX_READ_SIZE_EXCEEDED, PARTIAL_DELETE, MAX_LIST_SIZE_EXCEEDED, DRY_RUN_FAILED, RESOURCE_LIMIT_EXCEEDED, DIRECTORY_NOT_EMPTY, DIRECTORY_PROTECTED, MAX_NOTEBOOK_SIZE_EXCEEDED, MAX_CHILD_NODE_SIZE_EXCEEDED, SEARCH_QUERY_TOO_LONG, SEARCH_QUERY_TOO_SHORT, MANAGED_RESOURCE_GROUP_DOES_NOT_EXIST, PERMISSION_NOT_PROPAGATED, DEPLOYMENT_TIMEOUT, GIT_CONFLICT, GIT_UNKNOWN_REF, GIT_SENSITIVE_TOKEN_DETECTED, GIT_URL_NOT_ON_ALLOW_LIST, GIT_REMOTE_ERROR, PROJECTS_OPERATION_TIMEOUT, IPYNB_FILE_IN_REPO, INSECURE_PARTNER_RESPONSE, MALFORMED_PARTNER_RESPONSE, METASTORE_DOES_NOT_EXIST, DAC_DOES_NOT_EXIST, CATALOG_DOES_NOT_EXIST, SCHEMA_DOES_NOT_EXIST, TABLE_DOES_NOT_EXIST, SHARE_DOES_NOT_EXIST, RECIPIENT_DOES_NOT_EXIST, STORAGE_CREDENTIAL_DOES_NOT_EXIST, EXTERNAL_LOCATION_DOES_NOT_EXIST, PRINCIPAL_DOES_NOT_EXIST, PROVIDER_DOES_NOT_EXIST, METASTORE_ALREADY_EXISTS, DAC_ALREADY_EXISTS, CATALOG_ALREADY_EXISTS, SCHEMA_ALREADY_EXISTS, TABLE_ALREADY_EXISTS, SHARE_ALREADY_EXISTS, RECIPIENT_ALREADY_EXISTS, STORAGE_CREDENTIAL_ALREADY_EXISTS, EXTERNAL_LOCATION_ALREADY_EXISTS, PROVIDER_ALREADY_EXISTS, CATALOG_NOT_EMPTY, SCHEMA_NOT_EMPTY, METASTORE_NOT_EMPTY, PROVIDER_SHARE_NOT_ACCESSIBLE

messagestring

stack_tracestring

detailsarray of object

responseobjectRequired: The normal, successful response of the operation.

View as Markdown

Request

{
  "workspace_base_environment": {
    "name": "string",
    "display_name": "string",
    "filepath": "string",
    "creator_user_id": "string",
    "create_time": "string",
    "last_updated_user_id": "string",
    "update_time": "string",
    "status": "string",
    "message": "string",
    "is_default": true,
    "base_environment_type": "string",
    "spec": {}
  }
}

Response

{
  "name": "string",
  "metadata": {},
  "done": true,
  "error": {
    "error_code": "string",
    "message": "string",
    "stack_trace": "string",
    "details": [
      {}
    ]
  },
  "response": {}
}

Update GA

PATCH /api/environments/v1/{name=workspace-base-environments/*}

Updates an existing WorkspaceBaseEnvironment. This is a long-running operation. The operation will asynchronously regenerate the materialized environment and is only marked as done when the materialized environment has been successfully generated or has failed. The existing materialized environment remains available until it expires.

API scopes: environments

Parameters

namestringpath

Request body

workspace_base_environmentobject

Required. The workspace base environment with updated fields. The name field is used to identify the environment to update.

Show child attributesHide child attributes

namestring: The resource name of the workspace base environment. Format: workspace-base-environments/{workspace-base-environment}

display_namestring: Human-readable display name for the workspace base environment.

filepathstring: The WSFS or UC Volumes path to the environment YAML file.

creator_user_idstring: User ID of the creator.

create_timestring: Timestamp when the environment was created.

last_updated_user_idstring: User ID of the last user who updated the environment.

update_timestring: Timestamp when the environment was last updated.

statusstring: The status of the materialized workspace base environment.
Values: STATUS_UNSPECIFIED, PENDING, CREATED, FAILED, EXPIRED, INVALID, REFRESHING

messagestring: Status message providing additional details about the environment status.

is_defaultboolean: Whether this is the default environment for the workspace.

base_environment_typestring: The type of base environment (CPU or GPU).
Values: BASE_ENVIRONMENT_TYPE_UNSPECIFIED, CPU, GPU

specobjectBeta

The environment specification containing version and dependencies.

Show child attributesHide child attributes

dependenciesarray of stringBeta: List of pip dependencies, as supported by the version of pip in this environment. Each dependency is a valid pip requirements file line per https://pip.pypa.io/en/stable/reference/requirements-file-format/. Allowed dependencies include a requirement specifier, an archive URL, a local project path (such as WSFS or UC Volumes in <Databricks>), or a VCS project URL.

environment_versionstringBeta: Environment version used by the environment. Each version comes with a specific Python version and a set of Python packages. The version is a string, consisting of an integer.
Example: 5

Response

namestring: The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the name should be a resource name ending with operations/{unique_id}.

metadataobject: Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata.

doneboolean: If the value is false, it means the operation is still in progress. If true, the operation is completed, and either error or response is available.

errorobjectRequired

The error result of the operation in case of failure or cancellation.

Show child attributesHide child attributes

error_codestring: Values: UNKNOWN, INTERNAL_ERROR, TEMPORARILY_UNAVAILABLE, IO_ERROR, BAD_REQUEST, SERVICE_UNDER_MAINTENANCE, WORKSPACE_TEMPORARILY_UNAVAILABLE, DEADLINE_EXCEEDED, CANCELLED, RESOURCE_EXHAUSTED, ABORTED, NOT_FOUND, ALREADY_EXISTS, UNAUTHENTICATED, UNAVAILABLE, INVALID_PARAMETER_VALUE, ENDPOINT_NOT_FOUND, MALFORMED_REQUEST, INVALID_STATE, PERMISSION_DENIED, FEATURE_DISABLED, CUSTOMER_UNAUTHORIZED, REQUEST_LIMIT_EXCEEDED, RESOURCE_CONFLICT, UNPARSEABLE_HTTP_ERROR, NOT_IMPLEMENTED, DATA_LOSS, INVALID_STATE_TRANSITION, COULD_NOT_ACQUIRE_LOCK, RESOURCE_ALREADY_EXISTS, RESOURCE_DOES_NOT_EXIST, QUOTA_EXCEEDED, MAX_BLOCK_SIZE_EXCEEDED, MAX_READ_SIZE_EXCEEDED, PARTIAL_DELETE, MAX_LIST_SIZE_EXCEEDED, DRY_RUN_FAILED, RESOURCE_LIMIT_EXCEEDED, DIRECTORY_NOT_EMPTY, DIRECTORY_PROTECTED, MAX_NOTEBOOK_SIZE_EXCEEDED, MAX_CHILD_NODE_SIZE_EXCEEDED, SEARCH_QUERY_TOO_LONG, SEARCH_QUERY_TOO_SHORT, MANAGED_RESOURCE_GROUP_DOES_NOT_EXIST, PERMISSION_NOT_PROPAGATED, DEPLOYMENT_TIMEOUT, GIT_CONFLICT, GIT_UNKNOWN_REF, GIT_SENSITIVE_TOKEN_DETECTED, GIT_URL_NOT_ON_ALLOW_LIST, GIT_REMOTE_ERROR, PROJECTS_OPERATION_TIMEOUT, IPYNB_FILE_IN_REPO, INSECURE_PARTNER_RESPONSE, MALFORMED_PARTNER_RESPONSE, METASTORE_DOES_NOT_EXIST, DAC_DOES_NOT_EXIST, CATALOG_DOES_NOT_EXIST, SCHEMA_DOES_NOT_EXIST, TABLE_DOES_NOT_EXIST, SHARE_DOES_NOT_EXIST, RECIPIENT_DOES_NOT_EXIST, STORAGE_CREDENTIAL_DOES_NOT_EXIST, EXTERNAL_LOCATION_DOES_NOT_EXIST, PRINCIPAL_DOES_NOT_EXIST, PROVIDER_DOES_NOT_EXIST, METASTORE_ALREADY_EXISTS, DAC_ALREADY_EXISTS, CATALOG_ALREADY_EXISTS, SCHEMA_ALREADY_EXISTS, TABLE_ALREADY_EXISTS, SHARE_ALREADY_EXISTS, RECIPIENT_ALREADY_EXISTS, STORAGE_CREDENTIAL_ALREADY_EXISTS, EXTERNAL_LOCATION_ALREADY_EXISTS, PROVIDER_ALREADY_EXISTS, CATALOG_NOT_EMPTY, SCHEMA_NOT_EMPTY, METASTORE_NOT_EMPTY, PROVIDER_SHARE_NOT_ACCESSIBLE

messagestring

stack_tracestring

detailsarray of object

responseobjectRequired: The normal, successful response of the operation.

View as Markdown

Request

{
  "workspace_base_environment": {
    "name": "string",
    "display_name": "string",
    "filepath": "string",
    "creator_user_id": "string",
    "create_time": "string",
    "last_updated_user_id": "string",
    "update_time": "string",
    "status": "string",
    "message": "string",
    "is_default": true,
    "base_environment_type": "string",
    "spec": {}
  }
}

Response

{
  "name": "string",
  "metadata": {},
  "done": true,
  "error": {
    "error_code": "string",
    "message": "string",
    "stack_trace": "string",
    "details": [
      {}
    ]
  },
  "response": {}
}

Delete GA

DELETE /api/environments/v1/{name=workspace-base-environments/*}

Deletes a WorkspaceBaseEnvironment. Deleting a base environment may impact linked notebooks and jobs. This operation is irreversible and should be performed only when you are certain the environment is no longer needed.

API scopes: environments

Parameters

namestringpath: Required. The resource name of the workspace base environment to delete. Format: workspace-base-environments/{workspace_base_environment}

WorkspaceBaseEnvironment object​

Get GA​

Parameters​

Response​

List GA​

Parameters​

Response​

Create GA​

Parameters​

Request body​

Response​

Update GA​

Parameters​

Request body​

Response​

Delete GA​

Parameters​

WorkspaceBaseEnvironment object

Get GA

Parameters

Response

List GA

Parameters

Response

Create GA

Parameters

Request body

Response

Update GA

Parameters

Request body

Response

Delete GA

Parameters