diff --git a/docs/source/search-syntax.rst b/docs/source/search-syntax.rst index b30726e1fd8da..347acc87d1df5 100644 --- a/docs/source/search-syntax.rst +++ b/docs/source/search-syntax.rst @@ -20,19 +20,23 @@ the left-hand side (LHS), a comparator, and constant on the right-hand side (RHS Example Expressions ^^^^^^^^^^^^^^^^^^^^ -Search for the subset of runs with logged accuracy metric greater than 0.92. +- Search for the subset of runs with logged accuracy metric greater than 0.92. -.. code-block:: sql + .. code-block:: sql - metrics.accuracy > 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. -Search for runs created using a Logistic Regression model, a learning rate (lambda) of 0.001, and -recorded error metric under 0.05. + .. code-block:: sql -.. code-block:: sql + params.model = "LogisticRegression" and params.lambda = "0.001" and metrics.error <= 0.05 + +- Search for all failed runs. + + .. code-block:: sql - params.model = "LogisticRegression" and params.lambda = "0.001" and metrics.error <= 0.05 + attributes.status = "FAILED" Identifier @@ -40,7 +44,8 @@ Identifier 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 ``metrics``, ``params``, or ``tags``. The entity name can contain alphanumeric characters and special characters. +The type of the entity is ``metrics``, ``params``, ``tags``, or ``attributes``. The entity name can +contain alphanumeric characters and special characters. For example: ``metrics.accuracy``. Entity Name Contains Special Characters @@ -72,13 +77,24 @@ For example: metrics."2019-04-02 error rate" +Run Attributes +~~~~~~~~~~~~~~ + +The search syntax supports searching runs using two attributes: ``status`` and ``artifact_uri``. Both attributes have string values. Other fields in :py:class:`mlflow.entities.RunInfo` are :ref:`system-tags` that are searchable using the UI and the API. The search returns an error if you use other attribute names in the filter string. + +.. note:: + + - The experiment ID is implicitly selected by the search API. + - A run's ``lifecycle_stage`` attribute is not allowed because it is already encoded as a part of the API's ``run_view_type`` field. To search for runs using ``run_id``, it is more efficient to use ``get_run`` APIs. + - The ``start_time`` and ``end_time`` attributes are not supported. + Comparator ^^^^^^^^^^ There are two classes of comparators: numeric and string. - Numeric comparators (``metrics``): ``=``, ``!=``, ``>``, ``>=``, ``<``, and ``<=``. -- String comparators (``params`` and ``tags``): ``=`` and ``!=``. +- String comparators (``params``, ``tags``, and ``attributes``): ``=`` and ``!=``. Constant ^^^^^^^^