After you’ve mastered search query construction , your next step is to actually run your query. The Console supports two ways to carry out a basic search. You can:

• Carry out a “default search”, which automatically searches on your default search default attributes (and only on those default attributes.

• Use the Simple Search query language to create custom searches that can search on any of your indexed attributes.

Default searches

To perform a default search of your user profiles, all you have to do is go to the Manage Profiles page, type your search value in the Search for profiles field, and then click Search (or press ENTER). For example, to search for the email address terrance_oreilly@mail.com, type that address into the Search for profiles field and then click Search:

In turn, the Console returns a collection of all the users who have the specified email address or display name. And yes, the Console automatically searches both the email attribute and the displayName attribute, whether you want it to or not. That’s the whole idea behind the default search: you specify the search value, and the Console searches all of your default search attributes.

Ah, good question: how do you restore the default and show all the user profiles again? That’s easy: just select and delete any text in the Search for profiles field. Alternatively, you can click the Clear button (X) to clear the Search**profiles**field (and, at the same time, delete the corresponding filter)

That’s a little bit easier and a bit more intuitive.

You can also use wildcard characters in a default search. For example, this syntax returns information for terrance_oreilly@mail.com:

"ter*"

As we learned elsewhere, the preceding syntax is interpreted as “Find all the users who have a display name or an email address that begins with the characters ter. And don’t worry about any characters that come after those first three letters, assuming there even are any.” Among other things, that means that wildcard searches often return more than one profile; for example, the preceding query returns terry@janrain.com and terkel@janrain.com as well as terrance_oreilly@mail.com. That’s not a good thing or a bad thing; it’s just something to keep in mind.

📘

One way to limit the number of returned profiles is to use multiple wildcards, or to put the wildcard in a different location. For example, this query returns users who have a display name or email address that starts with ter and that ends with @mail.com:

"ter*@mail.com"

If nothing else, that keeps email addresses like terry@janrain.com and terkel@janrain.com from being returned.

When doing a default search you must also be on the lookout for search queries that include blank spaces. For example, suppose you want to search for the user with the display name Bob Jones. Intuitively, you might expect this query to do the trick:

Bob Jones

As it turns out, however, that query won’t do the trick, Instead, you get back the message No records found.

The Console uses the blank space to separate search values. In this case, that means the Console thinks you’re searching for two different things: 1) all the users who have a display name or email address equal to Bob, or, 2) all the users who have a display name or email address equal to Jones. Because there aren’t any users who fulfill either condition, no records are returned.

Instead, searching for Bob Jones (or for any other term that includes a blank space) requires you to enclose the search query in double quotes:

"bob jones"

And what if you did want to search for users named either Bob or Jones? That’s fine; you can specify multiple criteria in a default search. For example, suppose you wanted to find Bob Jones and/or Maria Fuentes. This query does just that:

"Bob Jones" "Marie Fuentes"

As you can see, each search query is enclosed in double quotes, and the two terms (Bob Jones and Marie Fuentes) are separated by a blank space. As a result, the Console searches for, well, Bob Jones and Marie Fuentes, the same as if you had written out this full search query:

displayName = "Bob Jones" or email = "Bob Jones" or displayName = "Maria Fuentes" or email = "Maria Fuentes"

And, yes, you can use wildcards in a “fancy” search like the previous. For example:

"Bob*" "Marie*"

Custom searches

Default searches can be conducted very quickly and very easily. That’s the good news. The bad news is that default searches lack power and flexibility. For example, default searches can only be performed on the default search attributes (typically the email and displayName attributes); if you want to search for the date an account was created (created) or the date when an account was last updated (lastUpdated), well, you’re out of luck.

That’s where custom searches come in. With a custom search, you take the different parts of a search query (attribute names; operators; target search values; etc.) and then put those pieces together to return user data. Best of all, you can run these searches against any of your indexed attributes.

Let’s start by composing a basic query. Suppose we have a user UUID – 64d3449b-26ed-4abe-98a3-f232494ef085 – and we want to determine which user that UUID belongs to. To do that, we need three things:

• The name of the attribute we want to search on (uuid).
• The operator to be used in the search (=).
• The value we want to search for (64d3449b-26ed-4abe-98a3-f232494ef085).

If we put those pieces together, we get a query that looks like this:

