experiment_runs

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

Overview

Name	experiment_runs
Type	Resource
Id	databricks_workspace.ml.experiment_runs

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
▶run	object	A single run.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	run_id, deployment_name	run_uuid	Gets the metadata, metrics, params, and tags for a run. In the case where multiple metrics with the
create	insert	deployment_name		Creates a new run within an experiment. A run is usually a single execution of a machine learning or
delete	exec	deployment_name, run_id		Marks a run for deletion.
delete_bulk	exec	deployment_name, experiment_id, max_timestamp_millis		Bulk delete runs in an experiment that were created prior to or at the specified timestamp. Deletes at
delete_tag	exec	deployment_name, run_id, key		Deletes a tag on a run. Tags are run metadata that can be updated during a run and after a run
log_batch	exec	deployment_name		Logs a batch of metrics, params, and tags for a run. If any data failed to be persisted, the server
log_inputs	exec	deployment_name, run_id		Logs inputs, such as datasets and models, to an MLflow Run.
log_metric	exec	deployment_name, key, value, timestamp		Log a metric for a run. A metric is a key-value pair (string key, float value) with an associated
log_model	exec	deployment_name		Note: the Create a logged model API replaces this
log_outputs	exec	deployment_name, run_id		Logs outputs, such as models, from an MLflow Run.
log_param	exec	deployment_name, key, value		Logs a param used for a run. A param is a key-value pair (string key, string value). Examples include
restore	exec	deployment_name, run_id		Restores a deleted run. This also restores associated metadata, runs, metrics, params, and tags.
restore_bulk	exec	deployment_name, experiment_id, min_timestamp_millis		Bulk restore runs in an experiment that were deleted no earlier than the specified timestamp. Restores
search	exec	deployment_name		Searches for runs that satisfy expressions.
set_tag	exec	deployment_name, key, value		Sets a tag on a run. Tags are run metadata that can be updated during a run and after a run completes.
update	exec	deployment_name		Updates run 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)
run_id	string	ID of the run to fetch. Must be provided.
run_uuid	string	[Deprecated, use run_id instead] ID of the run to fetch. This field will be removed in a future MLflow version.

SELECT examples

get

Gets the metadata, metrics, params, and tags for a run. In the case where multiple metrics with the

SELECT
run
FROM databricks_workspace.ml.experiment_runs
WHERE run_id = '{{ run_id }}' -- required
AND deployment_name = '{{ deployment_name }}' -- required
AND run_uuid = '{{ run_uuid }}'
;

INSERT examples

create

Creates a new run within an experiment. A run is usually a single execution of a machine learning or

INSERT INTO databricks_workspace.ml.experiment_runs (
experiment_id,
run_name,
start_time,
tags,
user_id,
deployment_name
)
SELECT 
'{{ experiment_id }}',
'{{ run_name }}',
{{ start_time }},
'{{ tags }}',
'{{ user_id }}',
'{{ deployment_name }}'
RETURNING
run
;

Manifest

# Description fields are for documentation purposes
- name: experiment_runs
props:
  - name: deployment_name
    value: "{{ deployment_name }}"
    description: Required parameter for the experiment_runs resource.
  - name: experiment_id
    value: "{{ experiment_id }}"
    description: |
      ID of the associated experiment.
  - name: run_name
    value: "{{ run_name }}"
    description: |
      The name of the run.
  - name: start_time
    value: {{ start_time }}
    description: |
      Unix timestamp in milliseconds of when the run started.
  - name: tags
    description: |
      Additional metadata for run.
    value:
      - key: "{{ key }}"
        value: "{{ value }}"
  - name: user_id
    value: "{{ user_id }}"
    description: |
      ID of the user executing the run. This field is deprecated as of MLflow 1.0, and will be removed in a future MLflow release. Use 'mlflow.user' tag instead.

Lifecycle Methods

delete

Marks a run for deletion.

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

delete_bulk

Bulk delete runs in an experiment that were created prior to or at the specified timestamp. Deletes at

