User profile searches

The Console potentially allows you to search on any attribute in your entity type schema. (This includes any custom attributes that you might have added to the schema.) Want to search for users based on their birthday? No problem: the user schema includes an attribute named birthday. Want to search for users based on the country they live in? No problem: the user schema includes an attribute named primaryAddress.country. Want to search for users based on their opt-in status? No problem: the schema includes an attribute named optin.status. Want to – well, you get the idea.

📘

When we say that you can search on any attribute in your schema, that includes plural attributes, individual attributes that can store more than one value. However, while plural attributes can be searched, the stored values cannot be displayed in the Console search results.

But wait a second: if you can search for any attribute in your user schema (and you can), then why did we preface this topic by saying that you can potentially search for any attribute in your user schema? That’s a good question, and we have an answer for you: straight out of the box, there are only a dozen or so attributes that you can search on.

Wait: what? Are those really the only attributes you can search on? Initially, yes: those are the only attributes you can search on. By design, the Console only searches on the so-called “searchable attributes,” attributes that have been indexed. And what is an indexed attribute? To answer that question, let’s start by pointing out that, in the user profile database, all the information about a user is stored as a single record; that record contains information such as the user’s name, email address, physical address, telephone number, etc. Without indices, and without indexed attributes, searching this database would require sifting through all those user records and all that accompanying data, a very time-consuming and resource-intensive task.

So then what’s an index? For our purposes, an index is a data structure (separate from the main database) that contains two pieces of information for each user: the value of an attribute (for example, the user’s email address) and a pointer to the complete user record. If you want to search for an email address, it’s much faster and much more efficient to search the email index (which, in this case, is just a list of email addresses) than it is to search through the entire database.

For example, imagine looking for a phone number in the phone book, but having to look through not just all the phone numbers but all the names and addresses and ads and maps and everything else you might encounter in a phone book. That’s obviously going to be slower and more-cumbersome than looking for a phone number in a list that has nothing but phone numbers. If you’re trying to find a specific email address, you (or, at any rate, the computer) can quickly search through the email index, locate the target email address, then, if necessary, use the pointer to the complete user record to retrieve additional information like the user’s name or telephone number.

To make a long story short (which is kind of what an index does), an index is a data structure that speeds up searches; in turn, an indexed attribute is any attribute that has its own index. In the Console, you can only search on indexed attributes, because searches are then carried out on an index rather than on the entire database.

Admittedly, if you only have a handful of user records, well, then an index won’t make much difference. But because user profile databases have the potential to grow extremely large (it’s not unusual for organizations to have millions of records in their user profile databases), using indices and limiting search queries to indexed attributes helps ensure faster and more efficient database performance.

📘

That’s the upside to an index. The downside? Each index you create requires additional storage space. That’s one reason why only a few attributes are indexed by default: if you indexed everything, your database could instantly double or triple in size, and disk storage space might suddenly become a major concern.

By default, the following attributes come “pre-indexed,” meaning that they are searchable in the Console:

• displayName
• email
• familyName
• givenName
• primaryAddress.phone
• birthday
• uuid
• profiles.identifier
• lastUpdated
• clients.clientId
• id
• created
• profiles.profile.preferredUsername
• janrain.properties.managedBy.clientId

To verify which of your attributes are searchable and which ones aren’t, click the Searchable fields link on the Console’s Manage Profiles page. That displays a dialog box showing all the attributes you can search on:

If you later index other attributes (such as primaryAddress.country), those attributes will also appear in this dialog box.

You can also find this information on the Manage Schemas page.

Out of the box, those are the only attributes that you can use in a search query. For example, suppose you try to search for an attribute (such as primaryAddress.country) that has not been indexed:

primaryAddress.country = "Japan"

The preceding search will fail with the error message Some fields are not queryable: primaryAddress.country. And why isn’t the attribute queryable? You got it: because, by default, primaryAddress.country is not an indexed attribute.

But all is not lost: if you want to search on other attributes (primaryAddress.country, deactivateAccount, etc.) you just need to create indices for those attributes. That’s done by contacting your ​Akamai​ representative.

The point to remember: the Console lets you search for any attribute in your user profile database (including any custom attributes you might have added to the database). Just make sure that the attribute is indexed before you try searching on it.