Search Editor screen

Syntax of Saved Searches

A saved search is the Agility Query Language (AQL) filter needed to perform a search, with embedded placeholders for user input. For example, this search:

         FIND ANY WHERE (#123 = "%1" AND "Category" != "%2")

is expecting two items of user input: one for the attribute with id 123, and one for the attribute called "Category". When the user selects this search, the Search gadget parses the AQL and detects the attribute expressions. Using the type of the attributes it can calculate what extra UI controls it should present to let the user fill in the missing search parameters.

Some saved searches will not need additional user input: for instance if they are testing attributes using NULL or EXISTS, or if all the attribute values have been fixed. For example:

         FIND ANY WHERE (#123 IS NULL AND "Category" EXISTS)

or

         FIND ANY WHERE (#123 = "42.5" AND "Category" != "Premium")

Using the Search Editor

You must first select the saved search you want to edit. The Saved Search dropdown contains any searches that have been previously created by the user using the Search Editor, and will always include the choice New Search that lets the user create a completely new search. It does not include the saved searches defined in the workspace editor because these cannot be edited.

The Search Editor tries to anticipate what you want to edit, as follows:

• If the Search gadget is displaying a traditional (non-saved) search, then the Search Editor will open showing New Search, the search clause will be shown, and the AQL box will contain the AQL that the search would generate.
• If the Search gadget is showing a search created by the user, then it will populate the Search Editor with details of that search.
• If the Search gadget is showing a Saved Search, then the Search Editor will populate the editor with its details.

The large text area near the bottom shows the AQL of the search, which is updated as you add search conditions. It is editable; however, there is no syntax checking—the only way to discover that the AQL is malformed is to try executing the search and use the resultant error message from Agility Server to diagnose your mistake.

To the right of the saved search selector is a Delete button. Its operation is straightforward: it deletes the selected search. The search's name disappears from the list of available searches, and the other controls become blank. This button will be disabled when you're adding a new search.

Below the search selector is a text box that lets you specify the name of the saved search. When you create a new search, the OK and Save buttons will not be enabled until the search has a name. Below the name box there is another box to let you add an optional description of what the search is for, and what user input it expects. This text will appear as a tooltip on the Saved Search dropdown selector in the Search gadget.

The Add a Search Clause button lets you add conditions to your search. It generates four new UI controls: a dropdown containing Name (object name) and all the attributes in the database (not just the ones defined in the workspace configuration for the Search gadget); a dropdown containing the normal operators such as 'equals', 'contains', 'exists'; a control for the attribute value; and a small  icon that will remove the whole clause.

The third control is normally a text input box, but will be a dropdown if the attribute is a choice list. You can either enter a value, or leave it blank to create a placeholder expression.

The Save and OK buttons will not be enabled until the Name box has been given a value and until either at least one search clause has been added or the AQL box has been edited.

Editing Searches Using Only AQL

You can enter the AQL for a search directly into the AQL box.

See the article A Guide to the Agility Query Language (AQL) for information on writing AQL.