The Allegra Query Language (AQL)

With the Allegra Query Language (AQL), you define filters that can also include a full-text search across all attachments (HTML, text, XML, OpenOffice, PDF, Excel, Word, PowerPoint).

AQL supports exact searches, fuzzy searches, and searches for nearby terms.

Terms

A filter expression consists of at least one term and, optionally, one or more operators. There are two kinds 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 in quotation marks — for example, “Down under”.

You combine terms with logical operators to form more complex filter expressions.

If a term consists of a positive integer, Allegra searches only the item number. This lets you bring up an item with a known number very quickly on screen — you simply type the number into the search box.

Attributes

AQL searches the full text and item attributes. In the query, you either specify a particular attribute — or Allegra searches the preset attributes.

Without an attribute specification, Allegra searches all text attributes. You restrict a filter term to a single attribute by prefixing the attribute name followed by a colon.

Example: you are looking for an item with the title “The right way” that also contains “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"

The “Description” attribute is preset as a search field — you do not have to specify it. However, Allegra then also finds items that carry the phrase in another text attribute, such as the title.

You specify either the internal attribute name (e.g. “Description”) or the localized text (“Beschreibung”). You can see the available attributes in the column selection of the item overview. A complete list of all standard attributes is in the section Standard attributes.

Warning

The attribute expression applies only to the exact term it is prefixed to. The expression Title:Do it right searches for “Do” only in the title — but for “it” and “right” in all text attributes.

Term modifiers

AQL extends the search options through term modifiers.

Wildcard search

AQL supports wildcards for a single character (?) and for multiple characters (*).

The single-character wildcard stands for exactly one arbitrary character. Example — finds both “test” and “text”:

te?t

Multi-character wildcards stand for zero or more characters. Example — finds “test”, “tests”, or “tester”:

test*

You can also use the multi-character wildcard in the middle of an expression:

te*t

Note

A wildcard must not be the first character of a term.

Fuzzy search

For a fuzzy search, append ~ to a single term. Example — finds words similar to “room”:

room~

This search also finds “roam” or “broom”. With an optional parameter between 0 and 1, you control the desired similarity — values close to 1 mean higher similarity. Example:

room~0.9

finds “rooms” but not “broom”. The default is 0.5.

Proximity search

A proximity search finds terms within a maximum word distance. Append ~ to a phrase. Example — finds “Allegra” and “item” at most ten words apart:

"Allegra item"~10

Range search

A range search filters attribute values between two bounds — the bounds can be included or excluded. Sorting is lexicographical:

Modified:[20240101 TO 20241231]

finds items whose last modification date lies between 1 Jan 2024 and 31 Dec 2024 — bounds included. Range searches are not limited to numeric or date attributes. This works too:

Title:{Aida TO Carmen}

finds items whose titles contain words between “Aida” and “Carmen” — without “Aida” and “Carmen” themselves.

Square brackets include the range bounds; curly braces exclude them.

Boosting a term

Internally, AQL computes a relevance score per item. You increase the relevance of an item in the query by giving a term more weight. To do so, append ^ and a boost factor to the term — the higher the value, the greater the weight.

Example — you are searching for both expressions but want to weight “project” more heavily than “management”:

project^4 management

You boost whole phrases the same way:

"project management"^4 "AQL"

The default factor is 1. The factor must be positive — but it can be less than 1 (e.g. 0.3).

Boolean operators

With Boolean operators, you combine terms. AQL supports AND, +, OR, NOT, and -. Always write Boolean operators entirely in uppercase.

OR operator

OR is the default operator — implied when there is no operator between terms. Allegra then returns items that contain at least one of the terms. Alternatively, you write ||.

Example — items that contain “project management” or “project”, but not just “management”:

"project management" project

or

"project management" OR project

AND operator

AND requires both terms to appear somewhere in the item. Alternatively, you write &&.

Example — items with “project management” and “AQL new”:

"project management" AND "AQL new"

Plus operator

The + or “required” operator requires that the term following the + symbol appears in the item.

Example — items with “project”, optionally also “AQL”:

+project AQL

NOT operator

NOT excludes items that contain the term. Alternatively, you write !.

Example — items with “project management” but without “AQL new”:

"project management" NOT "AQL new"

Attention

NOT does not work with only a single term. This query returns no result: NOT "project management"

Minus operator

The - or exclusion operator excludes items that contain the term following the - symbol.

Example — items with “project management” but without “issue tracking”:

"project management" -"issue tracking"