.. _section-Trace Query with right-click menu:

Trace Query with right-click menu
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**Sunflower** offers 3 options to trace the execution of a query: **Trace Query**, **Trace Query (all bindings)**, and **Trace Query (all bindings, all explanations)**.  When the body of a query is highlighted in the **Text Editor**, these 3 options automatically become enabled in the right-click menu, as shown in :numref:`figure-trace-query-right-click-menu.png`.

.. _figure-trace-query-right-click-menu.png:

.. figure:: ../../figs/trace-query-right-click-menu.png
   :alt: Right-click menu shows the 3 enabled trace query options

   Right-click menu shows the 3 enabled trace query options


To use these trace query options, be sure that only the body of a query is highlighted.  If the label of a query is also included in the highlighted query, it will result in a parse error.

All 3 trace query options display trace results in the **Query Results** window.

The first option (**Trace Query**) selects one instantiation of the highlighted query to display, along with one selected explanation.  For example, in :numref:`figure-trace-query-1-instantiation-1-explanation.png`, the trace results for highlighted query "Who has a brother?" is shown in the **Query Results** window.  It shows one instantiation: **Herb is a brother of Greg**, along with one selected explanation for the instantiation.

.. _figure-trace-query-1-instantiation-1-explanation.png:

.. figure:: ../../figs/trace-query-1-instantiation-1-explanation.png
   :alt: **Trace Query** shows 1 selected instantiation and 1 explanation

   **Trace Query** shows 1 selected instantiation and 1 explanation


The second option is **Trace Query (all bindings)**.  It shows all instantiations for the highlighted query, and one selected explanation for each instantiation.  :numref:`figure-trace-query-all-instantiations-1-explanation.png` shows such an example.  The 6 instantiations of the highlighted query "Who has a brother?" are shown in the **Query Results** window, along with a single explanation for each instantiation.

.. _figure-trace-query-all-instantiations-1-explanation.png:

.. figure:: ../../figs/trace-query-all-instantiations-1-explanation.png
   :alt: **Trace Query (all bindings)** shows all instantiations with 1 explanation each

   **Trace Query (all bindings)** shows all instantiations with 1 explanation each


Lastly, the **Trace Query (all bindings, all explanations)** option shows all instantiations for the highlighted query.  For each instantiation, it also shows all explanations, as shown in :numref:`figure-trace-query-all-instantiations-all-explanations.png`.  Compared to the case of **Trace Query (all bindings)**, where only one explanation for the instantiation: **Emma has brother Darryn** is listed in the **Query Results** window, **Trace Query (all bindings, all explanations)** lists both explanations for the same instantiation.

.. _figure-trace-query-all-instantiations-all-explanations.png:

.. figure:: ../../figs/trace-query-all-instantiations-all-explanations.png
   :alt: **Trace Query (all bindings, all explanations)** shows all instantiations with all explanations

   **Trace Query (all bindings, all explanations)** shows all instantiations with all explanations


Results generated from the option **Trace Query** can be saved for regression testing with the FloraScript command **CompareTraceWithFile**.  The use of this command is explained in :ref:`section-Regression Testing With FloraScript and Saved Query Results`.