Skip to end of metadata
Go to start of metadata

Available:

Crowd 2.2 and later.

 

On this page:

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.

In order to search for all users with an email of bob@example.net, you would previously POST to http://myhost.com:8095/rest/usermanagement/1/search?entity-type=user, with the following XML content:

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.

The above XML content now becomes:

i.e.


Keywords Reference

AND

Used to combine multiple restrictions, allowing you to refine your search. The AND statement is satisfied if all of the conditions are true.

Note that you can use #parentheses to control the order in which statements are executed.

Examples
  • Find all users with a first name of bob and an email of bob@example.net:

  • Find all inactive groups with a name starting with "admin":

OR

Used to combine multiple restrictions, allowing you to expand your search. The OR statement is satisfied if any of the conditions are true.

Note that you can use #parentheses to control the order in which statements are executed.

Examples
  • Find all users with either a last name of Smith or Jones:

  • Find all users created after December 2010 or a first name starting with Jo:


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.

Examples
  • Find all groups created before the year 2011:


Fields Reference

User Fields

The following fields may be used in user queries.


Name

Search for users with the specified user name.

Note: this field supports partial-matching.

Syntax
Field Type

String

Supported Operators

=

= with wildcard (*)

>

<

(tick)

(tick)

(error)

(error)

Examples
  • Find the user with username ernie:

  • Find all users with a username starting with ern:

  • Find all users with a username containing rni:


Email

Search for users with the specified email.

Note: this field supports partial-matching.

Syntax
Field Type

String

Supported Operators

=

= with wildcard (*)

>

<

(tick)

(tick)

(error)

(error)

Examples
  • Find all users with an email of bob@example.net:

  • Find all users with an email starting with bob:

  • Find all users with an email containing example:


First Name

Search for users with the specified first name.

Note: this field supports partial-matching.

Syntax
Field Type

String

Supported Operators

=

= with wildcard (*)

>

<

(tick)

(tick)

(error)

(error)

Examples
  • Find all users with a first name of Shrek:

  • Find all users with a first name starting with Sh:

  • Find all users with a first name containing hr:


Last Name

Search for users with the specified last name.

Note: this field supports partial-matching.

Syntax
Field Type

String

Supported Operators

=

= with wildcard (*)

>

<

(tick)

(tick)

(error)

(error)

Examples
  • Find all users with a last name of Smith:

  • Find all users with a last name starting with Smi:

  • Find all users with a last name containing mit:


Display Name

Search for users with the specified display name.

Note: this field supports partial-matching.

Syntax
Field Type

String

Supported Operators

=

= with wildcard (*)

>

<

(tick)

(tick)

(error)

(error)

Examples
  • Find all users with a display name of John Smith:

  • Find all users with a display name starting with John:

  • Find all users with a display name containing Smi:


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 (*)

>

<

(tick)

(error)

(error)

(error)

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 (*)

>

<

(tick)

(error)

(tick)

(tick)

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".

Syntax
Field Type

ISO-8601 Date

Supported Operators

=

= with wildcard (*)

>

<

(tick)

(error)

(tick)

(tick)

Examples
  • Find all users updated exactly at 5:23pm on 15 December 2010:

  • Find all users updated before 2010:

  • Find all users updated after 15 December 2010 midnight:

Group Fields

The following fields may be used in group queries.


Name

Search for groups with the specified name.

Note: this field supports partial-matching.

Syntax
Field Type

String

Supported Operators

=

= with wildcard (*)

>

<

(tick)

(tick)

(error)

(error)

Examples
  • Find the group with the name administrators:

  • Find all groups with a name starting with admin:

  • Find all groups with a name containing nistra:


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 (*)

>

<

(tick)

(error)

(error)

(error)

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 (*)

>

<

(tick)

(error)

(tick)

(tick)

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 (*)

>

<

(tick)

(error)

(tick)

(tick)

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:

  1. OR
  2. AND
  3. =, <, >

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 (")); and
  • precede them with two backslashes (unless it is the space character).

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.

  • No labels

1 Comment

  1. Anonymous

    How to search by email? if email contains "+" character