The MLflow UI and API support searching runs within a single experiment or a group of experiments
using a search filter API. This API is a simplified version of the SQL
Table of Contents
A search filter is one or more expressions joined by the
The syntax does not support
OR. Each expression has three parts: an identifier on
the left-hand side (LHS), a comparator, and constant on the right-hand side (RHS).
Search for the subset of runs with logged accuracy metric greater than 0.92.
metrics.accuracy > 0.92
Search for runs created using a Logistic Regression model, a learning rate (lambda) of 0.001, and recorded error metric under 0.05.
params.model = "LogisticRegression" and params.lambda = "0.001" and metrics.error <= 0.05
Search for all failed runs.
attributes.status = "FAILED"
Required in the LHS of a search expression. Signifies an entity to compare against.
An identifier has two parts separated by a period: the type of the entity and the name of the entity. The type of the entity is
tags. The entity name can contain alphanumeric characters and special characters.
This section describes supported entity names and how to specify such names in search expressions.
In this section:
When a metric, parameter, or tag name contains a special character like hyphen, space, period, and so on, enclose the entity name in double quotes or backticks.
Unlike SQL syntax for column names, MLflow allows logging metrics, parameters, and tags names that have a leading number. If an entity name contains a leading number, enclose the entity name in double quotes. For example:
metrics."2019-04-02 error rate"
You can search using the following run attributes contained in
artifact_uri attributes have string values, while
end_time are numeric. Other fields in
mlflow.entities.RunInfo are not searchable.
The experiment ID is implicitly selected by the search API.
lifecycle_stageattribute is not allowed because it is already encoded as a part of the API’s
run_view_typefield. To search for runs using
run_id, it is more efficient to use
attributes.artifact_uri = 'models:/mymodel/1' attributes.status = 'ACTIVE' # RHS value for start_time and end_time are unix timestamp attributes.start_time >= 1664067852747 attributes.end_time < 1664067852747 attributes.user_id = 'user1' attributes.run_name = 'my-run' attributes.run_id = 'a1b2c3d4' attributes.run_id IN ('a1b2c3d4', 'e5f6g7h8')
There are two classes of comparators: numeric and string.
Numeric comparators (
String comparators (
The search syntax requires the RHS of the expression to be a constant. The type of the constant depends on LHS.
If LHS is a metric, the RHS must be an integer or float number.
If LHS is a parameter or tag, the RHS must be a string constant enclosed in single or double quotes.
The MLflow UI supports searching runs contained within the current experiment. To search runs across multiple experiments, use one of the client APIs.
mlflow.search_runs() API to
search programmatically. You can specify the list of columns to order by
(for example, “metrics.rmse”) in the
order_by column. The column can contain an
ASC value; the default is
ASC. The default ordering is to sort by
start_time DESC, then
mlflow.search_runs() API can be used to search for runs within specific experiments which
can be identified by experiment IDs or experiment names, but not both at the same time.
experiment_names in the same call will result
in error unless one of them is
For example, if you’d like to identify the best active run from experiment ID 0 by accuracy, use:
from mlflow import MlflowClient from mlflow.entities import ViewType run = MlflowClient().search_runs( experiment_ids="0", filter_string="", run_view_type=ViewType.ACTIVE_ONLY, max_results=1, order_by=["metrics.accuracy DESC"] )
To get all active runs from experiments IDs 3, 4, and 17 that used a CNN model with 10 layers and had a prediction accuracy of 94.5% or higher, use:
from mlflow import MlflowClient from mlflow.entities import ViewType query = "params.model = 'CNN' and params.layers = '10' and metrics.`prediction accuracy` >= 0.945" runs = MlflowClient().search_runs(experiment_ids=["3", "4", "17"], filter_string=query, run_view_type=ViewType.ACTIVE_ONLY)
To search all known experiments for any MLflow runs created using the Inception model architecture:
from mlflow import MlflowClient from mlflow.entities import ViewType all_experiments = [exp.experiment_id for exp in MlflowClient().list_experiments()] runs = MlflowClient().search_runs(experiment_ids=all_experiments, filter_string="params.model = 'Inception'", run_view_type=ViewType.ALL)
To get all runs from the experiment named “Social NLP Experiments”, use:
import mlflow runs = mlflow.search_runs(experiment_names=["Social NLP Experiments"])
The R API is similar to the Python API.
library(mlflow) mlflow_search_runs( filter = "metrics.rmse < 0.9 and tags.production = 'true'", experiment_ids = as.character(1:2), order_by = "params.lr DESC" )
The Java API is similar to Python API.
List<Long> experimentIds = Arrays.asList("1", "2", "4", "8"); List<RunInfo> searchResult = client.searchRuns(experimentIds, "metrics.accuracy_score < 99.90");