Searching in Crowd

The Crowd Query Language (CQL) allows developers using the Crowd REST API to perform user and group searches in a more intuitive and simpler form.

The Crowd REST API since version 2.1 has allowed applications to POST to the Search resource with the search restriction in XML or JSON. The XML and JSON form is similar to the Java search restriction classes that Crowd uses.

From Crowd 2.2 onwards, there is a much simpler way to perform user and group searches. You can now perform a GET request to the search resource with the restrictions expressed in CQL as a query parameter.

where ENTITY_TYPE is: user or group and RESTRICTION is the URL encoded search restriction expressed in CQL.

Operators Reference

EQUALS: =

The "=" operator is used to search for exact and partial matches of the specified value.

To find entities where the value of a specified field exactly matches multiple values, use multiple "=" statements with the #AND operator. Partial matches are performed with the wildcard, "*", symbol. The only currently supported partial matches are:

starts-with ("term*") and

contains ("*term*")

Icon

The only currently supported partial matches are: "starts-with" and "contains". For instance, these restrictions are illegal: "email=*@example.net", "firstName=Ro*ert"

Examples

Find all active users:

Find all users with a display name of John Smith:

Find all users with a first name starting with Jo:

Find all users with an email containing atlassian:

GREATER THAN: >

The ">" operator is used to search for entities where the value of the specified field is greater than the specified value. Cannot be used with #string fields.

Note that the ">" operator can only be used with fields which support ordering (e.g. date fields). To see a field's supported operators, check the individual #field reference.

Examples

Find all groups created after 1 January 2010:

LESS THAN: <

The "<" operator is used to search for entities where the value of the specified field is less than the specified value. Cannot be used with #string fields.

Note that the "<" operator can only be used with fields which support ordering (e.g. date fields). To see a field's supported operators, check the individual #field reference.

Supported Operators

Examples

Active

Search for users with the specified active field value. The only valid values for active are: true, false.

Syntax

Field Type

Boolean

Supported Operators

=

= with wildcard (*)

>

<

Examples

Find all active users:

Find all inactive users:

Created Date

Search for users created on, before or after a particular date.

The date is specified in ISO-8601 format: YYYY-MM-DDTHH-MM-SS-ZZ±hhmm

The final "±hhmm" is the UTC offset.

Valid examples include:

2010-12-08T16:11:21.181+1100

2010-12-08T16:11:21.181

2010-12-08T16:11:21

2010-12-08T16:11

2010-12-08T16

2010-12-08

2010-12

2010

As seen in the example above, the date element can be omitted from the smallest date element up to (but not including) the year element. It is important to note that though the smaller date elements can be omitted, each of the above examples represent a date instance. So a date of "2010" represents "2010-01-01T00:00:00.000+0000".

Syntax

Field Type

ISO-8601 Date

Supported Operators

=

= with wildcard (*)

>

<

Examples

Find all users created exactly at 5:23pm on 15 December 2010:

Find all users created before 2010:

Find all users created after 15 December 2010 midnight:

Updated Date

Search for users updated on, before or after a particular date.

The date is specified in ISO-8601 format: YYYY-MM-DDTHH-MM-SS-ZZ±hhmm

The final "±hhmm" is the UTC offset.

Valid examples include:

2010-12-08T16:11:21.181+1100

2010-12-08T16:11:21.181

2010-12-08T16:11:21

2010-12-08T16:11

2010-12-08T16

2010-12-08

2010-12

2010

As seen in the example above, the date element can be omitted from the smallest date element up to (but not including) the year element. It is important to note that though the smaller date elements can be omitted, each of the above examples represent a date instance. So a date of "2010" represents "2010-01-01T00:00:00.000+0000".

Field Type

Supported Operators

Examples

Active

Search for groups with the specified active field value. The only valid values for active are: true, false.

Syntax

Field Type

Boolean

Supported Operators

=

= with wildcard (*)

>

<

Examples

Find all active groups:

Find all inactive groups:

Created Date

Search for groups created on, before or after a particular date.

The date is specified in ISO-8601 format: YYYY-MM-DDTHH-MM-SS-ZZ±hhmm

The final "±hhmm" is the UTC offset.

Valid examples include:

2010-12-08T16:11:21.181+1100

2010-12-08T16:11:21.181

2010-12-08T16:11:21

2010-12-08T16:11

2010-12-08T16

2010-12-08

2010-12

2010

As seen in the example above, the date element can be omitted from the smallest date element up to (but not including) the year element. It is important to note that though the smaller date elements can be omitted, each of the above examples represent a date instance. So a date of "2010" represents "2010-01-01T00:00:00.000+0000".

Syntax

Field Type

ISO-8601 Date

Supported Operators

=

= with wildcard (*)

>

<

Examples

Find all groups created exactly at 5:23pm on 15 December 2010:

Find all groups created before 2010:

Find all groups created after 15 December 2010 midnight:

Updated Date

Search for groups updated on, before or after a particular date.

The date is specified in ISO-8601 format: YYYY-MM-DDTHH-MM-SS-ZZ±hhmm

The final "±hhmm" is the UTC offset.

Valid examples include:

2010-12-08T16:11:21.181+1100

2010-12-08T16:11:21.181

2010-12-08T16:11:21

2010-12-08T16:11

2010-12-08T16

2010-12-08

2010-12

2010

As seen in the example above, the date element can be omitted from the smallest date element up to (but not including) the year element. It is important to note that though the smaller date elements can be omitted, each of the above examples represent a date instance. So a date of "2010" represents "2010-01-01T00:00:00.000+0000".

Syntax

Field Type

ISO-8601 Date

Supported Operators

=

= with wildcard (*)

>

<

Examples

Find all groups updated exactly at 5:23pm on 15 December 2010:

Find all groups updated before 2010:

Find all groups updated after 15 December 2010 midnight:

Setting Precedence of Operators

You can use parentheses in complex CQL statements to enforce the precedence of #operators.

For example, if you want to find all users with a username of "bob", updated after January 2011, with either an email starting with "bob@ex" or the user was created before 1 January 2010, you can use parentheses to enforce the precedence of the boolean operators in your query, i.e.:

Note that if you do not use parentheses, the operators have the following precedence starting from least to most:

OR

AND

=, <, >

Reserved Characters

CQL has a list of reserved characters:

space (" ")

"+"

"."

","

";"

"?"

"|"

"*"

"/"

"%"

"^"

"$"

"#"

"@"

"["

"]"

"<"

">"

If you wish to use these characters in queries, you need to surround them with quote-marks (you can use either single quote-marks (') or double quote-marks (")).

For example:

While some of these characters are not being used at the moment, it is highly recommended that none of the characters in the above list are used as they may be used in future releases of Crowd.

Reserved Words

CQL has a list of reserved words. These words need to be surrounded by quote-marks if you wish to use them in queries:

"and", "or", "<", ">"

Icon

You can use either single quote-marks (') or double quote-marks (").

While some of these words are not being used at the moment, it is highly recommended that none of the words in the above list are used unquoted, as they may be used in future releases of Crowd.