experiments

Creates, updates, deletes, gets or lists an experiments resource.

Overview

Name	experiments
Type	Resource
Id	databricks_workspace.ml.experiments

Fields

The following fields are returned by SELECT queries:

get_by_name

Name	Datatype	Description
▶experiment	object	An experiment and its metadata.

get

Name	Datatype	Description
▶experiment	object	An experiment and its metadata.

list

Name	Datatype	Description
name	string	Human readable name that identifies the experiment.
experiment_id	string	Unique identifier for the experiment.
artifact_location	string	Location where artifacts for the experiment are stored.
creation_time	integer	Creation time
last_update_time	integer	Last update time
lifecycle_stage	string	Current life cycle stage of the experiment: "active" or "deleted". Deleted experiments are not returned by APIs.
▶tags	array	Tags: Additional metadata key-value pairs.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_by_name	select	experiment_name, deployment_name		Gets metadata for an experiment.
get	select	experiment_id, deployment_name		Gets metadata for an experiment. This method works on deleted experiments.
list	select	deployment_name	max_results, page_token, view_type	Gets a list of all experiments.
create	insert	deployment_name, name		Creates an experiment with a name. Returns the ID of the newly created experiment. Validates that
delete	exec	deployment_name, experiment_id		Marks an experiment and associated metadata, runs, metrics, params, and tags for deletion. If the
restore	exec	deployment_name, experiment_id		Restore an experiment marked for deletion. This also restores associated metadata, runs, metrics,
search	exec	deployment_name		Searches for experiments that satisfy specified search criteria.
set_tag	exec	deployment_name, experiment_id, key, value		Sets a tag on an experiment. Experiment tags are metadata that can be updated.
update	exec	deployment_name, experiment_id		Updates experiment metadata.

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 (default: dbc-abcd0123-a1bc)
experiment_id	string	ID of the associated experiment.
experiment_name	string	Name of the associated experiment.
max_results	integer	Maximum number of experiments desired. If max_results is unspecified, return all experiments. If max_results is too large, it'll be automatically capped at 1000. Callers of this endpoint are encouraged to pass max_results explicitly and leverage page_token to iterate through experiments.
page_token	string	Token indicating the page of experiments to fetch
view_type	string	Qualifier for type of experiments to be returned. If unspecified, return only active experiments.

SELECT examples

get_by_name

Gets metadata for an experiment.

SELECT
experiment
FROM databricks_workspace.ml.experiments
WHERE experiment_name = '{{ experiment_name }}' -- required
AND deployment_name = '{{ deployment_name }}' -- required
;

get

Gets metadata for an experiment. This method works on deleted experiments.

SELECT
experiment
FROM databricks_workspace.ml.experiments
WHERE experiment_id = '{{ experiment_id }}' -- required
AND deployment_name = '{{ deployment_name }}' -- required
;

list

Gets a list of all experiments.

SELECT
name,
experiment_id,
artifact_location,
creation_time,
last_update_time,
lifecycle_stage,
tags
FROM databricks_workspace.ml.experiments
WHERE deployment_name = '{{ deployment_name }}' -- required
AND max_results = '{{ max_results }}'
AND page_token = '{{ page_token }}'
AND view_type = '{{ view_type }}'
;

INSERT examples

create

Creates an experiment with a name. Returns the ID of the newly created experiment. Validates that

INSERT INTO databricks_workspace.ml.experiments (
name,
artifact_location,
tags,
deployment_name
)
SELECT 
'{{ name }}' /* required */,
'{{ artifact_location }}',
'{{ tags }}',
'{{ deployment_name }}'
RETURNING
experiment_id
;

Manifest

# Description fields are for documentation purposes
- name: experiments
props:
  - name: deployment_name
    value: "{{ deployment_name }}"
    description: Required parameter for the experiments resource.
  - name: name
    value: "{{ name }}"
    description: |
      Experiment name.
  - name: artifact_location
    value: "{{ artifact_location }}"
    description: |
      Location where all artifacts for the experiment are stored. If not provided, the remote server will select an appropriate default.
  - name: tags
    description: |
      A collection of tags to set on the experiment. Maximum tag size and number of tags per request depends on the storage backend. All storage backends are guaranteed to support tag keys up to 250 bytes in size and tag values up to 5000 bytes in size. All storage backends are also guaranteed to support up to 20 tags per request.
    value:
      - key: "{{ key }}"
        value: "{{ value }}"

Lifecycle Methods

delete

Marks an experiment and associated metadata, runs, metrics, params, and tags for deletion. If the

EXEC databricks_workspace.ml.experiments.delete 
@deployment_name='{{ deployment_name }}' --required 
@@json=
'{
"experiment_id": "{{ experiment_id }}"
}'
;

restore

Restore an experiment marked for deletion. This also restores associated metadata, runs, metrics,

EXEC databricks_workspace.ml.experiments.restore 
@deployment_name='{{ deployment_name }}' --required 
@@json=
'{
"experiment_id": "{{ experiment_id }}"
}'
;

search

Searches for experiments that satisfy specified search criteria.

EXEC databricks_workspace.ml.experiments.search 
@deployment_name='{{ deployment_name }}' --required 
@@json=
'{
"filter": "{{ filter }}", 
"max_results": {{ max_results }}, 
"order_by": "{{ order_by }}", 
"page_token": "{{ page_token }}", 
"view_type": "{{ view_type }}"
}'
;

set_tag

Sets a tag on an experiment. Experiment tags are metadata that can be updated.

EXEC databricks_workspace.ml.experiments.set_tag 
@deployment_name='{{ deployment_name }}' --required 
@@json=
'{
"experiment_id": "{{ experiment_id }}", 
"key": "{{ key }}", 
"value": "{{ value }}"
}'
;

update

Updates experiment metadata.

EXEC databricks_workspace.ml.experiments.update 
@deployment_name='{{ deployment_name }}' --required 
@@json=
'{
"experiment_id": "{{ experiment_id }}", 
"new_name": "{{ new_name }}"
}'
;