Skip to content

Building a Search Query

Once you're familiar with the fields that are available for you to search on, you can start constructing queries. You can use those fields and choose search terms to find important information about your data.

In a search, a field is where you search, and a term is what you search for.

In most queries, your search will look like this:

field:term

Make sure not to put spaces in the field portion of your query, or after the colon following the field. If you have spaces in your term, put them in double quotes. All spaces that aren't in double quotes will be treated as an OR operator.

Search Terms

Terms are simply words you use in a query.

Some terms can be searched on with no other words in the query.

Single-word terms can be searched alone or with double quote marks surrounding them. If you search using quote marks, the search results will contain all words in your query.

Description of Results Query
All results with any attribute that contains the word london are returned. london
All results with any attribute that contains the word sydney are returned. sydney
All results with any attribute that contains the phrase sao paulo are returned. "sao paulo"

A query without a field, like the ones above, searches within all search categories. For example, searching on "london" returns all identities in London - but also all identities who are named London, or who have any entitlements based in London, or any roles with London in their names.

If you want to specify which search categories to return, click the Filter icon next to the Search bar.

Quotation Marks

You can use quote marks to help you make your query more specific.

Single quotes are treated as an ordinary character. If there's more than one word in single quotes, the search engine ignores the single quotes and treats the terms as if they had an OR operator between them.

Double quotes should be placed around words that must be searched together as a phrase.

Description of Results Query
All results that contain the words sao or paulo are returned. sao paulo
All results that contain the words sao or paulo are returned. 'sao paulo'
All results that contain the phrase "sao paulo" are returned. "sao paulo"
All identities that have the phrase Sao Paulo listed as their location are returned. attributes.location:"sao paulo"

To specify which data about the search category to return, use fields.

First-Level Fields

First-level field searches are constructed using this format:

field:term

A list of the fields that can be searched is available in Searchable Fields. These fields are based on the IdentityNow data model for each searchable item.

Description of Results Query
Returns identities with john.smith as their IdentityNow display names. displayName:john.smith
Returns all identities that were created on June 1, 2018. created:2018-06-01
Returns all identities that are listed as Active in the identity list. status:ACTIVE

Second-Level Fields

Second-level field searches from any search category are constructed using the following format:

secondLevelField.firstLevelField:term

All objects and fields are based on the IdentityNow data model. Second-level fields are present in identity data, event data, and account activity data.

Description of Results Query
Returns all identities that have the word london in the location attribute on their identity profile. attributes.location:london
Returns all identities that have Amanda Ross as their manager. manager.name:amanda.ross
Returns a list of identities that are in an identity profile called ID_Profile_1. identityProfile.name:ID_Profile_1
Returns a list of account activity that was initiated by the user bob.dobbs. requester.name:bob.dobbs

Using Nested Queries

You'll need to use a nested query to search for data when it's possible for a searchable category to have more than one of the item. Nested queries give IdentityNow more information so that it can search those fields correctly.

Nested queries follow a distinct format:

@<nestedObject>(<object.field:term>)

<nestedObject> is where you specify the type of nested object to search in.

<object.field:term> is where you'll enter the rest of your query.

Nested-level fields are present in identity data, access profile data, and account activity data.

If your search term is multiple words in a nested query, you should surround it with double quote marks. Results will exactly match the text in your query.

The table below includes some examples of complete nested queries that search for only one term.

Description of Results Query
Searches within each identity's accounts for the source name, Acme. @accounts(source.name:Acme)
Searches within each identity's access for items marked as privileged. @access(privileged:TRUE)
Searches within each identity's apps for apps that have an account source identical to Azure AD. @apps(source.name:"Azure AD")
Returns all account activity with one or more create action performed on a source. @accountRequests(op:create)
Returns all account activity that contained one or more actions that failed to complete successfully. @accountRequests(result.status:failed)

Combining Multiple Search Criteria with Operators

You can include more than one criteria in your query to narrow down results.

Combine queries using operators. All operators must always be in all capital letters. If you don't specify an operator between two queries, the OR operator will be used.

When you're combining multiple search criteria, make sure you're using fields from the same search category. For example, searching for a field from identity data and a field from account activity data in the same query won't return any results.

OR

The OR operator, which can be symbolized by two vertical bars ||, links two terms and finds a match if either term exists anywhere in the item.

Description of Results Query
Search for identities that have the text "sao paulo" or "london" anywhere in their identity data. "sao paulo" OR london
Search for identities that list Sao Paulo or London as their location. attributes.location:"sao paulo" OR attributes.location:london
Search for identities in Sao Paulo or London using the symbols for the OR operator. attributes.location:"sao paulo" || attributes.location:london

AND

The AND operator, which can be symbolized by two ampersands &&, returns items which have both of your search terms in the identity data.

Description of Results Query
Search for results that have the text london and amanda.ross anywhere in their data. london AND amanda.ross
Search for identities that have their location listed as London, whose manager is Amanda Ross. attributes.location:london AND manager.name:amanda.ross
Using symbols in place of the AND operator, search for identities in London whose manager is Amanda Ross. attributes.location:london && manager.name:amanda.ross

NOT

The NOT operator, which can be symbolized with an exclamation point !, excludes search items that contain the term you enter after NOT in the fields you specify.

