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 allows 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: ``` xml email STRING

EXACTLY_MATCHES

bob@example.net ``` 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. ``` bash 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: ``` bash email=bob@example.net ``` i.e. ``` bash 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](#setting-precedence-of-operators) 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: ``` sql firstName = "bob" and email = "bob@example.net" ``` - Find all inactive groups with a name starting with "admin": ``` sql 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](#setting-precedence-of-operators) to control the order in which statements are executed. ###### Examples - Find all users with either a last name of Smith or Jones: ``` sql lastName = Smith or lastName = Jones ``` - Find all users created after December 2010 or a first name starting with Jo: ``` sql 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](#and) operator. Partial matches are performed with the wildcard, "\*", symbol. The only currently supported partial matches are: - starts-with ("term\*") and - contains ("\*term\*")

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: ``` sql active = true ``` - Find all users with a display name of John Smith: ``` sql displayName = "John Smith" ``` - Find all users with a first name starting with Jo: ``` sql firstName = "Jo*" ``` - Find all users with an email containing atlassian: ``` sql 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](#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](#fields-reference) reference. ###### Examples - Find all groups created after 1 January 2010: ``` sql 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](#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](#fields-reference) reference. ###### Examples - Find all groups created before the year 2011: ``` sql updatedDate < 2011 ``` ### Fields Reference - [User Fields](#user-fields) - [Email](#email) - [Group Fields](#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](#partial-matching). ###### Syntax ``` javascript name ``` ###### Field Type String ###### Supported Operators

=	= with wildcard (*)	>	<
yes	yes	no	no

###### Examples - Find the user with username ernie: ``` javascript name = "ernie" ``` - Find all users with a username starting with ern: ``` javascript name = "ern*" ``` - Find all users with a username containing rni: ``` javascript name = *rni* ``` #### Email Search for users with the specified email. Note: this field supports [partial-matching](#partial-matching). ###### Syntax ``` javascript email ``` ###### Field Type String ###### Supported Operators

=	= with wildcard (*)	>	<
yes	yes	no	no

###### Examples - Find all users with an email of bob@example.net: ``` javascript email = "bob@example.net" ``` - Find all users with an email starting with bob: ``` javascript email = "bob*" ``` - Find all users with an email containing example: ``` javascript email = *example* ``` ##### First Name Search for users with the specified first name. Note: this field supports [partial-matching](#partial-matching). ###### Syntax ``` javascript firstName ``` ###### Field Type String ###### Supported Operators

=	= with wildcard (*)	>	<
yes	yes	no	no

###### Examples - Find all users with a first name of Shrek: ``` javascript firstName = "Shrek" ``` - Find all users with a first name starting with Sh: ``` javascript firstName = "Sh*" ``` - Find all users with a first name containing hr: ``` javascript firstName = *hr* ``` ##### Last Name Search for users with the specified last name. Note: this field supports [partial-matching](#partial-matching). ###### Syntax ``` javascript lastName ``` ###### Field Type String ###### Supported Operators

=	= with wildcard (*)	>	<
yes	yes	no	no

###### Examples - Find all users with a last name of Smith: ``` javascript lastName = "Smith" ``` - Find all users with a last name starting with Smi: ``` javascript lastName = "Smi*" ``` - Find all users with a last name containing mit: ``` javascript lastName = *mit* ``` ##### Display Name Search for users with the specified display name. Note: this field supports [partial-matching](#partial-matching). ###### Syntax ``` javascript displayName ``` ###### Field Type String ###### Supported Operators

=	= with wildcard (*)	>	<
yes	yes	no	no

###### Examples - Find all users with a display name of John Smith: ``` javascript displayName = "John Smith" ``` - Find all users with a display name starting with John: ``` javascript displayName = "John*" ``` - Find all users with a display name containing Smi: ``` javascript displayName = *Smi* ``` ##### Active Search for users with the specified active field value. The only valid values for active are: true, false. ###### Syntax ``` javascript active ``` ###### Field Type Boolean ###### Supported Operators

=	= with wildcard (*)	>	<
yes	no	no	no

###### Examples - Find all active users: ``` javascript active = true ``` - Find all inactive users: ``` javascript 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 ``` javascript createdDate ``` ###### Field Type ISO-8601 Date ###### Supported Operators

=	= with wildcard (*)	>	<
yes	no	yes	yes

###### Examples - Find all users created exactly at 5:23pm on 15 December 2010: ``` javascript createdDate = 2010-12-15T17:23 ``` - Find all users created before 2010: ``` javascript createdDate < 2010 ``` - Find all users created after 15 December 2010 midnight: ``` javascript 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 ``` javascript updatedDate ``` ###### Field Type ISO-8601 Date ###### Supported Operators

=	= with wildcard (*)	>	<
yes	no	yes	yes

###### Examples - Find all users updated exactly at 5:23pm on 15 December 2010: ``` javascript updatedDate = 2010-12-15T17:23 ``` - Find all users updated before 2010: ``` javascript updatedDate < 2010 ``` - Find all users updated after 15 December 2010 midnight: ``` javascript 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](#partial-matching). ###### Syntax ``` javascript name ``` ###### Field Type String ###### Supported Operators

=	= with wildcard (*)	>	<
yes	yes	no	no

###### Examples - Find the group with the name administrators: ``` javascript name = "administrators" ``` - Find all groups with a name starting with admin: ``` javascript name = "admin*" ``` - Find all groups with a name containing nistra: ``` javascript name = *nistra* ``` ##### Active Search for groups with the specified active field value. The only valid values for active are: true, false. ###### Syntax ``` javascript active ``` ###### Field Type Boolean ###### Supported Operators

=	= with wildcard (*)	>	<
yes	no	no	no

###### Examples - Find all active groups: ``` javascript active = true ``` - Find all inactive groups: ``` javascript 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 ``` javascript createdDate ``` ###### Field Type ISO-8601 Date ###### Supported Operators

=	= with wildcard (*)	>	<
yes	no	yes	yes

###### Examples - Find all groups created exactly at 5:23pm on 15 December 2010: ``` javascript createdDate = 2010-12-15T17:23 ``` - Find all groups created before 2010: ``` javascript createdDate < 2010 ``` - Find all groups created after 15 December 2010 midnight: ``` javascript 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 ``` javascript updatedDate ``` ###### Field Type ISO-8601 Date ###### Supported Operators

=	= with wildcard (*)	>	<
yes	no	yes	yes

###### Examples - Find all groups updated exactly at 5:23pm on 15 December 2010: ``` javascript updatedDate = 2010-12-15T17:23 ``` - Find all groups updated before 2010: ``` javascript updatedDate < 2010 ``` - Find all groups updated after 15 December 2010 midnight: ``` javascript updatedDate > 2010-12-15 ``` ### Setting Precedence of Operators You can use parentheses in complex CQL statements to enforce the precedence of [\#operators](#property-names-reference). 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.: ``` javascript 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: ``` javascript 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", "<", ">"

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.