EXEC databricks_workspace.ml.experiment_runs.delete_bulk 
@deployment_name='{{ deployment_name }}' --required 
@@json=
'{
"experiment_id": "{{ experiment_id }}", 
"max_timestamp_millis": {{ max_timestamp_millis }}, 
"max_runs": {{ max_runs }}
}'
;

delete_tag

Deletes a tag on a run. Tags are run metadata that can be updated during a run and after a run

EXEC databricks_workspace.ml.experiment_runs.delete_tag 
@deployment_name='{{ deployment_name }}' --required 
@@json=
'{
"run_id": "{{ run_id }}", 
"key": "{{ key }}"
}'
;

log_batch

Logs a batch of metrics, params, and tags for a run. If any data failed to be persisted, the server

EXEC databricks_workspace.ml.experiment_runs.log_batch 
@deployment_name='{{ deployment_name }}' --required 
@@json=
'{
"metrics": "{{ metrics }}", 
"params": "{{ params }}", 
"run_id": "{{ run_id }}", 
"tags": "{{ tags }}"
}'
;

log_inputs

Logs inputs, such as datasets and models, to an MLflow Run.

EXEC databricks_workspace.ml.experiment_runs.log_inputs 
@deployment_name='{{ deployment_name }}' --required 
@@json=
'{
"run_id": "{{ run_id }}", 
"datasets": "{{ datasets }}", 
"models": "{{ models }}"
}'
;

log_metric

Log a metric for a run. A metric is a key-value pair (string key, float value) with an associated

EXEC databricks_workspace.ml.experiment_runs.log_metric 
@deployment_name='{{ deployment_name }}' --required 
@@json=
'{
"key": "{{ key }}", 
"value": {{ value }}, 
"timestamp": {{ timestamp }}, 
"dataset_digest": "{{ dataset_digest }}", 
"dataset_name": "{{ dataset_name }}", 
"model_id": "{{ model_id }}", 
"run_id": "{{ run_id }}", 
"run_uuid": "{{ run_uuid }}", 
"step": {{ step }}
}'
;

log_model

Note: the Create a logged model API replaces this

EXEC databricks_workspace.ml.experiment_runs.log_model 
@deployment_name='{{ deployment_name }}' --required 
@@json=
'{
"model_json": "{{ model_json }}", 
"run_id": "{{ run_id }}"
}'
;

log_outputs

Logs outputs, such as models, from an MLflow Run.

EXEC databricks_workspace.ml.experiment_runs.log_outputs 
@deployment_name='{{ deployment_name }}' --required 
@@json=
'{
"run_id": "{{ run_id }}", 
"models": "{{ models }}"
}'
;

log_param

Logs a param used for a run. A param is a key-value pair (string key, string value). Examples include

EXEC databricks_workspace.ml.experiment_runs.log_param 
@deployment_name='{{ deployment_name }}' --required 
@@json=
'{
"key": "{{ key }}", 
"value": "{{ value }}", 
"run_id": "{{ run_id }}", 
"run_uuid": "{{ run_uuid }}"
}'
;

restore

Restores a deleted run. This also restores associated metadata, runs, metrics, params, and tags.

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

restore_bulk

Bulk restore runs in an experiment that were deleted no earlier than the specified timestamp. Restores

EXEC databricks_workspace.ml.experiment_runs.restore_bulk 
@deployment_name='{{ deployment_name }}' --required 
@@json=
'{
"experiment_id": "{{ experiment_id }}", 
"min_timestamp_millis": {{ min_timestamp_millis }}, 
"max_runs": {{ max_runs }}
}'
;

search

Searches for runs that satisfy expressions.

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

set_tag

Sets a tag on a run. Tags are run metadata that can be updated during a run and after a run completes.

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

update

Updates run metadata.

EXEC databricks_workspace.ml.experiment_runs.update 
@deployment_name='{{ deployment_name }}' --required 
@@json=
'{
"end_time": {{ end_time }}, 
"run_id": "{{ run_id }}", 
"run_name": "{{ run_name }}", 
"run_uuid": "{{ run_uuid }}", 
"status": "{{ status }}"
}'
;