uuid = "64d3449b-26ed-4abe-98a3-f232494ef085"

If we go to the Manage Profiles page, type that query into the Search for profiles field, and click Search (or press ENTER) we should get back something similar to this:

That’s about as easy as it can get.

Before we go any further, a couple quick reminders about formatting your search queries. To begin with, and because the query value (64d3449b-26ed-4abe-98a3-f232494ef085) doesn’t have any blank spaces, the double quote marks are optional; this syntax works equally well:

uuid = "64d3449b-26ed-4abe-98a3-f232494ef085"

Double quotes or no double quotes? That’s up to you. (Although we would argue that using the double quotes makes it easier to pick out the target search value.)

Second, the blank spaces that surround the equals sign ( = ) are also optional. The blank spaces make the query a little easier to read, but if you leave them out you’ll get the expected results. There aren’t any blank spaces around the operator in this query, but it still returns the correct user profile:

"uuid=64d3449b-26ed-4abe-98a3-f232494ef085"

The only thing that isn’t optional is the attribute name (uuid), which must be in all lowercase letters. Anything other than uuid (for example, UUID) will not provide the expected results:

Now let’s try something a little fancier; let’s search for all the users whose who live in the city of Portland, starting with this:

primaryAddress.city = "Portland"

The preceding command works, but with one little quirk: it returns users for Portland, OR (like we wanted), but it also returns users from Portland, ME; Portland, OH, Portland, NY; Portland, TX; and any of the other 30-plus American cities named Portland. Believe it or not, that’s to be expected: we said we wanted users who lived in the city of Portland, and the query returned users who live in the (or, more correctly, live in a) city named Portland. Citizens of either town might disagree, but Portland, ME is just as much a city as Portland, OR.

To limit returned data to users from Portland, OR, we need a more specific query. In particular, we need a query that specifies both the user’s city and the user’s state. In other words, we need this:

primaryAddress.city = "Portland" AND primaryAddress.stateAbbreviation = "OR"

In this query, we use the AND operator to indicate that the returned data meet two criteria: the user’s city must equal Portland and the user’s state must equal OR. People from Salem, OR won’t make the cut because they don’t have live in the specified city; people from Portland, ME won’t make the cut because they don’t come live in the required state.

And if we do want to return data as long as a user meets just one of a specified set of criteria? That’s what the OR operator is for. For example, here’s a query that returns all the users who live in Oregon or who live in Washington:

primaryAddress.stateAbbreviation = "OR" OR primaryAddress.stateAbbreviation = "WA"

Want to add Alaska, Idaho and California to the list? Then just keep adding OR clauses:

primaryAddress.stateAbbreviation = "OR" OR primaryAddress.stateAbbreviation = "WA" OR primaryAddress.stateAbbreviation = "AK"
OR primaryAddress.stateAbbreviation = "ID" OR primaryAddress.stateAbbreviation = "CA"

Etc., etc.

But suppose we want only the females who live in Oregon or Washington. Can we do that? You bet we can:

gender = "Female" AND (primaryAddress.stateAbbreviation = "OR" OR primaryAddress.stateAbbreviation = "WA")

In the preceding query, we’re looking for user profiles that meet two criteria:

• The user’s preferred gender must be female.
• The user must live in either Oregon or Washington.

In order to enforce those two conditions, we put parentheses around the OR clause. When a clause is enclosed in parentheses, the Console resolves that part of the search before it does anything else. In this case, that means we first determine the state the user lives in (either Washington or Oregon) and then we make sure that the user is also female. Note that the placement of the parentheses is very important. For example, consider this query which, on the surface, looks very similar to our previous one:

gender = "Female" AND (primaryAddress.stateAbbreviation = "OR" OR primaryAddress.stateAbbreviation = "WA")

But notice how that query gets interpreted. The Console first looks at the clause contained in the parentheses:

(gender = "Female" AND primaryAddress.stateAbbreviation = "OR")

In other words, it’s going to return all the female users who live in the state of Oregon. That’s fine. But now look at the rest of the query:

OR primaryAddress.stateAbbreviation = "WA"

Because of the way we’ve positioned our parentheses, the Console is going to return all the females who live in Oregon, and then return any user (female or not) who lives in Washington. That’s not what we were hoping to return. And the difference in our two queries lies solely in how (and where) we put the parentheses.