The Allegra Query Language (AQL)

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

In addition to 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 that are framed by quotation marks, like for example “Down under”.

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

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

Attributes

AQL supports full-text and item attribute searches. When you define a query filter, you can either specify an attribute or the preset attributes will be considered in 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 name followed by a colon.

Let’s assume, for example, that 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, you do not necessarily have to specify it. However, this would also find items that contain this phrase in another text attribute such as the title.

You can either specify the internal attribute name (e.g. “Description”) or the localized text (”Description”). The available attributes can be seen from the setting box for column selection in the item overview. A complete list of all standard attributes can be found in the section List of Standard Attributes.

Warning

The attribute expression only applies to the exact term it precedes. The expression `` Title:Do it right`` will only search for “Do” in the title. It will search for “it” and “right” in all text attributes.

Term Modifiers

AQL supports the modification of filter terms to expand search capabilities.

Wildcard Search

AQL supports wildcard searches. Wildcards are possible for both single and multiple characters. To define a single-character wildcard, use the question mark “?”. To define a multi-character wildcard, use the asterisk “*”. 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!

Fuzzy Search

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 expression: Room~ This search would also find words like foam or plum. With an optional parameter you can influence the desired similarity. It must be between 0 and 1, with values closer to 1 as words with greater similarity. For example: Room~0.9 finds Dream, but not Foam. The default value for similarity is 0.5.

Proximity Search

AQL supports the search for terms that occur a certain number of words away from another term (proximity search). For a proximity search, use the character “~” at the end of a phrase. If you are looking for the words “Allegra” and “item”, and these should not be more than 10 words apart, then use: "Allegra item"~10

Term Boost

Range searches allow filtering of attribute values by value ranges. The filter only lets items through whose attribute value lies within the specified search range. Range searches can include or exclude the range limits. The sorting is lexicographic. Changed:[20240101 TO 20241231] This will find all items whose last modification date is between January 1, 2024 and December 31, 2024, including these 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.

Square brackets define a range including the range boundaries; curly brackets a range without the range boundaries.

Term Boost

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

For example, if you are searching for the following two expressions Project Management and you want the expression “Project” to be more important than the expression “Management”, then you can weight it more heavily by the symbol ^ followed by a boost factor. You would enter: Project^4 Management This will weight items that contain the expression “Project” more heavily than those that contain the expression “Management”. You can also boost entire phrases, as in this example: "Project Management"^4 "AQL" A boost factor of 1 is preset. The boost factor must be positive, but it can be less than 1 (e.g. 0.3).

Boolean Operators

With boolean operators you can combine terms. AQL supports the operators AND, “+”, OR, NOT and “-”. Please note that boolean operators must always be written in capital letters.

OR Operator

The OR operator is the default operator, i.e. if no operators are specified between terms, the OR operator is automatically implied. It thus lets through items that contain at least one of the terms. Instead of the word OR, the character combination || can also be used.

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

AND Operator

The AND operator lets through items that contain both terms somewhere in the item. Instead of the word AND, the character combination && can also be used.

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

“+” Operator

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

To search for documents that definitely 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 the 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 yield 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"