Description of Results Query
Search for data that contains the text amanda.ross that don't contain the text "london". amanda.ross NOT london
Specify fields to search for identities whose manager is amanda.ross who aren't located in London. manager.name:amanda.ross NOT attributes.location:london
Use symbols in place of the NOT operator to find identities with amanda.ross as their manager, who aren't located in London. manager.name:amanda.ross ! attributes.location:london
Search for identities who don't have amanda.ross listed as their manager. Note that because the ! operator is at the beginning of the query string, it must always be followed immediately by the query, with no space. !manager.name:amanda.ross

Combining Multiple Operators

You can determine how your query is evaluated using parentheses. Anything in parentheses will be evaluated as a single query within your original query.

Description of Results Query
Search for identities that have amanda.ross listed as their manager, are in London, and have the last name of either Trent or Primrose. attributes.location:london AND manager.name:amanda.ross AND (lastName:trent OR lastName:primrose)
This query returns the same results as the one above. The parentheses are slightly different. attributes.location:london AND manager.name:amanda.ross AND lastName:(trent OR primrose)

Combining Nested Queries with Other Queries

A nested query combined with another nested query is written like this:

@<nestedObject>(<object.field:term>) <operator> @<nestedObject>(<object.field:term>)

  • The is the nested object in each nested query.
  • The is the rest of the fields in your query.
  • The is AND, OR, or NOT, or their symbols.

A nested query combined with a simple query is written like this:

@<nestedObject>(<object.field:term>) <operator> <simple_query>

Description of Results Query
This query returns a list of all identities that have amanda.ross listed as their manager and who have the access item that has the display name Engineering_Access. @access(displayName:"Engineering_Access") AND manager.name:"amanda.ross"
This query returns a list of all identities who are listed as Not Invited in the identity list, who have an access item called Base Access. status:"UNREGISTERED" AND @access(displayName:"Base Access")
This query returns all identities who have an account on the Acme source, but don't have the Adobe app. @accounts(source.name:Acme) AND NOT @apps(name:Adobe)
This query returns all identities with disabled accounts who have an entitlement with the title Building_Access. @accounts(disabled:TRUE) && @access(name:Building_Access)

Additional Search Use Cases

Wildcards

You can also include wildcards in any search you make. The * wildcard represents any number of characters, while the ? wildcard always represents only a single character.

Description of Results Query
Returns all search data in your site. *
Return all data named Jon, John, Johnson, and Jan. name:j*n
Return data named Jon and Jan only. name:j?n

Greater Than and Less Than

The greater than and less than operators (> and <) can be used to search for dates and numbers that are greater or less than the value you state. You can also use these operators with an equal sign (=> and <=) to symbolize greater than or equal to, or less than or equal to. Be sure not to add a space between the colon and your range operator.

Description of Results Query
All identities that have more than 12 apps appCount:>12
All identities created on or before February 4, 2015 created:<=2015-02-04

Using the .exact Keyword

You can add .exact to your first- and second-level field searches for results that match the exact string including case sensitivity. You can also use the wildcards * and ?. Adding .exact is not required to search on an email.

Use the .exact keyword to search on data that includes any characters that aren’t letters or numbers.

On identities, the .exact keyword is available for use with the following fields and field types:

  • name
  • displayName
  • lastName
  • firstName
  • description
  • All identity extended attributes
  • Other free text fields

The table below includes some examples of queries that use the .exact keyword.

Description of Results Query
Returns only identities who have a manager named "amanda ross" in lowercase. manager.name.exact:"amanda ross"
Returns only identities who have the last name "Ross" with a capital R. lastName.exact:Ross
Returns only identities whose locations start with "Aus", such as Austin or Australia. attributes.location.exact:Aus*
Returns only identities that have an account source called "ad", not Azure AD or Active Directory. @accounts(source.name.exact:"ad")
Return identities with the name jon-smith. name.exact:"jon-smith"
Search for roles with the name TaxProject#2019. name.exact:"TaxProject#2019"

Using Range Queries

You can search for a range of numerical values in IdentityNow by using brackets.

To search between two values and include those values in your results, use square brackets []. To search between values and exclude those values from your results, use curly brackets {}.

Description of Results Query
Search for identities that have 1, 2, 3, or 4 accounts. accountCount:[1 TO 4]
Search for identities that have exactly 2 or 3 accounts. accountCount:{1 TO 4}
Return all identities who have accounts created during March of 2018. @accounts(created:[2018-03-01 TO 2018-03-31])

Using Special Characters

Many search queries, such as queries to find an identity's distinguished name, use special characters. These characters include =, +, -, and others.

If you're searching for data in a string-type field, and you need to include a special character, there are some additional query requirements.

  • They must use the .exact keyword.
  • They must use a regular expression format, which requires wrapping them in forward slashes: /
  • If your query uses wildcards, those wildcards must use a different format.
  • Any * wildcards must be preceded by a period: .*
  • Any ? wildcards must be replaced by a period: .

If these requirements aren't followed, the special characters are not counted in the search query.

Note that dates, phone numbers, and emails do not need to follow these requirements because of the data expected.

The table below includes some examples of queries using special characters.

Description of Results Query
Returns all identities with hyphens in their last name. attributes.lastName.exact:/.*-.*/
Returns all items with "AUSTIN_<any single character>_GI" and "File Access" as organizational units, including distinguished names with other OU's before or after this pair. name.exact:/.*OU=AUSTIN_._GI.*OU=File Access*/