Skip to main content

How to Write a Search Filter for MLflow Runs

· 7 min read
Jagdish Kumawat
Founder @ Dewiride

MLflow finds runs with a filter string, a short condition such as metrics.loss < 0.35. The same string works in the UI's search box and in Python's mlflow.search_runs(). It looks like the WHERE part of SQL, with a few rules of its own: which comparisons each kind of value allows, what needs quotes, and no OR. This guide gives the general form, runs five filters on three small runs, and lists the exact errors MLflow 3.18.0 gives when a rule is broken.

Syntax​

Syntax
<prefix>.<key> <comparator> <value>
<condition> AND <condition>
PartWhat it means
<prefix>What kind of value to look at: metrics, params, tags, attributes (the run's own fields, such as its name or status) or datasets. The singular forms, such as metric or param, work too
<key>The name: a metric such as loss, a parameter such as optimizer, a tag such as team, an attribute such as run_name, or a dataset's name, digest or context. Put a name in backticks if it has spaces or dashes: metrics.`f1 score`
<comparator>Metrics, and the times attributes.start_time and attributes.end_time: =, !=, >, >=, <, <=. Parameters and tags: =, !=, LIKE, ILIKE, IS NULL, IS NOT NULL. Other attributes and datasets: =, !=, LIKE, ILIKE, and IN for dataset fields and attributes.run_id
<value>A number for metrics and times, with no quotes. Text in single or double quotes for everything else. A list in parentheses for IN: ('a', 'b')
ANDJoins conditions; a run must meet all of them. There is no OR

LIKE matches a pattern, where % stands for any number of characters and _ for exactly one; ILIKE does the same but ignores upper and lower case. IS NULL matches runs that never logged that parameter or tag.

Prerequisites​

Step 1: Create Three Runs​

The example is three training runs: two with the adam optimizer and one with sgd, each with a number of layers, a loss and a team tag. Create filter_runs.py:

filter_runs.py
import mlflow

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

for name, optimizer, layers, loss, team in [
("adam-small", "adam", 2, 0.30, "vision"),
("adam-large", "adam", 8, 0.22, "vision"),
("sgd-small", "sgd", 2, 0.41, "speech"),
]:
with mlflow.start_run(run_name=name):
mlflow.log_params({"optimizer": optimizer, "layers": layers})
mlflow.log_metric("loss", loss)
mlflow.set_tag("team", team)
Terminal
uv run python filter_runs.py

It prints a View run link for each run.

Step 2: Run Five Filters​

Create filters.py. It passes each filter string to mlflow.search_runs() and prints the names of the runs that match:

The filters.py script in a macOS-style code window: it sets the tracking URI, loops over five filter strings, metrics.loss < 0.35, params.optimizer = 'adam', tags.team = 'speech', attributes.run_name LIKE 'adam%' and params.optimizer = 'adam' AND metrics.loss < 0.25, searches the filter-demo experiment with each, and prints the filter next to the sorted run names.

filters.py
import mlflow

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

for search in [
"metrics.loss < 0.35",
"params.optimizer = 'adam'",
"tags.team = 'speech'",
"attributes.run_name LIKE 'adam%'",
"params.optimizer = 'adam' AND metrics.loss < 0.25",
]:
runs = mlflow.search_runs(experiment_names=["filter-demo"], filter_string=search)
print(f"{search:52} -> {sorted(runs['tags.mlflow.runName'])}")
Terminal
uv run python filters.py
Output
metrics.loss < 0.35 -> ['adam-large', 'adam-small']
params.optimizer = 'adam' -> ['adam-large', 'adam-small']
tags.team = 'speech' -> ['sgd-small']
attributes.run_name LIKE 'adam%' -> ['adam-large', 'adam-small']
params.optimizer = 'adam' AND metrics.loss < 0.25 -> ['adam-large']

A terminal running uv run python filters.py: metrics.loss < 0.35 and params.optimizer = 'adam' each match adam-large and adam-small, tags.team = 'speech' matches sgd-small, attributes.run_name LIKE 'adam%' matches both adam runs, and the AND filter matches only adam-large.

FilterWhy these runs
metrics.loss < 0.35A number with no quotes: losses 0.30 and 0.22 are below it, 0.41 isn't
params.optimizer = 'adam'Parameters are text, so the value is quoted
tags.team = 'speech'Tags are text too
attributes.run_name LIKE 'adam%'The run's own name, starting with adam
... AND metrics.loss < 0.25Both conditions must hold; only adam-large has adam and a loss below 0.25

You can paste any of these filters into the UI's search box and get the same runs.

Step 3: Know the Rules That Raise Errors​

Each of these was run against the same three runs. MLflow refuses the filter and says why:

FilterError
params.optimizer = 'adam' OR params.optimizer = 'sgd'Invalid clause(s) in filter string: 'OR'
params.optimizer IN ('adam', 'sgd')Expected a quoted string value for parameter (e.g. 'my-value'). Got value ('adam', 'sgd')
params.layers > '2'Invalid comparator '>' not one of '{'IS NULL', 'ILIKE', 'IS NOT NULL', '=', '!=', 'LIKE'}'
params.optimizer = adamParameter value is either not quoted or unidentified quote types used for string value adam. Use either single or double quotes.
metrics.loss < "0.35"Expected numeric value type for metric. Found "0.35"
metrics.loss IS NULLIS NULL / IS NOT NULL is only supported for tags and params, not for 'metric' 'loss'

Through the tracking server, each message starts with INVALID_PARAMETER_VALUE:; in the UI it appears under Request error.

Common Mistakes​

MistakeWhat happensDo this instead
Using ORInvalid clause(s) in filter string: 'OR'Run two searches, or use LIKE or IN where they fit
Comparing a parameter with > or <Invalid comparator '>' not one of ...Compare with = or LIKE; parameters are text: Fixed: "Invalid comparator '>' not one of"
Quoting a metric's valueExpected numeric value type for metric. Found "0.35"Write numbers bare: metrics.loss < 0.35
Writing an apostrophe inside single quotesThe filter breaks or matches nothingWrap that value in double quotes: attributes.run_name = "bob's run"

Troubleshooting​

SymptomLikely causeFix
A filter returns no runs and no errorA name's spelling or capitalisation differs from what was loggedCopy the name from the run's page
Invalid attribute key '...' specifiedThe prefix is missing, so the name is read as a run attributeAdd metrics., params. or tags.
LIKE 'Adam%' misses adam runsLIKE is case-sensitiveUse ILIKE

FAQ​

Do the UI and Python use exactly the same syntax?​

Yes. The UI's search box sends the same filter string to the same search as mlflow.search_runs(filter_string=...).

How do I match one character in a pattern?​

_ matches exactly one: attributes.run_name LIKE 'adam-_____' matches adam-small and adam-large, which both have five letters after the dash.

How do I get "this or that" without OR?​

For datasets and run IDs, IN takes a list. For other fields, run one search per value and combine the results, or use a LIKE pattern that covers both.

Conclusion​

A filter is <prefix>.<key> <comparator> <value>, joined with AND: numbers bare for metrics, text in quotes for parameters, tags and attributes, LIKE and ILIKE for patterns, IS NULL for missing parameters and tags, and no OR. MLflow's error messages say exactly which rule a filter broke.

Additional Resources​