Crowd Query Language

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:

1
2
<?xml version="1.0" encoding="UTF-8"?>
<property-search-restriction>
  <property>
    <name>email</name>
    <type>STRING</type>
  </property>
  <match-mode>EXACTLY_MATCHES</match-mode>
  <value>bob@example.net</value>
</property-search-restriction>

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.

1
2
GET http://myhost.com:8095/rest/usermanagement/1/search?entity-type=ENTITY_TYPE&restriction=RESTRICTION

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

The above XML content now becomes:

1
2
email=bob@example.net

i.e.

1
2
GET http://myhost.com:8095/rest/usermanagement/1/search?entity-type=user&restriction=email%3Dbob%40example.net

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:

  1
  2
  firstName = "bob" and email = "bob@example.net"
  

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

  1
  2
  name = "admin*" and active = false
  

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:

  1
  2
  lastName = Smith or lastName = Jones
  

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

  1
  2
  createdDate > 2010-12 or firstName = Jo*
  

Property Names Reference

Crowd distinguishes between entity primary properties and entity secondary properties. The set of primary properties for each entity type is listed below with their type:

• User primary properties: name (String), email (String), firstName (String), lastName (String), displayName (String), active (Boolean), externalId (String), createdDate (Date), updatedDate (Date).
• Group primary properties: name (String), description (String), active (Boolean), local (Boolean), createdDate (Date), updatedDate (Date).

Custom attributes are secondary properties of type String and can be referred by their attribute key.

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

###### Examples

• Find all active users:

  1
  2
  active = true
  

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

  1
  2
  displayName = "John Smith"
  

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

  1
  2
  firstName = "Jo*"
  

• Find all users with an email containing atlassian:

  1
  2
  email = "*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:

  1
  2
  createdDate > 2010-01-01
  

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:

  1
  2
  updatedDate < 2011
  

Fields Reference

• User Fields
  • Email
  • Group Fields

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

1
2
name

Field Type

String

Supported Operators

Examples

• Find the user with username ernie:

  1
  2
  name = "ernie"
  

• Find all users with a username starting with ern:

  1
  2
  name = "ern*"
  

• Find all users with a username containing rni:

  1
  2
  name = *rni*
  

Email

Search for users with the specified email.

Note: this field supports partial-matching.

Syntax

1
2
email

Field Type

String

Supported Operators

Examples

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

  1
  2
  email = "bob@example.net"
  

• Find all users with an email starting with bob:

  1
  2
  email = "bob*"
  

• Find all users with an email containing example:

  1
  2
  email = *example*
  

First Name

Search for users with the specified first name.

Note: this field supports partial-matching.

Syntax

1
2
firstName

Field Type

String

Supported Operators

Examples

• Find all users with a first name of Shrek:

  1
  2
  firstName = "Shrek"
  

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

  1
  2
  firstName = "Sh*"
  

• Find all users with a first name containing hr:

  1
  2
  firstName = *hr*
  

Last Name

Search for users with the specified last name.

Note: this field supports partial-matching.

Syntax

1
2
lastName

Field Type

String

Supported Operators

Examples

• Find all users with a last name of Smith:

  1
  2
  lastName = "Smith"
  

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

  1
  2
  lastName = "Smi*"
  

• Find all users with a last name containing mit:

  1
  2
  lastName = *mit*
  

Display Name

Search for users with the specified display name.

Note: this field supports partial-matching.

Syntax

1
2
displayName

Field Type

String

Supported Operators

Examples

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

  1
  2
  displayName = "John Smith"
  

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

  1
  2
  displayName = "John*"
  

• Find all users with a display name containing Smi:

  1
  2
  displayName = *Smi*
  

Active

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

Syntax

1
2
active

Field Type

Boolean

Supported Operators

Examples

• Find all active users:

  1
  2
  active = true
  

• Find all inactive users:

  1
  2
  active = false
  

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

1
2
createdDate

Field Type

ISO-8601 Date

Supported Operators

Examples

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

  1
  2
  createdDate = 2010-12-15T17:23
  

• Find all users created before 2010:

  1
  2
  createdDate < 2010
  

• Find all users created after 15 December 2010 midnight:

  1
  2
  createdDate > 2010-12-15
  

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

1
2
updatedDate

Field Type

ISO-8601 Date

Supported Operators

Examples

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

  1
  2
  updatedDate = 2010-12-15T17:23
  

• Find all users updated before 2010:

  1
  2
  updatedDate < 2010
  

• Find all users updated after 15 December 2010 midnight:

  1
  2
  updatedDate > 2010-12-15
  

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

1
2
name

Field Type

String

Supported Operators

Examples

• Find the group with the name administrators:

  1
  2
  name = "administrators"
  

• Find all groups with a name starting with admin:

  1
  2
  name = "admin*"
  

• Find all groups with a name containing nistra:

  1
  2
  name = *nistra*
  

Active

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

Syntax

1
2
active

Field Type

Boolean

Supported Operators

Examples

• Find all active groups:

  1
  2
  active = true
  

• Find all inactive groups:

  1
  2
  active = false
  

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

1
2
createdDate

Field Type

ISO-8601 Date

Supported Operators

Examples

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

  1
  2
  createdDate = 2010-12-15T17:23
  

• Find all groups created before 2010:

  1
  2
  createdDate < 2010
  

• Find all groups created after 15 December 2010 midnight:

  1
  2
  createdDate > 2010-12-15
  

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

1
2
updatedDate

Field Type

ISO-8601 Date

Supported Operators

Examples

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

  1
  2
  updatedDate = 2010-12-15T17:23
  

• Find all groups updated before 2010:

  1
  2
  updatedDate < 2010
  

• Find all groups updated after 15 December 2010 midnight:

  1
  2
  updatedDate > 2010-12-15
  

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

1
2
name="bob" AND (email = "bob@ex*" OR createdDate < 2010) AND updatedDate > 2011-01

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

For example:

1
2
firstName = "John Smith"

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

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.