Today, we’re excited to announce the Beta release of Custom Data Search. In a nutshell, Custom Data Search gives you the ability to search for accounts based on the custom attributes you define in your application.

Custom Data Search

Adding customized search of this magnitude (millions of JSON objects in a schemaless database) represents a huge milestone for the team here at Stormpath, but more importantly it adds the robust search functionality our developers have been clamoring for.

Learn more about Custom Data Search with Stormpath in our upcoming webinar!

Let’s take a tour!

The Stormpath data model gives you a lot of flexibility when it comes to what data is stored for user accounts. We like to say that a key benefit of implementing Stormpath as your user management service is that you never have to store user credentials again. But our data store can house a lot more than just credentials. In addition to the normal information (username, password, etc.) stored for objects like Accounts, Custom Data allows you can add an almost limitless amount of additional data in the form of JSON key-value pairs.

For example, you may want to include street address, city, state, and postal code in your user data. In custom data, that would look like this:

It’s an entirely flexible data store, and also allows you to do things like store fine-grained permissions at the user or group level.

Custom Data Search in the Stormpath API

Stormpath has offered search capability before now — administrators can search for Accounts based upon the core data attributes mentioned above: username, email address, and last name. Custom data search expands that functionality to let you search the custom data on Accounts in a Directory, either using the API or one of our SDKs.

Custom Data Search in Action

Here is the general structure for a custom data query:

You will receive back an array of resources that contain that value in their custom data. You can currently search a Directory’s “accounts” within Stormpath via this endpoint:

For example, if you know that Accounts have a shippingState key in their customData, you could find all Accounts in a Directory that have a shippingState custom data key set to Nevada by sending a GET to:

Custom data search gives you a lot of flexibility when it comes to what kind of searches you can perform. If instead of finding all Accounts that had customData where shippingState=nevada we wanted to find all Accounts where shippingsState was any of the states starting with “I” (such as Illinois, Iowa, Indiana): we would simply change the query to: ?customData.shippingState=i*

Searching Numbers and Datetimes in Custom Data

Custom Data Search also provides robust search capability with regard to dates and numbers. For example, you can search for accounts using exact numerical values, ranges of values, and even incorporate inclusion, exclusion, and precision logic. Or, you can store an ISO 8601 datetime in Custom Data and use the datetime search function to query these values.

For additional explanation please refer to the Stormpath documentation for this feature.

The real value of this feature comes from what you can do with the results of the searches. It depends upon the nature of the application, but here are a few examples that are often requested by our users:

  • Store last login date for your SaaS application: Use the results to enable customer usage analysis and outreach
  • Store subscription info: Search for everyone in the “pro” tier and send them a custom email
  • Store third party IDs to enable custom integrations: Who are your users with an associated Stripe account?
  • We invite you to try out Custom Data Search for yourself. The best place to start is the documentation, which contains more usage examples.

    If you have not yet created a Stormpath account, that would be a great next step as well!

    As excited as we are to bring Custom Data Search into production, you should be aware that this is a Beta release in both our core REST API and all our SDKs, not a final release. Further, Custom Data Search is as yet only available for our public cloud deployments. We have not yet added this feature to enterprise and private deployment environments.

    As always, Stormpath provides support even for free developers accounts, so feel free to contact our technical team at [email protected] with any support questions or to report any bugs you run into.