Documentation for search using attributes and system tags (mlflow#1326)

docs/source/search-syntax.rst

@@ -20,27 +20,32 @@ 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
 ^^^^^^^^^^
 
 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
 ^^^^^^^^