Use AQL

The Allegra Query Language (AQL) allows to define filters that include full text search in all attachments (HTML, Text, XML, OpenOffice, PDF, Excel, Word, Powerpoint).

Besides direct searches, fuzzy searches are also supported and it is possible to search for adjacent terms.

Terms

A filter expression consists of at least one term and optionally one or more operators. There are two types of terms: single terms and phrases.

A single term consists of a single word such as “test” or “hello”.

A phrase consists of a group of words framed by quotation marks, such as “down under”, for example.

Terms can be combined with logical operators to create more complex filter expressions.

If a term consists of only one positive integer number, only the item number attribute is searched for that number. So you can quickly look up an item whose item number you know by entering this number in the search box.

Attributes

AQL supports searches in full text and item attributes. When you define a query filter, you can either specify an attribute or the default attributes that are going to be taken into account for the search.

If you do not specify an attribute, Allegra searches all text attributes by default. You can limit a filter term to an attribute by prefixing the term with the attribute “title” followed by a colon in front of the term.

For example, let’s say you want to find an item with the title “The right way” that also contains the text “not this way” in the description attribute: title: "The right way" AND description: "not this way" or title: "The right way" AND "not this way". Since the attribute Description is preset as a search field, it is not necessary to specify it. However, items would then be found that have this phrase in another text attribute, such as the title.

You can specify either the internal attribute name (e.g. “Description”) or the localized text (“Description”). The available attributes can be seen in the column selection setting box in the Task Navigator. For a complete list of all default attributes, see List of Default Attributes.

Attention

The attribute expression is valid for the exact term it is prefixed to. The expression title: "Do it right" will only look for the do in the title but it will search it and right in all text attributes.

Term modifiers

AQL supports modification of filter terms to extend search capabilities.

AQL supports wildcard searches. Wildcards are possible for single as well as multiple characters. To define a single character wildcard, use the “?” character. To define a multi-character wildcard, use the “*” character. The single-character wildcard searches for expressions that match the specified term, but with the wildcard replaced by any other character. For example, the following expression searches for both “test” and “text”: te?t.

Multi-character wildcards replace zero or more characters. For example, to search for test, tests, or tester you can use this filter expression: test. You can also use the multi-character wildcard in the middle of an expression: te*t.

Note

You cannot use the wildcard characters as the first character of a term.

AQL supports fuzzy searches. To define a fuzzy search, use the “~” character at the end of a single term. For example, to search for a term that is spelled similarly to “room”, use the the expression: room~.

This search would also find words like foam or plum. You can use an optional parameter to control the desired similarity. It must be between 0 and 1, with values closer to 1 than words with greater similarity. For example, room~0.9 finds dream, but not foam. The default value for similarity is 0.5.

AQL supports the search of terms that occur a certain number of words away from another term (neighbor search). To perform a neighbor search, use the “~” character at the end of a phrase. For example, if you are searching for the words “Allegra” and “item”, and they should be no more than 10 words apart, then you would use: "Allegra Vorgang"~10.

Range searches allow filtering attribute values by value range. The filter allows to pass only items whose attribute value is in the specified search range. Range searches can include or exclude the range limits. The sorting is done lexicographically.

Modified:[20190101 TO 20191231]

This will find all items with a last modified date between 1/1/2019 and 12/31/2019, including those values. Please note that range searches are not limited to numeric or date attributes. You can also search as follows: Title:{Aida TO Carmen}. This will find all items whose title contains words between Aida and Carmen, but without Aida and without Carmen.

Rectangular braces define a workspace including the range boundaries while curly braces define a workspace without the range boundaries.

Amplify Term

AQL internally returns a relevance level that determines how relevant an item is with respect to the query filter criteria. You can increase the relevance of an item in the query by giving some terms of the query more weight than others. To do this, use the “^” character followed by a number to specify a boost term. The higher the boost term, the higher the relevance of the item, if this term is contained in it.

For example, if you search for the following two terms Project Management and you want the term project to be more relevant than the term management, then you can give it more weight by using the ^ symbol followed by a boost factor. Therefore, you would enter: Project^4 Management. This will give more weight to items containing the phrase “project” than to those containing the phrase “management”. You can also boost entire phrases, as in this example: "Project Management"^4 "AQL" There is a default amplification factor of 1. The amplification factor must be positive, but it can be less than 1 (e.g., 0.3).

Boolean operators

Boolean operators allow you to combine terms. AQL supports the operators AND, “+”, OR, NOT and “-“. Please note that boolean operators must always be written in all uppercase letters.

OR operator

The OR operator is the default operator, that is, if no operators are specified between terms, the OR operator is automatically implied. This allows to pass the items that contain at least one of the terms. Instead of the word OR, the character || can also be used.

To search for items that contain either “project management” or just “project”, but not only “management”, use this query: "project management" project or "project management" OR project.

AND operator

The AND operator passes items where both terms occur somewhere in the item. Instead of the word AND, you can also use the symbol ‘&&’.

To search for items that contain “project management” and also “AQL new” somewhere in the text, use this query: "project management" AND "AQL new".

“+” operator

The “+” or “required” operator specifies that the term occurs after the ‘+’ symbol in the item.

To search for documents that absolutely contain the word “project”, and if possible also “AQL”, use this query: +project AQL.

NOT operator

The NOT operator excludes items that contain the term after NOT. Instead of the word NOT the symbol ‘!’ can also be used.

To search for items that contain the term “project management” but not the term “AQL new”, use the query: "project management" NOT "AQL new"

Attention

The NOT operator cannot be used with only one term. The following query would return no result: NOT "project management".

“-” operator

The “-” or exclusion operator excludes items that contain the term after the “-” symbol. To search for items that contain “project management” but not “issue tracking”, you would use this expression: "project management" - "issue tracking".