Each of your queries must include a target search value; search values define exactly what it is you are looking for. For example, suppose you have this search query:

displayName = "Bob Jones"

In this case, Bob Jones is the target search value: you only want to return information for users who have the display name Bob Jones. To search for users with the display name Marie Fuentes, use this command instead:

displayName = "Maria Fuentes"

And so on.

Search for string or numeric values

For the most part, there’s not much you need to know when searching for string or numeric values: all you have to do is specify the value you want to search for. For example, here’s how you can format a search for a specific email address:

email = "bob.jones@janrain.com"

And here’s how you can search for a given UUID:

uuid = "9596f146-3221-43e4-ba09-a50167992109"

That said, there are two special instances to keep in mind when searching for string values:

• Values that include a blank space
• Values that include special characters

Values that include a blank space

This restriction is easy to explain: if a search value includes a blank space that value must be enclosed in double quotes. Period. For example, to search for a user who has the display name Bob either of these constructions will work:

displayName = Bob
displayName = "Bob"

That’s because, without a blank space in the search value, double quotes are optional.

However, to search for a user named Bob Jones, only this syntax works:

displayName = "Bob Jones"

The moral of the story? To search for Bob Jones (or for any other string value that includes a blank space) you must surround the value with double quotes (“Bob Jones”). That’s an absolute must.

And before you ask, yes, the following syntax appears to work (at the very least, it doesn’t return an error):

displayName = Bob Jones

However, while the preceding syntax doesn’t return an error, it does fail to return the expected data. That’s because the Console uses blank spaces to separate individual target values. As far as the Console is concerned, the preceding query is equivalent to this:

displayName = Bob OR displayName = Jones OR email = Jones

In other words, the Console is searching for a user named Bob or for a user named Jones or for someone with the email address Jones. What it isn’t searching for is a user named Bob Jones.

📘

Why the “email = Jones” clause? Because, to the Console, you didn’t specify an attribute to search on; you only specified a value to search for (Jones). As a result, the Console searches your default search fields (typically displayName and email).

To avoid this problem, put double quotes around the entire search value. Any time you enclose a search value in double quotes that value is treated as a single string. With the following syntax, the Console does search for Bob Jones and not for user Bob or user Jones:

displayName = "Bob Jones"

📘

In this documentation, you’ll often see double quotes even when they aren’t required; for example:

givenName = "Bob"

Although there’s no technical reason for using double quotes, the quote marks can make a query more readable: it’s easier to pick out search values if they’re enclosed in double quotes. However, unless your search value contains a blank space, the double quotes are optional. It’s up to you.

Values that include special characters

Admittedly, this might never come up in any of your Console searches. However, the following characters can complicate your queries (although, as you’ll see, there’s a simple workaround for those complications):

! ( ) { } [ ] " ? * : \/

The preceding characters are referred to as “special characters,” which means that they must be given special treatment when used in search queries. In the case of the Console, special characters must be “escaped” whenever they are referenced in a search value, a process that simply means prefacing the character with a \ (also known as the backslash). For example, suppose you want to search for the Windows path C:\Windows\System32. If so, then each backslash in the path must be prefaced by another backslash. In other words, you must escape each \ with a second :

C:\\Windows\\System32

Yahoo\!

Likewise, to search for the company Yahoo! you must use this syntax, escaping the exclamation point:

Escaping is required any time you reference a search value without using double quotes: if you don’t use double quotes then you must escape any special characters in your search value. However, suppose your target value is enclosed in double quotes:

"Yahoo!"

In that case, things are a little different. If you enclose the search value in double quotes, then you only have to escape these four characters:

" \ * ?

That means that, as long as you’re using double quotes, there’s you don’t have to escape the ! character in Yahoo!:

"Yahoo!"

However, you still have to escape the \ character, double quotes or no double quotes:

"C:\\Windows\\System32"

If that’s confusing, well, don’t worry too much about it: try it a few times (using different search characters and alternating between double quotes and no double quotes) and you’ll soon see how it works. And, as we noted earlier, there’s a good chance you’ll never encounter special characters when working with user profiles anyway.

Uppercase letters and search queries

As a general rule, Console searches are not case-sensitive. For example, here’s a successful search for skeeterjdavis@gmail.com (all lowercase characters):

Here’s another successful search for that same user, this time using all uppercase characters:

And, finally, one more example, this time using a bizarre (but ultimately successful) mix of uppercase and lowercase characters:

Now let’s search for a different user: alexandria.torres@akamai.org. An all-lowercase search works just fine:

However, that’s not true if our search contains nothing but uppercase letters:

In other words, even though search is (generally) case-insensitive, we can find aexandria.torres@akamai.org, but we can’t find ALEXANDRIA.TORRES@AKAMAI.ORG. Why not?

The problem we’re running into here is that Console’s search syntax uses several all-uppercase terms such as AND and OR. As you can see, the preceding search query features three instances of those reserved terms:

ALEXANDRIA.TORRES@AKAMAI.ORG

And that’s the problem. Because of the AND and the ORs, Console is trying to create a complicated search query that, not surprisingly, comes up empty. Without getting too bogged down in the details, Console is searching for ALEX ANDRIA.T OR RES@AKAMAI. OR G. We know this because a user who has the display name G*is* returned by this search:

If you’ve ever searched for ALEXANDRIA.TORRES@AKAMAI.ORG and gotten back someone like greg.stemp@janrain.com, well, now you know why.

