Searching and filtering runs

Basic Filtering

You can perform the simplest filtering by:

  • typing into the search field

  • choosing a tag

  • choosing a run status

For more advanced filtering criteria you should switch to the “advanced search” and use Neptune Query Language described in the next section.

To do that you should click on the “Go to advanced search” button.

Searching Runs with Neptune Query Language

Neptune Query Language (NQL) enables you to apply complex filters to your runs view. You can build NQL queries in the query editor inside the Neptune dashboard.

Basic Examples

Let’s assume that you want to see runs where the recall metric is higher than 0.9. In other words, you are looking for runs, where:

recall > 0.9

The statement above is called a clause and follows the following format:

field-name operator value

Note that a field name must be on the left side of an operator.

Now, imagine you are looking for runs where the recall metric is higher than 0.9 and, at the same time, the learning_rate parameter is smaller or equal to 0.005.

In this example, two clauses are joined together using a logical operator. Specify:

recall > 0.9 AND learning_rate <= 0.005

In a similar way, you can build even more complex queries.

The example below yields runs where the recall metric is higher than 0.9 and at least one of two conditions is satisfied: either the learning_rate parameter is smaller or equal to 0.005, or encoder (a text log) is ResNet101

recall > 0.9 AND (learning_rate <= 0.005 OR encoder = ResNet101)

For more information, see NQL reference.

Advanced examples

  • Fetching specific runs by ids:

id = SAN-3 OR id = SAN-5 OR id = SAN-43
  • Fetching runs by using a complex logical expression:

((param1 = 5 AND recall >= 0.9) OR (param1 < 5 AND param1 > 2 AND recall >= 0.7)) AND owner = Fred AND NOT status = Succeeded
  • Fetching runs that contain three specific tags:

tags CONTAINS some_tag_1 AND tags CONTAINS some_tag_2 AND tags CONTAINS another_tag
  • Fetching runs that contain at least one of the specific tags:

tags CONTAINS some_tag_1 OR tags CONTAINS some_tag_2 OR tags CONTAINS another_tag
  • Fetching runs that contain the tag expected but do not contain the tag unexpected. Use either of the following queries:

tags CONTAINS expected AND NOT tags CONTAINS unexpected
tags CONTAINS expected AND tags NOT CONTAINS unexpected
  • Fetching runs with a name that contains a specific substring:

name CONTAINS some_substring
  • Fetching runs containing channel with given name and non-null value:

some_column_name EXISTS
  • Fetching runs not containing channel, parameter or property with given name:

some_column_name NOT EXISTS
NOT some_column_name EXISTS
  • Fetching finished runs:

timeOfCompletion EXISTS
finished EXISTS
  • Fetching runs created in notebook:

notebookName EXISTS

Neptune Query Language reference


A clause can take one of the following forms:

  • A relation consisting of three elements:

field-name OPERATOR value
  • A search term consisting of a single string value (a few words in quotes are considered a single string):

"some string value"

Relation clauses


Field-names are case insensitive, so you can write both state and State or even STATE. It can be one of the following:

  • metric name

Only last value in the metric is taken into account. Example:

recall > 0.9
  • parameter name


learning_rate <= 0.005
  • tags

Can be used only with the CONTAINS operator. Condition is fulfilled if run contains a specific tag.


tags CONTAINS example-tag
  • text metadata

Only last value in the log is taken into account.


stderr = "example text in log file"
stderr CONTAINS error
  • id


id = SAN-12
  • owner


owner = Fred
  • name


name = Approach-1
name CONTAINS test
  • description


description = "My first run"
description CONTAINS test
  • size

Without any unit bytes are assumed, however following units are supported and are case insensitive: kb, mb, gb. If there is a space between the number and its unit, the whole value needs to be enclosed in quotation marks. Comparison of this field works on its corresponding value, not on strings.


size > 20MB
size < 100
size >= "35 kb"
  • hostname


hostname = my-server-1
hostname CONTAINS server
hostname EXISTS
  • commitId


commitId = 381ed1e25230cc1a08e0b901b90ecb00a8f5fd41
commitId CONTAINS 381ed1e25
commitId EXISTS
  • notebookName


