Skip to main content
All CollectionsBest Practices
Sharding Owned Custom Entity Collections
Sharding Owned Custom Entity Collections

Any high-volume owned collections should be sharded for best performance.

Paul Winterhalder avatar
Written by Paul Winterhalder
Updated over a year ago

Custom Entities are brainCloud's most advanced form of Entity (i.e. JSON-based data objects).

They come in two varieties:

  • Owned Custom Entities - these are entities owned by individual end-users

  • Unowned Custom Entities - these entities are not owned by individual end-users -- they are global to the app as a whole.

Depending upon how they are used, Owned Custom Entity collections can grow very large. If you are using an Owned Custom Entity collection to store the cars a player owns in a racing game, and your game has millions of players, you will have potentially tens or hundreds of millions of entities in your Cars collection!

To better scale these scenarios, brainCloud supports sharding of Owned Custom Entity collections -- which automatically distributes the collection's objects across a set of database servers for better performance and scalability.

Important notes:

  • API changes - there are a few custom entity calls that are not sharding-safe. Your app should be sure to use the sharding-safe versions of those calls before sharding the collection

  • Sharding a collection cannot be done via the Portal. You must send a request to brainCloud support (via the Chat widget) with the

    • collection name - the name of the custom entity collection to shard

    • app name(s) and id(s) - the names and appIds of the apps that have this collection. There will be multiple if you have separate DEV vs. PROD versions of your app

  • You can shard a collection at any time - but it is best to shard it before your app goes live - as there an be a performance impact if MongoDB needs to move a lot of objects across database shards

API Changes

The following methods are not safe to use with sharded Custom Entity collections.

  • IncrementData() -- use IncrementDataSharded() instead

  • SysIncrementData() -- use SysIncrementDataSharded() instead

  • UpdateEntityFields() -- use UpdateEntityFieldSharded() instead

  • SysUpdateEntityFields() -- use SysUpdateEntityFieldSharded() instead

What's the difference? The sharded methods contain an additional parameter, shardKeyJson, where you provide the ownerId of the entity to be updated. This ownerId field is used by MongoDB to determine which server shard to target for the update.

A valid shardKeyJson object will look something like this:

{
  "ownerId": "aaaaa-bbbbb-ccccc-ddddd-eeee"
}

where aaaaa-bbbbb-ccccc-ddddd-eeeee is the profileId of the end-user who's entity we are editing <- e.g. probably the current player

The Request

Once you are ready to shard your entities, just send a request off to support. Something like this!

Hi,

We'd like to shard the following Owned Custom Entity collections:

  • saveData

  • playerPrefs

For the following apps:

  • AwesomeApp Prod (55555)

  • AwesomeApp Dev (55556)

Thanks a bunch!

Conclusion

We hope that helps!

Did this answer your question?