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

Note. 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"
Note. 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

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

Yahoo\!

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.