notebookName = my_notebook
notebookName CONTAINS note
notebookName EXISTS
  • checkpointName


checkpointName = my_checkpoint
checkpointName CONTAINS check
checkpointName EXISTS


It is one of the relational operators that lets you specify what you are looking for. See the operators table below for list of all operators.

Operator CONTAINS can be used only with text parameters, text logs, tags, id, name, description, hostname, commitId, notebookName, checkpointName and owner.


Value is a specific value within a given column, like 0.95 or ResNet101. Values are case sensitive. Two types of values are supported:

  • Numbers

  • Strings

Numbers are compared based on values, however strings are compared lexicographically basing on ASCII codes. Some fields, like size and state are exceptions to this rule.

Search term clauses

A clause consisting of a single string value will be treated as a search term. Such query matches all runs that contain a given string in their names, description or run id. Search terms are case insensitive and some typos are automatically recognized.


"untitled Test"

Complex query

AND and OR operators

An NQL query consists of a number of clauses connected with logical operators. For example:

recall > 0.9 AND learning_rate <= 0.005 AND encoder = ResNet101

Additionally, brackets can be used to control logical operators precedence:

recall > 0.9 AND (learning_rate <= 0.005 OR encoder = ResNet101)

Note: The AND operator has a higher precedence than OR, so the following two queries are identical:

learning_rate <= 0.005 OR encoder = ResNet101 AND recall > 0.9
learning_rate <= 0.005 OR (encoder = ResNet101 AND recall > 0.9)

NOT operator

The NOT operator can be used to negate a single clause or an entire sub-query. For example, if you want to find all runs that are not owned by Fred, you can use either of the following queries:

NOT owner = Fred
owner != Fred

The NOT operator has a higher precedence than AND and OR but a lower precedence than relational operators. So, the following queries are identical:

recall > 0.9 AND NOT learning_rate <= 0.005 OR encoder = ResNet101
recall > 0.9 AND NOT (learning_rate <= 0.005) OR encoder = ResNet101
recall > 0.9 AND (NOT learning_rate <= 0.005) OR encoder = ResNet101

but they are different from:

recall > 0.9 AND NOT (learning_rate <= 0.005 OR encoder = ResNet101)

In addition, you can use the NOT operator with the CONTAINS operator like this:

description NOT CONTAINS test
tags NOT CONTAINS test

Logical operators are case insensitive.

Operators reference

Syntax elements

Logical operators


Relational operators

=, ==, !=, >, >=, <, <=, CONTAINS, EXISTS


(, )

Quotation marks

"", ``

Precedence order

If there are any field name collisions, the following order precedence is applied:

  • system

  • column

  • parameter

  • metric

  • text log

For example, if there is a metric, and a parameter called owner, the following query will return only runs created by Fred, but no runs of other users who have a parameter called owner with value Fred:

owner = Fred


There are two types of quotation marks in NQL:

  • A double quote ("") is used with values,

  • back quote (``) is used with field names.

While in most cases it is not required to use quotation marks, there are some cases when it is necessary.

Special characters

Typically, field name and string values can consist of letters of English alphabet, digits, dots (.), underscores (_) and dashes (-). However, it is possible to write a query using strings containing any unicode character. For this purpose you will need to use quotation marks:

name = "my first run"
`[email protected]#$%^&*()_+` <= 0.005
tags CONTAINS "Déjà vu"

If your field name contains a back quote character (`) you will need to escape it using a backslash "\". Similarly, double quote character (") has to be escaped in case of quote enclosed string value. Backslash character has to be preceded by another backslash in both cases - field names and string values. For example:

windows_path = "tmp\\dir\\file"
text_with_quote = "And then he said: \"Hi!\""
`\`backquoted_parameter_name\`` > 55
`long\\parameter\\name\\with\\backslashes` > 55


There are four reserved keywords in NQL: AND, OR, NOT and CONTAINS. They can not be simply used as fields or values. Execution of one of the following queries will result in a syntax error:

AND = some_string

You can handle such situations by escaping the name of the column with back quotes (`) and the value of the field with quotes (").

`AND` = some_string
name = "CONTAINS"