= Running semantic queries =
This service is available under the ”Queries” menu.

[[Image(webinterface_queries.jpg)]][[BR]]

''Web interface after running a query from the A variable node.''

== Constructing semantic queries ==
To learn more about semantic queries see the [SemanticQuery Semantic Queries page].

The query construct assistant is located at the top-left corner of the page. While typing a query the interface offers possible continuations for uncompleted sub-terms. An offered option can be chosen from a drop-down list. This auto-complete mechanism helps new !RefactorErl users using the language, and also all developers to speed up query constructions and avoiding constructing wrong queries.

Pressing ”Run” evaluates the query and displays the result.
== Starting queries ==

'''Before browsing source files, it is recommended to pre-generate them from the [wiki:WebInterface#Browsingloadedfiles File browser].'''

A file browser is placed at the left side of the page under the ’File browser’ tab. A file can be viewed by clicking on it.
You can also filter files in the filter textbox. The filter can contain the * (any number) and ? (only one) wildcards for unknown characters.

You can set a starting point for a query in two ways:
* Selecting a region or pointing at a position in the shown code. You can only start queries from the query construct assistant this way. Also, if a node is selected, deselect it first by clicking on it again or by clicking on the ”Deselect Node” button.
* Clicking on a node (bold text) - the selected node will be highlighted. 
{{{#!comment
 Note that, the forms which contain errors are not clickable. 
}}}


After selecting a node you can either:
* Run pre-defined queries for that node from the top-right corner of the screen - the result of these won't appear in the ’previous queries’ tab.
* Run previously made queries for that node type by selecting one from the ”Choose previous query” dropdown box.
* Run a query from the query construct assistant text-box, which will start from that node.

{{{#!comment
* Run pre-defined queries from that node from the now shown context menu - the result of these won't appear in the ’previous queries’ tab.
* Run previously made queries for that node type by selecting one from the ”Choose previous query” dropdown box.
* Run a query from the query construct assistant text-box (either at the top of the page or the context menu), which will start from that node.
* Start a new investigation (beta feature) from the clause the selected node is in. 
}}}

The first result of the query will be shown (if there was any). Results can be browsed with the appearing ''Prev'' and ''Next'' buttons. The total number of results as well as the currently shown result's number are displayed under those buttons. You can also select results from the ”Last result” tab.

[[Image(webinterface_prevqueries.jpg, right)]][[BR]]
== Previous Queries ==

For your convenience, the interface stores previously executed queries and their results, which are listed at the left side of the page under the ”Previous Queries” tab. You can either choose to list only queries which belong to the current user, or all queries stored in the system.

Clicking a previous query the interface first examines if the database has changed since that query was last run. If there were no changes, the stored result is displayed, otherwise the query is re-executed, the stored result is updated, and the new result is displayed.

Users can delete their own queries from the list by clicking the corresponding ”X” icon.

By clicking the corresponding ”?” icon, the query string and previously added comments are shown. If the query was started from a position, the starting file and position are also shown.

You can rename a query by clicking on the corresponding ’E’ icon, writing a new name in the appearing text-field, then pressing the ’Save’ button.
This is useful, because named queries can be identified easier, and are also more readable.
The actual query string can still be shown by clicking the ’?’ icon.

Users can add or modify a comment on any query by clicking the corresponding ”C” icon.
== Running Queries ==
The list of currently running queries are displayed at the left side of the page under the ”Running Queries” tab. The list is updated every second. A running query (started by the current user) can be aborted by pressing the corresponding ’X’ icon. The user is notified about the success of the abort.
== Displaying the result of queries ==
The results of the last query are displayed at the left side of the page under the ”Last Result” tab. Clicking on an entry shows that result by either selecting the result node or highlighting the result depending on that node being selectable or not.
== Skeleton of queries ==
Large amounts of queries are similar to each-other. The only difference is usually the actual value of their filter parameter or the used sub-query. Some examples are shown below.

{{{
mods[name = a].funs[(name = f) and (arity = 2)].refs 
mods[name = b].funs[(name = g) and (arity = 3)].refs
}}}

or

{{{
mods.funs[arity = 2] 
mods.funs[exported and is_tail_rec]
}}}

A new abstract level is introduced, where these queries are not only similar to each-other, but are equal, we called these Skeletons. They are actually queries with parameters. Examples are shown below.

{{{
mods[name = $ModName$].funs[name = $FunName$ and arity = $Arity$].refs
mods.funs[$FunSubQuery$]
}}}
== Usage of skeletons ==
A skeleton can be constructed by typing its body into the query construct assistant, then clicking the ’Save as skeleton’ button. The desired name of the skeleton can be typed in the appearing textbox. The skeleton can then be saved by clicking the ’Save’ button. If any error occurs during saving, an error message is shown.

A previously saved skeleton can be evaluated like a function by filling it's actual parameter values. A valid parameter cannot contain the {{{`}}} character (back-tick), because the {{{`}}} character is the delimiter of the parameter values. Auto-complete in the query textbox also offers skeleton names.

An example of a valid skeleton is shown below:

{{{
Name: skeleton_name
Body: mods.funs[$FunSubQuery$]
Call: skeleton_name(` (arity>0) and (name like s) `).
}}}

Constructed skeletons are listed under the ’Skeletons’ tab.

[[Image(webinterface_skeletons.jpg, right)]][[BR]]
When clicking on a skeleton, a valid ’skeleton call’ will be placed in the query construct assistant, where the actual parameters should be filled out (spaces between `` characters).

After a successful evaluation of a skeleton, the generated semantic query string and its result are saved in the ’Previous queries’ list, and the result of the semantic query will be shown as usual.

By clicking the ? icon, the body and owner of the corresponding skeleton will be shown.

By clicking the corresponding ’E’ icon, you can edit the body of the skeleton in the query construct assistant. Clicking the ’Update skeleton’ button will update the body of the skeleton.

By clicking the corresponding ’X’ icon, the skeleton will be deleted.

Only the owner of a skeleton can edit or delete it.