Skip to main content

How to Search MLflow Runs by Parameter Value

· 5 min read
Jagdish Kumawat
Founder @ Dewiride

Parameters are the settings a run was trained with, such as a model type or a tree depth, and searching by them answers "which runs used this setting?". MLflow stores every parameter as text, which shapes every search: values go in quotes, a setting of None is the text 'None', and > and < don't work. This guide searches three runs by parameter four ways, with real results from MLflow 3.18.0.

Syntax​

Syntax
params.<name> = '<value>'
params.<name> != '<value>'
params.<name> LIKE '<pattern>'
params.<name> IS NULL
PartWhat it means
params.<name>The parameter to look at, such as params.max_depth
'<value>'The value as text, in single or double quotes, even when it's a number: '3'
LIKE '<pattern>'A pattern, where % stands for any number of characters: 'tr%' matches tree. ILIKE does the same but ignores case
IS NULLRuns that never logged this parameter. IS NOT NULL is the opposite

The same strings work in the UI's search box and in mlflow.search_runs(filter_string=...).

Prerequisites​

Step 1: Create Three Runs​

The example is three models: a tree limited to depth 3, a tree with no depth limit, logged as None, and a linear model that has no depth setting at all. Create depth_runs.py:

depth_runs.py
import mlflow

mlflow.set_tracking_uri("http://127.0.0.1:8080")
mlflow.set_experiment("param-search-demo")

with mlflow.start_run(run_name="shallow-tree"):
mlflow.log_params({"model": "tree", "max_depth": 3})
with mlflow.start_run(run_name="deep-tree"):
mlflow.log_params({"model": "tree", "max_depth": None})
with mlflow.start_run(run_name="linear"):
mlflow.log_param("model", "linear")
Terminal
uv run python depth_runs.py

It prints a View run link for each run.

Step 2: Search by Parameter​

Create param_search.py. It tries five searches and prints either the matching runs or MLflow's error:

The param_search.py script in a macOS-style code window: it loops over five filters, params.max_depth = '3', params.model LIKE 'tr%', params.max_depth = 'None', params.max_depth IS NULL and params.max_depth = 3, searches the param-search-demo experiment with each, and prints the matching run names or the error's message.

param_search.py
import mlflow
from mlflow.exceptions import MlflowException

mlflow.set_tracking_uri("http://127.0.0.1:8080")

for search in [
"params.max_depth = '3'",
"params.model LIKE 'tr%'",
"params.max_depth = 'None'",
"params.max_depth IS NULL",
"params.max_depth = 3",
]:
try:
runs = mlflow.search_runs(experiment_names=["param-search-demo"], filter_string=search)
print(f"{search:28} -> {sorted(runs['tags.mlflow.runName'])}")
except MlflowException as error:
print(f"{search:28} -> {error.message}")
Terminal
uv run python param_search.py
Output
params.max_depth = '3' -> ['shallow-tree']
params.model LIKE 'tr%' -> ['deep-tree', 'shallow-tree']
params.max_depth = 'None' -> ['deep-tree']
params.max_depth IS NULL -> ['linear']
params.max_depth = 3 -> INVALID_PARAMETER_VALUE: Expected a quoted string value for parameter (e.g. 'my-value'). Got value 3

A terminal running uv run python param_search.py: max_depth = '3' finds shallow-tree, model LIKE 'tr%' finds both trees, max_depth = 'None' finds deep-tree, max_depth IS NULL finds linear, and max_depth = 3 without quotes fails with INVALID_PARAMETER_VALUE: Expected a quoted string value for parameter.

Step 3: Read the Results​

SearchResultWhy
params.max_depth = '3'shallow-treelog_params turned the number 3 into the text '3', so the value must be quoted
params.model LIKE 'tr%'both treestr% is any value starting with tr
params.max_depth = 'None'deep-treeLogging Python's None stored the text 'None': the run has the parameter
params.max_depth IS NULLlinearOnly the run that never logged max_depth
params.max_depth = 3an errorA number without quotes isn't accepted for a parameter

The difference between 'None' and IS NULL matters when a setting is optional: "no limit" logged as None is a value you can search for, while a parameter that was never logged is missing.

Common Mistakes​

MistakeWhat happensDo this instead
A number without quotes, params.max_depth = 3Expected a quoted string value for parameter (e.g. 'my-value'). Got value 3Quote it: params.max_depth = '3'
Comparing with > or <, such as params.max_depth > '2'Invalid comparator '>' not one of ...: the fixUse =, != or LIKE
Searching for a None setting with IS NULLNo match: the run logged the text 'None'Use params.max_depth = 'None'

Troubleshooting​

SymptomLikely causeFix
A search by a parameter returns nothing, with no errorThe name or the value differs in spelling or caseCheck both on the run's Overview
You need runs with a setting above some numberParameters can't be compared as numbersLog the value as a metric as well, or filter the results in Python

FAQ​

Why are parameters text?​

MLflow stores every parameter value as a string, whatever type you logged. Metrics are the numbers.

Can I search several parameters at once?​

Yes, with AND: params.model = 'tree' AND params.max_depth = '3'.

Does IN work for parameters?​

No. params.model IN ('tree', 'linear') fails with Expected a quoted string value for parameter. In MLflow, IN works for dataset fields and run IDs only.

Conclusion​

params.max_depth = '3' found the run by its setting, with the number in quotes because parameters are text. LIKE matched a pattern, = 'None' found the run that logged None, and IS NULL the one that never logged the parameter.

Additional Resources​