Custom data search within an array

Question

Is it possible to search an account's custom data to find a value contained in an array?

Something like:

?customData.[arrayName].{key}=value

The Stormpath docs don't mention array searching.

Answer 1

Searching for custom data in an array can definitely be done. The syntax is: customData.{fieldName}\[{index}\]=value where {index} can be the specific index you are looking for, or * if you want to find it anywhere in the array. (Note that the [] characters are escaped with a backslash or the query interpreter gets it confused with a range query.)

If you leave off the index entirely, then \[*\] is implied. More precisely, Stormpath will check for either the value in the fieldName or the value as an element in an array of fieldName. However, syntactic sugar can only work if the array field is the last element in your search. Since you can put literally any JSON object into your custom data, Stormpath cannot check every single possibility. Imagine something like customData.foo.bar.baz.qux=bingo. Stormpath would not try to guess that maybe foo is an array, maybe bar is an array or not, maybe baz is an array or not - only maybe qux is an array or not. So, if you want to search an array of objects, you cannot leave out the \[*\].

Here is an example. I have an account with the custom data:

{
  "favoriteThings": [
    {
      "thing": "raindrops",
      "location": "on roses"
    },
    {
      "thing": "whiskers",
      "location": "on kittens"
    },
    {
      "thing": "snowflakes",
      "location": "on my nose and eye lashes"
    }
  ],
  "favoriteColors": [
    "blue",
    "grey"
  ]
}

The following queries will yield the following results:

• customData.favoriteColors=blue will include this account.
• customData.favoriteColors\[1\]=blue will not include this account because blue is not at index 1.
• customData.favoriteThings\[*\].thing=whiskers will include this account
• customData.favoriteThings\[*\].thing=ponies will not include this account because it does not list ponies as one of his favorite things, but may include other accounts with custom data in the same structure.
• customData.favoriteThings.thing=whiskers would not include this account or any other accounts with the same custom data structure because in that case, Stormpath would be looking for a single nested JSON favoriteThings object, not an array.

Answer 2

Yes, with Stormpath it is totally possible to search for custom data even if the values are stored as an array!

Please note that the field names are simple names, and the values are what are different data types like array, map, string etc... so the query is not as complex as one would think :-)

For example, if I want to store custom data called favoriteColors, which is an array like

"favoriteColors": [ "red", "black", "blue", "white" ]

Notice the field name is just like any other field name. The value is the array.

To search for accounts which have a value red in the favoriteColors array, you just need the normal query syntax:

?customData.favoriteColors=red

The full request (if searching a Directory of accounts), might look like this:

https://api.stormpath.com/v1/directories/<directory_uid>/accounts?customData.favoriteColors=red

You could also do the same search on the Tenant resource to search tenant-wide (across all accounts):

https://api.stormpath.com/v1/tenants/<tenant_uid>/accounts?customData.favoriteColors=red

This query would match an account that contains red in the favoriteColors array. If I changed the query to ?customData.favoriteColors=yellow it would not match unless yellow was also added to the array.