Fortunately, there are two ways to work around this issue. One way is to use nothing but lowercase letters when conducting a search. That works although , admittedly, it isn’t always very feasible. For example, if you copy an email address like AKAMAI-ORDER-INFORMATION-AND-SHIPPING-AND-DELIVERY-STATUS-UPDATES@AKAMAI.COM, you can’t just paste that address into your search. Instead, you first have to convert the address to all lowercase characters. Sure, that’s doable, but ….

Because of that, a better solution is to always enclose your search terms in double quote marks:

When you put the search term in double quotes, Console searches for the exact value you specified, and ignores any reserved terms (such as OR or AND) that might show up in between the quote marks. Use double quotes and you won’t have to worry about whether or not your search term includes any reserved words.

And before you ask, yes, you must use double quotes. Single quotes won’t do you any good:

Search for null values

When searching for user profiles, you might want to identify users who are “missing” an attribute value; for example, users who haven’t listed their birthday or users who haven’t designated a city or state. To search for missing values, use the keyword NULL. This syntax searches for users who haven’t entered a value for their birthday:

birthday = NULL

To return a collection of all the users who have supplied a value for the birthday attribute, use the != (not equal to) operator:

birthday != NULL

Two things to keep in mind here. First, NULL queries are only valid when using the = or the != operator; if you use NULL with any other operator (such as >) you’ll receive the following error message: ‘Null’ can only be used with exact matches.

Second, you must specify the NULL keyword using all uppercase letters. This query looks for all the user profiles that have not specified a country:

primaryAddress.country = NULL

However, this query looks for all the users who live in the country Null:

primaryAddress.country = Null

Definitely not the same thing.

Search for datetime values

Dates are an important part of managing user profiles. For example, you’ll often want to know the date that a profile was created. You’ll want to know the date when a user first logged on, or maybe the date when the user last user logged on. You’ll want to know when (if) an account was deactivated; you’ll want to – well, again, you get the idea. Fortunately, the Console makes it easy to search for user profiles based on the date when something (a log on, a profile update, a birthday) took place.

In fact, the only potentially-confusing thing when it comes to searching for dates is the fact that the Console employs two different date-related attributes: date attributes and datetime attributes. A datetime attribute is an attribute that contains both a date and a time; for example, October 18, 2017, 11:35 AM. By comparison, a date attribute contains only the date: October 18, 2017. The Identity Cloud user schema includes attributes of both types, and while there’s no real difference between the two (at least when it comes to searching for user profiles), it’s useful to understand exactly what you’re dealing with.

For starters, the Console formats datetime values by using ISO (International Organization for Standardization) 8061. If you run a search that returns a datetime value (such as the created attribute), the Console returns values similar to this:

How do you interpret values like those? Here’s how:

Is that complicated? Maybe. But, fortunately, you don’t have to worry about the level of precision prescribed by ISO 8061. Instead, when you conduct a search in the Console you only have to deal with the date itself: the month, the day, and the year. In addition, you don’t have to use the ISO 8061 format when searching for those dates. For example

created = 09-25-2017

Or you can employ the standard US date format, using forward slashes instead of hyphens:

created = 9/25/2017

Either way, you get back all the user accounts created on September 25, 2017:

That’s how you search for datetime attributes. So how do you search for date attributes? You use the exact same approach. Because they don’t include the time of day, there’s no doubt that date attributes look different in the Console search results:

Be that as it may, you still search for birthdays (or other date attributes) using the same method employed when searching for datetime attributes:

birthday = 12/24/1963

Could it get easier? Well, maybe. But we’re not sure how.

Good question: what about date ranges? For example, can we search for all the accounts created in the year 2017 or earlier? Or what about all the accounts created in February 2018? Can we do more than just find accounts created on a specific day?

Of course we can; we just have to specify the correct operator and the correct starting/ending point. For example, suppose we do want to get back all the accounts created in the year 2017 or earlier. That means that we want to get back all the accounts that were created before January 1, 2018. In turn, that means we want to use the less than operator (<) to return all the user profiles created prior to January 1, 2018:

created < 1/1/2018

Voila:

To find all the user accounts created in the year 2018 or later, all we need to do is switch to the greater than operator and change our starting date to December 31, 2017:

created > 12/31/2017

That returns creation dates like these:

And, yes, we could have used the greater than or equal to operator (>=) and a start date of January 1, 2018.:

created >= 1/1/2018

That returns all the user profiles created sometime in the year 2018:

Again, you have some flexibility here to search for dates in the way that seems the easiest and most intuitive to you.

To find all the accounts created in a specific month, use a query similar to this:

created >= 2/1/2018 AND created <= 2/28/2018

In the preceding query we’re looking for all the profiles where the creation date is greater than or equal to 2/1/2018 and where the creation date is less than or equal to 2/28/2018. In other words, we’re looking all the profiles created in February 2018:

Keep in mind that, for the moment anyway, you’re limited to searching for dates only: although datetime attributes also keep track of the time of day when an event took place, you can’t do something like, say, search for all the user profiles created between 8:00 AM and 9:00 AM on a specified day. Granted, you can include the time of day in your query; for example, you can write a query similar to this:

created = "10-02-2017 04:16:29.017481"

When you actually run that query, however, the Console strips off the time information, leaving you with this:

created = "10-02-2017"

In turn, you get back all the profiles created on October 2, 2017, regardless of what time of day those profiles were created: