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. Searches are case insensitive, but you can use the .exact keyword to make a case-sensitive search.

In most queries, your search will look like this:

field:term

Do not 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 or they 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, select 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 on the Identities page.	`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 Microsoft Entra ID.	`@apps(source.name:"Microsoft Entra ID")`
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 @<nestedObject> is the nested object in each nested query.
The <object.field:term> is the rest of the fields in your query.
The <operator> 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 on the Identities page, 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 your searches. 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`

Wildcards can only be used with text fields; they do not apply to other data types, like numeric fields or dates. They are particularly useful in exact searches.

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 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 Relative Date Comparisons

You can search for dates relative to today using the same range brackets available in range queries. Review Elasticsearch's Date Math documentation for more information about supported time units.

Description of Results	Query
Objects created within the last month	`created:[now-1M TO now]`
Identities with an endDate attribute set to within the next year	`attributes.endDate:[now+1y TO now]`

Using the `.exact` Keyword

You can add .exact to your first- and second-level field searches for results that match the exact string. You can also use the wildcards * and ?.

Use the .exact keyword if your search requires case sensitivity or includes characters that aren't letters or numbers. Regular expressions with capital letters will fail unless they have the .exact keyword.

Note

Adding .exact is not required to search on an email.

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

name
displayName
lastName
firstName
description
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 the `_exists_` Keyword

You can use the _exists_ keyword to search for items that have any non-null value in the specified field.

To use an _exists_ query, enter the name of a field after the keyword.

Description of Results	Query
Returns any identities that have an end date listed.	`_exists_:attributes.endDate`
Returns any identities that either don't have a name listed for their manager or that have a null value in their manager name field.	`NOT _exists_:manager.name`

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.