Searching with Wildcard Characters

In poker, a wild card (such as the joker) can be used to represent any card: for example, if you have 2 aces and a joker, you effectively have three aces, the joker being used as an ace. If you have a joker and the 4, 5, 6, and 8 of spades, you can use the joker as a 7 of spades, giving you a straight flush. Most likely you already know all that.

Wildcards perform a similar function in the Janrain Console: they can be used represent any character. When searching user profiles, the Console supports two wildcard characters:

  • The question mark wildcard
  • The asterisk wildcard
     
Note. Yes, those are the only supported characters. The Console does not support any other wildcard characters, including commonly-used characters such as the period (used in regular expressions) or the range (e.g., [A-Z]).

The Question Mark Wildcard

In the Janrain Console, the question mark serves as a stand-in for a single character. For example, suppose you want to search for a user, but you aren’t sure if that user is named Johnson or Johnsen. This query returns users named either Johnson or Johnsen:

familyName = Johns?n

In the preceding example, the search value Johns?n means “Return all the users who have a family name that begins with the letters Johns, is followed by any other character (even a number), and then ends with the letter n.” That means that the query returns users named Johnson or Johnsen. It also means that this query returns users with names like Johnsun, Johnsin, Johnsxn, or even Johns4n. For example:

  • Johnsan
  • Johnsbn
  • Johnscn
  • Johnsdn
  • Johnsen
  • Johnsfn

And so on. Like we said, the question mark represents any character.

And yes, you can use multiple question mark wildcards in a single search query. For example:

familyName = J?ns?n

The preceding query returns names such as Jansen, Jensen, Jonson, etc., etc.

As it turns out, however, there’s even more that you can do with wildcard characters.

The Asterisk Wildcard

The question mark wildcard represents a single letter; for example, the query T?m returns both Tim and Tom. However, that query won’t return term or them. Why not? Because those words have more than one character between the T and the m. To return term or them, you need to use this construction: t??m.

Of course, that syntax specifies two characters between the T and the m; that means that the query won’t return either Tim or Tom (which both have just one character between the T and the m). The question mark wildcard is very specific in its function: one character per question mark. Period.

Is that a problem? No, not as long as you use the asterisk wildcard (also known as the “star” wildcard). As we’ve seen, the question mark has one job: each question mark stands in for one (and only one) character. By comparison, the asterisk stands in for any number of characters (including zero characters). For example, this query finds both Tim and Tom:

givenName = T*m

That query also finds term, them, transcendentalism, tearoom, tandem, thermogram, and any other word or phrase that starts with a T and ends with an M. In fact, the query even finds tm, a case in which there are no (0) characters between the T and the M.

For example, do you want to find all the users who have a last name that begins with Smith (that is, Smith, Smithers, Smithson, Smithman, Smithberg, etc.)? Here you go:

familyName = Smith*

That syntax should be easy to understand: we’re simply asking for all the users whose last name (familyName) starts with the letters Smith and ends with – well, we don’t care what those last names end with (if anything). That’s the purpose of the * wildcard.

An even better use of the * wildcard is to put it at the front of your target values. For example, suppose you are planning a targeted marketing campaign, and you need a list of all the users who have Yahoo! email accounts. This query returns that information for you:

email = "*@yahoo.com"

Or, to find all the users who don’t have Yahoo! email accounts, use this query instead:

email != "*@yahoo.com"

There’s just one catch to putting an asterisk (or a question mark) at the beginning of a search value. In order to do that, the attribute in question (e.g., email) must not only be indexed, but it must also be “reverse-queryable.” By default, none of your attributes (including the default indexed attributes such as email and displayName) are reverse queryable. As a result, searching for a value like *.@yahoo.com returns the error message Some fields are not reverse-queryable: email. To get an attribute designated as reverse-queryable, contact your Janrain representative.

Like the question mark, you can use more than one asterisk wildcard in a query. For example, this query returns (among other many possibilities) the user who has the display name Bob Jones:

displayName = "B*b*J*"

Oh, and there’s one more catch to using wildcards: wildcard characters can only be employed when searching for string values. That means that you can’t use wildcards to search for things like dates or numbers or UUIDs. For example, the following query, which tries to return all the users with the birthday December 19, fails, because birthday is not a string value:

birthday = "12/19/*"
Note. But what if you need to know which users have a birthday on a specified day? Well, if you don’t have too many users, you could search for all your users, sort on birthday, and then export the data. That’s a potentially big export with a lot of data, but at least the users with a birthday on December 19 will be grouped together.